Convert markdown to any output that Sphinx supports
Project description
mdsphinx
Convert markdown to any output format that Sphinx supports.
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>
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
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"
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
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.