Some actions needs a
GH_PAT secret in your repository settings. This token should have the
workflows scope. You can create a token here.
If you set security on your main branch, you need to add two more secrets:
You need to update the workflow like this:
If you want to use the Advanced Vercel/Netlify Workflow, you needs to configure more secrets keys.
You can get more information here.
You need to configure the plugin and the
mkdocs configuration for it to work properly.
You can find more information about creating the site using the Material Mkdocs Documentation.
In the repository that you cloned, you will find a
mkdocs.yml file. This file allows you to customize your blog. The most important settings to edit are:
site_url(critical): By default, it’s
To edit the logo and favicon, first put the chosen files in the
assets/logo directory, and then change
- To properly work with SEO, also edit the
You can also customize:
- Color scheme, palette, and icons
You don’t need to touch anything in
The last part of the
mkdocs.yml is a configuration for the
hooks and the template Jinja displaying the list of articles (
There are also :
string): Link to your default image displayed by the SEO.
boolean) : Allow the comments block at the end of the page
boolean): Generate the graph view
boolean): For configuration and image in SEO. Change it according to your Obsidian Plugin settings.
Blog list (article listing)¶
The list of articles is configured by the key
blog_list and can take the following parameters :
boolean, default: True): Display a pagination if the list is too long.
boolean, default: True): Display a message with the number of posts (article/file) in the folder.
string, default: 'posts in'): Translation of the pagination’s message.
string, default: "No pages found!"): The text to display if no pages were found.
This part contains the configuration of
hooks, short python scripts that allow to patch some Obsidian parts incompatible with Mkdocs.
You can configure :
- The suppression of the Obsidian’s comments (
- A fix for headings, which adds a
#to all headings (except the 6th one) because the Mkdocs TOC considers that the H1 is the main heading/title of the file:
To run the blog locally, you need to install the requirements and run
cd publish_blog pip install -r requirements.txt mkdocs serve
A tip: You can use a conda environment here (or a venv, but I prefer conda). Just use this command:
Run this command just before running