Convert markdown to any output that Sphinx supports
Project description
mdsphinx
Convert markdown to any output format that Sphinx supports.
In contrast to something like pandoc, this tool is useful if you want to...
- Use Jinja2 templating.
- Use MyST Markdown syntax.
- Use other Sphinx extensions.
- Push Markdown to a Confluence page.
Installation
pipx install mdsphinx
Usage
- Create a markdown file or directory with markdown files.
- Run
mdsphinx env create
to create the default environment. - Optionally, create a
conf.py.jinja
file to customize the Sphinxconf.py
. - Optionally, create a
context.yml
file with variables to be injected via Jinja2. - 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 theMyST
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 theMyST
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.
Sphinx conf.py Variable |
Default Source | Environment Variable Name | Example Value |
---|---|---|---|
confluence_publish_dryrun |
env |
CONFLUENCE_PUBLISH_DRYRUN |
1 |
confluence_server_url |
env |
CONFLUENCE_SERVER_URL |
https://example.atlassian.net/wiki |
confluence_server_user |
netrc[url].login |
example@gmail.com |
|
confluence_api_token |
netrc[url].password |
api-token |
|
confluence_space_key |
env |
CONFLUENCE_SPACE_KEY |
~MySpace |
confluence_parent_page |
env |
CONFLUENCE_PARENT_PAGE |
ParentPage |
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}"
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.