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", 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:

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.

# 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.

# .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:

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 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.

License

This project is licensed under the MIT License - see the LICENSE file for details.