A simple mkdocs plugin, enable to sort nav by setting "weight" in markdown metadata
Project description
mkdocs-nav-weight
A simple mkdocs plugin, enables to organize Navigation in a more markdownic way.
This plugin tries to read markdown resources before mkdocs, which may add some performance overhead on building.
Usage
Three additional keys can be configured in Markdown Metadata ( also known as "front-matter", see metadata):
-
weight: number
- value: number, eg:
-1
,2.3
..., if unset, it goes0
. - like weight in Hugo but has some differences, used for ordering your sections/pages. Lower weight gets higher precedence. So content with lower weight will come first.
weight
in anindex
will be offered to its parentsection
, there is a fixed value for itself, and the value is configurable, see: index_weight.
- value: number, eg:
-
headless: bool
- value: bool,
true
orfalse
, if unset, it goesfalse
. - like headless in Hugo, pages/sections with
headless: true
will be hidden from nav, but these contents will still be rendered and accessible via URL. headless
in anindex
will be offered to its parentsection
, too
- value: bool,
-
section: bool
- value: bool,
true
orfalse
, if unset, it goesfalse
. - For
index
only. - If there is an
index
only used to offer metadata for its parentsection
and without any meaningful content, settingsection
totrue
can help you to hide thisindex
itself.
- value: bool,
Installation
Install with pip
:
pip install mkdocs-nav-weight
Add the following lines to mkdocs.yml
plugins:
- search
- mkdocs-nav-weight
Options
Setting in mkdocs.yml
:
plugins:
- search
- mkdocs-nav-weight:
section_renamed: false
index_weight: -10
warning: true
reverse: false
section_renamed
Default: false
:
-
If
true
, section name will use thetitle
of itsindex
instead of the folder name. -
For compatibility we have to name a folder like "C#" as "CSharp", but what we actually want is "C#" , that's what this option does
index_weight
Default: -10
:
- The
weight
value forindex
itself, to ensure it's always the first at the same level
warning
Default: true
:
- Controls whether to send a
Warning
when invalid values are detected in markdown metadata
reverse
- If
true
, sort nav byweight
from largest to smallest.
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 mkdocs_nav_weight-0.0.5-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | ee4aa78a9b99f95d16530d0a44a6999b409f54e2733a5232fc6fae177bc87eac |
|
MD5 | 8126c5aa0ee43589d83fa4c868191311 |
|
BLAKE2b-256 | fa47d45f696804692e9cb7d7cdf98ad5a8395abb2c8d953b4bf738d5fd136d66 |