Support per-category settings

README.md

@@ -1,10 +1,13 @@
 # mkdocs-blogging-plugin
 
-A mkdocs plugin that generates a blog page listing selected pages, sorted by time.
+A mkdocs plugin that generates a blog page listing selected pages, sorted by time. It supports:
 
-- Automatically generates a blog index page
-- Can be grouped by tags
-- Support deep customization without dirty work
+- Auto-generated blog pages
+- Tags
+- Category-level customization
+- Template-based customization
+
+Demo site: https://liang2kl.github.io/mkdocs-blogging-plugin-example
 
 ![preview](https://s2.loli.net/2021/12/03/GqhwCYTsimlkXK1.png)
 

docs/index.md

@@ -27,7 +27,10 @@ Before setting up the plugin, set `site_url` to the url of your published site:
 site_url: https://liang2kl.github.io/mkdocs-blogging-plugin/
 ```
 
-Add `blogging` in `plugins` and specify the directories to be included:
+### Basic
+
+Add `blogging` in `plugins` and specify the directories to be included. This is the
+minimum configuration needed.
 
 ``` yaml title="mkdocs.yml"
 plugins:
@@ -36,14 +39,18 @@ plugins:
         - blog
 ```
 
-In the page you want to insert the blog content, just add a line `{{ blog_content }}` into your desired place:
+In the page you want to insert the blog content, add a line `{{ blog_content }}` into your desired place:
 
 ```markdown title="blog index page"
 # Blogs
 
 {{ blog_content }}
 ```
 
+That's all. You can open the page where you insert `{{ blog_content }}` and see how it is working.
+
+### More Configurations
+
 Optionally, in your articles, add meta tags providing their titles and descriptions, which will be displayed on the blog page:
 
 ```markdown title="article"
@@ -53,7 +60,7 @@ 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:
+You can also set tags for all articles. First, turn on this feature in the configuration:
 
 ```yaml title="mkdocs.yml"
 plugins:
@@ -74,30 +81,31 @@ tags:
 
 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:
+Finally, to exclude certain pages from the blog collection, add a meta tag `exculde_from_blog` in the meta section of the markdown file:
 
 ```markdown title="article"
 ---
 exculde_from_blog: true
 ---
 ```
 
-And it's done! You can open the page where you insert `{{ blog_content }}` and see how it is working.
-
 ## Options
 
-Configure the plugin via following options:
+### Category-specific Settings
 
-```yaml title="mkdocs.yml"
-theme:             # Use a predefined theme
-  name: card
-features:          # Additional features
-  tags:
-    ...
+The plugin supports generating different blog index pages based on a concept
+named *category*. It enables you to setup multiple
+blog index pages, each with specific purpose.
+For example, one might setup a page for technical articles, and another for life recording.
+
+You can specify the included directories for each category
+and configure the options seperately. The *category-specific* settings include:
+
+```yaml title="category settings"
+dirs:              # The directories included in the category
+  - reviews
+  - ...
 size: 5            # Number of articles in one page, default: 10
-locale: en         # The locale for time localizations, default: system's locale
-time_format: '%Y-%m-%d %H:%M:%S' # The format used to display the time
-meta_time_format: '%Y-%m-%d %H:%M:%S' # The format used to parse the time from meta
 sort: 
   from: new        # Sort from new to old, default
   # or old         # Sort from old to new
@@ -106,23 +114,66 @@ sort:
 paging: false      # Disable paging
 show_total: false  # Remove 'total pages' label
 template: blog-override.html # Path to customized template
+theme:             # Use a predefined theme
+  name: card
+```
+
+The structure for the configuration in `mkdocs.yml`:
+
+```yaml title="mkdocs.yml"
+plugins:
+  - blogging:
+      # GLOBAL CATEGORY: configs for {{ blog_content }}
+      dirs:
+        - blogs
+      size: 5
+      ...
+
+      # INDIVIDUAL CATEGORIES: configs for {{ blog_content name }}
+      categories:
+        - name: review
+          dirs:
+            - review
+          size: 5
+          ...
+```
+
+To generate a blog page for a category, place `{{ blog_content name }}` in your markdown file,
+where `name` is the name of the category.
+
+Note that you can either setup settings mentioned above at the top level of the plugin config,
+or define them within a specific category. The former will apply to `{{ blog_content }}`, and the
+latter will apply to `{{ blog_content name }}`.
+
+For more about themes and custom templates, see [Themes](theme.md) and [Template](template.md) respectively.
+
+### Global Settings
+
+Aside from the category settings, there are some globally applied options, which should be defined
+at the top level of the plugin configuration:
+
+```yaml title="mkdocs.yml"
+features:          # Additional features
+  tags:
+    ...
+locale: en         # The locale for time localizations, default: system's locale
+time_format: '%Y-%m-%d %H:%M:%S' # The format used to display the time
+meta_time_format: '%Y-%m-%d %H:%M:%S' # The format used to parse the time from meta
 ```
 
-These parameters deserve special care:
+Of all the options mentioned above, these ones deserve special attention:
 
-- `time_format` is used to change the display style of the time, with higher priority than `locale`. 
+- `time_format` in *global settings* is used to change the display style of the time, with higher priority than `locale`. 
 
-- `meta_time_format` is used to tell the plugin how to parse the given time string from the meta. 
+- `meta_time_format` in *global settings* is used to tell the plugin how to parse the given time string from the meta. 
 When `meta_time_format` is set, for all posts with a `time` or `date` metadata, the plugin will
 use this format to parse the that time, and replace the time from git logs. This is
-useful to alter specific posts' time where git commit time is not accurate or desired.
+useful to alter specific posts' time when git commit time is not accurate or desired.
 See [the list of datetime placeholders](https://docs.python.org/3/library/datetime.html#strftime-and-strptime-format-codes).
 
-- When `paging` is set to `false`, if `size` is not set, all posts will be displayed on the first page; otherwise the first
+- When `paging` in *category settings* is set to `false`, if `size` is not set, all posts will be displayed on the first page; otherwise the first
 `size` posts will be displayed and *the rest will not*.
 
-For more about themes and custom templates, see [Themes](theme.md) and [Template](template.md) respectively.
-
 ## Publish with Github Pages
 
 A few more steps need to be taken for hosting with Github Pages:
@@ -136,7 +187,7 @@ A few more steps need to be taken for hosting with Github Pages:
 ```
 
 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.
+If it is not set, the plugin will take the build time as fallback.
 
 **Configure your locale in the plugin's configuration**
 

docs/template.md

@@ -1,4 +1,4 @@
-The `template` entry in the configuration allows you to override the appearance of the blog page.
+The `template` entry in the *category settings* allows you to override the appearance of the blog page.
 
 To customize the appearance, create an HTML template with name **other than `blog.html` and `blog-*.html`**, then provide
 **the path relative to the parent directory of `mkdocs.yml`** to the plugin's configuration.
@@ -88,8 +88,8 @@ You can refer to the original template for help.
 
 ## Access to the Original MkDocs Template Variables
 
-Use `mkdocs_context` inside your template to access variables that are available inside MkDocs' templates. For example, to access `base_url`:
+Use `mkdocs_context` inside your template to access variables that are available inside MkDocs' templates. For example, to access `config.site_url`:
 
 ```jinja
-<img href="{{ mkdocs_context.base_url }}/img/1.png" alt="">
+<img src="{{ mkdocs_context.config.site_url }}/img/1.png" alt="">
 ```

docs/theme.md

@@ -1,4 +1,6 @@
-The plugin has some built-in themes, you can select one as alternative. If you are to use one of them, in the plugin's config, specify the theme's name, and optionally specify some options to customize the appearance.
+You can select one from the plugin's built-in themes to render your content. If you are to use one of them, in the plugin's config, specify the theme's name, and optionally specify some options to customize the appearance.
+
+Note that this is a *category-specific* setting, so you should set them for each category seperately.
 
 ```yaml title="mkdocs.yml"
 plugins:

mkdocs_blogging_plugin/config.py

@@ -0,0 +1,17 @@
+class BloggingConfig:
+    dirs: list
+    size: int
+    sort: dict
+    paging: bool
+    show_total: bool
+    template: str
+    theme: dict
+
+    def __init__(self, config: dict):
+        self.dirs = config.get("dirs", [])
+        self.size = config.get("size", 10)
+        self.sort = config.get("sort", {"from": "new", "by": "creation"})
+        self.paging = config.get("paging", True)
+        self.show_total = config.get("show_total", True)
+        self.template = config.get("template")
+        self.theme = config.get("theme")