https://github.com/thomaszwagerman/mkdocs-authors-plugin
MkDocs plugin to display authors dynamically on a template using an .authors.yml file
https://github.com/thomaszwagerman/mkdocs-authors-plugin
authors documentation mkdocs plugin
Last synced: about 1 month ago
JSON representation
MkDocs plugin to display authors dynamically on a template using an .authors.yml file
- Host: GitHub
- URL: https://github.com/thomaszwagerman/mkdocs-authors-plugin
- Owner: thomaszwagerman
- License: mit
- Created: 2025-07-29T13:44:32.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-08-05T16:33:26.000Z (11 months ago)
- Last Synced: 2025-09-24T18:45:40.410Z (9 months ago)
- Topics: authors, documentation, mkdocs, plugin
- Language: Python
- Homepage: https://thomaszwagerman.github.io/mkdocs-authors-plugin/
- Size: 1.46 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# MkDocs Authors Plugin
[](https://pypi.org/project/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.