Merge pull request #3 from liang2kl/dev

v0.3.0
liang2kl · Dec 2, 2021 · e1c4268 · e1c4268
2 parents 44f8fc6 + 5a11148
commit e1c4268
Show file tree

Hide file tree

Showing 14 changed files with 504 additions and 110 deletions.
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -0,0 +1,15 @@
+name: publish 
+on:
+  push:
+    branches: 
+      - main
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.x
+      - run: pip install -r requirements.txt
+      - run: mkdocs gh-deploy --force
diff --git a/README.md b/README.md
@@ -2,6 +2,10 @@
 
 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.
+
 ![preview](https://i.loli.net/2021/09/09/LhX9IFkbu2K3lRi.png)
 
 ## Installation
@@ -55,7 +59,7 @@ exculde_from_blog: true
 And it's done! You can open the page where you insert `{{ blog_content }}` and see how it is working.
 
 Some more steps need to be taken if you want to host your blog with GitHub Pages.
-Please refer to [Publishing on Github Pages](#publishing-on-github-pages).
+Please refer to [Publishing on Github Pages](#publish-on-github-pages).
 
 ## Customization
 
@@ -64,6 +68,8 @@ Please refer to [Publishing on Github Pages](#publishing-on-github-pages).
 Optionally, you can customize some behaviours of the plugin:
 
 ```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: 
@@ -73,89 +79,12 @@ sort:
   # 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, see below
-```
-
-### Override the Template
-
-The `template` entry in the configuration allows you to override the appearance of the blog page.
-
-To customize the appearance, create an HTML template with name **other than `blog.html`**, then provide
-**the path relative to the parent directory of `mkdocs.yml`** to the plugin's configuration.
-
-> For example:
-> 
-> ```text
-> .
-> ├─ overrides/
-> │  └─ template.html
-> └─ mkdocs.yml
-> ```
-> 
-> then the configuration should be `template: overrides/template.html`.
-
-For introduction and usage of HTML templates, refer to [jinja's documentation](https://jinja.palletsprojects.com/en/3.0.x/).
-
-You have the following customization options:
-
-#### Partial Customization
-
-You can override how the plugin render a single blog entry through this method. An example can be found [here](https://github.com/liang2kl/mkdocs-blogging-plugin-example).
-
-In your template, import the original template:
-
-```jinja
-{% extends "blog.html" %}
+template: blog-override.html # Path to customized template
 ```
 
-Then, define a macro named `render_blog` with parameters `title`, `description`, `time` and `url`, which
-returns HTML elements that represent a single blog entry.
-Please note that `{{ caller() }}` must be present somewhere inside the macro, though it has no use here.
-
-```jinja
-{% macro render_blog(title, description, time, url) -%}
-    <a href="{{ url }}">
-        <h3>{{ title }}</h3>
-    </a>
-    <div>{{ description }}</div>
-    <div>{{ time }}</div>
-    <hr/>
-    {{ caller() }}
-{%- endmacro %}
-```
-
-Further more, if you want to customize the css, write a block named `style`. Call `{{ super() }}` first
-if you want to preserve the original styles.
-
-```jinja
-{% block style %}
-    {{ super() }}
-    <style>
-        {# your style goes here #}
-    </style>
-{% endblock %}
-```
-
-Check [the original template](mkdocs_blogging_plugin/templates/blog.html) for available customization points. Here are some common ones:
-
-- `.md-typeset .blog-post-title`: post title
-- `.md-typeset .blog-post-description`: post description
-- `.md-typeset .blog-post-extra`: extra section for creation / revision time
-
-#### Global Override
-
-Alternatively, you can provide a template that works completely independent from the original template.
-
-These variables are available inside your template:
-
-- `pages`: sorted blog pages, see mkdocs' documentation for available attributes
-- `page_size`: number of articles on a single page
-- `is_revision`: `True` if sorted by revision time, `False` if by creation time
-- `show_total`: whether to show the total number of the blog
-
-You can refer to [the original template](mkdocs_blogging_plugin/templates/blog.html) for help.
+Check [the guide](https://liang2kl.github.io/mkdocs-blogging-plugin) for more detail.
 
-## Publishing on Github Pages
+## Publish on Github Pages
 
 A few more steps need to be taken for hosting with Github Pages:
 

diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,99 @@
+---
+title: Setup
+---
+
+# Setup
+
+## Installation
+
+```shell
+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).
+
+## 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:
+
+```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.
+
+## Options
+
+Configure the plugin via following options:
+
+```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
+```
+
+For more about themes and custom templates, see [Themes](theme.md) and [Template](theme.md) respectively.
+
+## 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.
+
+**Configure your locale in the plugin's configuration**
+
+```yml
+locale: zh-CN
+```
+
+Otherwise, the plugin will use locale of the server, which might not be expected.
diff --git a/docs/migration.md b/docs/migration.md
@@ -0,0 +1,12 @@
+# Migration Guide
+
+## v0.2.x to v0.3.x
+
+Breaking changes:
+
+- Added a new paramter `page` to `render_blog`.
+    - **Effect:** This will stop previous macro definitions from working.
+    - **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.
diff --git a/docs/template.md b/docs/template.md
@@ -0,0 +1,89 @@
+# Template
+
+The `template` entry in the configuration 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-*-theme.html`**, then provide
+**the path relative to the parent directory of `mkdocs.yml`** to the plugin's configuration.
+
+For introduction and usage of HTML templates, refer to [jinja's documentation](https://jinja.palletsprojects.com/en/3.0.x/).
+
+You have following customization options:
+
+## Partial Customization
+
+You can override how the plugin render a single blog entry through this method. An example can be found [here](https://github.com/liang2kl/mkdocs-blogging-plugin-example).
+
+### Customize HTML
+
+In your template, import the original template. The template can be the basic `blog.html`, or one of the built-in themes, like `blog-card-theme.html`:
+
+```jinja
+{% extends "blog.html" %}
+```
+
+Then, define a macro named `render_blog` with parameters `title`, `description`, `time`, `url`, `page`, which
+returns HTML elements that represent a single blog entry.
+Please note that `{{ caller() }}` must be present somewhere inside the macro, though it has no use here.
+
+```jinja
+{% macro render_blog(title, description, time, url, page) -%}
+<a href="{{ url }}">
+    <h3>{{ title }}</h3>
+</a>
+<div>{{ description }}</div>
+<div>{{ time }}</div>
+<hr/>
+{{ caller() }}
+{%- endmacro %}
+```
+
+The parameter `page` allows you to add arbitary additional information to any page using its `meta` attribute. For example, we want to show the author's name on the blog page. We can add an entry `author` in the markdown file's meta section:
+
+```yaml
+---
+author: Liang Yesheng
+---
+```
+
+Then, access it through `page.meta`:
+
+```jinja
+{% if "author" in page.meta %}
+<div>{{ page.meta["author"] }}</div>
+{% endif %}
+```
+
+and it will display the author.
+
+### Customize styles
+
+Further more, if you want to customize the css, write a block named `style`. Call `{{ super() }}` first
+if you want to preserve the original styles.
+
+```jinja
+{% block style %}
+    {{ super() }}
+    <style>
+        {# your style goes here #}
+    </style>
+{% endblock %}
+```
+
+Check [the original template](mkdocs_blogging_plugin/templates/blog.html) for available customization points. Here are some common ones:
+
+- `.md-typeset .blog-post-title`: post title
+- `.md-typeset .blog-post-description`: post description
+- `.md-typeset .blog-post-extra`: extra section for creation / revision time
+
+## Global Override
+
+Alternatively, you can provide a template that works completely independent from the original template.
+
+These variables are available inside your template:
+
+- `pages`: sorted blog pages, see mkdocs' documentation for available attributes
+- `page_size`: number of articles on a single page
+- `is_revision`: `True` if sorted by revision time, `False` if by creation time
+- `show_total`: whether to show the total number of the blog
+
+You can refer to [the original template](mkdocs_blogging_plugin/templates/blog.html) for help.
diff --git a/docs/theme.md b/docs/theme.md
@@ -0,0 +1,40 @@
+# Themes
+
+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.
+
+```yaml
+theme:
+  name: <theme name>
+  options:
+    <theme options>
+```
+
+You can use one of the predefined themes:
+
+### Card
+
+Display the blog entries as cards with hover effects.
+
+```yaml
+theme:
+  name: card
+```
+
+![card](https://i.loli.net/2021/12/02/91UlyeKPOVuRwvq.png)
+
+### Button
+
+Add "Continue Reading" button.
+
+```yaml
+theme:
+  name: button
+  options: # Optional
+    # `true` if display the button as plain text
+    # `false` or not present if display as rectangle button
+    - plain_button: true
+    # Replacement for 'Continue Reading'
+    - label: Read
+```
+
+![button](https://i.loli.net/2021/12/02/r1eEQYmFwXOT5jD.png)