Metadata-Version: 2.1
Name: mdsphinx
Version: 1.1.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.

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

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

