Common Extensions

Compatibility with mdbook Preprocessors

• mdbook-bib

  • Restrict mdbook-bib to run only for the HTML backend (see Locking a preprocessor dependency to a renderer):

    [preprocessor.mdbook-bib]
    renderers = ["html"]

  • Transform mdbook-bib's citations to Pandoc Cite AST nodes using a Pandoc Lua filter:

    Note that mdbook-pandoc does not pass markdown to pandoc, but rather Pandoc's native AST format. This means that instead of translating {{#cite key}} and @@key to [@key], we need to translate them to Pandoc Cite AST nodes, and we do this in the form of a Pandoc filter. In book.toml, we tell Pandoc to use this filter, and afterwards run citeproc to process the citations.

    mdbook-bib.lua

    function Inlines (inlines)
      for i = 1, #inlines do
        e = inlines[i]
        -- Replace {{#cite key}}
        is_bracketed_citation = e.t == 'Str' and string.sub(e.text, 1, 8) == '{{#cite ' and string.sub(e.text, #e.text-1, -1) == '}}'
        if is_bracketed_citation then
          cite = string.sub(e.text, 9, #e.text-2)
          inlines[i] = pandoc.Cite({pandoc.Str(cite)}, {pandoc.Citation(cite, "AuthorInText")})
        end
        -- Replace @@key
        is_citation = e.t == 'Str' and string.sub(e.text, 1, 2) == '@@'
        if is_citation then
          cite = string.sub(e.text, 3, -1)
          inlines[i] = pandoc.Cite({pandoc.Str(cite)}, {pandoc.Citation(cite, "AuthorInText")})
        end
      end
      return inlines
    end

    [output.pandoc.profile.example]
    filters = ["mdbook-bib.lua", "citeproc"]
    bibliography = "bib.bib" # replace with path to your bibliography

• mdbook-mermaid

  Use mermaid-filter:

  [output.pandoc.profile.example]
  filters = ["mermaid-filter"]

Common Pandoc Filters