markdown-meta-extension 0.5.2

Markdown Meta Extension for using Python functions and classes from within documents.

Markdown Meta Extension

The Markdown Meta Extension, a Python-Markdown extension, enables users to use Python functions and classes from within Markdown documents and assign results to variables.

This software has been created by Martin Schorfmann (@schorfma) for his bachelor thesis at the Universität Bremen with the following title:

Markdown Meta Extension: Providing programmable Content in Markdown Documents

Getting Started

Prerequisites

You need to have a working installation of

• Python ≥ 3.7.0

Installation

Install from PyPI

Execute the following command to install the Markdown Meta Extension from PyPI.

$ pip install markdown-meta-extension

Install from the GitLab repository

Execute the following command to install the Markdown Meta Extension from this Git repository.

$ pip install git+https://gitlab.com/markdown-meta-extension/markdown-meta-extension.git

Install from downloaded source

Execute the following command in the main directory of the downloaded repository for manual installation of Markdown Meta Extension.

$ pip install .

Usage

Usage as Python-Markdown extension

The extension name for use with Python-Markdown is markdown_meta_extension.

The extension can be used with Python-Markdown as follows:

import markdown

parser = markdown.Markdown(extensions=["markdown_meta_extension"])
# Convert a Markdown Meta Extension string
parser.convert("""
---
now: datetime:datetime.now
---

{{ now }}
""")

Usage of the CLI command

1. Navigate to the directory the document is in.
2. Install requirements of custom Python modules, if needed.
3. Convert the document using the command markdown-meta-extension

$ cd ./example
$ pip install -r requirements.txt
$ markdown-meta-extension ./document.md --yes
Output path document.html is assumed.
3 callables were imported.
19 calls were made.
File document.html will be overwritten.
Output written to file document.html

Available options

$ markdown-meta-extension --help
Usage: markdown-meta-extension [OPTIONS] INPUT_PATH

  CLI command for converting an input Markdown file to an output HTML file.

  [...]

Options:
  -o, --output PATH  The optional path for the HTML output.
  -q, --quiet        Mute all command line output.
  -v, --verbose      Display additional command line output and file contents.
  -y, --yes          Confirm overwriting existing output file.
  --help             Show this message and exit.

Tutorial

Import Front Matter

The Markdown document needs to start with a YAML front matter, in which the import statements are assigned to variables:

---
Date: datetime:date                     # Import of class from an installed package
now: datetime:datetime.now              # Import of a class method
echo: ./echo_module.py:echo_function    # Import of a function from a file system module
demo: ./jinja_template.html:demo_macro  # Import of a Jinja macro from a Jinja HTML Template
---

The import statements use a : to separate the top-level package or file name from the remaining import statement.

For relative import paths the current working directory (where the command is executed) is the base for the relative paths.

The possible import types are the following:

• Installed Python package
  • Any defined variable or callable
• Python module in file system
  • Any defined variable or callable
• Jinja HTML template
  • Jinja Macro defined in template

Outsourcing Common Imports

import:
- ../base_imports.yaml
- ./more_specific_imports.yaml
echo: ./echo_module.py:echo_function

It is possible to outsource commonly used imports into dedicated YAML files. The outsourced imports are imported in order, potentially overwriting duplicate keys with the import defined the later file or the front matter itself.

Call Blocks

Call blocks are used to invoke a callable with potential parameters. Any import key or variable can be either directly invoked or subscripted to invoke a method or attribute. The parameters can be either a YAML list or mapping. If no parameters are needed they can be omitted entirely.

If no assignment to a variable is made, the result gets displayed unless the invocation returns an empty result. When assigning the result to a variable, a Force Display Flag (!) is needed to display the result.

{{! variable_name = ClassName.class_method_name
argument: value
}}

Calling a function without parameters

{{ now }}

Calling a function with parameters

Block with list parameters:

{{ echo
- My Message
}}

Inline with list parameters:

{{ echo [My Message] }}

Block with mapping parameters:

{{ echo
message: My Message
}}

Inline with mapping parameters:

{{ echo {message: My Message} }}

Instantiating a class

{{! board = ChessBoard }}

{{ board.move
move: a2a4
}}

Nesting

Call blocks can be nested if needed. It is important, that they are explicitly marked as strings in YAML

{{ sum
- 42
- "{{ my_number }}"
}}

Variable Blocks

Variable blocks allow for defining multiple variables in one block.

{{
number: 42
quote: |
  First Line.
  Second Line.
pi: "{{ get_pi }}"
budget: |
  {{ money
  value: 12.34
  currency: EUR
  }}
}}

Standalone Documents

Standalone documents are used to insert the result document in a Jinja template together with additional meta data variables.

---
meta-data:
  template: ./template.html
  title: The Title
  author: The Author
today: datetime:date.today
# ...

Outsourced Meta Data Imports

The outsourcing of meta data follows the same rules like the outsourcing of imports.

meta-data-import:
- ../base-information.yaml
- ./external-data.yaml
meta-data:
  title: Another Title
today: datetime:date.today
# ...

Behavior

If an object has an __html__() method, it is used as a representation. The string representation __str__()is used as a fallback.

The syntax to access attributes and methods can also be used to access the __getitem__() builtin method.

Some data types have a default display behavior. For example lists of items are displayed as an HTML unordered list when used in a block, and as comma-separated values when used inline.

Examples

Seven examples have been implemented in the subdirectories of the directory examples

Used Libraries

Without these libraries the development of the Markdown Meta Extension would not have been possible. Thanks to their authors and contributors!

• Python-Markdown
• Click
• Jinja
• MarkupSafe
• PyYAML
• pathvalidate

Libraries used in Tests

• beautifulsoup4
• lxml
• parse