diff --git a/README.md b/README.md index b509ec9a..54397516 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,12 @@ A plugin for [MkDocs](https://www.mkdocs.org), the static site generator, which creates [RSS 2.0](https://wikipedia.org/wiki/RSS) feeds using the creation and modification dates from [git log](https://git-scm.com/docs/git-log) and page metadata ([YAML frontmatter](https://www.mkdocs.org/user-guide/writing-your-docs/#yaml-style-meta-data)). +## Installation + +```sh +pip install mkdocs-rss-plugin +``` + ## Usage Minimal [`mkdocs.yml` configuration](https://www.mkdocs.org/user-guide/configuration/#project-information): diff --git a/docs/changelog.md b/docs/changelog.md index f756eaa5..350c0564 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -1,7 +1,12 @@ --- -title: Changelog for the MkDocs RSS Plugin -description: "Changelog of the RSS plugin for MkDocs." -categories: ["Release notes", "test"] +title: Changelog +description: "Release notes of the RSS plugin for MkDocs." +categories: + - Release notes +search: + exclude: true +tags: + - development --- --8<-- "CHANGELOG.md" diff --git a/docs/configuration.md b/docs/configuration.md index 754b94a8..dfb38dad 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -4,15 +4,13 @@ authors: - "Julien Moura" date: 2020-12-31 14:20 description: Configuration steps and settings for MkDocs RSS plugin -image: "https://svgsilh.com/png-512/97849.png" +image: https://svgsilh.com/png-512/97849.png tags: - settings - options - plugin --- -# Configuration - To produce a valid RSS feed, the plugin uses: - some global settings from [MkDocs configuration](#mkdocs-configuration) @@ -132,7 +130,7 @@ Output: ## Plugin options -For a sample see [homepage](../#usage). +For a sample see [homepage](./index.md#quickstart). ### Disabling the plugin @@ -426,23 +424,5 @@ Will result in: Default: `None`. ----- - -## Integration - -### Reference RSS feeds in HTML meta-tags - -To facilitate the discovery of RSS feeds, it's recommended to add relevant meta-tags into the pages ``, through template customization in `main.html` : - -```html -{% extends "base.html" %} - -{% block extrahead %} - - - -{% endblock %} -``` - [page metadata]: https://python-markdown.github.io/extensions/meta_data/ diff --git a/docs/index.md b/docs/index.md index 69ab65a7..308e9bd4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,24 +1,50 @@ --- title: The MkDocs RSS Plugin -authors: ["dev@ingeoveritas.com (Julien Moura)", "vinktim@gmail.com (Tim Vink)"] +authors: + - Julien Moura + - Tim Vink date: 2020-07-06 -description: "MkDocs RSS plugin: generate RSS feeds for your static website using git log." +description: "MkDocs RSS plugin: generate RSS feeds for your static website using git log ad YAML frontmatter (markdown pages'metadata header)." image: "rss_icon.svg" +tags: + - Mkdocs + - plugin + - RSS --- ---8<-- "README.md" +[![PyPi version badge](https://badgen.net/pypi/v/mkdocs-rss-plugin)](https://pypi.org/project/mkdocs-rss-plugin/) +[![PyPI - Downloads](https://img.shields.io/pypi/dm/mkdocs-rss-plugin)](https://pypi.org/project/mkdocs-rss-plugin/) +[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mkdocs-rss-plugin)](https://pypi.org/project/mkdocs-rss-plugin/) + +[![codecov](https://codecov.io/gh/Guts/mkdocs-rss-plugin/branch/main/graph/badge.svg?token=A0XPLKiwiW)](https://codecov.io/gh/Guts/mkdocs-rss-plugin) +[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) +[![flake8](https://img.shields.io/badge/linter-flake8-green)](https://flake8.pycqa.org/) +[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/) +[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit) +[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/Guts/mkdocs-rss-plugin/master.svg)](https://results.pre-commit.ci/latest/github/Guts/mkdocs-rss-plugin/master) +[![📚 Documentation](https://github.com/Guts/mkdocs-rss-plugin/actions/workflows/documentation.yml/badge.svg)](https://github.com/Guts/mkdocs-rss-plugin/actions/workflows/documentation.yml) + +A plugin for [MkDocs](https://www.mkdocs.org), the static site generator, which creates [RSS 2.0](https://wikipedia.org/wiki/RSS) feeds using the creation and modification dates from [git log](https://git-scm.com/docs/git-log) and page metadata ([YAML frontmatter](https://www.mkdocs.org/user-guide/writing-your-docs/#yaml-style-meta-data)). ## Quickstart Installation: -```bash -pip install mkdocs-rss-plugin + + +```sh +> pip install mkdocs-rss-plugin +---> 100% +RSS plugin for Mkdocs installed! Add 'rss' to your 'plugins' section in mkdocs.yml ``` Then in your `mkdocs.yml`: -```yml +```yaml +site_description: required. Used as feed mandatory channel description. +site_name: required. Used as feed mandatory channel title and items source URL label. +site_url: required. Used to build feed items URLs. + plugins: - rss ``` @@ -33,16 +59,15 @@ As examples, here come the feeds generated for this documentation: Or it could be displayed as a Feedly follow button: [![Feedly button](https://s3.feedly.com/img/follows/feedly-follow-rectangle-flat-big_2x.png "Follow us on Feedly"){: width=130 height= 50 loading=lazy }](https://feedly.com/i/subscription/feed%2Fhttps%3A%2F%2Fguts.github.io%2Fmkdocs-rss-plugin%2Ffeed_rss_created.xml) +{: align=middle } ## Credits ![RSS logo](rss_icon.svg "RSS icon - Wikimedia"){: align=right } -Plugin logic is inspired from [Tim Vink git-based plugins](https://github.com/timvink?tab=repositories&q=mkdocs-git&type=&language=) and main parts of Git stuff are nearly copied/pasted. - -Using magic from: - -- [GitPython](https://gitpython.readthedocs.io/) -- [Jinja2](https://jinja.palletsprojects.com/en/2.11.x/) - -Documentation theme [United from mkdocs-bootswatch](https://mkdocs.github.io/mkdocs-bootswatch/#united) as a tribute to the classic RSS color scheme: orange and white. +- Plugin logic is inspired from [Tim Vink git-based plugins](https://github.com/timvink?tab=repositories&q=mkdocs-git&type=&language=) and main parts of Git stuff are nearly copied/pasted. +- Using magic mainly from: + - [GitPython](https://gitpython.readthedocs.io/) + - [Jinja2](https://jinja.palletsprojects.com/) +- Documentation colors are a tribute to the classic RSS color scheme: orange and white. +- Logo generated with DALL·E. diff --git a/docs/integrations.md b/docs/integrations.md new file mode 100644 index 00000000..e23482c0 --- /dev/null +++ b/docs/integrations.md @@ -0,0 +1,26 @@ +--- +title: Integrations +icon: octicons/plug-16 +--- + +## Reference RSS feeds in HTML meta-tags + +To facilitate the discovery of RSS feeds, it's recommended to add relevant meta-tags in `` section in HTML pages. + +### Automatically set with Material theme + +If you're using the Material theme, everything is automagically set up (see [the related documentation page](https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#rss)) :partying_face:. + +### Manually + +You need to customize the theme's template. Typically, in `main.html`: + +```html +{% extends "base.html" %} + +{% block extrahead %} + + + +{% endblock %} +``` diff --git a/mkdocs.yml b/mkdocs.yml index ec43aa05..628c5d89 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -14,6 +14,15 @@ edit_uri: blob/main/docs/ docs_dir: "docs/" use_directory_urls: true +extra: + social: + - icon: "fontawesome/brands/mastodon" + link: https://mapstodon.space/@geojulien + name: "Follow me on Mastodon" + - icon: "fontawesome/solid/piggy-bank" + link: /team/sponsoring/ + name: "Sponsor development" + # Extensions to enhance markdown markdown_extensions: - admonition @@ -26,10 +35,11 @@ markdown_extensions: anchor_linenums: true line_spans: __span pygments_lang_class: true - use_pygments: true + - pymdownx.inlinehilite - pymdownx.snippets: base_path: "." check_paths: true + - pymdownx.superfences - pymdownx.tabbed: alternate_style: true slugify: !!python/object/apply:pymdownx.slugs.slugify @@ -39,9 +49,12 @@ markdown_extensions: permalink: "#" nav: - - "Home": "index.md" - - "Settings": "configuration.md" - - "Changelog": "changelog.md" + - Home: index.md + - Settings: + - configuration.md + - integrations.md + - Contributing: contributing.md + - Changelog: changelog.md plugins: - git-committers: @@ -68,17 +81,18 @@ plugins: cache_dir: !ENV [MKDOCS_PLUGIN_PRIVACY_EXTERNAL_CACHE_DIR, .cache/plugins/privacy] - rss: + abstract_chars_count: 160 + abstract_delimiter: date_from_meta: as_creation: "date" as_update: false datetime_format: "%Y-%m-%d %H:%M" default_timezone: "Europe/Paris" default_time: "22:00" - abstract_chars_count: 160 - abstract_delimiter: + enabled: !ENV [MKDOCS_ENABLE_PLUGIN_RSS, true] image: https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Feed-icon.svg/128px-Feed-icon.svg.png match_path: ".*" - pretty_print: false + pretty_print: true url_parameters: utm_source: "documentation" utm_medium: "RSS" @@ -88,7 +102,11 @@ plugins: - social: enabled: !ENV [MKDOCS_ENABLE_PLUGIN_SOCIAL, true] cache_dir: !ENV [MKDOCS_PLUGIN_SOCIAL_CACHE_DIR, .cache/plugins/social] - - termynal + - termynal: + title: "Youpi" + prompt_literal_start: + - "$" + - ">" theme: name: material @@ -96,7 +114,6 @@ theme: features: - content.action.edit - content.action.view - - content.code.annotate - content.code.copy - content.tabs.link - content.tooltips @@ -109,6 +126,7 @@ theme: - search.share - search.suggest - toc.follow + - toc.integrate font: code: Ubuntu Mono text: Ubuntu @@ -125,6 +143,16 @@ theme: primary: deep orange scheme: default +validation: + links: + absolute_links: warn + not_found: warn + unrecognized_links: warn + nav: + absolute_links: warn + not_found: warn + omitted_files: warn + watch: - CONTRIBUTING.md - README.md