docs: add how to make JSON Feeds discoverable (#240)

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"

docs/index.md

@@ -4,9 +4,10 @@ authors:
   - [email protected] (Julien Moura)
   - [email protected] (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.

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`:
   <link rel="alternate" type="application/rss+xml" title="RSS feed of updated content" href="{{ config.site_url }}feed_rss_updated.xml">
 {% 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 `<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 { #feed-discovery-manual-json }
+
+You need to customize the theme's template. Typically, in `main.html`:
+
+```html
+{% extends "base.html" %}
+
+{% block extrahead %}
+  <!-- JSON Feed -->
+  <link rel="alternate" title="RSS feed of created content" type="application/feed+json" href="{{ config.site_url }}feed_rss_created.xml" />
+  <link rel="alternate" title="RSS feed of updated content" type="application/feed+json" href="{{ config.site_url }}feed_rss_updated.xml" />
+{% endblock %}
+```

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

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