Skip to content

# API

## Core

### `mkdocs_rss_plugin.plugin.GitRssPlugin(*args, **kwargs)`

Bases: `BasePlugin[RssPluginConfig]`

Main class for MkDocs plugin.

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
--- | ---
`str | None` | 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

### `mkdocs_rss_plugin.config.RssPluginConfig`

Bases: `Config`

Configuration for RSS plugin for Mkdocs.

### `mkdocs_rss_plugin.config._DateFromMeta`

Bases: `Config`

Sub configuration object for related date options.

### `mkdocs_rss_plugin.config._FeedsFilenamesConfig`

Bases: `Config`

Sub configuration for feeds filenames.

### `mkdocs_rss_plugin.constants`

## Models

### `mkdocs_rss_plugin.models.PageInformation(abs_path=None, categories=None, authors=None, comments_url=None, created=None, description=None, guid=None, image=None, link=None, pub_date=None, title=None, updated=None, _mkdocs_page_ref=None)` `dataclass`

Object describing a page information gathered from Mkdocs and used as feed's item.

### `mkdocs_rss_plugin.models.RssFeedBase(author=None, buildDate=None, copyright=None, description=None, entries=list(), generator=f'{__title__} - v{__version__}', html_url=None, json_url=None, language=None, logo_url=None, pubDate=None, repo_url=None, rss_url=None, stylesheet=None, title=None, ttl=None)` `dataclass`

Object describing a feed.

## Integrations

### `mkdocs_rss_plugin.integrations.theme_material_base.IntegrationMaterialThemeBase(mkdocs_config)`

Integration instantiation.

Parameters:

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

#### `is_mkdocs_theme_material(mkdocs_config=None)`

Check if the theme set in mkdocs.yml is material or not.

Parameters:

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

Returns:

Name | Type | Description
--- | --- | ---
`bool` | `bool` | True if the theme's name is 'material' or 'materialx'. False if not.

### `mkdocs_rss_plugin.integrations.theme_material_blog_plugin.IntegrationMaterialBlog(mkdocs_config, switch_force=True)`

Bases: `IntegrationMaterialThemeBase`

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`

#### `author_name_from_id(author_id)` `cached`

Return author name from author_id used in Material blog plugin (.authors.yml).

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`author_id` | `str` | author key in .authors.yml | required

Returns:

Name | Type | Description
--- | --- | ---
`str` | `str` | author name or passed author_id if not found within .authors.yml

#### `is_blog_plugin_enabled_mkdocs(mkdocs_config)`

Check if blog plugin is installed and enabled.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`mkdocs_config` | `Optional[MkDocsConfig]` | Mkdocs website configuration object. | required

Returns:

Name | Type | Description
--- | --- | ---
`bool` | `bool` | True if the theme material and the plugin blog is enabled.

#### `is_page_a_blog_post(mkdocs_page)`

Identifies if the given page is part of Material Blog.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`mkdocs_page` | `Union[Post, MkdocsPageSubset]` | page to identify | required

Returns:

Type | Description
--- | ---
`bool` | True if the given page is a Material Blog post.

### `mkdocs_rss_plugin.integrations.theme_material_social_plugin.IntegrationMaterialSocialCards(mkdocs_config, switch_force=True)`

Bases: `IntegrationMaterialThemeBase`

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` | `MkdocsPageSubset` | Mkdocs page object. | required
`mkdocs_site_dir` | `str | None` | Mkdocs build site dir. If None, the 'class.mkdocs_site_build_dir' is used. is Defaults to None. | `None`

Returns:

Type | Description
--- | ---
`Path | None` | 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.

The cache mechanism in stores images directly with the corresponding Page's path and name and keep a correspondance matrix with hashes in a manifest.json.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`mkdocs_page` | `MkdocsPageSubset` | Mkdocs page object. | required

Returns:

Type | Description
--- | ---
`Path | None` | 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` | `MkdocsPageSubset` | subset of Mkdocs page object. | required
`mkdocs_site_url` | `str | None` | Mkdocs site URL. If None, the 'class.mkdocs_site_url' is used. is Defaults to None. | `None`

Returns:

Type | Description
--- | ---
`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
--- | --- | ---
`Path` | `Path` | Absolute path of the assets dir 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
--- | --- | ---
`Path` | `Path` | The cache dir if the theme material and the plugin social cards is enabled.

#### `get_social_cards_dir(mkdocs_config)`

Get Social Cards folder relative to 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` | `str` | The cards_dir 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` | `MkdocsPageSubset` | 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:

Type | Description
--- | ---
`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
--- | ---
`dict | None` | dict | None: manifest as dict or None if the file does not exist

## Utils

### `mkdocs_rss_plugin.git_manager.ci.CiHandler(repo)`

Helper class to handle CI specific warnings.

Initialize the CI handler.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`repo` | `Git` | Git repository object | required

#### `commit_count()`

Helper function to determine the number of commits in a repository.

Returns:

Name | Type | Description
--- | --- | ---
`int` | `int` | Number of commits

#### `is_shallow_clone()`

Helper function to determine if repository is a shallow clone.

References & Context: - https://github.com/timvink/mkdocs-rss-plugin/issues/10 - https://stackoverflow.com/a/37203240/5525118

Returns:

Name | Type | Description
--- | --- | ---
`bool` | `bool` | True if a repo is shallow clone

#### `raise_ci_warnings()`

Raise warnings when users use mkdocs-rss-plugin on CI build runners.

### `mkdocs_rss_plugin.timezoner`

Manage timezones for pages date(time)s using zoneinfo module, added in Python 3.9.

#### `set_datetime_zoneinfo(input_datetime, config_timezone='UTC')`

Apply timezone to a naive datetime.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`input_datetime` | `datetime` | offset-naive datetime | required
`config_timezone` | `str` | name of timezone as registered in IANA database. Defaults to "UTC". Example : Europe/Paris. | `'UTC'`

Returns:

Name | Type | Description
--- | --- | ---
`datetime` | `datetime` | offset-aware datetime

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

Plugin logic.

Class hosting the plugin logic.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`cache_dir` | `Path` | description. Defaults to DEFAULT_CACHE_FOLDER. | `DEFAULT_CACHE_FOLDER`
`integration_material_blog` | `bool` | option to enable integration with Blog plugin from Material theme. Defaults to None. | `None`
`integration_material_social_cards` | `bool` | option to enable integration with Social Cards plugin from Material theme. Defaults to None. | `None`
`mkdocs_command_is_on_serve` | `bool` | description. Defaults to False. | `False`
`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`

#### `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)` `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

Returns:

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

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

Filter pages based on an attribute and a max number of items.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`pages` | `list[PageInformation]` | pages to filter | required
`filter_attribute` | `Literal['created', 'updated']` | page attribute to use as filter variable | required
`length` | `int` | max number of pages to return | required

Returns:

Type | Description
--- | ---
`list[PageInformation]` | 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` | `MkdocsPageSubset` | 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]]` | (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, req_timeout=(5, 30), 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`
`req_timeout` | `tuple[float, float]` | (connect, read) timeout in secondes. Defaults to (5, 30). | `(5, 30)`
`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

#### `load_images_for_pages(pages, base_url, processed_refs=None)`

Load images for a list of pages (mutation in-place).

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`pages` | `list[PageInformation]` | list of PageInformation | required
`base_url` | `str` | final website base URL | required
`processed_refs` | `Optional[set]` | deduplication set | `None`