| Name | mkdocs-authors-plugin JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | A MkDocs plugin to generate an authors page from a YAML file. |
| upload_time | 2025-07-30 13:38:47 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | MIT License
Copyright 2025 Thomas Zwagerman
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
mkdocs
plugin
authors
documentation
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# MkDocs Authors Plugin
[](https://codecov.io/gh/thomaszwagerman/mkdocs-authors-plugin)
A custom MkDocs plugin designed to dynamically generate an "Authors" page for your documentation site from a simple YAML file. This allows you to easily manage and display information about contributors without manually updating Markdown files.
The YAML format is kept consistent with Material's ["Defining authors"](https://squidfunk.github.io/mkdocs-material/tutorials/blogs/navigation/#defining-authors), which enables blog post author attribution. This means that if you are
creating a blog you will not have to define `.authors.yml` twice. Note that `authors` can be used
independently (without a blog) as well.
## Features
* **Dynamic Page Generation:** Automatically creates an `authors.md` page based on your `.authors.yml` file.
* **Configurable Paths:** Easily customize the input YAML file name and the output Markdown page name.
* **Author Profiles:** Supports fields for name, description, avatar, affiliation, email, and social media links.
## Installation
You can install this plugin using `pip`:
```
pip install mkdocs-authors-plugin
```
If you are developing the plugin locally, navigate to the plugin's root directory (the one containing `pyproject.toml`) and install it in editable mode:
```shell
cd /path/to/your/mkdocs-authors-plugin/
pip install -e .
```
## Usage
### 1. Configure `mkdocs.yml`
Add the `authors` plugin to your `plugins` list in your `mkdocs.yml` file. You also need to include the `authors.md` page in your `nav` section.
```yml
# mkdocs.yml
site_name: My Awesome Docs
plugins:
- search
- authors:
# Optional: specify the authors file if it's not .authors.yml
# authors_file: my_custom_authors.yaml
# Optional: specify the output page name if it's not authors.md
# output_page: team.md
nav:
- Home: index.md
- Authors: authors.md # This is the page that will be generated by the plugin
- About: about.md
```
### 2. Create your `.authors.yml` file
Create an `.authors.yml` file in the root directory of your MkDocs documentation project (the same directory as `mkdocs.yml`). This file will contain the data for your authors.
The plugin expects a top-level `authors` key, under which each author is defined by a unique ID (e.g., `author_one`).
You can also define optional page parameters under `page_params`, such as an overall title and
description.
```yml
# .authors.yml
# Optional: Define page-level parameters for the generated authors page
page_params:
title: Our Project Team
description: "Meet the team."
avatar_size: 150
avatar_shape: circle
avatar_align: left
# Required: Define individual author data
authors:
author_one:
name: Author One
description: Owner
avatar: headshot_one.png
affiliation: British Antarctic Survey
email: author.one@example.com
github: authorone
linkedin: author-one-profile
twitter: author_one_dev
orcid: 0123-4567-8910-1112
author_two:
name: Author Two
description: Maintainer
avatar: headshot_two.png
affiliation: UK Centre for Ecology & Hydrology
# You can omit any fields not applicable to an author
author_three:
name: Author Three
description: Core Contributor
avatar: headshot_three.png
affiliation: University of Edinburgh
```
### 3. Run MkDocs
Navigate to your main MkDocs documentation project root (the directory containing `mkdocs.yml`) and run:
```shell
mkdocs serve
```
The plugin will generate the `authors.md` page, and you should see it in your site's navigation.
### Where is authors.md?
When mkdocs serve detects a file change in `docs/` , it triggers a rebuild. If `authors.md` was
written into `docs/`, that write itself is a "change," leading to an endless cycle of rebuilding.
To prevent this endless loop, the plugin adds a `File` object representing `authors.md` to MkDocs'
internal list of files. This tells MkDocs that there is a page called `authors.md` that should be
part of the documentation build. This mean a physical file does not have to exist at
`docs/authors.md`.
## Other plugins
If you wish to automatically generate authors based on a git repository, [git-authors](https://github.com/timvink/mkdocs-git-authors-plugin) is a tidy plugin to do this.
The `authors-plugin` is developed for instances where you want to manually define an authors list,
for example for a wider project team, or non-code contributors.
## Contributing
Contributions are welcome! If you find a bug or have a feature request, please open an issue or submit a pull request on the [GitHub repository](https://github.com/thomaszwagerman/mkdocs-authors-plugin).
## License
This project is licensed under the MIT License - see the `LICENSE` file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-authors-plugin",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "mkdocs, plugin, authors, documentation",
"author": null,
"author_email": "Thomas Zwagerman <thozwa@bas.ac.uk>",
"download_url": "https://files.pythonhosted.org/packages/45/88/41688f042f2f5e23d8dce2f44ce5b3bc743d4e95db0871253a923fe95913/mkdocs_authors_plugin-0.1.0.tar.gz",
"platform": null,
"description": "# MkDocs Authors Plugin\n\n\n[](https://codecov.io/gh/thomaszwagerman/mkdocs-authors-plugin)\n\n\n\nA custom MkDocs plugin designed to dynamically generate an \"Authors\" page for your documentation site from a simple YAML file. This allows you to easily manage and display information about contributors without manually updating Markdown files.\n\nThe YAML format is kept consistent with Material's [\"Defining authors\"](https://squidfunk.github.io/mkdocs-material/tutorials/blogs/navigation/#defining-authors), which enables blog post author attribution. This means that if you are\ncreating a blog you will not have to define `.authors.yml` twice. Note that `authors` can be used\nindependently (without a blog) as well.\n\n## Features\n\n* **Dynamic Page Generation:** Automatically creates an `authors.md` page based on your `.authors.yml` file.\n\n* **Configurable Paths:** Easily customize the input YAML file name and the output Markdown page name.\n\n* **Author Profiles:** Supports fields for name, description, avatar, affiliation, email, and social media links.\n\n## Installation\n\nYou can install this plugin using `pip`:\n\n```\npip install mkdocs-authors-plugin\n```\n\nIf you are developing the plugin locally, navigate to the plugin's root directory (the one containing `pyproject.toml`) and install it in editable mode:\n\n```shell\ncd /path/to/your/mkdocs-authors-plugin/\npip install -e .\n```\n\n## Usage\n\n### 1. Configure `mkdocs.yml`\n\nAdd the `authors` plugin to your `plugins` list in your `mkdocs.yml` file. You also need to include the `authors.md` page in your `nav` section.\n\n```yml\n# mkdocs.yml\nsite_name: My Awesome Docs\n\nplugins:\n - search\n - authors:\n # Optional: specify the authors file if it's not .authors.yml\n # authors_file: my_custom_authors.yaml\n # Optional: specify the output page name if it's not authors.md\n # output_page: team.md\n\nnav:\n - Home: index.md\n - Authors: authors.md # This is the page that will be generated by the plugin\n - About: about.md\n```\n\n### 2. Create your `.authors.yml` file\n\nCreate an `.authors.yml` file in the root directory of your MkDocs documentation project (the same directory as `mkdocs.yml`). This file will contain the data for your authors.\n\nThe plugin expects a top-level `authors` key, under which each author is defined by a unique ID (e.g., `author_one`).\n\nYou can also define optional page parameters under `page_params`, such as an overall title and \ndescription.\n\n```yml\n# .authors.yml\n\n# Optional: Define page-level parameters for the generated authors page\npage_params:\n title: Our Project Team\n description: \"Meet the team.\"\n avatar_size: 150 \n avatar_shape: circle \n avatar_align: left\n\n# Required: Define individual author data\nauthors:\n author_one:\n name: Author One\n description: Owner\n avatar: headshot_one.png\n affiliation: British Antarctic Survey\n email: author.one@example.com\n github: authorone\n linkedin: author-one-profile\n twitter: author_one_dev\n orcid: 0123-4567-8910-1112\n author_two:\n name: Author Two\n description: Maintainer\n avatar: headshot_two.png\n affiliation: UK Centre for Ecology & Hydrology\n # You can omit any fields not applicable to an author\n author_three:\n name: Author Three\n description: Core Contributor\n avatar: headshot_three.png\n affiliation: University of Edinburgh\n```\n\n### 3. Run MkDocs\n\nNavigate to your main MkDocs documentation project root (the directory containing `mkdocs.yml`) and run:\n\n```shell\nmkdocs serve\n```\n\nThe plugin will generate the `authors.md` page, and you should see it in your site's navigation.\n\n### Where is authors.md?\nWhen mkdocs serve detects a file change in `docs/` , it triggers a rebuild. If `authors.md` was\nwritten into `docs/`, that write itself is a \"change,\" leading to an endless cycle of rebuilding.\n\nTo prevent this endless loop, the plugin adds a `File` object representing `authors.md` to MkDocs'\ninternal list of files. This tells MkDocs that there is a page called `authors.md` that should be\npart of the documentation build. This mean a physical file does not have to exist at\n`docs/authors.md`.\n\n## Other plugins\n\nIf you wish to automatically generate authors based on a git repository, [git-authors](https://github.com/timvink/mkdocs-git-authors-plugin) is a tidy plugin to do this.\n\nThe `authors-plugin` is developed for instances where you want to manually define an authors list,\nfor example for a wider project team, or non-code contributors. \n\n## Contributing\n\nContributions are welcome! If you find a bug or have a feature request, please open an issue or submit a pull request on the [GitHub repository](https://github.com/thomaszwagerman/mkdocs-authors-plugin).\n\n## License\n\nThis project is licensed under the MIT License - see the `LICENSE` file for details.\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright 2025 Thomas Zwagerman\n \n Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "A MkDocs plugin to generate an authors page from a YAML file.",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/thomaszwagerman/mkdocs-authors-plugin"
},
"split_keywords": [
"mkdocs",
" plugin",
" authors",
" documentation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e2077a9d179934f1fbdd8cc1f086003cc2ff782540fe9aa93b73d31909c24c7b",
"md5": "16d12a1df9056e62ad86502de10b6395",
"sha256": "73d039559cee9af78bf6a9766bc11053c7b328442cf53117858af339c0e3cda6"
},
"downloads": -1,
"filename": "mkdocs_authors_plugin-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "16d12a1df9056e62ad86502de10b6395",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 8070,
"upload_time": "2025-07-30T13:38:46",
"upload_time_iso_8601": "2025-07-30T13:38:46.224615Z",
"url": "https://files.pythonhosted.org/packages/e2/07/7a9d179934f1fbdd8cc1f086003cc2ff782540fe9aa93b73d31909c24c7b/mkdocs_authors_plugin-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "458841688f042f2f5e23d8dce2f44ce5b3bc743d4e95db0871253a923fe95913",
"md5": "2a27667e9f5d47eb8bb25423837ca2cd",
"sha256": "941b447e7faeb789c9b636ff8ba731d2561756bf6be7261e686e5ebc0ba9f5f9"
},
"downloads": -1,
"filename": "mkdocs_authors_plugin-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "2a27667e9f5d47eb8bb25423837ca2cd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 10765,
"upload_time": "2025-07-30T13:38:47",
"upload_time_iso_8601": "2025-07-30T13:38:47.327598Z",
"url": "https://files.pythonhosted.org/packages/45/88/41688f042f2f5e23d8dce2f44ce5b3bc743d4e95db0871253a923fe95913/mkdocs_authors_plugin-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-30 13:38:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "thomaszwagerman",
"github_project": "mkdocs-authors-plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-authors-plugin"
}
