Skip to content

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

Description

@iJungleboy

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

  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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions