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 Sphinx configuration. - Optionally, create a
context.yml
file with variables to be injected via Jinja2. - Run
mdsphinx process <inp> --to <out> --using <preset> --as <out>
to convert the markdown to the desired output format.
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
Jinja2 Templating
You can inject values into your markdown files using Jinja2 templating.
Simply 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 }}
Sphinx Configuration
You can alter the default Sphinx conf.py
file generated by sphinx-quickstart
by adding 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
Confluence Configuration
The default Sphinx conf.py
tries to set 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 > env |
CONFLUENCE_SERVER_USER |
example@gmail.com |
confluence_api_token |
netrc[url].password |
CONFLUENCE_API_TOKEN |
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 set your environment variables before running
mdsphinx
:
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.