Metadata-Version: 2.4
Name: zendoc
Version: 0.1.0
Summary: A family of Python-Markdown extensions for section cross-references and bibliography/citation handling
Project-URL: Homepage, https://github.com/buckwem/zendoc-extension
Project-URL: Issues, https://github.com/buckwem/zendoc-extension/issues
Author: Mark Buckwell
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.10
Requires-Dist: markdown>=3.4
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: types-markdown; extra == 'dev'
Provides-Extra: docs
Requires-Dist: zensical; extra == 'docs'
Description-Content-Type: text/markdown

# zendoc

A family of [Python-Markdown](https://python-markdown.github.io/) extensions
for section cross-references and bibliography/citation handling, in the
spirit of [pymdown-extensions](https://facelessuser.github.io/pymdown-extensions/):
each extension is independent and enabled separately. Factored out of
[zendoc-template](https://github.com/buckwem/zendoc-template) so it can be
installed and reused independently of that template.

> **Status:** early - `zendoc.headings` and `zendoc.refs` are implemented;
> citation handling isn't yet. See
> [zendoc-template#25](https://github.com/buckwem/zendoc-template/issues/25)
> for the tracking issue and scope.

**[Full documentation](https://buckwem.github.io/zendoc-extension/)**

## Installation

```bash
pip install zendoc
```

## Extensions

| Extension | Description |
|---|---|
| [`zendoc.headings`](https://buckwem.github.io/zendoc-extension/extensions/headings/) | Gives every heading an id and a hierarchical section number ("1", "1.1", "1.2", "2", ...). |
| [`zendoc.refs`](https://buckwem.github.io/zendoc-extension/extensions/refs/) | `\ref{id}` section cross-references, resolving to the target's current number - similar in spirit to LaTeX's `\ref`. |

```python
import markdown

html = markdown.markdown(text, extensions=["zendoc.headings", "zendoc.refs"])
```

```md
# Introduction {: #intro }

See \ref{intro} for background.
```

`\ref{intro}` resolves to a link reading `1` - the heading's current
section number - and stays correct if sections are reordered, since
numbering is recomputed on every conversion. See the
[docs](https://buckwem.github.io/zendoc-extension/) for options, multi-page
registry sharing, and full syntax details.

## Development

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest
```

To build the documentation locally:

```bash
pip install -e ".[docs]"
zensical serve
```

## License

MIT - see [LICENSE](LICENSE).
