DOCSEARCHbyAlgolia
Submit Docs

pandocfilters

repository·master·Indexed 20 days ago

https://github.com/jgm/pandocfilters

A Python module for writing Pandoc filters that transform the Pandoc Abstract Syntax Tree (AST) via JSON serialization. It provides utilities like toJSONFilter for creating JSON-to-JSON filters and supports the integration of various diagram types—including blockdiag, actdiag, nwdiag, rackdiag, packetdiag, and seqdiag—directly within Markdown using fenced code blocks.

Tokens
2.2K
Snippets
11
Records
13
Agent score
19%

What's inside pandocfilters

  2. How to use pandocfilters with Pandoc

    master

    Pandoc filters are pipes that read a JSON serialization of the Pandoc AST from stdin, transform it, and write it to stdout. You can use them with Pandoc in two ways:

    1. Using pipes: pandoc -t json -s | ./your_filter.py | pandoc -f json

    2. Using the --filter (or -F) flag: pandoc --filter ./your_filter.py -s

    pandoc --filter ./caps.py -s

  3. Manage temporary image directories with PANDOCFILTER_CLEANUP

    master

    By default, filters using get_filename4code create a directory named ...-images in the current directory to cache temporary files. This directory is not automatically removed.

    To force the creation of a temporary directory that is removed at the end of execution, set the environment variable PANDOCFILTER_CLEANUP to any non-empty value (e.g., 1).

    export PANDOCFILTER_CLEANUP=1

  4. Configure diagram attributes using braced syntax

    master

    You can provide configuration options for diagrams (like caption and width) using braced syntax immediately following the code block identifier. This is useful for controlling how the diagram is rendered and captioned in the output.

    Example with options:

    blockdiag {
   A -> B -> C -> D;
   A -> E -> F -> G;
}

    DRY Tip: If you are using the braced syntax, you do not need to include the diagram type (e.g., blockdiag { ... }) inside the code block itself; you can just provide the diagram definition.

       A -> B -> C -> D;
   A -> E -> F -> G;

  5. Create seqdiag diagrams and control element order

    master

    Use seqdiag for sequence diagrams.

    Controlling Order: By default, seqdiag sorts elements by the order they appear. To explicitly define the order of participants (e.g., browser; database; webserver;), list them at the beginning of the seqdiag { ... } block.

    seqdiag {
  # define order of elements
  # seqdiag sorts elements by order they appear
  browser; database; webserver;

  browser  -> webserver [label = "GET /index.html"];
  browser <-- webserver;
  browser  -> webserver [label = "POST /blog/comment"];
              webserver  -> database [label = "INSERT comment"];
              webserver <-- database;
  browser <-- webserver;
}

  6. Create blockdiag diagrams in Markdown

    master

    You can embed blockdiag diagrams directly in Markdown using fenced code blocks. The filter supports standard ASCII characters as well as Unicode characters (e.g., Ä, ü, ö).

    To use the diagram type, specify it in the language identifier of the code block:

    blockdiag {
   A -> B -> C -> D;
   A -> E -> F -> G;
}

  7. Create nwdiag diagrams

    master

    Use nwdiag for network diagrams. It allows you to define networks and assign IP addresses to specific nodes within those networks.

    nwdiag {
  network dmz {
      address = "210.x.x.x/24"

      web01 [address = "210.x.x.1"];
      web02 [address = "210.x.x.2"];
  }
  network internal {
      address = "172.x.x.x/24";

      web01 [address = "172.x.x.1"];
      web02 [address = "172.x.x.2"];
      db01;
      db02;
  }
}

  9. Create actdiag diagrams

    master

    Use actdiag for activity diagrams. You can define lanes (e.g., lane user) to organize actions within the diagram.

      write -> convert -> image

  lane user {
     label = "User"
     write [label = "Writing reST"];
     image [label = "Get diagram IMAGE"];
  }
  lane actdiag {
     convert [label = "Convert reST to Image"];
  }

  10. Create packetdiag diagrams

    master

    Use packetdiag to visualize packet structures, such as TCP headers. You can define bit ranges (e.g., 0-15) and set global properties like colwidth and node_height.

      colwidth = 32
  node_height = 72

  0-15: Source Port
  16-31: Destination Port
  32-63: Sequence Number
  64-95: Acknowledgment Number
  96-99: Data Offset
  100-105: Reserved
  106: URG [rotate = 270]
  107: ACK [rotate = 270]
  108: PSH [rotate = 270]
  109: RST [rotate = 270]
  110: SYN [rotate = 270]
  111: FIN [rotate = 270]
  112-127: Window
  128-143: Checksum
  144-159: Urgent Pointer
  160-191: (Options and Padding)
  192-223: data [colheight = 3]

  11. Create a simple Pandoc filter with toJSONFilter

    master

    Most users only need toJSONFilter(action). This function generates a JSON-to-JSON filter that reads from stdin and writes to stdout.

    An action is a function with the signature action(key, value, format, meta):

    • key: The type of the pandoc object (e.g., 'Str', 'Para').
    • value: The contents of the object (e.g., a string for 'Str', a list of inline elements for 'Para').
    • format: The target output format.
    • meta: The document's metadata.

    Action Return Values:

    • None: The object remains unchanged.
    • pandoc object: Replaces the original object.
    • list of pandoc objects: Replaces the original object; the list is spliced into the parent. An empty list deletes the object.
    #!/usr/bin/env python

from pandocfilters import toJSONFilter, Str

def caps(key, value, format, meta):
  if key == 'Str':
    return Str(value.upper())

if __name__ == "__main__":
  toJSONFilter(caps)

  12. Pandoc and pandocfilters version compatibility

    master

    Due to changes in how Pandoc handles attributes, ensure you use the correct version of pandocfilters for your Pandoc version:

    • Pandoc 1.12–1.15: Use pandocfilters <= 1.2.4.
    • Pandoc >= 1.16: Use pandocfilters >= 1.3.0.
    • Pandoc 1.17.3+: pandocfilters 1.4.0 supports both old and new JSON formats.