Markdown reference links cannot be used from DFM include files

Markdown reference links cannot be used from DFM include files

Functional impact

This is a markdown reference link: [example]: http://example.com This is a DFM include statement: [!include[links](../linksinc.md)] Currently markdown-reference-links must be used from the same md file in which they are defined.

Minimal repro steps

1. Create a file “a.md”:

This is an [example], the last word should be a link.
[!include[links](linksinc.md)]

1. Create a file “linksinc.md”

This is an [example], the last word should be a link.
[example]: http://example.com

1. Include a.md into a docfx project, and build it.

Expected result

Both “[example]” sections should be found an expanded.

Actual result

Only “[example]” sections inside of linksinc.md will be expanded.

Further technical details

It seems the way the markdown engine is built, the included markdown files are being expanded separately, not allowing markdown reference links to be resolved into an include-file.

Maybe the markdown-engine not resolve markdown reference links until !include statements have merged all include files into a single unit. [This would work more like the Standard C preprocessor]

Thank you for creating Docfx, it is a awesome project!.

[vwxyzh]

@cameron-elliott If your document has many reference definition, why not use xref? e.g.: your article is:

Content is: [Intel Quick Sync Video][Intel_Quick_Sync_Video] and [Intel HD and Iris Graphics][Intel_HD_and_Iris_Graphics]

[Intel_Quick_Sync_Video]: https://en.wikipedia.org/wiki/Intel_Quick_Sync_Video
[Intel_HD_and_Iris_Graphics]: https://en.wikipedia.org/wiki/Intel_HD_and_Iris_Graphics

1. Create an xref map file:

   ### YamlMime:XRefMap
   hrefUpdated: true
   references:
   - uid: Intel_Quick_Sync_Video
     name: "Intel Quick Sync Video"
     href: https://en.wikipedia.org/wiki/Intel_Quick_Sync_Video
   - uid: Intel_HD_and_Iris_Graphics
     name: "Intel HD and Iris Graphics"
     href: https://en.wikipedia.org/wiki/Intel_HD_and_Iris_Graphics
   

2. then update your article:

   Content is: @Intel_Quick_Sync_Video and @Intel_HD_and_Iris_Graphics
   

3. final, update your docfx.json, add the path of xref map in “xref”, or use command line option -x

[weitzhandler]

A bit related: #8712.