Metadata-Version: 2.1
Name: mdsphinx
Version: 1.2.0
Summary: Convert markdown to any output that Sphinx supports
Home-page: https://github.com/AdamGagorik/mdsphinx
License: WTFPL
Author: Adam Gagorik
Author-email: adam.gagorik@gmail.com
Requires-Python: >=3.12,<4.0
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Dist: jinja2 (>=3.1.4,<4.0.0)
Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
Requires-Dist: typer (>=0.12.3,<0.13.0)
Project-URL: Repository, https://github.com/AdamGagorik/mdsphinx
Description-Content-Type: text/markdown

# 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 configuration.
4. Optionally, create a `context.yml` file with variables to be injected via Jinja2.
5. Run `mdsphinx process <inp> --to <out> --using <preset> --as <out>` to convert the markdown to the desired output format.

```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
```

## 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.

```yaml
a: 1
b: 2
```

You can then reference these variables in your markdown files.

```markdown
{{ 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.

```jinja2
{% 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:

```plaintext
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`:

```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}"
```

