https://github.com/foliant-docs/foliantcontrib.customids
Custom heading ID's for Foliant.
https://github.com/foliant-docs/foliantcontrib.customids
Last synced: 5 months ago
JSON representation
Custom heading ID's for Foliant.
- Host: GitHub
- URL: https://github.com/foliant-docs/foliantcontrib.customids
- Owner: foliant-docs
- License: mit
- Created: 2018-03-27T09:55:32.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2023-10-09T13:26:23.000Z (over 2 years ago)
- Last Synced: 2025-09-28T00:22:53.778Z (9 months ago)
- Language: Python
- Size: 30.3 KB
- Stars: 1
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: changelog.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://pypi.org/project/foliantcontrib.customids/) [](https://github.com/foliant-docs/foliantcontrib.customids)
# СustomIDs
CustomIDs is a preprocessor that allows to define custom identifiers (IDs) for headings in Markdown source by using Pandoc-style syntax in projects built with MkDocs or another backend that provides HTML output. These IDs may be used in hyperlinks that refer to a specific part of a page.
## Installation
```bash
$ pip install foliantcontrib.customids
```
## Usage
To enable the preprocessor, add `customids` to `preprocessors` section in the project config:
```yaml
preprocessors:
- customids
```
The preprocessor supports the following options:
```yaml
- customids:
stylesheet_path: !path customids.css
targets:
- pre
- mkdocs
- site
- ghp
```
`stylesheet_path`
: Path to the CSS stylesheet file. This stylesheet should define rules for `.custom_id_anchor_container`, `.custom_id_anchor_container_level_N`, `.custom_id_anchor`, and `.custom_id_anchor_level_N` classes. Here `N` is the heading level (`1` to `6`). Default path is `customids.css`. If stylesheet file does not exist, default built-in stylesheet will be used.
`targets`
: Allowed targets for the preprocessor. If not specified (by default), the preprocessor applies to all targets.
Custom ID may be specified after a heading content at the same line. Examples of Markdown syntax:
```markdown
# First Heading {#custom_id_for_first_heading}
A paragraph.
## Second Heading {#custom_id_for_second_heading}
Some another paragraph.
```
This Markdown source will be finally transformed into the HTML code:
```html
First Heading
A paragraph.
Second Heading
Some another paragraph.
```
(Note that CustomIDs preprocessor does not convert Markdown syntax into HTML; it only inserts HTML tags `
...` into Markdown code.)
Custom IDs must not contain spaces and non-ASCII characters.
Examples of hyperlinks that refer to custom IDs:
```markdown
[Link to Heading 1](#custom_id_for_first_heading)
[Link to Heading 2 in some document at the current site](/some/page/#custom_id_for_second_heading)
[Link to some heading with custom ID at an external site](https://some.site/path/to/the/page/#some_custom_id)
```