Skip to content

options.md

Latest commit

 

History

History
173 lines (121 loc) · 6.74 KB

options.md

File metadata and controls

173 lines (121 loc) · 6.74 KB

Options

You can customize the plugin by setting options in mkdocs.yml. For example:

=== ":octicons-file-code-16: mkdocs.yml"

plugins:
  - git-revision-date-localized:
      type: timeago
      custom_format: "%d. %B %Y"
      timezone: Europe/Amsterdam
      locale: en
      fallback_to_build_date: false
      enable_creation_date: true
      exclude:
          - index.md
      enable_git_follow: true
      enabled: true
      strict: true
      ignored_commits_file: .git-blame-ignore-revs

type

Default is date. The format of the date to be displayed. Valid values are date, datetime, iso_date, iso_datetime, timeago and custom. Example outputs:

November 28, 2019           # type: date (default)
November 28, 2019 13:57:28  # type: datetime
2019-11-28                  # type: iso_date
2019-11-28 13:57:26         # type: iso_datetime
20 hours ago                # type: timeago
28. November 2019           # type: custom

custom_format

Default is %d. %B %Y. The date format used when type: custom. Passed to python's strftime, see the cheatsheat for details.

timezone

Default is UTC. Specify a time zone database name (reference). This option is especially relevant when using type: datetime and type: iso_datetime. Note that when using timeago (with type: timeago) any difference in time zones between server and client will be handled automatically.

=== ":octicons-file-code-16: mkdocs.yml"

plugins:
  - git-revision-date-localized:
      timezone: Europe/Amsterdam

locale

Default is None. Specify a two letter ISO639 language code to display dates in your preferred language. Note this plugin supports many different ways to specify the locale, but if not specified anywhere the fallback is English (en).

Example outputs:

April 27, 2021                # `locale: en` with `type: date` (default)
April 27, 2021 13:11:28       # `locale: en` with `type: datetime`
2 weeks ago                   # `locale: en` with `type: timeago`
27 de marzo de 2021           # `locale: es` with `type: date`
27 de marzo de 2021 13:57:28  # `locale: es` with `type: datetime`
hace 2 semanas                # `locale: es` with `type: timeago`

=== ":octicons-file-code-16: mkdocs.yml"

plugins:
  - git-revision-date-localized:
      locale: en

fallback_to_build_date

Default is false. Enables falling back to the time when mkdocs build was executed when git is not available. This means the revision date will be incorrect, but this can be acceptable if you want your project to also successfully build in environments with no access to GIT.

=== ":octicons-file-code-16: mkdocs.yml"

plugins:
  - git-revision-date-localized:
      fallback_to_build_date: true

enable_creation_date

Default is false (because it has a small effect on build time). Enables a Created date variables, see available variables. This will also add a created date at the bottom of each page in mkdocs-material as it has native support (see overriding a theme).

=== ":octicons-file-code-16: mkdocs.yml"

plugins:
  - git-revision-date-localized:
      enable_creation_date: true

exclude

Default is empty. Specify a list of page source paths (one per line) that should not have a revision date included (excluded from processing by this plugin). This can be useful for example to remove the revision date from the front page. The source path of a page is relative to your docs/ folder. You can also use globs instead of full source paths. To exclude docs/subfolder/page.md specify in your mkdocs.yml a line under exclude: with - subfolder/page.md. Some examples:

=== ":octicons-file-code-16: mkdocs.yml"

plugins:
  - git-revision-date-localized:
      exclude:
        - index.md
        - subfolder/page.md
        - another_page.md
        - folder/*

enable_git_follow

Default is true. When enabled it will use git log --follow to find the git history. This means git will follow changes if you rename or move the file also. Despite being a sensible default, there is a known bug with --follow: if you have committed an empty version of a file, then git log --follow can follow the wrong trail and give wrong results (see this blogpost).

When disabled (by setting it to false), each file's history will only consist of its current name and path, it's history from the previous paths or names will not be included.

enabled

Default is true. Enables you to deactivate this plugin. A possible use case is local development where you might want faster build times and/or do not have git available. It's recommended to use this option with an environment variable together with a default fallback (introduced in mkdocs v1.2.1, see docs). Example:

=== ":octicons-file-code-16: mkdocs.yml"

plugins:
  - git-revision-date-localized:
      enabled: !ENV [ENABLED_GIT_REVISION_DATE, True]

Which enables you to disable the plugin locally using:

export ENABLED_GIT_REVISION_DATE=false
mkdocs serve

strict

Default is true. When enabled, the logs will show warnings when something is wrong but a fallback has been used. When disabled, the logger will use the INFO level instead.

  • If you want to raise an error when a warning is logged, use mkdocs strict mode (with mkdocs build --strict).
  • If you are already using mkdocs strict mode, but do not care about these warnings, you can set strict: false to ensure no errors are raised.

=== ":octicons-file-code-16: mkdocs.yml"

plugins:
  - git-revision-date-localized:
      strict: true

ignored_commits_file

Default is None. You can specify a file path (relative to your mkdocs.yml directory) that contains a list of commit hashes to ignore when determining the revision date. The format of the file is the same as the format of git blame.ignoreRevsFile. This can be useful to ignore specific commits that apply formatting updates or other mass changes to the documents.

=== ":octicons-file-code-16: mkdocs.yml"

plugins:
  - git-revision-date-localized:
      ignored_commits_file: .git-blame-ignore-revs