Package: markdown-meta-extension
Markdown Meta ExtensionTheMarkdown Meta Extension, aPython-Markdownextension, enables users to usePythonfunctions and classes from withinMarkdowndocuments and assign results to variables.This software has been created byMartin Schorfmann(@schorfma) for his bachelor thesis at theUniversität Bremenwith the following title:Markdown Meta Extension: Providing programmable Content in Markdown DocumentsGetting StartedPrerequisitesYou need to have a working installation ofPython≥3.7.0InstallationInstall from PyPIExecute the following command to install theMarkdown Meta ExtensionfromPyPI.$pipinstallmarkdown-meta-extensionInstall from the GitLab repositoryExecute the following command to install theMarkdown Meta Extensionfrom thisGitrepository.$pipinstallgit+https://gitlab.com/markdown-meta-extension/markdown-meta-extension.gitInstall from downloaded sourceExecute the following command in the main directory of the downloaded repository for manual installation ofMarkdown Meta Extension.$pipinstall.UsageUsage asPython-MarkdownextensionThe extension name for use withPython-Markdownismarkdown_meta_extension.The extension can be used withPython-Markdownas follows:importmarkdownparser=markdown.Markdown(extensions=["markdown_meta_extension"])# Convert a Markdown Meta Extension stringparser.convert("""---now: datetime:datetime.now---{{ now }}""")Usage of theCLIcommandNavigate to the directory the document is in.Install requirements of customPythonmodules, if needed.Convert the document using the commandmarkdown-meta-extension$cd./example
$pipinstall-rrequirements.txt
$markdown-meta-extension./document.md--yes
Outputpathdocument.htmlisassumed.3callableswereimported.19callsweremade.
Filedocument.htmlwillbeoverwritten.
Outputwrittentofiledocument.htmlAvailable options$markdown-meta-extension--help
Usage:markdown-meta-extension[OPTIONS]INPUT_PATHCLIcommandforconvertinganinputMarkdownfiletoanoutputHTMLfile.[...]Options:-o,--outputPATHTheoptionalpathfortheHTMLoutput.-q,--quietMuteallcommandlineoutput.-v,--verboseDisplayadditionalcommandlineoutputandfilecontents.-y,--yesConfirmoverwritingexistingoutputfile.--helpShowthismessageandexit.TutorialImport Front MatterTheMarkdowndocument needs to start with aYAMLfront matter, in which the import statements are assigned to variables:---Date:datetime:date# Import of class from an installed packagenow:datetime:datetime.now# Import of a class methodecho:./echo_module.py:echo_function# Import of a function from a file system moduledemo:./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:InstalledPythonpackageAny defined variable or callablePythonmodule in file systemAny defined variable or callableJinjaHTMLtemplateJinjaMacro defined in templateOutsourcing Common Importsimport:-../base_imports.yaml-./more_specific_imports.yamlecho:./echo_module.py:echo_functionIt is possible to outsource commonly used imports into dedicatedYAMLfiles.
The outsourced imports are imported in order, potentially overwriting duplicate keys with the import defined the later file or the front matter itself.Call BlocksCall 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 aYAMLlist 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, aForce 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 parametersBlock 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
}}NestingCall blocks can be nested if needed. It is important, that they are explicitly marked as strings inYAML{{ sum-42-"{{ my_number }}"
}}Variable BlocksVariable 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 DocumentsStandalone documents are used to insert the result document in aJinjatemplate together with additional meta data variables.---meta-data:template:./template.htmltitle:The Titleauthor:The Authortoday:datetime:date.today# ...Outsourced Meta Data ImportsThe outsourcing of meta data follows the same rules like the outsourcing of imports.meta-data-import:-../base-information.yaml-./external-data.yamlmeta-data:title:Another Titletoday:datetime:date.today# ...BehaviorIf 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 anHTMLunordered list when used in a block, and as comma-separated values when used inline.ExamplesSeven examples have been implemented in the subdirectories of the directoryexamplesUsed LibrariesWithout these libraries the development of theMarkdown Meta Extensionwould not have been possible. Thanks to their authors and contributors!Python-MarkdownClickJinjaMarkupSafePyYAMLpathvalidateLibraries used in Testsbeautifulsoup4lxmlparse