dotnet / dotnet/docfx

[Feature Request] Include Markdown Files by UID

Open
#9,947 0 comments 1 reaction 0 assignees View on GitHub
markdown
Dominant language
C#
Stars
4.4k
Forks
890
Avg merge
2h 9m
Merged PRs (30d)
11

Description

**Is your feature request related to a problem? Please describe.**

Yes. References made by file paths to reused content are prone to break when files are moved or renamed. When dozens of people work on a large doc project, breakages like these happen frequently.

I'm frustrated when I...
* reuse content in a folder managed by someone else and the relative path breaks
* need to clutter my Markdown files with long paths rather than short UIDs

**Describe the solution you'd like**

Allow the following or similar "Include" syntax, where the UID is stored in the YML frontmatter of the Includes Markdown file:

`[!INCLUDE]()`

This is in addition to the currently supported:

`[!INCLUDE [](<filepath>)]`

Referencing files by UID is a more robust option than by file path. Using UIDs is currently possible with links (i.e., [cross references](https://dotnet.github.io/docfx/docs/links-and-cross-references.html?q=cross#cross-references
) but not with [Include Markdown files](https://dotnet.github.io/docfx/docs/markdown.html?tabs=linux%2Cdotnet#include-markdown-files)), so reused content is more prone to break.

**Describe alternatives you've considered**

None

**Additional context**

None

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.