个人网站搭建指南¶

本网站原基于 mkdocs-material 开发，后因 mkdocs 1.x 长时间无人维护，mkdocs 2.0 不兼容 mkdocs-material，故转向 material 团队的新作 Zensical .

pip install Zensical

由于可能存在的安装包冲突等未知问题，推荐使用一个独立环境，用 uv 管理或许会是个好选择。

uv init
uv add --dev Zensical

或者

uv venv .venv
.\.venv\Scripts\activate.ps1 # for Powershell
uv pip install Zensical

然后在根目录下运行

Zensical serve

即可在 localhost:8000 预览网页效果。更多相关信息，请访问官方Wiki.

一些经验¶

这种搭建网站的方式仅支持以 markdown 格式作为网页内容，实际上相当于个人博客。

推荐把网站搭载在 github 提供的免费网站服务器上，并且按照教程配置 gh-pages 分支的自动化追踪更新行为。

在过去，部署 GitHub Pages 的标准做法是：借助脚本将代码编译成 HTML，然后再把这些生成的静态文件用 git push 强制推送到一个名为 gh-pages 的孤儿分支（orphan branch）。GitHub 后台会监听这个分支，并将其内容挂载到 Web 服务器上。

现在的流程完全变了，完全跳过 Git 的版本控制机制，在一个云端的一次性虚拟机里把网页建好，打包成一个压缩包，然后直接通过后台 API 把压缩包‘投递’给 GitHub Pages 的网页服务器

upload-pages-artifact：把生成的 site 文件夹打包成一个压缩包（Artifact），存在这次 Action 运行的临时空间里。

deploy-pages：拿着上面那个压缩包，直接调用 GitHub Pages 的内部 API，把网页塞进服务器。

超链接相关¶

可以如下进行超链接编辑

[显示的的文字内容](跳转的地址){其它设置}

例如：[git 相关操作](./git 用法.md#3-ssh){target="_blank"}

这里的 {target="_blank"} 代表新开一个页面；#3-ssh 是特定章节的代号，有公式，但是不用记，直接在浏览器上打开这个要跳转的内部地址，点到这个章节，看网址就行。比如，以上例子的网址是 https://cloudmosquito.github.io/工具/git 用法/#3-ssh 。

效果如下：git 相关操作 。

数学公式相关¶

文档中的行间公式支持以下两种语法：

$$ JiaZhuang = Zhe * (Shi - Yi_Ge) + Shi^{Zi} $$

\[ JiaZhuang = Zhe * (Shi - Yi_Ge) + Shi^{Zi} \]

效果如下：

admonition¶

上面的 warning 警告块，就是一种 "admonition" 块，其基本语法为一个块以 !!! 开头，随后是一个用作类型限定符的单个关键词。块的内容在下一行，缩进四个空格：

!!! warning "（可选）自定义的标题"

    这里输入你想输入的文字

如果把 !!! 改成 ??? ，那么这个块就是可展开的（默认收起），如果是 ???+ ，那么这个块就是可展开的（默认展开）。

目前支持的 admonition 类型有官方自带的 note abstract info tip success question warning failure danger bug example quote .

图片相关¶

如需在文档内添加图片等资源，在文档根目录下创建 <文件名>.assets/ 目录来存放。

并且在 markdown里如下调用：

![](./ROS2%20学习记录.assets/rcl_layer.png){width=50%}

效果如下：

美观起见，一般需要让图片居中。可以在 docs/stylesheets/extra.css 里添加

.img-center {
    display: block;
    margin-left: auto;
    margin-right: auto;
}

extra_css:
    - stylesheets/extra.css

然后修改 Markdown ：

![](./ROS2%20学习记录.assets/rcl_layer.png){.img-center width=50%}

效果如下：