[Bug] Markdown to Override API fails if it has multiple "---"
- Dominant language
- C#
- Stars
- 4.4k
- Forks
- 890
- Avg merge
- 2h 9m
- Merged PRs (30d)
- 11
Description
**Describe the bug**
I have a setup which uses the docfx.json "override" to augment API docs with additional markdown.
But I kept on getting errors like this:
```text
SomeFile.md: warning invalid-yaml-header: Exception during deserialization
```
After long research I found out that the problem is `---` (triple dashes) in the body of the file, used to create lines (`
`) tags. As soon as you have at least 2 in the body, docfx seems to get confused and thinks it's another **yaml header**.
This fails:
```markdown
---
uid: ToSic.Sys
summary: ToSic.Sys is for internal helpers and base classes which are just FYI.
---
Some content
---
## History
1. Introduced in 2sxc 15.0 as `ToSic.Lib` (previously was part of `ToSic.Eav`)
1. Changed to `ToSic.Sys` in 2sxc 19.0 to better reflect that it's the core system functionality.
---
```
While this works (note I removed one of the `---`).
```markdown
---
uid: ToSic.Sys
summary: ToSic.Sys is for internal helpers and base classes which are just FYI.
---
Some content
REMOVED THIS LINE
## History
1. Introduced in 2sxc 15.0 as `ToSic.Lib` (previously was part of `ToSic.Eav`)
1. Changed to `ToSic.Sys` in 2sxc 19.0 to better reflect that it's the core system functionality.
---
```
**To Reproduce**
1. Setup an override to get md files
2. Create the md-file with just the yml header, works
3. add content with tripple-dashes, once you add 2, it fails.
**Expected behavior**
Docfx should only treat the initial `---` block as yml header.
**Context (please complete the following information):**
- OS: Windows
- Docfx version: 2.78.4 and 2.78.5
**Workaround**
As of now, you can work around this by creating 6-dashes like `------` for separation lines.
But it took me hours to figure out what was going on.
Contributor guide
Research direction
Start with the docfx.json override path and the Markdown YAML-header handling that emits invalid-yaml-header; reproduce the issue using SomeFile.md and the two examples provided. Done means only the initial --- block is treated as the YAML header, while later --- separators remain body content without warnings.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- markdown
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100