dotnet / dotnet/docfx

[Bug] Markdown to Override API fails if it has multiple "---"

Closed
#11,088 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.