Custom heading IDs for Foliant.
Project description
С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
$ pip install foliantcontrib.customids
Usage
To enable the preprocessor, add customids
to preprocessors
section in the project config:
preprocessors:
- customids
The preprocessor supports the following options:
- 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:
# 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:
<div class="custom_id_anchor_container custom_id_anchor_container_level_1"><div id="custom_id_for_first_heading" class="custom_id_anchor custom_id_anchor_level_1"></div></div>
<h1>First Heading</h1>
<p>A paragraph.</p>
<div class="custom_id_anchor_container custom_id_anchor_container_level_2"><div id="custom_id_for_second_heading" class="custom_id_anchor custom_id_anchor_level_2"></div></div>
<h2>Second Heading</h2>
<p>Some another paragraph.</p>
(Note that CustomIDs preprocessor does not convert Markdown syntax into HTML; it only inserts HTML tags <div class="custom_id_anchor_container">...</div>
into Markdown code.)
Custom IDs must not contain spaces and non-ASCII characters.
Examples of hyperlinks that refer to custom IDs:
[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)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for foliantcontrib.customids-1.0.8.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 25df85045c73617abd21b73553c4a74f6ab689eb7445b92e3285a6ab86bea284 |
|
MD5 | 71fdd967c14f82ab0b5668cd429866ec |
|
BLAKE2b-256 | 7fe98d6fc77d4ef842038f7b0eddb30a8e1c49255a2c2f124416939b791cb07e |
Hashes for foliantcontrib.customids-1.0.8-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 09db12425f11c3cfc96554a92f5e6d067de6cae19bd4efc18cccf622707c3ba3 |
|
MD5 | 9ea6a7ed7df5e891bdeb873527e4dfcd |
|
BLAKE2b-256 | 1eb61f4b0ca6a01120eb0cbb6485a9192c27eaf7b735c30dd529e12f97117f87 |