# Tags
Support for tags in the yaml-metadata in the header of markdown files.
Extracts this metadata and creates a "Tags" page which lists all tags
and all pages for each tag.
## Quick Demo
Install this plugin (it will also install mkdocs if required)
```bash
pip install mkdocs-simple-tags-plugin
```
Create a new documentation folder:
```bash
mkdocs new demo
```
Edit the `.md` files to add initial metadata. Currently, the metadata has to be
enclosed in `---` lines, and must include a `title:` property
(otherwise the page will appear as "untitled" in the tags page). So, for example:
```bash
cd demo
cd docs
cat > index.md
---
title: Welcome
tags:
- testing
- unimportant
---
# Welcome to MkDocs
For full documentation visit [mkdocs.org](https://mkdocs.org).
^D
```
Edit `mkdocs.yml` to include this plugin:
```yaml
plugins:
- simple-tags:
```
Run the server:
```bash
mkdocs serve --livereload
```
Visit the URL `/tags` (it should appear in the nav panel).
This is an auto-generated page which contains the tags as level 2 headers,
and under each tag, a listing of the pages which declare that tag in the
metadata section.
## How it works
On each build (even with `--livereload`), all the `.md` files composing the
site are scanned, their "triple-dash-delimted" yaml header is extracted and
parsed, and the list of tags is collected.
After that, a new temporal file is created (by default in `aux/tags.md`, but
this is customizable) which contains the generated tags page, in markdown
format. This file is not in the documents folder to avoid retriggering a
build, but it is added to the list of files to be converted to HTML by mkdocs.
## Customization
The layout of the tags page is a markdown file with jinja2 embedded contents.
The package provides such a template by default, with the following content:
```markdown
---
title: Tags
---
# Contents grouped by tag
{% for tag, pages in tags %}
## <span class="tag">{{tag}}</span>
{% for page in pages %}
* [{{page.title}}]({{page.filename}})
{% endfor %}
{% endfor %}
```
You can style the `h2.tag` element via CSS, if you want.
You can also provide your own markdown template, in case that you want a
different layout or metadata. The `page` object contains all the metadata
in a mkdocs page, and in addition a `.filename` attribute, which contains
the file name of the source of the page (relative to the docs folder),
which can be used to link to that page.
The full customizable options for the plugin are:
* `folder`: Folder in which the auxiliar tags markdown file will be written
(`aux` by default, relative to the folder in which `mkdocs` is invoked).
It can be set to an absolute path, such as `/tmp/mysite/aux`.
The required folders are created.
* `template`: path to the file which contains the markdown-jinja template
for the tags page. It is `None` by default, which means that the
package-provided template is used. It can be an absolute path,
or relative to the folder in which `mkdocs` is run.
* `css_name`: this allows you to pick what name styles the tag that appears on
the top of the page that contains a tag. This way things won't be overloaded
For example, this can be put at `mkdocs.yaml`:
```yaml
plugins:
- search
- simple-tags:
folder: /tmp/mysite/aux
template: docs/theme/tags.md.template
```
Raw data
{
"_id": null,
"home_page": "https://github.com/BeyondIM/mkdocs-simple-tags-plugin",
"name": "mkdocs-simple-tags-plugin",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "\"mkdocs python markdown tags\"",
"author": "BeyondIM",
"author_email": "lypdarling@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/70/e4/958542a0705bee315a0e61e332696daddb66cbb67be73354b8196a25bacb/mkdocs-simple-tags-plugin-1.3.tar.gz",
"platform": null,
"description": "# Tags\n\nSupport for tags in the yaml-metadata in the header of markdown files.\n\nExtracts this metadata and creates a \"Tags\" page which lists all tags\nand all pages for each tag.\n\n## Quick Demo\n\nInstall this plugin (it will also install mkdocs if required)\n\n```bash\npip install mkdocs-simple-tags-plugin\n```\n\nCreate a new documentation folder:\n\n```bash\nmkdocs new demo\n```\n\nEdit the `.md` files to add initial metadata. Currently, the metadata has to be\nenclosed in `---` lines, and must include a `title:` property\n(otherwise the page will appear as \"untitled\" in the tags page). So, for example:\n\n```bash\ncd demo\ncd docs\ncat > index.md\n---\ntitle: Welcome\ntags:\n - testing\n - unimportant\n---\n# Welcome to MkDocs\n\nFor full documentation visit [mkdocs.org](https://mkdocs.org).\n\n^D\n```\n\nEdit `mkdocs.yml` to include this plugin:\n\n```yaml\nplugins:\n - simple-tags:\n```\n\nRun the server:\n\n```bash\nmkdocs serve --livereload\n```\n\nVisit the URL `/tags` (it should appear in the nav panel).\nThis is an auto-generated page which contains the tags as level 2 headers,\nand under each tag, a listing of the pages which declare that tag in the\nmetadata section.\n\n\n\n## How it works\n\nOn each build (even with `--livereload`), all the `.md` files composing the\nsite are scanned, their \"triple-dash-delimted\" yaml header is extracted and\nparsed, and the list of tags is collected.\n\nAfter that, a new temporal file is created (by default in `aux/tags.md`, but\nthis is customizable) which contains the generated tags page, in markdown\nformat. This file is not in the documents folder to avoid retriggering a\nbuild, but it is added to the list of files to be converted to HTML by mkdocs.\n\n## Customization\n\nThe layout of the tags page is a markdown file with jinja2 embedded contents.\nThe package provides such a template by default, with the following content:\n\n```markdown\n---\ntitle: Tags\n---\n# Contents grouped by tag\n\n{% for tag, pages in tags %}\n\n## <span class=\"tag\">{{tag}}</span>\n\n{% for page in pages %}\n * [{{page.title}}]({{page.filename}})\n{% endfor %}\n\n{% endfor %}\n```\n\nYou can style the `h2.tag` element via CSS, if you want.\n\nYou can also provide your own markdown template, in case that you want a\ndifferent layout or metadata. The `page` object contains all the metadata\nin a mkdocs page, and in addition a `.filename` attribute, which contains\nthe file name of the source of the page (relative to the docs folder),\nwhich can be used to link to that page.\n\nThe full customizable options for the plugin are:\n\n* `folder`: Folder in which the auxiliar tags markdown file will be written\n (`aux` by default, relative to the folder in which `mkdocs` is invoked).\n It can be set to an absolute path, such as `/tmp/mysite/aux`.\n The required folders are created.\n* `template`: path to the file which contains the markdown-jinja template\n for the tags page. It is `None` by default, which means that the\n package-provided template is used. It can be an absolute path,\n or relative to the folder in which `mkdocs` is run.\n* `css_name`: this allows you to pick what name styles the tag that appears on\n the top of the page that contains a tag. This way things won't be overloaded\n\nFor example, this can be put at `mkdocs.yaml`:\n\n```yaml\nplugins:\n - search\n - simple-tags:\n folder: /tmp/mysite/aux\n template: docs/theme/tags.md.template\n```",
"bugtrack_url": null,
"license": "MIT",
"summary": "\"Create tags in mkdocs\"",
"version": "1.3",
"project_urls": {
"Homepage": "https://github.com/BeyondIM/mkdocs-simple-tags-plugin"
},
"split_keywords": [
"\"mkdocs",
"python",
"markdown",
"tags\""
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "70e4958542a0705bee315a0e61e332696daddb66cbb67be73354b8196a25bacb",
"md5": "c000c8af6a9db09273278d5303fee71c",
"sha256": "73248091e0d1dd09ac144c86a8ec0b4ec41841f68f9c8498164ba2f9708098c5"
},
"downloads": -1,
"filename": "mkdocs-simple-tags-plugin-1.3.tar.gz",
"has_sig": false,
"md5_digest": "c000c8af6a9db09273278d5303fee71c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 5511,
"upload_time": "2023-05-23T17:19:47",
"upload_time_iso_8601": "2023-05-23T17:19:47.837211Z",
"url": "https://files.pythonhosted.org/packages/70/e4/958542a0705bee315a0e61e332696daddb66cbb67be73354b8196a25bacb/mkdocs-simple-tags-plugin-1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-23 17:19:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BeyondIM",
"github_project": "mkdocs-simple-tags-plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "mkdocs",
"specs": [
[
">=",
"1.4.3"
]
]
}
],
"lcname": "mkdocs-simple-tags-plugin"
}
JSON
