mdsphinx

Convert markdown to any output format that Sphinx supports.

In contrast to something like pandoc, this tool is useful if you want to...

1. Use Jinja2 templating.
2. Use MyST Markdown syntax.
3. Use other Sphinx extensions.
4. Push Markdown to a Confluence page.

Installation

pipx install mdsphinx

Usage

1. Create a markdown file or directory with markdown files.
2. Run mdsphinx env create to create the default environment.
3. Optionally, create a conf.py.jinja file to customize the Sphinx conf.py.
4. Optionally, create a context.yml file with variables to be injected via Jinja2.
5. Run mdsphinx process <inp> --to <fmt> --using <preset> --as <out> to convert the markdown.

TLDR

mdsphinx env create
mdsphinx process input.md --to pdf --using latex

You can also process a directory of markdown files.

mdsphinx process ./inputs --to pdf --using latex --as output.pdf

Output Formats

There are a few different formats you can convert to:

mdsphinx process input.md --to pdf        --using latex
mdsphinx process input.md --to html       --using default
mdsphinx process input.md --to confluence --using single.page

Environments

The default environment installs the following packages:

• sphinx
• nbsphinx
• myst-parser
• sphinxcontrib-confluencebuilder

However, you can register any virtual environment you want to use as long as it contains sphinx.

mdsphinx env add --name my_custom_env --path /path/to/my_custom_env
mdsphinx process input.md --to pdf --using latex --env-name my_custom_env

Environments and metadata are stored in the $MDSPHINX_CONFIG_ROOT, which defaults to ~/.config/mdsphinx.

You can safely delete this directory at any time.

Jinja2 Templating

Create a file named context.yml parallel to the input file or directory.

a: 1
b: 2

You can then reference these variables in your markdown files.

{{ a }} + {{ b }} = {{ a + b }}

Support for Mermaid diagrams is available as a custom jinja2 block.

You must have docker installed and ideally be using the MyST parser.

{% mermaid -%}
ext: .png
mode: myst
scale: 3
width: 75
align: center
caption: |
    An example mermaid diagram!
diagram: |
    graph TD
        A --> B
        B --> C
        A --> C
{% endmermaid %}

Likewise, you can use the tikz block to render LaTeX diagrams.

You must have tectonic installed and ideally be using the MyST parser.

{% tikz -%}
ext: .png
mode: myst
diagram: |
    \documentclass[margin=0pt]{standalone}
    \usepackage{tikz}
    \begin{document}
    \begin{tikzpicture}
        \draw (0,0) -- (1,1);
    \end{tikzpicture}
    \end{document}
{% endtikz %}

Sphinx Configuration

Create a file named conf.py.jinja parallel to the input file or directory.

{% include main_sphinx_config %}

html_theme = "alabaster"

You can generate a copy of the default conf.py.jinja file.

mdsphinx generate conf.py.jinja

This file will be used by sphinx-quickstart to generate the Sphinx configuration file.

Confluence Configuration

The default Sphinx conf.py sets up a confluence connection by reading your ~/.netrc and environment variables.

Obtain an API token from your Atlassian account settings and configure your ~/.netrc file:

machine <confluence_server_url>
  login <confluence_server_user>
  password <confluence_api_token>

Create a parent page manually on your confluence space and configure the environment variables.

export CONFLUENCE_PUBLISH_DRYRUN="0"
export CONFLUENCE_SERVER_URL="https://example.atlassian.net/wiki"
export CONFLUENCE_SPACE_KEY="~MySpace"
export CONFLUENCE_PARENT_PAGE="ParentPage"
mdsphinx process input.md --to confluence --using single.page

LaTeX Configuration

The default LaTeX configuration is set up to use tectonic as the LaTeX engine.

However, you can set MDSPHINX_LATEX_COMMAND to be a ; delimited list of commands to run instead.

export MDSPHINX_LATEX_COMMAND="xelatex {tex}"