Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bjoernricks/mdit-py-toc
A table of contents (TOC) plugin for markdown-it-py
https://github.com/bjoernricks/mdit-py-toc
Last synced: about 1 month ago
JSON representation
A table of contents (TOC) plugin for markdown-it-py
- Host: GitHub
- URL: https://github.com/bjoernricks/mdit-py-toc
- Owner: bjoernricks
- License: mit
- Created: 2024-02-02T08:22:00.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2024-03-25T14:08:33.000Z (8 months ago)
- Last Synced: 2024-04-25T18:43:36.752Z (7 months ago)
- Language: Python
- Size: 125 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# mdit-py-toc
A table of contents (TOC) plugin for [markdown-it-py](https://markdown-it-py.readthedocs.io/en/latest/)
based on [markdown-it-toc-done-right](https://github.com/nagaozen/markdown-it-toc-done-right).
- [Installation](#installation)
- [Install using poetry](#install-using-poetry)
- [Install using pip](#install-using-pip)
- [Options](#options)
- [Usage](#usage)
## Installation
### Install using poetry
Because **mdit-py-toc** is a plugin, you most likely need a tool to
handle Python package dependencies and Python environments. Therefore we
strongly recommend using [poetry].
You can install the latest stable release and add it as a dependency for your
current project using [poetry]
```
poetry add mdit-py-toc
```
### Install using pip
> [!NOTE]
> The `pip install` command does no longer work out-of-the-box in newer
> distributions like Ubuntu >= 23.04 because of [PEP 668](https://peps.python.org/pep-0668).
You can install the latest stable release from the Python Package Index (pypi)
using [pip]
```
python -m pip install mdit-py-toc
```
## Options
| Name | Description | Default |
| --------- | ---------------------------------------------------------------------- | --------------------- |
| pattern | The pattern serving as the TOC placeholder in your markdown | `r"^(\[TOC\]")` |
| level | Heading level to apply anchors on or iterable of selected levels | `(1, 2)` |
| list_type | Type of list (`"ul"` for unordered, `"ol"` for ordered) | `"ul"` |
| slug_func | Function to convert heading title text to id slugs for link references | `mdit_py_toc.slugify` |
## Usage
`mdit-py-toc` works best in conjunction with the [anchors plugin](https://mdit-py-plugins.readthedocs.io/en/latest/#heading-anchors).
```python
from markdown_it import MarkdownIt
from mdit_py_plugins.anchors import anchors_plugin
from mdit_py_toc import toc_plugin, slugify
md = (
MarkdownIt()
.use(anchors_plugin, permalink=True, slug_func=slugify)
.use(toc_plugin, list_type="ol")
)
markdown = """
# A Page
[TOC]
## Section 1
## Section 2
"""
html = md.render(markdown)
```
Creates the following HTML output
```
A Page ¶
Section 1 ¶
Section 2 ¶
```
[poetry]: https://python-poetry.org/
[pip]: https://pip.pypa.io/