mkdocs-calendar-plugin

mkdocs-calendar-plugin

This MkDocs plugin exposes calendar information to the 'extra' configuration variable. This plugin is particularly useful when used together with the mkdocs-macros-plugin

Installation

Install the package with pip:

pip install mkdocs-calendar-plugin

Activate the plugin in mkdocs.yml:

plugins:
  - search
  - calendar
  - macros

Configuration

The plugin can be configured in the plugins section of mkdocs.yml as follows:

plugins:
  - search
  - calendar:
      tz: Europe/Zurich
      start: 2023-02-20
      end: 2023-06-23
  - macros

It can be more convenient to use the extra configuration variable, so that the plugin section of mkdocs.yml can be kept clean. mkdocs-calendar-plugin can also be configured using the extra.calendar_plugin configuration variable as follows:

extra:
  calendar_plugin:
    start: 2023-02-20
    end: 2023-06-23

plugins:
  - search
  - calendar:
      tz: Europe/Zurich
  - macros

The plugin supports the following configuration options:

Option	Description
tz	The timezone to use for the calendar. Defaults to UTC.
start	The start date of the calendar.
end	The end date of the calendar.
today	The date to use as today (used mainly for testing). Defaults to now.
week_names	The names of the weeks. Defaults to [] (no week names).
plan	The plan to use for the calendar. Defaults to {} (no plan).
extra_key	The key to use in the extra configuration variable. Defaults to cal.

Extra configuration variable

The plugin exposes the following information in the extra.<extra_key> configuration variable:

Key	Description
now	The current date and time
today	The current date
weekday	The current weekday (Monday == 0 ... Sunday == 6)
iso_weekday	The current ISO weekday (Monday == 0 ... Sunday == 7)
week_number	The current ISO week number
start	A copy of extra.<extra_key>.start (only if extra.<extra_key>.start is defined)
academic_week	The academic week number staring from extra.<extra_key>.start (only if extra.<extra_key>.start is defined)
academic_week_name	The academic week name (from the week_names array) staring from extra.<extra_key>.start (only if extra.<extra_key>.start is defined)--
elapsed	The number of days elapsed since extra.<extra_key>.start (only if extra.<extra_key>.start is defined)
elapsed_weeks	The number of weeks elapsed since extra.<extra_key>.start (only if extra.<extra_key>.start is defined)
aw	alias for academic_week (only if extra.<extra_key>.start is defined)
awn	alias for academic_week_name (only if extra.<extra_key>.start is defined)
end	A copy of extra.<extra_key>.end (only if extra.<extra_key>.end is defined)
remaining	The remaining days to extra.<extra_key>.end (only if extra.<extra_key>.end is defined)
remaining_weeks	The remaining weeks to extra.<extra_key>.end (only if extra.<extra_key>.end is defined)

The plugin also exposes the information compited from the plan. A typical plan looks like this:

plan:
  P1: [s01, ex01, tp01]
  P2: [sol1, s02, ex02, tp02]

The keys of the plan (here above P1 and P2) must exists in the week_names array (see above). The values of the plan are boolean variables that will be True if the corresponding week is the present week (or before) and False otherwise.