Pandoc Compatibility

In many cases, simply run codebraid pandoc <normal pandoc options>.

Codebraid currently supports two categories of input formats:

  • Pandoc’s Markdown (--from markdown)
  • CommonMark-based formats, particularly CommonMark with Pandoc extension (--from commonmark_x)

There are no limitations on output formats.

Notice that the Codebraid command-line option --overwrite is required to overwrite existing files. codebraid should typically be run in the same directory as the document, so that the default working directory for code is the document directory.

Pandoc defaults files

If you are using a Pandoc defaults file, --from, --to, and --output must be given explicitly as command-line options and cannot currently be inherited from the defaults file.

If you are using a defaults file and converting to a standalone Markdown document, --standalone should be given explicitly rather than being inherited from the defaults file.

Converting to Markdown

If you are converting from Markdown to Markdown with --standalone (basically using codebraid to preprocess Markdown documents), note that the following YAML metadata fields and command-line options are ignored in that situation:

  • header-includes and --include-in-header
  • include-before and --include-before-body
  • include-after and --include-after-body
  • toc/table-of-contents and --toc/--table-of-contents

This is typically what you want. Usually, “includes” and a table of contents are desired in a final output format like HTML or PDF, not in a Markdown file. In cases where “includes” and a table of contents are needed in Markdown documents, this can be accomplished by piping the output of codebraid through pandoc.