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-includesand--include-in-headerinclude-beforeand--include-before-bodyinclude-afterand--include-after-bodytoc/table-of-contentsand--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.