mkdocs-git-latest-changes-plugin

MkDocs plugin that allows you to display a list of recently modified pages from the Git log

Features

  • Get all files of your MkDocs project currently in git with their file path, commit message, commit timestamp, commit hash and author.
  • Sort by commit timestamp descending.
  • Convert this to a markdown table.
  • Substitute the marker string {{ latest_changes }} with this markdown table.
  • Enjoy your latest changes table rendered by your MkDocs theme.

Configuration

    # mkdocs.yml plugin configuration example
    plugins:
      - git-latest-changes:
          limit_to_docs_dir: True  # [True|False], defaults to False
          repo_vendor: gitea  # [github|gitlab|gitea], defaults to `repo_name`
          enabled_on_serve: True  # [True|False], defaults to True
          history_limit: 5  # [Integer, defaults to -1 (no history limit)]

  • repo_vendor

    Set the "vendor" of your remote repository (currently supported: bitbucket, github, gitlab and gitea) via repo_vendor to get linkified commit hashes and filepaths.

  • limit_to_docs_dir

    Limit {{ latest_changes }} to your pages in your docs_dir and exclude the git history information for other files from your project repository via plugin config limit_to_docs_dir.

  • enabled_on_serve

    Not amused by slow builds during serve while developing your docs? Disable this plugin only when running MkDocs via mkdocs serve and only trigger this plugins functionality on builds (mkdocs build). Defaults to True.

  • history_limit

    Not interested in all the old commits? Limit the table of recent changes using history_limit = N. N should be a positive integer, negative values or zero disables this option.

Hints

  • This plugin depends of having any commits in the current git branch.
  • An error will be raised/rendered if no git repository exists.
  • For linked git commit hashes and filenames, the MkDocs config variable repo_url must be set and point to a Github or Gitlab repository.
  • Relax warnings with --no-strict (via MkDocs strict configuration, cli), e.g. if a expected file is not in the git working tree.
  • Log level: Request debug information for this plugin via MkDocs --verbose / -v command line flag.

Latest changes demo

Code

# docs_dir/file.md

{{ latest_changes }}

Rendered

Filepath Timestamp Author Message Commit
src/mkdocs_git_latest_changes_plugin/plugin.py 2024-06-02 18:17:41 Thomas Breitner Show brief information if a history_limit is set 319c36c
docs/index.md 2024-06-01 18:33:23 Thomas Breitner Fixed indentation 4b81a14
.github/workflows/tests.yml 2024-06-01 18:14:59 Thomas Breitner Run pytest in gh action 1d7612b
README.md 2024-06-01 18:13:58 Thomas Breitner New config option: history_limit e43a563
mkdocs.yml 2024-06-01 18:13:58 Thomas Breitner New config option: history_limit e43a563
tests/test_mkdocs_git_latest_changes_plugin.py 2024-06-01 18:13:58 Thomas Breitner New config option: history_limit e43a563
.pre-commit-config.yaml 2024-06-01 16:02:26 Thomas Breitner Bumped pre-commit hooks and freezed GitPython version ff6373e
pyproject.toml 2024-06-01 16:02:26 Thomas Breitner Bumped pre-commit hooks and freezed GitPython version ff6373e
docs/subdir/index.md 2024-01-12 11:42:24 Thomas Breitner Added sub directory to test new config option c987c89
.gitignore 2024-01-10 08:01:54 Thomas Breitner src-based directory layout c9a468d
src/mkdocs_git_latest_changes_plugin/init.py 2024-01-10 08:01:54 Thomas Breitner src-based directory layout c9a468d
.github/workflows/deploy.yml 2023-12-17 21:59:04 Thomas Breitner Github pages already triggered by test workflow: removed duplicate push trigger in ghpages.yml 6cb7efc
.github/workflows/ghpages.yml 2023-12-17 21:59:04 Thomas Breitner Github pages already triggered by test workflow: removed duplicate push trigger in ghpages.yml 6cb7efc
docs/test.md 2023-12-17 13:48:18 Thomas Breitner Some prose for test.md 4b0cccf
LICENSE 2023-12-17 13:45:29 Thomas Breitner Add traditional LICENSE file to allow github to pick it up 1b07bbb
LICENSES/CC0-1.0.txt 2023-12-02 19:16:43 Thomas Breitner REUSE-compliance a2981f6
LICENSES/MIT.txt 2023-12-02 19:16:43 Thomas Breitner REUSE-compliance a2981f6