API#

Core#

Bases: BasePlugin[RssPluginConfig]

Main class for MkDocs plugin.

`init(*args, **kwargs)` #

Instantiation.

`on_config(config)` #

The config event is the first event called on build and is run immediately after the user configuration is loaded and validated. Any alterations to the config should be made here.

See: https://www.mkdocs.org/user-guide/plugins/#on_config

Parameters:

Name	Type	Description	Default
`config`	`Config`	global configuration object	required

Raises:

Type	Description
`FileExistsError`	if the template for the RSS feed is not found
`PluginError`	if the 'date_from_meta.default_time' format does not comply

Returns:

Name	Type	Description
`MkDocsConfig`	`MkDocsConfig`	global configuration object

`on_page_content(html, page, config, files)` #

The page_content event is called after the Markdown text is rendered to HTML (but before being passed to a template) and can be used to alter the HTML body of the page.

See: https://www.mkdocs.org/user-guide/plugins/#on_page_content

Parameters:

Name	Type	Description	Default
`html`	`str`	HTML rendered from Markdown source as string	required
`page`	`Page`	`mkdocs.structure.pages.Page` instance	required
`config`	`MkDocsConfig`	global configuration object	required
`files`	`Files`	global files collection	required

Returns:

Type	Description
`Optional[str]`	Optional[str]: HTML rendered from Markdown source as string

`on_post_build(config)` #

The post_build event does not alter any variables. Use this event to call post-build scripts.

See

https://www.mkdocs.org/user-guide/plugins/#on_post_build

Parameters:

Name	Type	Description	Default
`config`	`Config`	global configuration object	required

`on_startup(*, command, dirty)` #

The startup event runs once at the very beginning of an mkdocs invocation. Note that for initializing variables, the init method is still preferred. For initializing per-build variables (and whenever in doubt), use the on_config event.

See: https://www.mkdocs.org/user-guide/plugins/#on_startup

Parameters:

Name	Type	Description	Default
`command`	`Literal['build', 'gh-deploy', 'serve']`	the command that MkDocs was invoked with, e.g. "serve" for `mkdocs serve`.	required
`dirty`	`bool`	whether `--dirty` flag was passed.	required

Bases: Config

Configuration for RSS plugin for Mkdocs.

Data type to set and get page information in order to produce the RSS feed.

Plugin logic.

`init(cache_dir=DEFAULT_CACHE_FOLDER, integration_material_blog=None, integration_material_social_cards=None, mkdocs_command_is_on_serve=False, path='.', use_git=True)` #

Class hosting the plugin logic.

Parameters:

Name	Type	Description	Default
`path`	`str`	path to the git repository to use. Defaults to ".".	`'.'`
`use_git`	`bool`	flag to use git under the hood or not. Defaults to True.	`True`
`integration_material_blog`	`bool`	option to enable integration with Blog plugin from Material theme. Defaults to True.	`None`
`integration_material_social_cards`	`bool`	option to enable integration with Social Cards plugin from Material theme. Defaults to True.	`None`

`build_url(base_url, path, args_dict=None)` #

Build URL using base URL, cumulating existing and passed path, then adding URL arguments.

Parameters:

Name	Type	Description	Default
`base_url`	`str`	base URL with existing path to use	required
`path`	`str`	URL path to cumulate with existing	required
`args_dict`	`dict \| None`	URL arguments to add. Defaults to None.	`None`

Returns:

Name	Type	Description
`str`	`str`	complete and valid URL

`feed_to_json(feed, *, updated=False)` `staticmethod` #

Format internal feed representation as a JSON Feed compliant dict.

Parameters:

Name	Type	Description	Default
`feed`	`dict`	internal feed structure, i. e. GitRssPlugin.feed_created or feed_updated value	required
`updated`	`bool`	True if this is a feed_updated. Defaults to False.	`False`

Returns:

Name	Type	Description
`dict`	`dict`	dict that can be passed to json.dump

`filter_pages(pages, attribute, length)` `staticmethod` #

Filter and return pages into a friendly RSS structure.

Parameters:

Name	Type	Description	Default
`pages`	`list`	pages to filter	required
`attribute`	`str`	page attribute as filter variable	required
`length`	`int`	max number of pages to return	required

Returns:

Name	Type	Description
`list`	`list`	list of filtered pages

`get_authors_from_meta(in_page)` #

Returns authors from page meta. It handles 'author' and 'authors' for keys, str and iterable as values types.

Parameters:

Name	Type	Description	Default
`in_page`	`Page`	input page to look into	required

Returns:

Type	Description
`Optional[tuple[str]]`	tuple[str] \| None: tuple of authors names

`get_categories_from_meta(in_page, categories_labels)` #

Returns category from page meta.

Parameters:

Name	Type	Description	Default
`in_page`	`Page`	input page to parse	required
`categories_labels`	`Iterable`	meta tags to look into	required

Returns:

Type	Description
`Optional[list]`	list \| None: found categories

`get_date_from_meta(date_metatag_value, meta_datetime_format, meta_datetime_timezone, meta_default_time)` #

Get date from page.meta handling str with associated datetime format and date already transformed by MkDocs.

Parameters:

Name	Type	Description	Default
`date_metatag_value`	`str`	value of page.meta.{tag_for_date}	required
`meta_datetime_format`	`str`	expected format of datetime	required
`meta_datetime_timezone`	`str`	timezone to use	required
`meta_default_time`	`datetime`	time to set if not specified	required

Returns:

Name	Type	Description
`datetime`	`datetime`	page datetime value

`get_description_or_abstract(in_page, chars_count=160, abstract_delimiter=None)` #

Returns description from page meta. If it doesn't exist, use the page content up to {abstract_delimiter} or the {chars_count} first characters from page content (in markdown).

Parameters:

Name	Type	Description	Default
`in_page`	`Page`	page to look at	required
`chars_count`	`int`	if page.meta.description is not set, number of chars of the content to use. Defaults to 160.	`160`
`abstract_delimiter`	`str`	description delimiter (also called excerpt). Defaults to None.	`None`

Returns:

Name	Type	Description
`str`	`str`	page description to use

`get_file_dates(in_page, source_date_creation, source_date_update, meta_datetime_format, meta_default_time, meta_default_timezone)` #

Extract creation and update dates from page metadata (yaml frontmatter) or git log for given file.

Parameters:

Name	Type	Description	Default
`in_page`	`Page`	input page	required
`source_date_creation`	`str`	which source to use (git or meta tag) for creation date	required
`source_date_update`	`str`	which source to use (git or meta tag) for update date	required
`meta_datetime_format`	`str`	datetime string format	required
`meta_default_time`	`datetime`	fallback time to set if not specified	required
`meta_default_timezone`	`str`	timezone to use	required

Returns:

Type	Description
`tuple[datetime, datetime]`	tuple[datetime, datetime]: tuple of timestamps (creation date, last commit date)

`get_image(in_page, base_url)` #

Get page's image from page meta or social cards and returns properties.

Parameters:

Name	Type	Description	Default
`in_page`	`Page`	page to parse	required
`base_url`	`str`	website URL to resolve absolute URLs for images referenced with local path.	required

Returns:

Type	Description
`Optional[tuple[str, str, int]]`	Optional[Tuple[str, str, int]]: (image url, mime type, image length) or None if there is no image set

`get_local_image_length(page_path, path_to_append)` #

Calculates local image size in octets.

Parameters:

Name	Type	Description	Default
`page_path`	`str`	source path to the Mkdocs page	required
`path_to_append`	`str`	path to append	required

Returns:

Name	Type	Description
`int`	`Optional[int]`	size in octets

`get_remote_image_length(image_url, http_method='HEAD', attempt=0, ssl_verify=True)` `cached` #

Retrieve length for remote images (starting with 'http').

Firstly, it tries to perform a HEAD request and get the length from the headers. If it fails, it tries again with a GET and disabling SSL verification.

Parameters:

Name	Type	Description	Default
`image_url`	`str`	image URL	required
`http_method`	`str`	HTTP method to use for the request. Defaults to "HEAD".	`'HEAD'`
`attempt`	`int`	request tries counter. Defaults to 0.	`0`
`ssl_verify`	`bool`	option to perform SSL verification or not. Defaults to True.	`True`

Returns:

Type	Description
`Optional[int]`	int \| None: image length as int or None

`get_site_url(mkdocs_config)` `staticmethod` #

Extract site URL from MkDocs configuration and enforce the behavior to ensure returning a str with length > 0 or None. If exists, it adds an ending slash.

Parameters:

Name	Type	Description	Default
`mkdocs_config`	`MkDocsConfig`	configuration object	required

Returns:

Type	Description
`Optional[str]`	str \| None: site url

`get_value_from_dot_key(data, dot_key)` #

Retrieves a value from a dictionary using a dot notation key.

Parameters:

Name	Type	Description	Default
`data`	`dict`	the dictionary from which to retrieve the value.	required
`dot_key`	`str \| bool`	The key in dot notation to specify the path in the dictionary.	required

Returns:

Name	Type	Description
`Any`	`Any`	The value retrieved from the dictionary, or None if the key does not exist.

`guess_locale(mkdocs_config)` #

Extract language code from MkDocs or Theme configuration.

Parameters:

Name	Type	Description	Default
`mkdocs_config`	`MkDocsConfig`	configuration object	required

Returns:

Type	Description
`Optional[str]`	str \| None: language code

Integrations#

Bases: IntegrationMaterialThemeBase

`init(mkdocs_config, switch_force=True)` #

Integration instantiation.

Parameters:

Name	Type	Description	Default
`mkdocs_config`	`MkDocsConfig`	Mkdocs website configuration object.	required
`switch_force`	`bool`	option to force integration disabling. Set it to False to disable it even if Social Cards are enabled in Mkdocs configuration. Defaults to True.	`True`

`get_social_card_build_path_for_page(mkdocs_page, mkdocs_site_dir=None)` #

Get social card path in Mkdocs build dir for a specific page.

Parameters:

Name	Type	Description	Default
`mkdocs_page`	`Page`	Mkdocs page object.	required
`mkdocs_site_dir`	`Optional[str]`	Mkdocs build site dir. If None, the 'class.mkdocs_site_build_dir' is used. is Defaults to None.	`None`

Returns:

Name	Type	Description
`Path`	`Optional[Path]`	path to the image once published

`get_social_card_cache_path_for_page(mkdocs_page)` #

Get social card path in social plugin cache folder for a specific page.

Note

As we write this code (June 2024), the cache mechanism in Insiders edition has stores images directly with the corresponding Page's path and name and keep a correspondance matrix with hashes in a manifest.json; the cache mechanism in Community edition uses the hash as file names without any exposed matching criteria.

Parameters:

Name	Type	Description	Default
`mkdocs_page`	`Page`	Mkdocs page object.	required

Returns:

Name	Type	Description
`Path`	`Optional[Path]`	path to the image in local cache folder if it exists

`get_social_card_url_for_page(mkdocs_page, mkdocs_site_url=None)` #

Get social card URL for a specific page in documentation.

Parameters:

Name	Type	Description	Default
`mkdocs_page`	`Page`	Mkdocs page object.	required
`mkdocs_site_url`	`Optional[str]`	Mkdocs site URL. If None, the 'class.mkdocs_site_url' is used. is Defaults to None.	`None`

Returns:

Name	Type	Description
`str`	`str`	URL to the image once published

`get_social_cards_build_dir(mkdocs_config)` #

Get Social Cards folder within Mkdocs site_dir. See: https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_dir

Parameters:

Name	Type	Description	Default
`mkdocs_config`	`MkDocsConfig`	Mkdocs website configuration object.	required

Returns:

Name	Type	Description
`str`	`Path`	True if the theme material and the plugin social cards is enabled.

`get_social_cards_cache_dir(mkdocs_config)` #

Get Social Cards folder within Mkdocs site_dir. See: https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_dir

Parameters:

Name	Type	Description	Default
`mkdocs_config`	`MkDocsConfig`	Mkdocs website configuration object.	required

Returns:

Name	Type	Description
`str`	`Path`	True if the theme material and the plugin social cards is enabled.

`is_social_plugin_and_cards_enabled_mkdocs(mkdocs_config)` #

Check if social cards plugin is enabled.

Parameters:

Name	Type	Description	Default
`mkdocs_config`	`MkDocsConfig`	Mkdocs website configuration object.	required

Returns:

Name	Type	Description
`bool`	`bool`	True if the theme material and the plugin social cards is enabled.

`is_social_plugin_enabled_mkdocs(mkdocs_config=None)` #

Check if social plugin is installed and enabled.

Parameters:

Name	Type	Description	Default
`mkdocs_config`	`Optional[MkDocsConfig]`	Mkdocs website configuration object.	`None`

Returns:

Name	Type	Description
`bool`	`bool`	True if the theme material and the plugin social cards is enabled.

`is_social_plugin_enabled_page(mkdocs_page, fallback_value=True)` #

Check if the social plugin is enabled or disabled for a specific page. Plugin has to be enabled in Mkdocs configuration before.

Parameters:

Name	Type	Description	Default
`mkdocs_page`	`Page`	Mkdocs page object.	required
`fallback_value`	`bool`	fallback value. It might be the 'plugins.social.cards.enabled' option in Mkdocs config. Defaults to True.	`True`

Returns:

Name	Type	Description
`bool`	`bool`	True if the social cards are enabled for a page.

`load_cache_cards_manifest()` #

Load social cards manifest if the file exists.

Returns:

Type	Description
`Optional[dict]`	dict \| None: manifest as dict or None if the file does not exist

API#

Core#

__init__(*args, **kwargs) #

on_config(config) #

on_page_content(html, page, config, files) #

on_post_build(config) #

on_startup(*, command, dirty) #

__init__(cache_dir=DEFAULT_CACHE_FOLDER, integration_material_blog=None, integration_material_social_cards=None, mkdocs_command_is_on_serve=False, path='.', use_git=True) #

build_url(base_url, path, args_dict=None) #

feed_to_json(feed, *, updated=False) staticmethod #

filter_pages(pages, attribute, length) staticmethod #

get_authors_from_meta(in_page) #

get_categories_from_meta(in_page, categories_labels) #

get_date_from_meta(date_metatag_value, meta_datetime_format, meta_datetime_timezone, meta_default_time) #

get_description_or_abstract(in_page, chars_count=160, abstract_delimiter=None) #

get_file_dates(in_page, source_date_creation, source_date_update, meta_datetime_format, meta_default_time, meta_default_timezone) #

get_image(in_page, base_url) #

get_local_image_length(page_path, path_to_append) #

get_remote_image_length(image_url, http_method='HEAD', attempt=0, ssl_verify=True) cached #

get_site_url(mkdocs_config) staticmethod #

get_value_from_dot_key(data, dot_key) #

guess_locale(mkdocs_config) #

Integrations#

__init__(mkdocs_config, switch_force=True) #

get_social_card_build_path_for_page(mkdocs_page, mkdocs_site_dir=None) #

get_social_card_cache_path_for_page(mkdocs_page) #

get_social_card_url_for_page(mkdocs_page, mkdocs_site_url=None) #

get_social_cards_build_dir(mkdocs_config) #

get_social_cards_cache_dir(mkdocs_config) #

is_social_plugin_and_cards_enabled_mkdocs(mkdocs_config) #

is_social_plugin_enabled_mkdocs(mkdocs_config=None) #

is_social_plugin_enabled_page(mkdocs_page, fallback_value=True) #

load_cache_cards_manifest() #

`init(*args, **kwargs)` #

`on_config(config)` #

`on_page_content(html, page, config, files)` #

`on_post_build(config)` #

`on_startup(*, command, dirty)` #

`init(cache_dir=DEFAULT_CACHE_FOLDER, integration_material_blog=None, integration_material_social_cards=None, mkdocs_command_is_on_serve=False, path='.', use_git=True)` #

`build_url(base_url, path, args_dict=None)` #

`feed_to_json(feed, *, updated=False)` `staticmethod` #

`filter_pages(pages, attribute, length)` `staticmethod` #

`get_authors_from_meta(in_page)` #

`get_categories_from_meta(in_page, categories_labels)` #

`get_date_from_meta(date_metatag_value, meta_datetime_format, meta_datetime_timezone, meta_default_time)` #

`get_description_or_abstract(in_page, chars_count=160, abstract_delimiter=None)` #

`get_file_dates(in_page, source_date_creation, source_date_update, meta_datetime_format, meta_default_time, meta_default_timezone)` #

`get_image(in_page, base_url)` #

`get_local_image_length(page_path, path_to_append)` #

`get_remote_image_length(image_url, http_method='HEAD', attempt=0, ssl_verify=True)` `cached` #

`get_site_url(mkdocs_config)` `staticmethod` #

`get_value_from_dot_key(data, dot_key)` #

`guess_locale(mkdocs_config)` #

`init(mkdocs_config, switch_force=True)` #

`get_social_card_build_path_for_page(mkdocs_page, mkdocs_site_dir=None)` #

`get_social_card_cache_path_for_page(mkdocs_page)` #

`get_social_card_url_for_page(mkdocs_page, mkdocs_site_url=None)` #

`get_social_cards_build_dir(mkdocs_config)` #

`get_social_cards_cache_dir(mkdocs_config)` #

`is_social_plugin_and_cards_enabled_mkdocs(mkdocs_config)` #

`is_social_plugin_enabled_mkdocs(mkdocs_config=None)` #

`is_social_plugin_enabled_page(mkdocs_page, fallback_value=True)` #

`load_cache_cards_manifest()` #