The knowledge base project has been migrated to the MkDocs project, and it works like a charm so far.
cons of DokuWiki
The knowledge base project was based on DokuWiki, with a Markdown plugin installed, I wrote wiki pages in Markdown format and using Doku’s media manager to host the attachments.
However, there are always some breaking changes for Doku, and it will get my theme and plugins incompatible once I upgraded. Moreover, creating or editing a wiki is also a tough job, the whole editing process is online, which may cause edit conflicts.
The ideal project structure should be a static site generator that schedules create pages based on the local markdown files. Finally, MkDocs is my concluding choice.
MkDocs feature
As its name, MkDocs is a static site generator especially for some project’s documents, it only uses a YAML config file to set up the meta info of the website, followed by a folder that contains all the markdown files, MkDocs will automatically create links hierarchy. It follows Markdown syntax, so do not need to worry about insert images, just simply put the image file in the directory or subdirectory.
Migration
Since I already use Markdown to write wiki, each file is already in Markdown format with a TXT extension name, so what I need to do is to change the extension name to .md for files in each subdirectory, a simple Python script can do this trick.
extension name from txt to MD for each subdirectory.
# ref: https://stackoverflow.com/a/37016368/3886059
import os
import sys
directory = os.path.dirname(os.path.realpath(sys.argv[0])) #get the directory of your script
for subdir, dirs, files in os.walk(directory):
for filename in files:
if filename.find('.txt') > 0:
subdirectoryPath = os.path.relpath(subdir, directory) #get the path to your subdirectory
filePath = os.path.join(subdirectoryPath, filename) #get the path to your file
newFilePath = filePath.replace(".txt",".md") #create the new name
os.rename(filePath, newFilePath) #rename your fileIf you insert images in DokuWiki using the web pop-up window (so called media-manager) , the image format should be ![[dir/imgurl.png]] , this need to be changed to markdown format ![]() , a simple Regex could also handle it.
host on GitHub
I host the knowledge base to a GitHub repo and implemented a Github Action for CI/CD. It means I can edit the wiki files locally, and when I finish editing, a simple git push to push all my local commits to GitHub and CI can automatically generate the site and publish to my server.
issue
The issue of MkDocs is mainly about the zh-CN localizations.
Currently, the MkDocs project did not support Chinese keyword searches. It works with English keywords, but for Chinese keywords, it returns nothing.
https://github.com/mkdocs/mkdocs/issues/2509#issuecomment-882689383
alternatives
If you use Obsidian as your note management tool, you can publish the Obsidian vault to the web as a knowledge base, despite the official publish service, Quartz, is also a good way to publish Obsidian to the web.