如何为该站点添砖加瓦？

1. 环境配置

本教程默认读者使用Win10及以上系统且有充足的存储/ram空间

1.0 网络配置

如果你不受GFW的限制可以畅通无阻地访问Github/pypi等站点请跳过此部分

在中国大陆内通过非国外渠道接入中国网络的用户上网都会受到一定程度的来自GFW 的干扰

因此我们需要配置一些工具来绕过GFW的干扰

1.0.1 Dev-SideCar

下载链接：https://github.com/docmirror/dev-sidecar/releases 下载完后运行按照指引安装根证书即可.

卸载与恢复：https://github.com/docmirror/dev-sidecar/blob/master/doc/recover.md

1.0.2 使用镜像源

PyPi镜像源设置已被写入本项目的pyproject.toml文件中无需设置.

Github镜像源

git config --global url."https://bgithub.xyz".insteadOf "https://github.com"

- 文中https://bgithub.xyz为镜像源网址如该镜像失效请替换为其他镜像站 - 请在Github Desktop安装完成(1.1.2步完成)后进行操作.

不可对Git镜像源进行push. 如需push 请恢复原有设置：

git config --global --unset url.https://bgithub.xyz.insteadof

1.0.3 科学上网

此方法不便描述请自行搜索.

Frez79(笔者)留：是的这一块只是为了让你知道有这么一个方法在这

1.1 Git/Github配置

1.1.1 Github注册

请参考官方文档：https://docs.github.com/zh/get-started/start-your-journey/creating-an-account-on-github

1.1.2 安装Github Desktop

访问https://desktop.github.com/download/ 点击图中包含Download字样的白色按钮以下载
运行下载下来的文件在经过非常短的安装后将会弹出如下界面：
点击Sign in to Github.com 在新打开的浏览器网页中点击Continue
在跳转到的授权页面中点击Authorize desktop按钮
此时授权完成回到Github Desktop 会进入如下图所示的界面勾选Use my开头的选项后再点击蓝色Finish按钮即可

1.2 Python/mkdocs环境配置

打开Github Desktop 点击左侧Clone开头的按钮在新弹出的窗口中选择URL 第一栏输入https://github.com/FET-CN/FlowEcho-Wave-Nexus.git 第二栏点击右侧Choose按钮以选择一个你希望存放仓库的文件夹最后点击Clone 等待下图界面出现
在上一步最后显示的窗口里按下 Ctrl+Shift+F 打开仓库进入tools目录双击运行firststep.bat

Note: Ctrl+Shift+F也是部分输入法的简繁切换快捷键

2. 文档编写

2.1 文档格式

该站点内容采用Markdown格式编写学习Markdown可参考：

2.2 文档分类

wiki 知识库: 位于docs/wiki目录下多带有教程性质
blog 博客: 位于docs/blog目录下多带有记录/随笔性质

目前其余分类暂不对外开放贡献权限.

2.3 放置图片

除不可抗因素该站点所有图片应均使用webp/svg格式存储于docs/images

每篇文章如有包含图片的都应在docs/images内创建文件夹并将图片放入其中

文件夹/文件的命名非必要不使用非ASCII字符/特殊字符/汉语拼音

2.4 [wiki]将文章加入导航栏

请先学习YAML(.yml文件格式)：https://www.runoob.com/w3cnote/yaml-intro.html

打开根目录下的mkdocs.yml文件搜索nav: 定位到导航栏部分.

找到知识库一栏在最后方追加你希望加入的文章例：

  - 知识库:
      - wiki/index.md
      - HandPy V2:
        - 固件编译: "wiki/HandPy_V2/FirmwareCompile.md"
        - MicroPython 1.12 QSTR 文档翻译: "wiki/HandPy_V2/Docs_QSTR.md"
        - 集成调试器: "wiki/HandPy_V2/IntegratedDebugger.md"
      - 如何为该站点添砖加瓦？: "wiki/How2Contribute.md"
      - 你需要添加的文章在导航栏内的标题: "wiki/你需要添加的文章在导航栏内的路径.md"
      - "wiki/不指定标题也是可以的.md"

创建分类同理.

需要注意的是所有填写的路径均以/docs为根目录也就是说路径内应省去/docs/

2.5 [blog]创建作者信息

请先学习YAML(.yml文件格式)：https://www.runoob.com/w3cnote/yaml-intro.html

打开/docs/blog/.authors.yml 在最后方追加内容格式如下：

    作者名(ID标记):
        name: 作者名字
        description: 作者介绍
        avatar: 作者头像(这里填URL)
        url: https://can1425.flowecho.org   # Author website URL

如该项不填写请注释该项(或删掉)

目前笔者(Frez79)还没读懂字段slug的作用有知道的可以在评论区说说吗

2.6 统一个人信息

该项目使用/dics/blog/.authors.yml与/mkdocs.yml存储博客作者信息与团队成员信息我们仅存储您的名字与ID 如果您原意提供更多你的信息我们也很乐意收下并在为此项目贡献文章时使用基于ID访问的名称/信息

您可以通过\{\{作者名(ID标记).name\}\}来引用作者名字.

您可以通过\{\{作者名(ID标记).\[对应信息的ID\]\}\}来引用作者\[对应信息\].

3. 预览文章

在Github Desktop中打开此仓库按下 Ctrl+` 打开命令行
使用命令uv run mkdocs serve 开启预览服务
在预览您的文章.

4. 上传文章

作为一般用户您可能没有足够的权限进行push操作此时您可以通过 PR(Pull Request) 解决这一问题：

https://blog.csdn.net/Supreme7/article/details/136813376

打开Github Desktop 映入眼帘的应该是你的Github仓库页面如图所示白色框框标记的位置将会显示你所做的更改你可以通过简单的鼠标单击来选择你希望提交的更改
填写左下角的Summary与Description
- Summary: 你这次贡献大致做了什么简短描述
- Description: 你这次贡献的详细描述可写可不写
填写完毕后点击左下角以Commit开头的蓝色按钮提交更改此时你刚刚填写的两个字段将会锁定等待出现如下界面即可

左下角将会显示您刚刚成功提交的信息此时点击Undo可以撤销提交
此时点击右上角带有Push字样的按钮即可