Skip to main content

Utils for converting headers to anchors for different backends

Project description


HeaderAnchors is a module which converts heading titles into IDs just like it is done by specific backends.

Module exports three main functions:

  • to_id which converts a title into an ID by the rules of specific backend,
  • make_unique which adds a digit to make duplicate heading ID unique, according to the rules of specific backend.
  • is_flat which determines whether backend uses flatten preprocessor or not.


All Foliant backends add anchors to each heading to make it possible to reference headings in URLs. The problem is that each backend has its own way to do that. For example, the heading My wife's birthday-party will get an ID my-wifes-birthday-party in Pandoc, header-my-wife’s-birthday-party in aglio and my-wife-39-s-birthday-party in slate.

Moreover, different backends have different ways to deal with duplicate IDs. Utils in this module help you cope with these problems.


To use functions from this module, first install it with command

pip3 install foliantcontrib.utils.header_anchors

Then import the main functions:

>>> from foliant.preprocessors.utils.header_anchors import to_id, make_unique, is_flat


Feed a header title to the to_id function to get the proper id for each backend:

>>> title = "My wife's birthday-party"
>>> to_id(title, 'pandoc')
>>> to_id(title, 'aglio')
>>> to_id(title, 'slate')

If the name of the backend is not recognized, pandoc will be used as a fallback backend:

>>> to_id(title, 'nonexistent backend')


If some headers in the document have the same title or their IDs match, each backend transforms the ID for it to remain unique. Pandoc adds subsequent numbers with a hyphen, MkDocs — numbers with an unerscore.

make_unique function handles the proper transformations for you. Feed it an id, backend name and number of occurrences of this title in the document to get the proper unique id:

>>> make_unique('my-title', 3, 'pandoc')
>>> make_unique('my-title', 3, 'mkdocs')
>>> make_unique('my-title', 3, 'slate')

If the name of the backend is not recognized, pandoc will be used as a fallback backend:

>>> make_unique('my-title', 3, 'nonexistent backend')


is_flat function takes the backend name as parameter and returns True if backend uses flatten preprocessor to make a single file out of all chapters.

>>> is_flat('pandoc')
>>> is_flat('mkdocs')

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for foliantcontrib.utils.header-anchors, version 1.0.1
Filename, size File type Python version Upload date Hashes
Filename, size foliantcontrib.utils.header_anchors-1.0.1-py3-none-any.whl (5.5 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size foliantcontrib.utils.header_anchors-1.0.1.tar.gz (4.4 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page