The template for Obsidian Mkdocs Publisher, a free obsidian publish alternative throught Mkdocs.
The repository and the template rely on GitHub Actions to generate the website. You need to configure the repository to allow the actions to work properly.
Carefully follow this links to understand which keys you need to create
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.
[!Warning] Configuration is mandatory. Do not configure the template will lead to crash during build and errors.
There is two way to edit the template for creating the website :
mkdocs.yml
and creating appropriate workflows files,Pages
: If you want to use the template with Github Pages, you need to activate the GitHub Pages in your repository settings, and use action to trigger the page build.
Actions
-> General
: Allow Github Actions to read and write, and allow GitHub Actions to create and approve pull requests, as follows:
Don't forget to save the changes!Run workflow
. A popup will appear, and fill the informations.
Each informations corresponding to the mkdocs.yml configuration file.
By default, the workflows will send you a pull requests, so you can review the generation before the merging. You can automatically merge with the last options.
The configuration of mkdocs.yml is explained here.
mkdocs.yml
files with editing:site_name
: The name of your websitesite_description
: The description of your websitesite_author
: The author of your websitesite_url
: The url of your websitelanguage
: The language of your website
comments
: If you want to enable comments, you need to set it to true
and configure the comments
generate_graph
: Set it to true
if you use GitHub Pages and you want to generate the graph view. Set it to false
if you use Netlify or Vercel. See here on how to configure the graph with Netlify/vercel
auto_h1
: Disable the automatic generation of h1 if no h1 is found.env
and deploy.yml
corresponding to your methods of deployment:
.env
must be placed at .github/
deploy.yml
must be placed at .github/workflows/
requirements_actions.txt
file at the root of your repository, and add the following lines:
obsidiantools==0.10.0
pyvis==0.3.1
runtime.txt
file with 3.8
in it.To edit the logo and favicon, first put the chosen files in the assets/logo
directory, and then change logo
and favicon
:
logo: assets/meta/logo_name.png
favicon: assets/meta/favicon.png
extra
with SEO: 'assets/meta/LOGO_SEO.png'
You can also customize:
Check the documentation for more information
You don't need to touch anything in features
or markdown_extensions
.
The last part of the mkdocs.yml
is a configuration for the hooks
and the template Jinja displaying the list of articles (blog_list.html
).
There are also :
SEO
(string
): Link to your default image displayed by the SEO.comments
(boolean
) : Allow the comments block at the end of the pagegenerate_graph
(boolean
): Generate the [[customization#Graph view|graph view]]attachments
(boolean
): For [[configuration#Blog list (article listing)]] and image in SEO. Change it according to your Obsidian Plugin settings.The list of articles is configured by the key blog_list
and can take the following parameters :
pagination
(boolean, default: True
): Display a pagination if the list is too long.pagination_message
(boolean, default: True
): Display a message with the number of posts (article/file) in the folder.pagination_translation
(string, default: 'posts in'
): Translation of the pagination's message.no_page_found
(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 :
%% comments %%
): strip_comments: true
#
to all headings (except the 6th one) because the Mkdocs TOC considers that the H1 is the main heading/title of the file: fix_heading: true