安装Material博客(sidecar to mkdocs)
Material for MkDocs makes it very easy to build a blog, either as a sidecar to your documentation or standalone. Focus on your content while the engine does all the heavy lifting, automatically generating archive and category indexes, post slugs, configurable pagination and more.
blog plugin#
The built-in blog plugin adds support for building a blog from a folder of posts, which are annotated with dates and other structured data. First, add the following lines to mkdocs.yml:
启用后，首次 serve 或 build，在 docs 目录下会创建一个 blog 文件夹：
Blog only#
如果想把 mkdocs 站点当做纯博客，可以去掉 blog 中间层目录，直接在 docs 目录下 posts。
You might need to build a pure blog without any documentation. In this case, you can create a folder tree like this:
And add the following lines to mkdocs.yml:
With this configuration, the url of the blog post will be /<post_slug> instead of /blog/<post_slug>.
doc with Blog#
本站是笔记文档+博客，即 sidecar 模式，博客只是其中一个专项入口。
在 blog/posts 下创建一个 hello-world.md：
Create a new file called hello-world.md and add the following lines:
---
draft: true
date: 2024-01-31
categories:
- Hello
- World
---
# Hello world!
Here is the content
...
that archive and category indexes have been automatically generated for you.
How it works#
The plugin scans the configured posts directory for .md files from which paginated views are automatically generated. If not configured otherwise, the plugin expects that your project has the following directory layout, and will create any missing directories or files for you:
The index.md file in the blog directory is the entry point to your blog – a paginated view listing all posts in reverse chronological order. Besides that, the plugin supports automatically creating archive and category pages that list a subset of posts for a time interval or category.
Post URLs are completely configurable, no matter if you want your URLs to include the post's date or not. Rendered dates always display in the locale of the site language of your project. Like in other static blog frameworks, posts can be annotated with a variety of metadata, allowing for easy integration with other built-in plugins, e.g., the social and tags plugin.
Posts can be organized in nested folders with a directory layout that suits your specific needs, and can make use of all components and syntax that Material for MkDocs offers, including admonitions, annotations, code blocks, content tabs, diagrams, icons, math, and more.
config blog#
- 配置 blog.blog_dir
- 配置 post_date_format, post_url_date_format 和 post_url_format
- nav 导航加入 blog 入口
plugins:
# enabled by default, but must be re-added when other plugins are used.
- search
# categorize any page with tags as part of the front matter of the page
- tags
- blog:
blog_dir: blog
# post_dir: posts
post_date_format: medium
post_url_date_format: yyyyMMdd
post_url_format: "{date}/{file}"
# pagination_per_page: 10 # default
# 页面导航
nav:
- Blog: blog/index.md
nav.Blog: blog/index.md ?
上面直接在 Blog 后指定博客首页路径，归档（archive）和分类（categories）将不会展示！
因为一行将 Blog 这个导航 section 占满，会抑制旗下自动插入 archive 和 category！
Adding an excerpt#
内容摘要 + 继续阅读
blog 默认的摘要和正文内容分割符为：post_excerpt_separator: <!-- more -->
The blog index, as well as archive and category indexes can either list the entire content of each post, or excerpts of posts. An excerpt can be created by adding a separator after the first few paragraphs of a post:
# Hello world!
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.
<!-- more -->
...
When the built-in blog plugin generates all indexes, the content before the excerpt separator is automatically extracted, allowing the user to start reading a post before deciding to jump in.
By default, the plugin makes post excerpts optional. When a post doesn't define an excerpt, views include the entire post. This setting can be used to make post excerpts required:
meta-data#
Adding categories#
blog 默认启用了分类插件。
Categories are an excellent way for grouping your posts thematically on dedicated index pages. This way, a user interested in a specific topic can explore all of your posts on this topic. Make sure categories are enabled and add them to the front matter categories property:
If you want to save yourself from typos when typing out categories, you can define your desired categories in mkdocs.yml as part of the categories_allowed configuration option. The built-in blog plugin will stop the build if a category is not found within the list.
Adding tags#
需要显式启用 tags 插件。
Besides categories, the built-in blog plugin also integrates with the built-in tags plugin. If you add tags in the front matter tags property as part of a post, the post is linked from the tags index:
As usual, the tags are rendered above the main headline and posts are linked on the tags index page, if configured. Note that posts are, as pages, only linked with their titles.
Changing the slug#
在文章开头的 meta 信息中可以指定 slug。
Slugs are the shortened description of your post used in the URL. They are automatically generated, but you can specify a custom slug for a page:
Setting the reading time#
需要 x 分钟阅读时间。
When enabled, the readtime package is used to compute the expected reading time of each post, which is rendered as part of the post and post excerpt. Nowadays, many blogs show reading times, which is why the built-in blog plugin offers this capability as well.
Sometimes, however, the computed reading time might not feel accurate, or result in odd and unpleasant numbers. For this reason, reading time can be overridden and explicitly set with the front matter readtime property for a post:
This will disable automatic reading time computation.
Adding pages#
正常情况下，配置好了 blog_dir/post_dir 后，mkdocs-material 会自动监测扫描 posts 目录下 .md 文件，并将博客列表添加到博客首页 index.md(index.html)。
当然，除了在 nav 中配置 blog 入口，也可手动将 blog 下的其他文件加入 nav 导航。
Besides posts, it's also possible to add static pages to your blog by listing the pages in the nav section of mkdocs.yml. All generated indexes are included after the last specified page. For example, to add a page on the authors of the blog, add the following to mkdocs.yml:
route to sub path#
jia.je 的导航栏有一个入口 知识库，主站点 的 mkdocs.yml 配置如下：
点击打开链接 jia.je/kb/ 指向另一个独立的 mkdocs 知识库 站点。
在服务上配置好二级目录路由 location /kb 即可。
refs#
Material for Mkdocs: Blog @github