{"id":15017505,"url":"https://github.com/ojacques/mkdocs-git-committers-plugin-2","last_synced_at":"2025-05-16T15:08:49.090Z","repository":{"id":39615747,"uuid":"224038921","full_name":"ojacques/mkdocs-git-committers-plugin-2","owner":"ojacques","description":"MkDocs plugin for displaying a list of GitHub (.com or Enterprise) contributors on each page. Encourages contributions to the documentation!","archived":false,"fork":false,"pushed_at":"2025-01-30T07:29:55.000Z","size":100,"stargazers_count":65,"open_issues_count":13,"forks_count":24,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-12T14:56:28.991Z","etag":null,"topics":["mkdocs","mkdocs-plugin"],"latest_commit_sha":null,"homepage":"","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/ojacques.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":["ojacques"],"custom":["https://www.paypal.me/ojacques2"]}},"created_at":"2019-11-25T20:50:44.000Z","updated_at":"2025-04-01T23:49:30.000Z","dependencies_parsed_at":"2023-01-22T02:48:39.092Z","dependency_job_id":"b7666ce0-d3a3-422f-8c7e-2fb73d931c83","html_url":"https://github.com/ojacques/mkdocs-git-committers-plugin-2","commit_stats":{"total_commits":72,"total_committers":14,"mean_commits":5.142857142857143,"dds":0.6666666666666667,"last_synced_commit":"877d52c8b9d6a4bf2480f92f57527fe915fcf311"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ojacques%2Fmkdocs-git-committers-plugin-2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ojacques%2Fmkdocs-git-committers-plugin-2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ojacques%2Fmkdocs-git-committers-plugin-2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ojacques%2Fmkdocs-git-committers-plugin-2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ojacques","download_url":"https://codeload.github.com/ojacques/mkdocs-git-committers-plugin-2/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254553958,"owners_count":22090417,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["mkdocs","mkdocs-plugin"],"created_at":"2024-09-24T19:50:34.643Z","updated_at":"2025-05-16T15:08:49.027Z","avatar_url":"https://github.com/ojacques.png","language":"Python","funding_links":["https://github.com/sponsors/ojacques","https://www.paypal.me/ojacques2"],"categories":[],"sub_categories":[],"readme":"# mkdocs-git-committers-plugin-2\r\n\r\nMkDocs plugin for displaying a list of committers associated with a file in\r\nmkdocs. The plugin uses GitHub or GitLab API to fetch the list of contributors\r\nfor each page.\r\n\r\n🥳 NEW! Works with GitLab too!\r\n\r\nFor ease of use, this plugin is integrated in the [material for\r\nmkdocs](https://squidfunk.github.io/mkdocs-material/) theme by [Martin\r\nDonath](https://github.com/squidfunk). See [Mkdocs material\r\ndocumentation](https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/#document-contributors).\r\n\r\nOther MkDocs plugins that use information to fetch authors:\r\n\r\n- [`mkdocs-git-authors-plugin`](https://github.com/timvink/mkdocs-git-authors-plugin) for displaying user names a number of lines contributed (uses local Git information)\r\n- [`mkdocs-git-committers-plugin`](https://github.com/byrnereese/mkdocs-git-committers-plugin) display contributors for a page (uses local Git information, completed with REST GitHub API v3)\r\n\r\n## Setup\r\n\r\nInstall the plugin using pip:\r\n\r\n`pip install mkdocs-git-committers-plugin-2`\r\n\r\nActivate the plugin in `mkdocs.yml`:\r\n\r\nFor a repository hosted on GitHub:\r\n\r\n```yaml\r\nplugins:\r\n  - git-committers:\r\n      repository: organization/repository\r\n```\r\n\r\nFor a repository hosted on GitLab:\r\n\r\n```yaml\r\nplugins:\r\n  - git-committers:\r\n      gitlab_repository: 12345678\r\n      token: !ENV [\"CI_JOB_TOKEN\"]\r\n```\r\n\r\nFor a repository hosted on GitLab, you need to provide a token so that the\r\nplugin can access the GitLab API. If the token is not set in `mkdocs.yml` it\r\nwill be read from the `MKDOCS_GIT_COMMITTERS_APIKEY` environment variable.\r\n\r\nFor a repository hosted on GitHub, you can provide a token to increase the rate\r\nlimit and go beyond the default 60 requests per hour per IP address. The plugin\r\nwill make one request per mkdocs document. The token does not need any scope:\r\nuncheck everything when creating the GitHub Token at\r\n[github.com/settings/personal-access-tokens/new](https://github.com/settings/personal-access-tokens/new),\r\nunless you access private repositories.\r\n\r\nFor private GitHub repositories, you only need to allow read-only access to `Contents` and `Metadata` on the target repository. This could be done by setting `Read-only` access of `Permissions \u003e Repository permissions \u003e Contents`.\r\n\r\n## Counting Contributors\r\n\r\n* In GitHub repositories, the commit authors, [committers](https://stackoverflow.com/a/18754896), and [co-authors](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors) are counted as contributors. However, the plugin requires a GitHub token to fetch the list of co-authors. If co-authors exist but no token is provided, the plugin will show a warning and will only display the commit authors and committers.\r\n* In GitLab repositories, only the commit authors are counted as contributors.\r\n\r\n## Config\r\n\r\n- `enabled` - Disables plugin if set to `False` for e.g. local builds (default: `True`)\r\n- `repository` - For GitHub, the name of the repository, e.g.\r\n  'ojacques/mkdocs-git-committers-plugin-2'\r\n- `gitlab_repository` - For GitLab, the project ID, e.g. '12345678'\r\n- `branch` - The name of the branch to get contributors from. Example: 'master'\r\n  (default)\r\n- `token` - A GitHub or GitLab personal access token for REST API calls. \r\n  - For GitHub, token does not need any scope: uncheck everything when creating\r\n    the GitHub Token at\r\n    [github.com/settings/personal-access-tokens/new](https://github.com/settings/personal-access-tokens/new),\r\n    unless you access private repositories.\r\n  - For GitLab, a\r\n    [project access token](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html)\r\n    scoped to `read_api` is expected to work. That way, the token is limited to\r\n    the project and has access to read the repository. You could use a personal\r\n    access token at\r\n    [gitlab.com/-/profile/personal_access_tokens](https://gitlab.com/-/profile/personal_access_tokens),\r\n    but it will grant access to more repositories than you want.\r\n- `enterprise_hostname` - For GitHub enterprise: the GitHub enterprise hostname.\r\n- `gitlab_hostname` - For GitLab: the GitLab hostname if different from \r\n  gitlab.com (self-hosted).\r\n- `api_version` - For GitHub and GitLab self-hosted, the API version part that needs to be appended to the URL. \r\n  Defaults to v4 for GitLab, and nothing for GitHub Enterprise (you may need `v3`).\r\n- `docs_path` - the path to the documentation folder. Defaults to `docs/`.\r\n- `cache_dir` - The path which holds the authors cache file to speed up\r\n  documentation builds. Defaults to `.cache/plugin/git-committers/`. The cache\r\n  file is named `page-authors.json`.\r\n- `exclude` - Specify a list of page source paths (one per line) that should not\r\n  have author(s) or last commit date included (excluded from processing by this\r\n  plugin). Default is empty. Examples:\r\n\r\n  ```\r\n  # mkdocs.yml\r\n  plugins:\r\n    - git-committers:\r\n        repository: organization/repository\r\n        exclude:\r\n          - README.md\r\n          - subfolder/page.md\r\n          - another_page.md\r\n          - all_files_inside_folder/*\r\n          - folder_and_subfolders/**\r\n  ```\r\n- `exclude_committers` - Specify a list of usernames to exclude certain committers. Default is empty.\r\n\r\n## History\r\n\r\nThis is a fork from the original [`mkdocs-git-committers-plugin`](https://github.com/byrnereese/mkdocs-git-committers-plugin) by @byrnereese.\r\n\r\nI had to create this fork so that it could be uploaded and distributed through PyPi. The package has been renamed to `mkdocs-git-committers-plugin-2`.\r\n\r\nThis \"v2\" differs from the original by:\r\n\r\n- Fetch contributors directly from GitHub\r\n- Eliminate the need to match git commit logs with entries in GitHub, and thus GitHub API calls\r\n- No more risk of matching the incorrect contributor as the information comes directly from GitHub\r\n- last_commit_date is now populated with local git info\r\n- Use a cache file to speed up following builds: authors are fetched from GitHub for a page only if that page has changed since the last build\r\n\r\nAll of the above improves accuracy and performances.\r\n\r\nNote: the plugin configuration in `mkdocs.yml` still uses the original `git-committers` sections.\r\n\r\n## Limitations\r\n\r\n- Getting the contributors relies on what is available on GitHub or GitLab.\r\n- For now, non-recursive Git submodule is supported for GitHub, while GitLab submodules and recursive submodules will report no contributors.\r\n- GitLab users may not be properly identified. See [issue #50](https://github.com/ojacques/mkdocs-git-committers-plugin-2/issues/50)\r\n\r\n## Usage\r\n\r\nYou have 2 options to use this plugin:\r\n\r\n1. Use Mkdocs material theme (see [Mkdocs material\r\ndocumentation](https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/#document-contributors)).\r\n1. Use the plugin directly in your template. See below.\r\n\r\n### Display Last Commit\r\n\r\nIn addition to displaying a list of committers for a file, you can also access\r\nthe last commit date for a page if you want to display the date the file was\r\nlast updated.\r\n\r\n#### Template Code for last commit\r\n\r\n```django hljs\r\n\u003cul class=\"metadata page-metadata\" data-bi-name=\"page info\" lang=\"en-us\" dir=\"ltr\"\u003e\r\n  \u003cli class=\"last-updated-holder displayDate loading\"\u003e\r\n    \u003cspan class=\"last-updated-text\"\u003eLast updated:\u003c/span\u003e\r\n    \u003ctime role=\"presentation\" datetime=\"2018-10-25T00:00:00.000Z\" data-article-date-source=\"ms.date\"\u003e{% if last_commit_date %}{{ last_commit_date }}{% endif %}\u003c/time\u003e\r\n  \u003c/li\u003e\r\n\u003c/ul\u003e\r\n```\r\n\r\n### Display List of Committers\r\n\r\n#### Avatar\r\n\r\nThe avatar of the contributors is provided by GitHub. It uses maximal resolution.\r\n\r\n#### Template Code for avatars\r\n\r\n```django hljs\r\n{% block footer %}\r\n\u003cul class=\"metadata page-metadata\" data-bi-name=\"page info\" lang=\"en-us\" dir=\"ltr\"\u003e\r\n  \u003cli class=\"contributors-holder\"\u003e\r\n    \u003cspan class=\"contributors-text\"\u003eContributors\u003c/span\u003e\r\n    \u003cul class=\"contributors\" data-bi-name=\"contributors\"\u003e\r\n      {%- for user in committers -%}\r\n      \u003cli\u003e\u003ca href=\"{{ user.url }}\" title=\"{{ user.name }}\" data-bi-name=\"contributorprofile\" target=\"_blank\"\u003e\u003cimg src=\"{{ user.avatar }}\" alt=\"{{ user.name }}\"\u003e\u003c/a\u003e\u003c/li\u003e\r\n      {%- endfor -%}\r\n    \u003c/ul\u003e\r\n  \u003c/li\u003e\r\n\u003c/ul\u003e\r\n{% endblock %}\r\n```\r\n\r\n#### CSS\r\n\r\n```css\r\n.metadata{\r\n    list-style:none;\r\n    padding:0;\r\n    margin:0;\r\n    margin-bottom: 15px;\r\n    color: #999;\r\n    font-size:0.85em;\r\n}\r\n.metadata.page-metadata .contributors-text{\r\n    margin-right:5px\r\n}\r\nbody[dir=rtl] .metadata.page-metadata .contributors-text{\r\n    margin-right:0;\r\n    margin-left:5px\r\n}\r\n.page-metadata .contributors{\r\n    display:inline-block;\r\n    list-style:none;\r\n    margin:0!important;\r\n    padding:0!important\r\n}\r\n.page-metadata .contributors li{\r\n    display:inline-block;\r\n    vertical-align:top;\r\n    margin:0;\r\n    padding:0\r\n}\r\n```\r\n\r\n#### Javascript\r\n\r\n```javascript\r\n    $( '.contributors img[data-src]' ).each( function() {\r\n        src = $(this).attr(\"data-src\");\r\n        $(this).attr('src',src);\r\n    });\r\n```\r\n\r\nMore information about templates [here][mkdocs-template].\r\n\r\nMore information about blocks [here][mkdocs-block].\r\n\r\n[mkdocs-plugins]: http://www.mkdocs.org/user-guide/plugins/\r\n[mkdocs-template]: https://www.mkdocs.org/user-guide/custom-themes/#template-variables\r\n[mkdocs-block]: https://www.mkdocs.org/user-guide/styling-your-docs/#overriding-template-blocks\r\n\r\n## Acknowledgements\r\n\r\nThank you to the following contributors:\r\n\r\n- Byrne Reese - original author, maintainer\r\n- Nathan Hernandez\r\n- Chris Northwood\r\n- Martin Donath\r\n- PTKay\r\n- Guts\r\n- Fir121\r\n- dstockhammer\r\n- thor\r\n- n2N8Z\r\n- barreeeiroo\r\n- j3soon\r\n- vrenjith\r\n- rkorzeniec\r\n- karelbemelmans\r\n- andrew-rowson-lseg\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fojacques%2Fmkdocs-git-committers-plugin-2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fojacques%2Fmkdocs-git-committers-plugin-2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fojacques%2Fmkdocs-git-committers-plugin-2/lists"}