Merge pull request #5 from liang2kl/dev

v1.0.0 release

README.md

@@ -2,110 +2,32 @@
 
 A mkdocs plugin that generates a blog page listing selected pages, sorted by time.
 
-A complete guide is available at https://liang2kl.github.io/mkdocs-blogging-plugin.
-You might need the [migration guide](https://liang2kl.github.io/mkdocs-blogging-plugin/migration)
-to upgrade to a new version.
+- Automatically generates a blog index page
+- Can be grouped by tags
+- Support deep customization without dirty work
 
-![preview](https://i.loli.net/2021/09/09/LhX9IFkbu2K3lRi.png)
-
-## Installation
-
-```shell
-pip3 install mkdocs-blogging-plugin
-```
+![preview](https://s2.loli.net/2021/12/03/GqhwCYTsimlkXK1.png)
 
 ## Prerequisites
 
-- Only `material` theme is adapted by far (pull requests are welcome).
-- `navigation.instant` feature cannot be enabled if blog paging is on.
-- Windows is not supported currently (pull requests are welcome).
-
-## Usage
-
-Add `blogging` in `plugins` and specify the directories to be included:
-
-```yml
-plugins:
-  - blogging:
-      dirs: # The directories to be included
-        - blog
-```
-
-In the page you want to insert the blog content, just add a line `{{ blog_content }}` into your desired place:
-
-```markdown
-# Blogs
-
-{{ blog_content }}
-```
-
-Optionally, in your articles, add meta tags providing their titles and descriptions, which will be displayed on the blog page:
+- Only `material` theme is adapted by far
+- `navigation.instant` feature cannot be enabled if blog paging is on
+- Windows is not supported currently
 
-```markdown
----
-title: Lorem ipsum dolor sit amet
-description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
----
-```
-
-To exclude certain pages from the blog collection, add a meta tag `exculde_from_blog` in the meta section of the markdown file:
-
-```markdown
----
-exculde_from_blog: true
----
-```
-
-And it's done! You can open the page where you insert `{{ blog_content }}` and see how it is working.
+Pull requests are welcome to break these constraints.
 
-Some more steps need to be taken if you want to host your blog with GitHub Pages.
-Please refer to [Publishing on Github Pages](#publish-on-github-pages).
-
-## Customization
-
-### Options
-
-Optionally, you can customize some behaviours of the plugin:
+## Installation
 
-```yml
-theme:             # Use a predefined theme
-  name: card
-size: 5            # Number of articles in one page, default: 10
-locale: en         # The locale for time localizations, default: system's locale
-sort: 
-  from: new        # Sort from new to old, default
-  # or old         # Sort from old to new
-  by: creation     # Sort by the first commit time, default
-  # or revision    # Sort by the latest commit time
-paging: false      # Disable paging
-show_total: false  # Remove 'total pages' label
-template: blog-override.html # Path to customized template
+```shell
+pip3 install mkdocs-blogging-plugin
 ```
 
-Check [the guide](https://liang2kl.github.io/mkdocs-blogging-plugin) for more detail.
-
-## Publish on Github Pages
-
-A few more steps need to be taken for hosting with Github Pages:
-
-- Set `fetch-depth` to `0` when checking out with `actions/checkout`:
-
-  ```yml
-  - uses: actions/checkout@v2
-    with:
-      fetch-depth: 0
-  ```
-
-  Creation and revision time for articles rely on git logs, so a complete respository is required.
-  If it is not set, the plugin will take the latest commit time as fallback.
+## Usage
 
-- Configure your locale in the plugin's configuration:
+A complete guide is available at https://liang2kl.github.io/mkdocs-blogging-plugin.
 
-  ```yml
-  locale: zh-CN
-  ```
-
-  Otherwise, the plugin will use locale of the server, which might not be expected.
+You might need to follow the [migration guide](https://liang2kl.github.io/mkdocs-blogging-plugin/migration)
+to upgrade to a new version.
 
 ## Credits
 

docs/features.md

@@ -0,0 +1,77 @@
+## Tags
+
+This feature enables you to set tags for articles, which can be used to group them into different topics.
+
+![preview](https://s2.loli.net/2021/12/03/H8wD4yY6W57TFbg.png)
+
+### Setup
+
+First, enable `tags` in the `features` entry of the configuration. Note that it is a dict, so by default (with no customize options), you should provide an empty dict `{}`:
+
+```yaml title="mkdocs.yml"
+features:
+  tags: {}
+```
+
+And, in any article to be tagged (including those not in the designated blog collection), add any number of tags in the meta section:
+
+```markdown title="article"
+---
+tags:
+  - mkdocs
+  - blogging
+---
+```
+
+Now, if you are not using customized templates, the tags will be displayed on the blog entries.
+
+For those who use a [customized template](template.md), you need a little extra work to get there. In the place you want to insert the tags of a page, insert following content, where `page` should be replaced by your naming of the variable, if necessary:
+
+```jinja title="template"
+{% if show_tags and "tags" in page.meta %}
+    {% call render_tags(page.meta["tags"], index_url) %}
+    {% endcall %}
+{% endif %}
+```
+
+### Get an index page
+
+Additionally, you can create an index page for all the tags and associated entries out of the box. Just like the blog content, add `{{ tag_content }}` in your desired position, and an index page will be there for you.
+
+```markdown title="tags index page"
+# Tags
+
+{{ tag_content }}
+```
+
+![preview](https://s2.loli.net/2021/12/03/AudcmgG9N5HzEn4.png)
+
+And, although you can insert the "index" page in multiple pages, it is recommended to specify a *true* index page, so that we can navigate the viewer to that page when they click on the tags. To achieve this, set `index_page` with the relative path of one of the page with `{{ tag_content }}`:
+
+```yaml title="mkdocs.yml"
+features:
+  tags:
+    index_page: tags.md
+```
+
+### Insert tags in articles
+
+You can display the tags of the article inside it if you like. Set `insert` to `top` or `bottom`, to add the tags to the top or bottom of all articles with at least one tag.
+
+```yaml title="mkdocs.yml"
+features:
+  tags:
+    insert: top
+```
+
+![preview](https://s2.loli.net/2021/12/03/DrYHLcmbqNKQznx.png)
+
+**Best practice**: rather than using Header 1 in the markdown, set the title in the meta section:
+
+```markdown title="article"
+---
+title: Lorem ipsum dolor sit amet
+---
+```
+
+With this, the tags will be correctly displayed below the header, rather than above it.

docs/index.md

@@ -12,15 +12,17 @@ pip3 install mkdocs-blogging-plugin
 
 ## Prerequisites
 
-- Only `material` theme is adapted by far (pull requests are welcome).
-- `navigation.instant` feature cannot be enabled if blog paging is on.
-- Windows is not supported currently (pull requests are welcome).
+- Only `material` theme is adapted by far
+- `navigation.instant` feature cannot be enabled if blog paging is on
+- Windows is not supported currently
+
+Pull requests are welcome to break these constraints.
 
 ## Usage
 
 Add `blogging` in `plugins` and specify the directories to be included:
 
-```yml
+``` yaml title="mkdocs.yml"
 plugins:
   - blogging:
       dirs: # The directories to be included
@@ -29,24 +31,45 @@ plugins:
 
 In the page you want to insert the blog content, just add a line `{{ blog_content }}` into your desired place:
 
-```markdown
+```markdown title="blog index page"
 # Blogs
 
 {{ blog_content }}
 ```
 
 Optionally, in your articles, add meta tags providing their titles and descriptions, which will be displayed on the blog page:
 
-```markdown
+```markdown title="article"
 ---
 title: Lorem ipsum dolor sit amet
 description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
 ---
 ```
 
+Additionally, you can also set tags for all articles, which can be access on certain pages. First, turn on this feature in the configuration:
+
+```yaml title="mkdocs.yml"
+plugins:
+  - blogging:
+      features:
+        tags: {}
+```
+
+And in articles:
+
+```markdown title="article"
+---
+tags:
+  - mkdocs
+  - blogging
+---
+```
+
+For more detail, check [Features - tags](features.md#tags).
+
 To exclude certain pages from the blog collection, add a meta tag `exculde_from_blog` in the meta section of the markdown file:
 
-```markdown
+```markdown title="article"
 ---
 exculde_from_blog: true
 ---
@@ -58,9 +81,12 @@ And it's done! You can open the page where you insert `{{ blog_content }}` and s
 
 Configure the plugin via following options:
 
-```yml
+```yaml title="mkdocs.yml"
 theme:             # Use a predefined theme
   name: card
+features:          # Additional features
+  tags:
+    ...
 size: 5            # Number of articles in one page, default: 10
 locale: en         # The locale for time localizations, default: system's locale
 sort: 
@@ -75,13 +101,13 @@ template: blog-override.html # Path to customized template
 
 For more about themes and custom templates, see [Themes](theme.md) and [Template](theme.md) respectively.
 
-## Publish on Github Pages
+## Publish with Github Pages
 
 A few more steps need to be taken for hosting with Github Pages:
 
 **Set `fetch-depth` to `0` when checking out with `actions/checkout`**
 
-```yml
+```yaml title="github action"
 - uses: actions/checkout@v2
   with:
     fetch-depth: 0
@@ -92,8 +118,10 @@ If it is not set, the plugin will take the latest commit time as fallback.
 
 **Configure your locale in the plugin's configuration**
 
-```yml
-locale: zh-CN
+```yaml title="article"
+plugins:
+  - blogging:
+      locale: zh-CN
 ```
 
 Otherwise, the plugin will use locale of the server, which might not be expected.

docs/migration.md

@@ -9,4 +9,12 @@ Breaking changes:
     - **Workaround:** Add a trailing parameter `page` to the marco.
 - Introduced new reserved template file names: `blog-*-theme.html`. 
     - **Effect:** If you have templates using these names, they might stop working now or in the future.
-    - **Workaround:** Rename them if your existing names of your templates have this pattern.
+    - **Workaround:** Rename them if your existing names of your templates have this pattern.
+
+## v0.3.x to v1.0.x
+
+Breaking changes:
+
+- Introduced new reserved template file names: `blog-*.html`. 
+    - **Effect:** If you have templates using these names, they might stop working now or in the future.
+    - **Workaround:** Rename them if your existing names of your templates have this pattern.