# [mdsphinx](https://pypi.org/project/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
```bash
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
```bash
mdsphinx env create
mdsphinx process input.md --to pdf --using latex
```
You can also process a directory of markdown files.
```bash
mdsphinx process ./inputs --to pdf --using latex --as output.pdf
```
## Output Formats
There are a few different formats you can convert to:
```bash
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`.
```bash
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.
```yaml
a: 1
b: 2
```
You can then reference these variables in your markdown files.
```markdown
{{ 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.
```jinja2
{% 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.
```jinja2
{% 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.
```jinja2
{% include main_sphinx_config %}
html_theme = "alabaster"
```
You can generate a copy of the default `conf.py.jinja` file.
```bash
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:
```plaintext
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.
```bash
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.
```bash
export MDSPHINX_LATEX_COMMAND="xelatex {tex}"
```
Raw data
{
"_id": null,
"home_page": "https://github.com/AdamGagorik/mdsphinx",
"name": "mdsphinx",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.12",
"maintainer_email": null,
"keywords": null,
"author": "Adam Gagorik",
"author_email": "adam.gagorik@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/af/f2/904892f78d898fe6f7ccb8de78cae2cea3f08a95c51e7c1e52b532153210/mdsphinx-1.8.0.tar.gz",
"platform": null,
"description": "# [mdsphinx](https://pypi.org/project/mdsphinx)\n\nConvert markdown to any output format that Sphinx supports.\n\nIn contrast to something like pandoc, this tool is useful if you want to...\n\n1) Use Jinja2 templating.\n2) Use MyST Markdown syntax.\n3) Use other Sphinx extensions.\n4) Push Markdown to a Confluence page.\n\n## Installation\n\n```bash\npipx install mdsphinx\n```\n\n## Usage\n\n1. Create a markdown file or directory with markdown files.\n2. Run `mdsphinx env create` to create the default environment.\n3. Optionally, create a `conf.py.jinja` file to customize the Sphinx `conf.py`.\n4. Optionally, create a `context.yml` file with variables to be injected via Jinja2.\n5. Run `mdsphinx process <inp> --to <fmt> --using <preset> --as <out>` to convert the markdown.\n\n### TLDR\n\n```bash\nmdsphinx env create\nmdsphinx process input.md --to pdf --using latex\n```\n\nYou can also process a directory of markdown files.\n\n```bash\nmdsphinx process ./inputs --to pdf --using latex --as output.pdf\n```\n\n## Output Formats\n\nThere are a few different formats you can convert to:\n\n```bash\nmdsphinx process input.md --to pdf --using latex\nmdsphinx process input.md --to html --using default\nmdsphinx process input.md --to confluence --using single.page\n```\n\n## Environments\n\nThe default environment installs the following packages:\n\n- `sphinx`\n- `nbsphinx`\n- `myst-parser`\n- `sphinxcontrib-confluencebuilder`\n\nHowever, you can register any virtual environment you want to use as long as it contains `sphinx`.\n\n```bash\nmdsphinx env add --name my_custom_env --path /path/to/my_custom_env\nmdsphinx process input.md --to pdf --using latex --env-name my_custom_env\n```\n\nEnvironments and metadata are stored in the `$MDSPHINX_CONFIG_ROOT`, which defaults to `~/.config/mdsphinx`.\n\n> You can safely delete this directory at any time.\n\n## Jinja2 Templating\n\nCreate a file named `context.yml` parallel to the input file or directory.\n\n```yaml\na: 1\nb: 2\n```\n\nYou can then reference these variables in your markdown files.\n\n```markdown\n{{ a }} + {{ b }} = {{ a + b }}\n```\n\nSupport for Mermaid diagrams is available as a custom `jinja2` block.\n\n> You must have `docker` installed and ideally be using the `MyST` parser.\n\n```jinja2\n{% mermaid -%}\next: .png\nmode: myst\nscale: 3\nwidth: 75\nalign: center\ncaption: |\n An example mermaid diagram!\ndiagram: |\n graph TD\n A --> B\n B --> C\n A --> C\n{% endmermaid %}\n```\n\nLikewise, you can use the `tikz` block to render LaTeX diagrams.\n\n> You must have `tectonic` installed and ideally be using the `MyST` parser.\n\n```jinja2\n{% tikz -%}\next: .png\nmode: myst\ndiagram: |\n \\documentclass[margin=0pt]{standalone}\n \\usepackage{tikz}\n \\begin{document}\n \\begin{tikzpicture}\n \\draw (0,0) -- (1,1);\n \\end{tikzpicture}\n \\end{document}\n{% endtikz %}\n```\n\n## Sphinx Configuration\n\nCreate a file named `conf.py.jinja` parallel to the input file or directory.\n\n```jinja2\n{% include main_sphinx_config %}\n\nhtml_theme = \"alabaster\"\n```\n\nYou can generate a copy of the default `conf.py.jinja` file.\n\n```bash\nmdsphinx generate conf.py.jinja\n````\n\nThis file will be used by `sphinx-quickstart` to generate the Sphinx configuration file.\n\n## Confluence Configuration\n\nThe default Sphinx `conf.py` sets up a confluence connection by reading your `~/.netrc` and environment variables.\n\n| Sphinx `conf.py` Variable | Default Source | Environment Variable Name | Example Value |\n|-----------------------------|-----------------------|-----------------------------|--------------------------------------|\n| `confluence_publish_dryrun` | `env` | `CONFLUENCE_PUBLISH_DRYRUN` | `1` |\n| `confluence_server_url` | `env` | `CONFLUENCE_SERVER_URL` | `https://example.atlassian.net/wiki` |\n| `confluence_server_user` | `netrc[url].login` | | `example@gmail.com` |\n| `confluence_api_token` | `netrc[url].password` | | `api-token` |\n| `confluence_space_key` | `env` | `CONFLUENCE_SPACE_KEY` | `~MySpace` |\n| `confluence_parent_page` | `env` | `CONFLUENCE_PARENT_PAGE` | `ParentPage` |\n\nObtain an API token from your Atlassian account settings and configure your `~/.netrc` file:\n\n```plaintext\nmachine <confluence_server_url>\n login <confluence_server_user>\n password <confluence_api_token>\n```\n\nCreate a parent page manually on your confluence space and configure the environment variables.\n\n```bash\nexport CONFLUENCE_PUBLISH_DRYRUN=\"0\"\nexport CONFLUENCE_SERVER_URL=\"https://example.atlassian.net/wiki\"\nexport CONFLUENCE_SPACE_KEY=\"~MySpace\"\nexport CONFLUENCE_PARENT_PAGE=\"ParentPage\"\nmdsphinx process input.md --to confluence --using single.page\n```\n\n## LaTeX Configuration\n\nThe default LaTeX configuration is set up to use `tectonic` as the LaTeX engine.\n\nHowever, you can set `MDSPHINX_LATEX_COMMAND` to be a `;` delimited list of commands to run instead.\n\n```bash\nexport MDSPHINX_LATEX_COMMAND=\"xelatex {tex}\"\n```\n",
"bugtrack_url": null,
"license": "WTFPL",
"summary": "Convert markdown to any output that Sphinx supports",
"version": "1.8.0",
"project_urls": {
"Homepage": "https://github.com/AdamGagorik/mdsphinx",
"Repository": "https://github.com/AdamGagorik/mdsphinx"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "befc32cdf4c5ee58de871c884b2e4d9602f639f31cef9ca33de630237c8b2b99",
"md5": "ba330c62a19ee87797a25791c46fece8",
"sha256": "e0c2cf73a62f1cb5459e69be454bdcf6b40eb602e88ed75bee3fae608c598793"
},
"downloads": -1,
"filename": "mdsphinx-1.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ba330c62a19ee87797a25791c46fece8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.12",
"size": 16848,
"upload_time": "2024-10-06T00:44:09",
"upload_time_iso_8601": "2024-10-06T00:44:09.633059Z",
"url": "https://files.pythonhosted.org/packages/be/fc/32cdf4c5ee58de871c884b2e4d9602f639f31cef9ca33de630237c8b2b99/mdsphinx-1.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "aff2904892f78d898fe6f7ccb8de78cae2cea3f08a95c51e7c1e52b532153210",
"md5": "03386a97c38c1f65e4bcd8beb0ff4449",
"sha256": "0a6977cb85e9f5d0defa505ae576fa0ab8898157a40b9516ed0678363564eda7"
},
"downloads": -1,
"filename": "mdsphinx-1.8.0.tar.gz",
"has_sig": false,
"md5_digest": "03386a97c38c1f65e4bcd8beb0ff4449",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.12",
"size": 14310,
"upload_time": "2024-10-06T00:44:11",
"upload_time_iso_8601": "2024-10-06T00:44:11.775196Z",
"url": "https://files.pythonhosted.org/packages/af/f2/904892f78d898fe6f7ccb8de78cae2cea3f08a95c51e7c1e52b532153210/mdsphinx-1.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-06 00:44:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AdamGagorik",
"github_project": "mdsphinx",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mdsphinx"
}
JSON
