清水阁目前是一个基于Git和自动构建的开源博客。所有文章存在于Git仓库中，具体来说，位于content/blog文件夹中。作者在此处新建一篇Markdown格式的文章并提交，然后推送到远程Git仓库，自动构建系统就会将更新后的网站发布。
当然，为保护网站，Git仓库并不是任何人都能够提交。只有通过我们允许的作者（一般来说是我们的朋友），才能够获得提交的权限。而且一般我们也通过PR来保护main分支。
接下来简要介绍一般情况下从零开始发布文章的流程。
成为仓库协作者
这是一个社交问题。一些和我们认识的人，可能通过线下的交谈，确定意向后，我们就会把他拉进仓库的协作者。当然，有朋自远方来不亦乐乎？其他人如果想在清水阁发表文章，也是完全欢迎的。既然对方都不嫌弃我们的博客简陋，我们又有何资格自视清高，将其大作拒之门外？
因此，如果您想要在清水阁发表文章，请给站长线粒体发送邮件，表示您想要成为作者的意向。想必知道清水阁的人，跟我们在现实生活中多少是有点交集的。所以简单写一下即可，表明一下自己的身份。当然最好不要对线粒体恶语相向（逃
随后如果不出意外，我们就会把您拉进仓库的协作者。
以下几节为零基础小白设计，具备Git使用经验及开发经验的读者请跳到项目结构一节，直接上手。
安装Git
清水阁的维护是基于Git的，有一定的使用门槛，不过最基础的用法还算简单。以下简要介绍。对Git感兴趣的读者，这里介绍一份很好的入门资料：《廖雪峰Git教程》。
首先从Git官网安装Git，具体过程不赘述，选择适合自己系统的版本即可。
安装好后，在自己觉得合适的文件夹打开终端。例如，对于Windows，右键对应文件夹，选择「在终端中打开」；对于macOS，打开终端，输入命令（只作示例，实际文件夹不必与此相同）：
cd ~/Repos
在所需文件夹打开终端后，输入命令：
git clone https://github.com/MitochondriaCN/qingshuige-hugo.git
即可将仓库克隆到这个文件夹。
现在来讲讲Git。Git本质上是一个版本管理的工具。在我们日常用的一些软件中，编辑文件然后保存，那么存在于电脑中的就是这个文件的当前版本，以前的版本就会丢失。而使用Git就可以避免这个问题，因为每一次更改都有记录，就像一个账本。
为了使用这个「账本」管理我们的文件，首先要为所有文件创建一个仓库（repository），比如我们刚才克隆下来的清水阁仓库。仓库的克隆（clone）就是复制一个一模一样的仓库。
随后，文件的每一次更改都需要提交（commit），就像记账，这样所作的更改才能固定。提交非常关键，Git管理的基本单位就是提交。
接着，提交完了还要推送到远程（push to origin）。因为每个人都可以克隆仓库，这些仓库彼此是独立的，但我们的网站不可能分头行动、另立中央。所以终归还是要有一个集权，以最高的那个仓库为准，来部署我们的网站。这个仓库我们就称为远程。我们在克隆下来的仓库里提交之后，把提交推送到远程，才能真正将改动同步到网站。就像国务院印发文件到各级单位，你是下级，那么你自己在文件上圈点勾画是没有用的，最后的官方正本还是以国务院的版本为主。你只能把自己的意见报请国务院，国务院同意把你的改动加入正本，那才有用。显然，我们的国务院远程就是GitHub的仓库，GitHub是全球最大的仓库托管平台。
大家都可以推送到远程，那也就是说远程可能会随时变化，而我们本地的仓库可能会落后。为了紧跟远程的步调，我们使用拉取（pull）来将远程的提交传送到本地，保持本地与远程一致。
不同的人可能会对不同部分作修改，这些修改又往往可能导致冲突，或者与当前主流的进展相偏离。因此，各自可以先创建不同的分支（branch），在各自的分支上提交。当然，一个仓库通常只有一个主（main或master）分支。分支之间可以相互合并（merge），也就是把一个分支上的提交传递到另一个分支上。
我们的清水阁也是这一套工作流程。先把仓库克隆下来，然后自己新建文章，写好了之后提交，然后再推送到远程，这样就会自动部署到网站。
介绍编辑工具
我们目前推荐的编辑工具是Visual Studio Code。我们的标准其实只有两条：Markdown编辑体验好、Git GUI体验好。当然也可以选择任何自己喜欢的工具，只要趁手即可。
用VS Code打开刚才克隆的文件夹。这里注意到，VS Code一般是以文件夹为单位的，推荐直接打开清水阁仓库的文件夹，不推荐打开单个文件，因为没有办法用Git。
各个部分的功能，读者可以自己摸索。最左侧垂直一列是常用面板，文件管理、Git管理、插件等等都在其中。实际上，我们只使用其中的少部分功能。
比如文件管理面板，可以新建、删除、重命名文件等等。
又如Git管理面板，可以提交、推送、拉取、切换分支等等。
在这里我们顺带介绍一款十分实用的VS Code插件：Front Matter CMS。它提供GUI界面管理文章，很大程度上可以降低手动操作文件、编写Front Matter的繁琐。
限于篇幅，这些介绍只能起到抛砖引玉的作用，具体操作并不困难，请读者自行探索尝试。
项目结构
清水阁是一个非常典型的Hugo项目。接下来只介绍作者需要了解的两个最重要的文件夹，方便快速上手。
content/blog：包含所有博客文章。所谓发文章，其实就是在这个文件夹里新建一个Markdown文件。static/uploads：包含所有图片，请将图片上传到这里。
知道这两点，实际上就可以写文章并推送了。
规范与细节
首先是Front Matter问题。由于纯Markdown文件不包含元信息，Front Matter就充当文章的元信息。其一般位于文件开头几行，类似下面这种形式：
---
title: 亡魂
date: 2026-01-18T16:36:48.000+08:00
author: 猕猴桃教教主
categories: 艺
draft: false
---
我们目前所用的元信息，也就是上面这五项，请广大读者认真填写。其中categories（分类）分为文、诗、艺、学、其他五大类，可以是数组类型（多选），但我们的惯例是一篇文章只选一个分类，并且仅能从这五类中选择。另外，author（作者）可以自由填写，没有固定要求，完全可以像鲁迅那样用大量的笔名（逃
其次是图片的引用。如果图片上传为static/uploads/image.png，那么引用时应当这样写：
请务必注意引用的路径一开始是带/的。
最后，所有文件的命名，应当以简洁为要，不要使用太多符号。
关于推送
我们建议作者通过pull request进行推送。
番外：本地预览
一般来说，写点纯文本图片的文章，用VS Code自带的Markdown预览就足够了。不过，有些时候也需要追求一定的品味，直接预览网页渲染效果，这时候就需要额外多几项操作。这部分内容只面向有一定开发能力或探究意愿的读者。
首先需安装Hugo，请参考官方安装文档。
随后，由于我们的主题是自己开发的，通过submodule的方式包含在项目中，如果不拉下来，构建会报错。因此请在项目文件夹中执行：
git submodule update --init --recursive
这就会把主题的仓库也拉到项目里。
接着执行：
hugo serve
注意是动词serve而不是名词server。这会在本地开启一个简单的HTTP服务器，然后终端会输出访问地址。通过浏览器访问该地址，就可以看到网站的渲染效果。该预览是热更新的，只要文件有更改且保存，那么就会重新渲染。因此，非常适合作为侧边栏，一边编写一边预览。