docs: working on new version

Guts · Dec 12, 2023 · df59a79 · df59a79
1 parent 9892f9a
commit df59a79
Show file tree

Hide file tree

Showing 6 changed files with 118 additions and 48 deletions.
diff --git 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
@@ -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
@@ -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 `<head>`, through template customization in `main.html` :
-
-```html
-{% extends "base.html" %}
-
-{% block extrahead %}
-  <!-- RSS Feed -->
-  <link rel="alternate" type="application/rss+xml" title="RSS feed of created content" href="{{ config.site_url }}feed_rss_created.xml">
-  <link rel="alternate" type="application/rss+xml" title="RSS feed of updated content" href="{{ config.site_url }}feed_rss_updated.xml">
-{% endblock %}
-```
-
 <!-- Hyperlinks reference -->
 [page metadata]: https://python-markdown.github.io/extensions/meta_data/
diff --git 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 <dev@ingeoveritas.com>
+  - Tim Vink <vinktim@gmail.com>
 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
+<!-- termynal: {"prompt_literal_start": [">"], title: Terminal} -->
+
+```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
@@ -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 `<head>` 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 %}
+  <!-- RSS Feed -->
+  <link rel="alternate" type="application/rss+xml" title="RSS feed of created content" href="{{ config.site_url }}feed_rss_created.xml">
+  <link rel="alternate" type="application/rss+xml" title="RSS feed of updated content" href="{{ config.site_url }}feed_rss_updated.xml">
+{% endblock %}
+```
diff --git 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: <!-- more -->
       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: <!-- more -->
+      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,15 +102,18 @@ 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
   favicon: assets/logo_rss_plugin_mkdocs.svg
   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