MkDocs portable Installation
(not necessary for build123d)
MkDocs is a python solution to build static websites from markdown files. I am using Obsidian MD for my notetaking. So my intention was to just document once in Obsidian MD and to create my static documentation website from one source in one workflow. Once I reviewed the static website and once I am satisfied with the website I can go on and publish it to github.
1) Python enviroment for MkDocs¶
Download WinPython 3.11.8 from Sourceforge: WinPython - 3.11.8
You find all WinPython Versions under this link: WinPython
WinPython is a portable setup of the Python runtime enviroment for windows.
After downloading the file double click it (and thus execute it). You might need to tell windows or your browser that the file is safe and that you want to keep it and that you want to execute it.
After starting you will be asked to extract it. Choose a location where you want your files to be extracted to.
For example: D:\Portable_MkDocs
Thats it your Python enviroment is setup and ready to run.
Go into the directory where you installed your Python enviroment (D:\Portable_MkDocs\WPy64-31180) and start "WinPython Powershell Prompt.exe".
This will open the windows Powershell. You can check your Python version by typing: python --version.
Also check if your paket manager pip is installed by typing: pip --version
2) Install MkDocs¶
Website MkDocs: MkDocs
To install MkDocs you need to install it with a paket manager into your python environment. To do so we will use pip which is the pre installed paket manager in WinPython.
Type: pip install mkdocs
3) Install a Theme¶
For my documentation the material theme seemed most usefull. Material is a theme which is widely used and also supported by many plugins.
You find informations for the material theme here: Material theme
To install type: pip install mkdocs-material
4) Install plugins¶
I installed several plugins which extend and enhance MkDocs
Roamlinks plugin¶
This plugin allows to keep the links you defined in your markdown and change them to working links in your static site.
You find the plugin here: mkdocs-roamlinks-plugin
Install the plugin by typing: pip install mkdocs-roamlinks-plugin
Awesom pages plugin¶
This plugin allows to configure your page navigation, your page naming and your page configuration in more detail.
You find the plugin here: awesome-pages-plugin
Install the plugin by typing: pip install mkdocs-awesome-pages-plugin
Mkdocs callouts plugin¶
This plugin allows to render your obsidian markdown callouts into html.
You find the plugin here: mkdocs-callouts
Install the plugin by typing: pip install mkdocs-callouts
5) Configuring MkDocs and creating a static website¶
To create your first project go into the directory where you installed your Python enviroment (D:\Portable_MkDocs\WPy64-31180) and start "WinPython Powershell Prompt.exe".
In the windows powershell type:
mkdocs new Testproject
This will create a new project and a new directory "Testproject". You will find this new directory and your Projektfiles in "D:\Portable_MkDocs\scripts\Testproject"
Type: cd Testproject
This let's you change into the Testproject directory.
You need to create a YAML file in the Testproject directory. This file is reponsible for defining the parameters how MkDocs builds your static website.
For details see: Setup - Material for MkDocs
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 | |
Configuration with Mermaid (a text based flowchart generator)
site_name: Build123d for noobs
site_url: https://cepeu.github.io/build123-for-noobs/
use_directory_urls: true
theme:
name: material
highlightjs: true
sticky_navigation: true
#repo_url: https://github.com/CePeU/build123d
features:
- search.highlight # Highlight all occurences of search after selecting link
- search.share # allows for a share button after searching
#- header.autohide # hides the header uppon scrolling use for more screen size?
- content.code.copy # Renders a copy button in the code block
#- content.code.select
#- content.code.annotate
- navigation.path
- toc.integrate # Integrates the left side table of content into the navigation to the right
#- toc.follow # Not sure yet what it does
- navigation.top # Back to top button is rendered uppon startin to scroll back to top
- navigation.tabs # top-level sections are rendered at the TOP in a menu layer below the header for viewports above 1220px, but remain as-is on mobile
- navigation.tabs.sticky # scrolling does not "hide" tabs
#- navigation.sections # groups first/second level into groups but disables folding. Looks nice but gets too long
#- navigation.expands # will expand alls collapsed subsection as default
#- navigation.prune # Will need to considere if site gets above 100+ pages
markdown_extensions:
- toc:
toc_depth: 4 # increase toc depth to 4
permalink: true # Can add a anchor link
- pymdownx.highlight:
# anchor_linenums: true
# line_spans: __span
# pygments_lang_class: true
#- pymdownx.inlinehilite # python code block highlighting?
#- pymdownx.snippets
- nl2br
- admonition
- pymdownx.details
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
plugins:
- search: # Enables search. If plugins are used search must be explicitly enabled
lang: en # the site language will be english so searching in english makes sense
#- privacy # Loads all external assets before build
- roamlinks # Plugin for translating markdown links to local and external links
- callouts
- mermaid2
Type mkdocs serve
This starts a local webserver and generates your website from the markdown files found in "D:\Portable_MkDocs\scripts\Testproject".
You can see the newly generated website by opening a browser and typing localhost:8000
See more details also on the MkDocs website: Getting Started - MkDocs
7) Getting your Obsidian markdown files to MkDocs¶
Currently I use an Obsidian community plugin: "markdown-export"
Github: markdown-export
The file structure of the local export directory needs to be:
Testproject --> mkdocs.yml
|-- .git --> for git integration
|-- .cache --> will be created by mkdocs during export
|-- docs --> index.md
| |-- subfolders --> keeping additional markdown files
As I needed some adjustment in the export files so that screenshots are correctly included into my static html I had to extend the plugin with a regex/replace ability. Currently that is pending pull request and I am not acquainted enough yet with github and the whole toolchain to publish it on my own. It took me allready some time to figure out how to setup TypeScript for Obsidian MD and how to improve the plugin.
Tip
The index.md in the docs directory NEEDS to be written as shown! The file is case sensitive you NEED to use a lowercase "i" --> index.md
8) Creating your static Website to deploy to github¶
I take my notes in a documentation folder in Obsidian MD. I adjusted the markdown-export plugin to have an output directory into the MkDocs Testproject/docs folder and export into that folder.
Then I start Mkdocs and build the static site typing: mkdocs serve
After controlling the build static website I upload it to github by typing mkdocs gh-deploy
Future improvements:
- Improve markdown export with a profile setting
- maybe use another plugin Github Publisher (but I did not figure out yet if you can export localy)
- Setup a workflow on Github to build everything there from markdown files