A guess at the line that would receive the option:

project.py:893: pdf_cmd = "pandoc --pdf-engine=xelatex --resource-path=docs -i datasheet.md -o datasheet.pdf"

After looking at the resulting PDF this --from markdown-yaml_metadata_block means turn OFF the YAML metadata block, which ends up rendering that block as inline text, which is not the intention.

I found best results with a sequence like:

## Note use of --strip-comments to help with removal of HTML style comments from MD document `<!---`
pandoc --from gfm --to markdown --strip-comments --resource-path=docs -i docs/info.md  -o datasheet.md

## edit datasheet.md to remove any empty HTML CODE blocks ```{=html}\s+``` which is in the default TT
## template of a markdown file, the use of `--strip-comments` above helped, maybe this can be done in
## python when the next stage is done?  like a multiline regex replace

## prepend the YAML  metadata header info for TeX, maybe it should end with `...` to indicate end of YAML
## document, although I did not find it makes much difference to pandoc.  I think the issue here is the pandoc
## feature of allowing the metadata to be anywhere in the document.

## Then process with the current command:
pandoc --pdf-engine=xelatex --resource-path=docs -i datasheet.md -o datasheet.pdf

The difference is there is a gfm (GitHub Markdown) to markdown (Pandoc Markdown) conversion that occurs, seems to resolve every issue when I try to break it.

See #84 as my suggested solution. I've marked it as draft so that we can discuss it here before merging. The changes are:

• use gfm (i.e. github flavored markdown) as per your last comment, but without the extra steps
• this turns off implicit raw tex support within markdown, so we replace our uses with explicit latex blocks, e.g. instead of \pagebreak we write

  ```{=latex}
  \pagebreak
  ```
  

• add the +raw_attribute extension so that we can use this feature in the yaml header block
• add the +smart extension that was enabled by default for markdown but not for gfm (it makes some changes like replacing apostrophes and quotation marks with nicer versions, i.e. ' becomes ʼ and " becomes ”).

The current PR only affects the project-level documentation, but if it works for your test cases I'll make another one for the full shuttle datasheet.

Before I forget the initial issue for me was the use of --- in the markdown, this was the cause of the failed docs GHA.

This is allowed in gfm markdown flavour for a horizontal-rule but because of the YAML metadata and the feature that metadata can appear anywhere in the markdown content, the use of --- has special meaning to YAML parser.

The solution was to just use ----- which side-steps the issue and is a compatible form of HR for both markdown flavours. But it was only known that this was a solution when I converted and inspected the output after a conversion from gfm to markdown (the native pandoc flavour markdown).

I think my extra steps were just trying to maintain using the native pandoc markdown by default for PDF generation as I assumed there maybe formatting differences and features in use (and didn't want/couldn't retest every scenario for every datasheet to know if it broke something).

So if switching to gfm and output looks good there be no need for extra steps to maintain internal use of pandoc markdown flavour.

The #84 solution looks fine to me.

--

It would be really nice if there was a diagnostic/linting mode to try to inform a failed docs GHA on what the problem might be. This might be a markdown syntax linter in the flavor of markdown that is always run before the PDF is produced so at least there is feedback in the logs. I did find and use some linting features but I don't recall the specifics.