API#
Core#
Bases: BasePlugin[RssPluginConfig]
Main class for MkDocs plugin.
__init__() #
Instanciation.
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. https://www.mkdocs.org/user-guide/plugins/#on_config
:param config: global configuration object :type config: config_options.Config
:raises FileExistsError: if the template for the RSS feed is not found
:return: plugin configuration object :rtype: dict
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.
https://www.mkdocs.org/user-guide/plugins/#on_page_content
:param html: HTML rendered from Markdown source as string :type html: str :param page: mkdocs.nav.Page instance :type page: Page :param config: global configuration object :type config: config_options.Config :param files: global navigation object :type files: [type]
:return: HTML rendered from Markdown source as string :rtype: str
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
:param config: global configuration object :type config: config_options.Config :return: global configuration object :rtype: dict
Plugin logic.
__init__(path='.', use_git=True, integration_material_social_cards=None) #
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_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.
:param base_url: base URL with existing path to use :type base_url: str :param path: URL path to cumulate with existing :type path: str :param args_dict: URL arguments to add, defaults to None :type args_dict: dict, optional
:return: complete and valid URL :rtype: str
feed_to_json(feed, *, updated=False) staticmethod #
Format internal feed representation as a JSON Feed compliant dict.
:param feed: internal feed structure, i. e. GitRssPlugin.feed_created/feed_updated value :type feed: dict :param updated: True if this is a feed_updated :type updated: bool
:return: dict that can be passed to json.dump :rtype: dict
filter_pages(pages, attribute, length) staticmethod #
Filter and return pages into a friendly RSS structure.
:param pages: pages to filter :type pages: list :param attribute: page attribute as filter variable :type attribute: str :param length: max number of pages to return :type length: int
:return: list of filtered pages :rtype: list
get_authors_from_meta(in_page) #
Returns authors from page meta. It handles 'author' and 'authors' for keys, str and iterable as values types.
:param in_page: page to look into :type in_page: Page
:return: tuple of authors names :rtype: Tuple[str] or None
get_categories_from_meta(in_page, categories_labels) #
Returns category from page meta.
:param in_page: input page to parse :type in_page: Page :param categories_labels: meta tags to look into :type categories_labels: Iterable
:return: found categories :rtype: tuple
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.
:param date_metatag_value: value of page.meta.{tag_for_date} :type date_metatag_value: str :param meta_datetime_format: expected format of datetime :type meta_datetime_format: str :param meta_datetime_timezone: timezone to use :type meta_datetime_timezone: str :param meta_default_time: time to set if not specified :type meta_default_time: datetime
:return: datetime :rtype: datetime
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).
:param Page in_page: page to look at :param int chars_count: if page.meta.description is not set, number of chars of the content to use. Defaults to: 160 - optional :param str abstract_delimiter: description delimiter, defaults to None
:return: page description to use :rtype: str
get_file_dates(in_page, source_date_creation='git', source_date_update='git', meta_datetime_format='%Y-%m-%d %H:%M', meta_default_timezone='UTC', meta_default_time=None) #
Extract creation and update dates from page metadata (yaml frontmatter) or git log for given file.
:param in_page: input page to work with :type in_page: Page :param source_date_creation: which source to use (git or meta tag) for creation date, defaults to "git" :type source_date_creation: str, optional :param source_date_update: which source to use (git or meta tag) for update date, defaults to "git" :type source_date_update: str, optional :param meta_datetime_format: datetime string format, defaults to "%Y-%m-%d %H:%M" :type meta_datetime_format: str, optional :param meta_default_timezone: timezone to use, defaults to "UTC" :type meta_default_timezone: str, optional :param meta_default_time: time to set if not specified, defaults to None :type meta_default_time: datetime, optional
:return: tuple of timestamps (creation date, last commit date) :rtype: Tuple[datetime, datetime]
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 | int | size in octets |
get_remote_image_length(image_url, http_method='HEAD', attempt=0, ssl_context=None) #
Retrieve length for remote images (starting with 'http' in meta.image or meta.illustration). 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.
:param image_url: remote image URL :type image_url: str :param http_method: HTTP method used to perform request, defaults to "HEAD" :type http_method: str, optional :param attempt: request tries counter, defaults to 0 :type attempt: int, optional :param ssl_context: SSL context, defaults to None :type ssl_context: ssl.SSLContext, optional
:return: image length as str or None :rtype: Optional[int]
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.
:param mkdocs_config: configuration object :type mkdocs_config: Config
:return: site url :rtype: str or None
get_value_from_dot_key(data, dot_key) #
Retrieves a value from a dictionary using a dot notation key.
:param data: The dictionary from which to retrieve the value. :type data: dict :param dot_key: The key in dot notation to specify the path in the dictionary. :type dot_key: Union[str, bool]
:return: The value retrieved from the dictionary, or None if the key does not exist. :rtype: Any
guess_locale(mkdocs_config) #
Extract language code from MkDocs or Theme configuration.
:param mkdocs_config: configuration object :type mkdocs_config: Config
:return: language code :rtype: str or None
Integrations#
__init__(mkdocs_config, switch_force=True) #
Integration instanciation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mkdocs_config | Config | 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 URL for a specific page in documentation.
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 |
|---|---|---|
str | Path | URL to the image once published |
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_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 | Config | Mkdocs website configuration object. | required |
Returns:
| Name | Type | Description |
|---|---|---|
str | str | 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 | Config | 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) #
Check if social plugin is installed and enabled.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mkdocs_config | Config | 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_page(mkdocs_page, fallback_value=True) #
Check if the social plugin is enabled or disabled for a specific page. Plugin has to 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. |
is_theme_material(mkdocs_config) #
Check if the theme set in mkdocs.yml is material or not.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
mkdocs_config | Config | Mkdocs website configuration object. | required |
Returns:
| Name | Type | Description |
|---|---|---|
bool | bool | True if the theme's name is 'material'. False if not. |