MkDocs

• https://www.mkdocs.org/getting-started/

官方文档step by step init既可

注意一些没有被mkdocs.yml索引的文件也会一起打包出去，比如secret可以被访问(exclude_docs, draft_docs, not_in_nav都没啥用)

基本配置

• site_name
• nav
• theme
• favicon
• 默认配置 https://github.com/mkdocs/mkdocs/blob/master/mkdocs/themes/readthedocs/mkdocs_theme.yml
• 详细配置 https://www.mkdocs.org/user-guide/configuration/

主题

• mkdocs 默认主题
• readthedocs Read the Docs 的子集
• Material for MkDocs

基本差不多，暂时选readthedocs(https://github.com/Brilliant/notes/releases/tag/readthedocs)看起来在文档上更专业一点 缺点有点朴素，最基本的屏幕适配都没有，因此尝试mkdocs-material

自定义主题(Using the theme custom_dir)

• https://www.mkdocs.org/user-guide/customizing-your-theme/

把自定义的东西都放到这里，docs里面只有md文件，比较清晰

copyright

• 协议选择及样式 https://chooser-beta.creativecommons.org/

阅读 https://github.com/mkdocs/mkdocs/blob/master/mkdocs/themes/readthedocs/footer.html发现有两种方法

1. yml配置里直接写html

copyright: <p xmlns:cc="http://creativecommons.org/ns#" xmlns:dct="http://purl.org/dc/terms/"><span property="dct:title">Brilliant's Notes</span> is licensed under &copy; 2024 <a href="https://creativecommons.org/licenses/by-nc-nd/4.0/?ref=chooser-v1" target="_blank" rel="license noopener noreferrer" style="display:inline-block;">CC BY-NC-ND 4.0<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/cc.svg?ref=chooser-v1" alt=""><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/by.svg?ref=chooser-v1" alt=""><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/nc.svg?ref=chooser-v1" alt=""><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/nd.svg?ref=chooser-v1" alt=""></a></p>

1. 直接自定义 footer.html

扩展插件

可能用得上的插件

官方插件

• toc
• wikilinks

第三方插件

Python-Markdown wiki

• Markdown-LaTeX

MkDocs project catalog

• Material for MkDocs，一个比较火的还在维护的主题
• rss，目测Cloudflare的Git集成只拉取了最新的commit，导致大多数文章的git history为空，所以需要通过Github Actions来部署
• mermaid2
• mkdocs-jupyter
• git-revision-date-localized，自动根据git文件的历史设置create/update时间，不会读Front Matter适配
• Math extension

超链接

wiki风格都超链接更加方便一点，但是git等网站接受度不高（不能自动调整），暂时还是选用传统风格的超链接

• WikiLink风格的超链接支持 https://github.com/orbikm/mkdocs-ezlinks-plugin
• 或者使用pre-commit hook做样式检查

files=$(git diff --cached --name-only --diff-filter=AM | grep '\.md$')

# Redirect output to stderr.
exec 1>&2

for file in $files; do
    if grep -q '\[\[.*\]\]' "$file"; then
        echo "Error: Markdown file '$file' contains '[[' which is not allowed."
        exit 1
    fi
done

exit 0