{"id":30068699,"url":"https://github.com/thomaszwagerman/mkdocs-authors-plugin","last_synced_at":"2026-05-18T15:05:09.895Z","repository":{"id":307124754,"uuid":"1028411208","full_name":"thomaszwagerman/mkdocs-authors-plugin","owner":"thomaszwagerman","description":"MkDocs plugin to display authors dynamically on a template using an .authors.yml file","archived":false,"fork":false,"pushed_at":"2025-08-05T16:33:26.000Z","size":1527,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-24T18:45:40.410Z","etag":null,"topics":["authors","documentation","mkdocs","plugin"],"latest_commit_sha":null,"homepage":"https://thomaszwagerman.github.io/mkdocs-authors-plugin/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thomaszwagerman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-29T13:44:32.000Z","updated_at":"2025-08-05T16:33:11.000Z","dependencies_parsed_at":"2025-07-29T16:57:44.945Z","dependency_job_id":"6138113a-133f-49ec-87de-afeb557db633","html_url":"https://github.com/thomaszwagerman/mkdocs-authors-plugin","commit_stats":null,"previous_names":["thomaszwagerman/mkdocs-authors-plugin"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/thomaszwagerman/mkdocs-authors-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomaszwagerman%2Fmkdocs-authors-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomaszwagerman%2Fmkdocs-authors-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomaszwagerman%2Fmkdocs-authors-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomaszwagerman%2Fmkdocs-authors-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thomaszwagerman","download_url":"https://codeload.github.com/thomaszwagerman/mkdocs-authors-plugin/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thomaszwagerman%2Fmkdocs-authors-plugin/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33181765,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-18T09:27:30.708Z","status":"ssl_error","status_checked_at":"2026-05-18T09:27:28.300Z","response_time":71,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authors","documentation","mkdocs","plugin"],"created_at":"2025-08-08T11:00:39.116Z","updated_at":"2026-05-18T15:05:09.864Z","avatar_url":"https://github.com/thomaszwagerman.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MkDocs Authors Plugin\n![tests](https://github.com/thomaszwagerman/mkdocs-authors-plugin/actions/workflows/tests.yml/badge.svg)\n![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mkdocs-authors-plugin)\n[![PyPI version](https://img.shields.io/pypi/v/mkdocs-authors-plugin)](https://pypi.org/project/mkdocs-authors-plugin/)\n[![codecov](https://codecov.io/gh/thomaszwagerman/mkdocs-authors-plugin/graph/badge.svg?token=Q6FAWKRJMK)](https://codecov.io/gh/thomaszwagerman/mkdocs-authors-plugin)\n![GitHub License](https://img.shields.io/github/license/thomaszwagerman/mkdocs-authors-plugin)\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 \u0026 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthomaszwagerman%2Fmkdocs-authors-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthomaszwagerman%2Fmkdocs-authors-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthomaszwagerman%2Fmkdocs-authors-plugin/lists"}