# 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
Four additional keys can be configured in Markdown Metadata ( also known as "front-matter", see [metadata](https://www.mkdocs.org/user-guide/writing-your-docs/#meta-data)).
- `weight: number`
- **Value: number, eg: `-1`, `2.3` ..., if unset, it goes `0`**.
- 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 an `index` will be offered to its parent `section`**, there is a fixed value for itself, and the value is configurable, see: [`index_weight`](#index_weight).
- `headless: bool`
- **Value: bool, `true` or `false`, if unset, it goes `false`**.
- 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 an `index` will be offered to its parent `section`**.
**For `index` only:**
- `retitled: bool`
- **Value: bool, `true` or `false`, if unset, it goes `false`**.
- A metadata version of [`section_renamed`](#section_renamed) which only applies this `index`'s title to its parent `section`, **it only works when `section_renamed` is `false`**.
- `empty: bool`
- **Value: bool, `true` or `false`, if unset, it goes `false`**.
- If there is an `index` only used to offer metadata for its parent `section` and without any meaningful content, setting `empty` to `true` can help you to hide this `index` itself.
## Installation
Install with `pip`:
```shell
pip install mkdocs-nav-weight
```
Add the following lines to `mkdocs.yml`
```yaml
plugins:
- search
- mkdocs-nav-weight
```
## Options
Configure in `mkdocs.yml`:
```yaml
plugins:
- search
- mkdocs-nav-weight:
section_renamed: false
index_weight: -10
warning: true
reverse: false
headless_included: false
```
#### `section_renamed`
Default: `false`:
- If `true`, section name will use the `title` of its `index` 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 for `index` 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`
Default: `false`:
- If `true`, sort nav by `weight` from largest to smallest.
#### `headless_included`
Default: `false`:
- An option to control whether `headless` pages should be included in `nav.pages` which is used by some plugins, eg: [mkdocs-pdf-export-plugin](https://github.com/zhaoterryy/mkdocs-pdf-export-plugin).
- If `true`, `headless` pages will be included.
Raw data
{
"_id": null,
"home_page": "https://github.com/shu307/mkdocs-nav-weight",
"name": "mkdocs-nav-weight",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "shu307",
"author_email": "shu307@qq.com",
"download_url": "https://files.pythonhosted.org/packages/93/d7/22668527f095cca37603be069b401a7412745f40191d931e376427b78ab9/mkdocs-nav-weight-0.2.0.tar.gz",
"platform": null,
"description": "# mkdocs-nav-weight\r\n\r\n**A simple mkdocs plugin, enables to organize Navigation in a more markdownic way.** \r\n\r\n> **This plugin tries to read markdown resources before mkdocs, which may add some performance overhead on building.**\r\n\r\n## Usage\r\n\r\nFour additional keys can be configured in Markdown Metadata ( also known as \"front-matter\", see [metadata](https://www.mkdocs.org/user-guide/writing-your-docs/#meta-data)).\r\n\r\n- `weight: number`\r\n - **Value: number, eg: `-1`, `2.3` ..., if unset, it goes `0`**.\r\n - 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. \r\n - **`weight` in an `index` will be offered to its parent `section`**, there is a fixed value for itself, and the value is configurable, see: [`index_weight`](#index_weight).\r\n\r\n- `headless:\u00a0bool`\r\n - **Value: bool, `true` or `false`, if unset, it goes `false`**.\r\n - 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.\r\n - **`headless` in an `index` will be offered to its parent `section`**.\r\n\r\n**For `index` only:**\r\n\r\n- `retitled: bool`\r\n - **Value: bool, `true` or `false`, if unset, it goes `false`**.\r\n - A metadata version of [`section_renamed`](#section_renamed) which only applies this `index`'s title to its parent `section`, **it only works when `section_renamed` is `false`**.\r\n\r\n- `empty:\u00a0bool`\r\n - **Value: bool, `true` or `false`, if unset, it goes `false`**.\r\n - If there is an `index` only used to offer metadata for its parent `section` and without any meaningful content, setting `empty` to `true` can help you to hide this `index` itself.\r\n\r\n## Installation\r\n\r\nInstall with `pip`:\r\n\r\n\r\n```shell\r\npip install mkdocs-nav-weight\r\n```\r\n\r\nAdd the following lines to `mkdocs.yml`\r\n\r\n```yaml\r\nplugins:\r\n - search\r\n - mkdocs-nav-weight\r\n```\r\n\r\n## Options\r\n\r\nConfigure in `mkdocs.yml`:\r\n\r\n```yaml\r\nplugins:\r\n - search\r\n - mkdocs-nav-weight:\r\n section_renamed: false\r\n index_weight: -10\r\n warning: true\r\n reverse: false\r\n headless_included: false\r\n```\r\n\r\n#### `section_renamed`\r\n\r\nDefault: `false`:\r\n\r\n- If `true`, section name will use the `title` of its `index` instead of the folder name. \r\n\r\n- 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\r\n\r\n#### `index_weight`\r\n\r\nDefault: `-10`:\r\n\r\n- The `weight` value for `index` itself, to ensure it's always the first at the same level\r\n\r\n#### `warning`\r\n\r\nDefault: `true`:\r\n\r\n- Controls whether to send a `Warning` when invalid values are detected in markdown metadata\r\n\r\n#### `reverse`\r\n\r\nDefault: `false`:\r\n\r\n- If `true`, sort nav by `weight` from largest to smallest.\r\n\r\n#### `headless_included`\r\n\r\nDefault: `false`:\r\n\r\n- An option to control whether `headless` pages should be included in `nav.pages` which is used by some plugins, eg: [mkdocs-pdf-export-plugin](https://github.com/zhaoterryy/mkdocs-pdf-export-plugin).\r\n\r\n- If `true`, `headless` pages will be included.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple mkdocs plugin, enables to organize Navigation in a more markdownic way.",
"version": "0.2.0",
"project_urls": {
"Homepage": "https://github.com/shu307/mkdocs-nav-weight"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "056fdb36b80b2f7afe76bf270646d27cdb6350402127d47628d15593bffdaf25",
"md5": "cae8c61febd5da9dff29f3bde060794a",
"sha256": "a6ed14bb57c6679f52ce8516e6576a5dbdf1a644e0725870d9ab4977d23270c3"
},
"downloads": -1,
"filename": "mkdocs_nav_weight-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cae8c61febd5da9dff29f3bde060794a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 7304,
"upload_time": "2023-11-17T05:39:14",
"upload_time_iso_8601": "2023-11-17T05:39:14.667392Z",
"url": "https://files.pythonhosted.org/packages/05/6f/db36b80b2f7afe76bf270646d27cdb6350402127d47628d15593bffdaf25/mkdocs_nav_weight-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "93d722668527f095cca37603be069b401a7412745f40191d931e376427b78ab9",
"md5": "9f79ff57076248c9729c8eedd368819a",
"sha256": "3a9531209fabb08ee7d18fa491cc5556d05f09631ff837c3b8d076f277e9b54b"
},
"downloads": -1,
"filename": "mkdocs-nav-weight-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "9f79ff57076248c9729c8eedd368819a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5229,
"upload_time": "2023-11-17T05:39:16",
"upload_time_iso_8601": "2023-11-17T05:39:16.492403Z",
"url": "https://files.pythonhosted.org/packages/93/d7/22668527f095cca37603be069b401a7412745f40191d931e376427b78ab9/mkdocs-nav-weight-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-17 05:39:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "shu307",
"github_project": "mkdocs-nav-weight",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mkdocs-nav-weight"
}
JSON
