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:
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 (<hr>) 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:
---
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 ---).
---
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
- Setup an override to get md files
- Create the md-file with just the yml header, works
- 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.
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:
After long research I found out that the problem is
---(triple dashes) in the body of the file, used to create lines (<hr>) 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:
While this works (note I removed one of the
---).To Reproduce
Expected behavior
Docfx should only treat the initial
---block as yml header.Context (please complete the following information):
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.