diff --git a/README.md b/README.md index ff7e101..2ed89c3 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ [![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)). +A plugin for [MkDocs](https://www.mkdocs.org), the static site generator, which creates [RSS 2.0](https://wikipedia.org/wiki/RSS) and [JSON Feed 1.1](https://www.jsonfeed.org/version/1.1/) 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 @@ -56,9 +56,11 @@ plugins: enabled: true feed_ttl: 1440 image: https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Feed-icon.svg/128px-Feed-icon.svg.png + json_feed_enabled: true length: 20 - pretty_print: false match_path: ".*" + pretty_print: false + rss_feed_enabled: true url_parameters: utm_source: "documentation" utm_medium: "RSS" diff --git a/docs/index.md b/docs/index.md index 530a232..6bd5ec3 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,9 +4,10 @@ authors: - dev@ingeoveritas.com (Julien Moura) - vinktim@gmail.com (Tim Vink) date: 2020-07-06 -description: "MkDocs RSS plugin: generate RSS feeds for your static website using git log ad YAML frontmatter (markdown pages'metadata header)." +description: "MkDocs RSS plugin: generate RSS and JSON feeds for your static website using git log ad YAML frontmatter (markdown pages'metadata header)." image: "assets/rss_icon.svg" tags: + - JSON Feed - Mkdocs - plugin - RSS @@ -49,6 +50,8 @@ plugins: - rss ``` +---- + ## Example As examples, here come the feeds generated for this documentation: @@ -61,13 +64,17 @@ 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 } +For JSON Feed, you can use the icon: + +[JSON Feed icon](https://jsonfeed.org/graphics/icon.png) + ## Credits ![RSS logo](assets/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 mainly from: - - [GitPython](https://gitpython.readthedocs.io/) - - [Jinja2](https://jinja.palletsprojects.com/) + - [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 index b832fd2..841fae8 100644 --- a/docs/integrations.md +++ b/docs/integrations.md @@ -27,7 +27,7 @@ To facilitate the discovery of RSS feeds, it's recommended to add relevant meta- 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 +### Manually { #feed-discovery-manual-rss } You need to customize the theme's template. Typically, in `main.html`: @@ -40,3 +40,27 @@ You need to customize the theme's template. Typically, in `main.html`: {% endblock %} ``` + +---- + +## Reference JSON feeds in HTML meta-tags + +To facilitate the discovery of JSON feeds, it's [recommended](https://www.jsonfeed.org/version/1.1/#discovery-a-name-discovery-a) to add relevant meta-tags in `` section in HTML pages. + + + +### Manually { #feed-discovery-manual-json } + +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 02d95bd..e55bdf0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,3 +1,5 @@ +# yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json + # Project information site_name: MkDocs RSS Plugin site_description: Documentation about the MkDocs RSS Plugin diff --git a/tests/fixtures/mkdocs_complete.yml b/tests/fixtures/mkdocs_complete.yml index b572a0d..a2136ff 100644 --- a/tests/fixtures/mkdocs_complete.yml +++ b/tests/fixtures/mkdocs_complete.yml @@ -26,13 +26,17 @@ plugins: enabled: true feed_ttl: 1440 image: https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Feed-icon.svg/128px-Feed-icon.svg.png + json_feed_enabled: true length: 20 - pretty_print: false match_path: ".*" + pretty_print: false + rss_feed_enabled: true url_parameters: utm_source: "documentation" utm_medium: "RSS" utm_campaign: "feed-syndication" + use_git: true + use_material_social_cards: true theme: name: readthedocs locale: fr