1
0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-12-25 05:44:54 +01:00
mkdocs-material/docs/setup/setting-up-a-blog.md

600 lines
17 KiB
Markdown
Raw Normal View History

2022-09-11 19:25:40 +02:00
# Setting up a blog
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.
---
__Check out our [blog], which is created with the new [built-in blog plugin]!__
2023-09-14 19:09:18 +02:00
[archive]: ../plugins/blog.md#archive
[category]: ../plugins/blog.md#categories
[post slugs]: ../plugins/blog.md#config.post_url_format
[pagination]: ../plugins/blog.md#pagination
2022-09-11 19:25:40 +02:00
[blog]: ../blog/index.md
## Configuration
2022-10-02 16:36:47 +02:00
### Built-in blog plugin
2022-09-11 19:25:40 +02:00
2023-09-14 19:09:18 +02:00
<!-- md:version 9.2.0 -->
<!-- md:plugin -->
<!-- md:flag experimental -->
2022-09-11 19:25:40 +02:00
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`:
``` yaml
plugins:
- blog
```
2023-09-14 19:09:18 +02:00
For a list of all settings, please consult the [plugin documentation].
2022-09-11 19:25:40 +02:00
2023-09-14 19:09:18 +02:00
[plugin documentation]: ../plugins/blog.md
2022-09-11 19:25:40 +02:00
[Insiders]: ../insiders/index.md
2023-09-14 19:09:18 +02:00
[built-in blog plugin]: ../plugins/blog.md
2022-09-11 19:25:40 +02:00
[built-in plugins]: ../insiders/getting-started.md#built-in-plugins
[docs_dir]: https://www.mkdocs.org/user-guide/configuration/#docs_dir
[start writing your first post]: #writing-your-first-post
### RSS
2023-09-14 19:09:18 +02:00
<!-- md:version 9.2.0 -->
<!-- md:plugin [rss] -->
2022-09-11 19:25:40 +02:00
The [built-in blog plugin] integrates seamlessly with the [RSS plugin][rss],
2023-09-14 19:09:18 +02:00
which provides a simple way to add an RSS feed to your blog (or to your whole
2022-09-11 19:25:40 +02:00
documentation). Install it with `pip`:
```
pip install mkdocs-rss-plugin
```
Then, add the following lines to `mkdocs.yml`:
``` yaml
plugins:
- rss:
match_path: blog/posts/.* # (1)!
date_from_meta:
as_creation: date
categories:
- categories
- tags # (2)!
```
1. The RSS plugin allows to filter for URLs to be included in the feed. In
this example, only blog posts will be part of the feed.
2. If you want to include a post's categories as well as its tags in the feed,
add both `categories` and `tags` here.
The following configuration options are supported:
2023-09-14 19:09:18 +02:00
<!-- md:option rss.enabled -->
2022-09-11 19:25:40 +02:00
2023-09-14 19:09:18 +02:00
: <!-- md:default `true` --> This option specifies whether
2022-10-22 08:43:36 +02:00
the plugin is enabled when building your project. If you want to speed up
local builds, you can use an [environment variable]:
2022-09-11 19:25:40 +02:00
``` yaml
plugins:
- rss:
2022-10-22 08:43:36 +02:00
enabled: !ENV [CI, false]
2022-09-11 19:25:40 +02:00
```
2023-09-14 19:09:18 +02:00
<!-- md:option rss.match_path -->
2022-09-11 19:25:40 +02:00
2023-09-14 19:09:18 +02:00
: <!-- md:default `.*` --> This option specifies which
2022-09-11 19:25:40 +02:00
pages should be included in the feed. For example, to only include blog
posts in the feed, use the following regular expression:
``` yaml
plugins:
- rss:
match_path: blog/posts/.*
```
2023-09-14 19:09:18 +02:00
<!-- md:option rss.date_from_meta -->
2022-09-11 19:25:40 +02:00
2023-09-14 19:09:18 +02:00
: <!-- md:default none --> This option specifies which
front matter property should be used as a creation date of a page in the
2022-09-11 19:25:40 +02:00
feed. It's recommended to use the `date` property:
``` yaml
plugins:
- rss:
date_from_meta:
as_creation: date
```
2023-09-14 19:09:18 +02:00
<!-- md:option rss.categories -->
2022-09-11 19:25:40 +02:00
2023-09-14 19:09:18 +02:00
: <!-- md:default none --> This option specifies which
2022-09-11 19:25:40 +02:00
front matter properties are used as categories as part of the feed. If you
use [categories] and [tags], add both with the following lines:
``` yaml
plugins:
- rss:
categories:
- categories
- tags
```
2023-09-14 19:09:18 +02:00
<!-- md:option rss.comments_path -->
2022-09-11 19:25:40 +02:00
2023-09-14 19:09:18 +02:00
: <!-- md:default none --> This option specifies the anchor
2022-09-11 19:25:40 +02:00
at which comments for a post or page can be found. If you've integrated a
[comment system], add the following lines:
``` yaml
plugins:
- rss:
comments_path: "#__comments"
```
Material for MkDocs will automatically add the [necessary metadata] to your site
which will make the RSS feed discoverable by browsers and feed readers. Note
that the [RSS plugin][rss] comes with several other configuration options.
For further information, see the [documentation].
[rss]: https://guts.github.io/mkdocs-rss-plugin/
2023-09-14 19:09:18 +02:00
[categories]: ../plugins/blog.md#categories
2022-09-11 19:25:40 +02:00
[tags]: setting-up-tags.md#built-in-tags-plugin
[comment system]: adding-a-comment-system.md
[necessary metadata]: https://guts.github.io/mkdocs-rss-plugin/configuration/#integration
[theme extension]: ../customization.md
[documentation]: https://guts.github.io/mkdocs-rss-plugin/configuration/
## Usage
### Writing your first post
After you've successfully set up the [built-in blog plugin], it's time to write
your first post. The plugin doesn't assume any specific directory structure, so
you're completely free in how you organize your posts, as long as they are all
located inside the `posts` directory:
``` { .sh .no-copy }
2022-09-11 19:25:40 +02:00
.
├─ docs/
│ └─ blog/
│ ├─ posts/
│ │ └─ hello-world.md # (1)!
│ └─ index.md
└─ mkdocs.yml
```
1. If you'd like to arrange posts differently, you're free to do so. The URLs
are built from the format specified in [`post_url_format`][post slugs] and
the titles and dates of posts, no matter how they are organized
inside the `posts` directory.
Create a new file called `hello-world.md` and add the following lines:
``` yaml
---
draft: true # (1)!
2023-09-14 19:09:18 +02:00
date: 2023-01-31
2022-09-11 19:25:40 +02:00
categories:
- Hello
- World
---
# Hello world!
...
```
2023-09-14 19:09:18 +02:00
1. If you mark a post as a [draft], a red marker appears next to the post date
on index pages. When the site is built, drafts are not included in the
output. [This behavior can be changed], e.g. for rendering drafts when
2022-09-11 19:25:40 +02:00
building deploy previews.
2023-08-21 19:18:59 +02:00
2. If you wish to provide multiple dates, you can use the following syntax,
allowing you to define a date when you last updated the blog post +
further custom dates you can add to the template:
``` yaml
---
date:
created: 2022-01-31
updated: 2022-02-02
---
# Hello world!
```
Note that the creation date __must__ be set under `date.created`, as each
blog post must have a creation date set.
2023-08-03 19:55:57 +02:00
2022-09-11 19:25:40 +02:00
When you spin up the [live preview server], you should be greeted by your first
post! You'll also realize, that [archive] and [category] indexes have been
automatically generated for you.
2023-09-14 19:09:18 +02:00
[draft]: ../plugins/blog.md#drafts
[This behavior can be changed]: ../plugins/blog.md#config.draft
2022-09-11 19:25:40 +02:00
[live preview server]: ../creating-your-site.md#previewing-as-you-write
#### Adding an excerpt
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 `<!-- more -->` separator after the first few paragraphs of a post:
``` py
# 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.
2023-09-14 19:09:18 +02:00
[excerpt separator]: ../plugins/blog.md#config.post_excerpt_separator
2022-09-11 19:25:40 +02:00
#### Adding authors
In order to add a little more personality to your posts, you can associate each
post with one or multiple [authors]. First, create the
[`.authors.yml`][authors_file] file in your blog directory, and add an author:
``` yaml
2023-08-21 22:38:04 +02:00
authors:
squidfunk:
name: Martin Donath
description: Creator
avatar: https://github.com/squidfunk.png
2022-09-11 19:25:40 +02:00
```
The [`.authors.yml`][authors_file] file associates each author with an
identifier (in this example `squidfunk`), which can then be used in posts.
The following properties are available for each author:
2023-09-14 19:09:18 +02:00
<!-- md:option blog.authors_file.name -->
2022-09-11 19:25:40 +02:00
2023-09-14 19:09:18 +02:00
: <!-- md:default none --> <!-- md:flag required -->
2022-09-11 19:25:40 +02:00
This property must define a name for the author. The name is displayed in
the left sidebar of each post as part of the author info.
2023-09-14 19:09:18 +02:00
<!-- md:option blog.authors_file.description -->
2022-09-11 19:25:40 +02:00
2023-09-14 19:09:18 +02:00
: <!-- md:default none --> <!-- md:flag required -->
2022-09-11 19:25:40 +02:00
This property can be used to add a short description for the author, e.g.
the role or profession of the author, or any other title.
2023-09-14 19:09:18 +02:00
<!-- md:option blog.authors_file.avatar -->
2022-09-11 19:25:40 +02:00
2023-09-14 19:09:18 +02:00
: <!-- md:default none --> <!-- md:flag required -->
2022-09-11 19:25:40 +02:00
This property must point to a valid image URL, internal or external, and is
used as part of posts and excerpts as the author's avatar.
Now, you can assign one or more authors to a post by referencing their
identifiers in the front matter of the Markdown file under the `authors`
property. For each author, a small profile is rendered in the left sidebar of
each post, as well as in post excerpts on index pages:
``` yaml
---
2023-09-14 19:09:18 +02:00
date: 2023-01-31
2022-09-11 19:25:40 +02:00
authors:
- squidfunk
...
---
# Hello world!
...
```
2023-09-14 19:09:18 +02:00
[authors]: ../plugins/blog.md#authors
[authors_file]: ../plugins/blog.md#config.authors_file
2022-09-11 19:25:40 +02:00
#### Adding categories
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
2022-10-02 16:36:47 +02:00
add them to the front matter `categories` property:
2022-09-11 19:25:40 +02:00
``` yaml
---
2023-09-14 19:09:18 +02:00
date: 2023-01-31
2022-09-11 19:25:40 +02:00
categories:
- Hello
- World
---
# Hello world!
...
```
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`][categories_allowed] configuration option. The
[built-in blog plugin] will stop the build if a category is not found within
the list.
2023-09-14 19:09:18 +02:00
[categories_allowed]: ../plugins/blog.md#config.categories_allowed
2022-09-11 19:25:40 +02:00
#### Adding tags
Besides [categories], the [built-in blog plugin] also integrates with the
2022-10-02 16:36:47 +02:00
[built-in tags plugin]. If you add tags in the front matter `tags` property as
2022-09-11 19:25:40 +02:00
part of a post, the post is linked from the [tags index]:
``` yaml
---
2023-09-14 19:09:18 +02:00
date: 2023-01-31
2022-09-11 19:25:40 +02:00
tags:
- Foo
- Bar
---
# Hello world!
...
```
2023-09-14 19:09:18 +02:00
As usual, the tags are rendered above the main headline and posts are linked
2022-09-11 19:25:40 +02:00
on the tags index page, if configured. Note that posts are, as pages, only
linked with their titles.
2023-09-15 09:25:50 +02:00
[built-in tags plugin]: ../plugins/tags.md
2022-09-11 19:25:40 +02:00
[tags index]: setting-up-tags.md#adding-a-tags-index
#### Changing the 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:
``` yaml
---
slug: hello-world
---
# Hello there world!
...
```
2022-09-11 19:25:40 +02:00
#### Adding related links
2023-09-14 19:09:18 +02:00
<!-- md:sponsors -->
<!-- md:version insiders-4.23.0 -->
<!-- md:flag experimental -->
2023-07-06 17:38:39 +02:00
2023-09-14 19:09:18 +02:00
Related links offer the perfect way to prominently add a _further reading_
section to your post that is included in the left sidebar, guiding the user to
other destinations of your documentation. Use the front matter `links` property
2022-09-11 19:25:40 +02:00
to add related links to a post:
``` yaml
---
2023-09-14 19:09:18 +02:00
date: 2023-01-31
2022-09-11 19:25:40 +02:00
links:
2023-09-15 09:25:50 +02:00
- plugins/search.md
2022-09-11 19:25:40 +02:00
- insiders/index.md#how-to-become-a-sponsor
---
# Hello world!
...
```
You can use the exact same syntax as for the [`nav`][nav] section in
`mkdocs.yml`, which means you can set explicit titles for links, add external
links and even use nesting:
``` yaml
---
2023-09-14 19:09:18 +02:00
date: 2023-01-31
2022-09-11 19:25:40 +02:00
links:
2023-09-15 09:25:50 +02:00
- plugins/search.md
2022-09-11 19:25:40 +02:00
- insiders/index.md#how-to-become-a-sponsor
- Nested section:
- External link: https://example.com
- setup/setting-up-site-search.md
---
# Hello world!
...
```
If you look closely, you'll realize that you can even use an anchor to link to
2023-09-14 19:09:18 +02:00
a specific section of a document, extending the possibilities of the [`nav`][nav]
syntax in `mkdocs.yml`. The [built-in blog plugin] resolves the anchor and sets
2022-10-03 11:10:16 +02:00
the title of the anchor as a [subtitle] of the related link.
2022-09-11 19:25:40 +02:00
2022-10-03 11:10:16 +02:00
Note that all links must be relative to [`docs_dir`][docs_dir], as is also the
case for the [`nav`][nav] setting.
2022-09-11 19:25:40 +02:00
[nav]: https://www.mkdocs.org/user-guide/configuration/#nav
2022-10-03 11:10:16 +02:00
[subtitle]: ../reference/index.md#setting-the-page-subtitle
2022-09-11 19:25:40 +02:00
#### Linking from and to posts
2023-09-14 19:09:18 +02:00
While [post URLs][post slugs] are dynamically computed, the [built-in blog
plugin] ensures that all links from and to posts and a post's assets are
correct. If you want to link to a post, just use the path to the Markdown file
2022-09-11 19:25:40 +02:00
as a link reference (links must be relative):
``` markdown
[Hello World!](blog/posts/hello-world.md)
```
Linking from a post to a page, e.g. the index, follows the same method:
``` markdown
[Blog](../index.md)
```
2023-09-14 19:09:18 +02:00
All assets inside the `posts` directory are copied to the `blog/assets` folder
2022-09-11 19:25:40 +02:00
when the site is being built. Of course, you can also reference assets from
posts outside of the `posts` directory. The [built-in blog plugin] ensures that
all links are correct.
#### Setting the reading time
When [enabled], the [readtime] package is used to compute the expected reading
2022-09-14 23:27:55 +02:00
time of each post, which is rendered as part of the post and post excerpt.
2023-09-14 19:09:18 +02:00
Nowadays, many blogs show reading times, which is why the [built-in blog plugin]
2022-09-11 19:25:40 +02:00
offers this capability as well.
Sometimes, however, the computed reading time might not feel accurate, or
2023-09-14 19:09:18 +02:00
result in odd and unpleasant numbers. For this reason, reading time can be
2022-10-02 16:36:47 +02:00
overridden and explicitly set with the front matter `readtime` property for a
2022-09-11 19:25:40 +02:00
post:
``` yaml
---
2023-09-14 19:09:18 +02:00
date: 2023-01-31
2022-09-11 19:25:40 +02:00
readtime: 15
---
# Hello world!
...
```
This will disable automatic reading time computation.
[readtime]: https://pypi.org/project/readtime/
2023-09-14 19:09:18 +02:00
[enabled]: ../plugins/blog.md#config.post_readtime
2022-09-11 19:25:40 +02:00
#### Setting defaults
If you have a lot of posts, it might feel redundant to define all of the above
for each post. Luckily, the [built-in meta plugin] allows to set default front
matter properties per folder. You can group your posts by categories, or
authors, and add a `.meta.yml` file to set common properties:
``` { .sh .no-copy }
2022-09-11 19:25:40 +02:00
.
├─ docs/
│ └─ blog/
│ ├─ posts/
│ ├─ .meta.yml # (1)!
│ └─ index.md
└─ mkdocs.yml
```
1. As already noted, you can also place a `.meta.yml` file in nested folders
2022-10-02 16:36:47 +02:00
of the `posts` directory. This file then can define all front matter
properties that are valid in posts, e.g.:
2022-09-11 19:25:40 +02:00
``` yaml
authors:
- squidfunk
categories:
- Hello
- World
```
Note that order matters the [built-in meta plugin] must be defined before the
blog plugin in `mkdocs.yml`, so that all set defaults are correctly picked up
by the [built-in blog plugin]:
``` yaml
plugins:
- meta
- blog
```
2022-09-11 19:25:40 +02:00
Lists and dictionaries in `.meta.yml` files are merged and deduplicated with the
values defined for a post, which means you can define common properties in
`.meta.yml` and then add specific properties or overrides for each post.
2023-09-15 09:25:50 +02:00
[built-in meta plugin]: ../plugins/meta.md
2022-09-11 19:25:40 +02:00
### Adding pages
Besides posts, it's also possible to add static pages to your blog by listing
the pages in the [`nav`][nav] section of `mkdocs.yml`. All generated indexes
2023-09-14 19:09:18 +02:00
are included after the last specified page. For example, to add a page on the
2022-09-11 19:25:40 +02:00
authors of the blog, add the following to `mkdocs.yml`:
``` yaml
nav:
- Blog:
- blog/index.md
- blog/authors.md
...
```
## Customization
### Custom index pages
2023-09-14 19:09:18 +02:00
<!-- md:sponsors -->
<!-- md:version insiders-4.24.0 -->
<!-- md:flag experimental -->
2023-09-14 19:09:18 +02:00
If you want to add custom content to automatically generated [archive] and
[category] indexes, e.g. to add a category description prior to the list of
posts, you can manually create the category page in the same location where
the [built-in blog plugin] would create it:
``` { .sh .no-copy }
.
├─ docs/
│ └─ blog/
│ ├─ category/
2023-02-18 11:15:25 +01:00
│ │ └─ hello.md # (1)!
│ ├─ posts/
│ └─ index.md
└─ mkdocs.yml
```
1. The easiest way is to first [add the category] to the blog post, then take
the URL generated by the [built-in blog plugin] and create the file at the
corresponding location in the [`blog_dir`][this is configurable] folder.
Note that the shown directory listing is based on the default configuration.
If you specify different values for the following options, be sure to adjust
the path accordingly:
- [`blog_dir`][this is configurable]
- [`categories_url_format`][categories_url_format]
- [`categories_slugify`][categories_slugify]
You can now add arbitrary content to the newly created file, or set specific
2022-10-02 16:36:47 +02:00
front matter properties for this page, e.g. to change the [page description]:
``` yaml
---
description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
---
# Hello
...
```
2022-10-02 16:36:47 +02:00
All post excerpts belonging to the category are automatically appended.
[add the category]: #adding-categories
[page description]: ../reference/index.md#setting-the-page-description
2023-09-14 19:09:18 +02:00
[categories_url_format]: ../plugins/blog.md#config.categories_url_format
[categories_slugify]: ../plugins/blog.md#config.categories_slugify
2022-09-11 19:25:40 +02:00
### Overriding templates
The [built-in blog plugin] is built on the same basis as Material for MkDocs,
which means you can override all templates used for the blog by using
[theme extension] as usual.
The following templates are added by the [built-in blog plugin]:
2023-08-21 18:54:53 +02:00
- [`blog.html`][blog.html] Template for blog, archive and category index
2022-09-11 19:25:40 +02:00
- [`blog-post.html`][blog-post.html] Template for blog post
[theme extension]: ../customization.md#extending-the-theme
2023-09-19 09:51:18 +02:00
[blog.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/blog.html
[blog-post.html]: https://github.com/squidfunk/mkdocs-material/blob/master/src/blog-post.htmlhtml