Markdown写作基础手册

个人使用

先从 Marktext 这个软件来熟悉 Markdown 的语法，如果已经熟悉了，跳到下一个环节

macOS系统安装

使用 Brew 这个命令行工具直接安装

brew install --cask mark-text

Windows系统安装

使用 choco 命令行工具直接安装

choco install marktext

使用 winget 命令行工具直接安装

winget install marktext

或者直接去marktext的github地址里下载 .exe 安装文件

当前版本是 v0.17.1

Vuepress的使用：资料编写

Node的安装及验证

  1. 去Node官方网站 下载当前的版本（推荐 LTS 版本），当前的 LTS 版本是 v22.11.0
  2. 找开一个命令行工具，windows 建议使用 powershell
    node -v
v22.11.0

Vuepress的安装及运行

  1. 去Vuepress官方网站 按要求安装，当前处版本是 v2.0.0-rc.18

  2. 创建项目，打开一个命令行工具，windows 建议使用 powershell

    npm init vuepress vuepress-starter

  3. 运行项目，打开一个命令行工具，windows 建议使用 powershell

    cd vuepress-starter #进入到项目的目录里去
npm run docs:dev #启动node运行项目

    应该能看到如下的内容

    ~ npm run docs:dev
> mediapipe_python@0.0.1 docs:dev
> vuepress dev docs

⠋ Initializing and preparing datawarning Broken links found in roadmap.md: /mediapipe/object.md, /mediapipe/image_classification.md, /mediapipe/image_segmentation.md, /mediapipe/gesture.md, /mediapipe/face.md
✔ Initializing and preparing data - done in 74ms

vite v5.4.10 dev server running at:

➜  Local:   http://localhost:8080/
➜  Network: http://192.168.0.141:8080/

  4. 在浏览器中，输入地址 http://localhost:8080/ ，就能看到默认的页面了

VSCode编辑器的安装

  1. 去VSCode官方网站 没有兼容问题，所以只需要下载最新版本就行

  2. 在编辑器中，打开上面的文件夹 vuepress-starter

  3. 进入页面Markdown语法说明 查看基本的书写语法

  4. 安装可选的插件，可以在上面的链接上面查看具体的说明，打开一个 bash 窗口，或者是 powershell窗口

    cd vuepress-starter #进入到项目的目录里去
npm i vuepress-plugin-md-enhance # 安装扩展插件

    修改文件 vuepress-starter/docs/.vuepress/config.js

    export default defineUserConfig({
    //在这个区域块中增加下面的代码
    plugins: [
        mdEnhancePlugin({
        // 启用 mermaid
        mermaid: true, //打开流程图的支持
        tasklist: true, //打开任务列表的支持
        }),
    ],
})

开始编写文件

  1. 打开编辑器 vscode
  2. 选择【打开文件夹】vuepress-starter
  3. 在目录 vuepress-starter/docs 下面新创建一个以 .md 为后缀名文件，例如 manual.md
  4. 在 vscode 中以 markdown 的格式来写文件，输入以下文字
    # Vuepress写作基础手册
## Vuepress的使用：资料编写
### Node的安装及验证
  5. 在上一步打开的文件夹中，输入地址 http://localhost:8080/manual.html ，确认一下是不是和看到的页面的内容一样，上面的内容分别表示一级，二级，三级标题

Git的使用

为了方便多方可以同时编写一个项目，可以使用 git 作为文档资料的版本控制软件，可以按下面步骤进行配置。每个人完成了自己的部分之后，推送到 git 服务器，其他人想看其他人写的，将文档资料从服务器同步到自己的电脑上，步骤可以演示为

安装 git

这里只给出客户端的操作步骤，服务器端假定已经完成，并且服务器端的操作都交给服务器管理员就行，如果有想法，可以参考其他文件

  1. 使用命令行安装 git

    brew install git #mac
choco install git #windows
winge install git  #window

  2. 生成本地 SSH 密钥

    brew install git #mac
choco install git #windows
winge install git  #window

  3. 把生成的密钥文件（ .pub结尾）传输给 Git 服务器管理员

  4. 使用如下命令检查是否可以拉取服务器端资源

    git clone git@git-server-name/repository-name.git

使用 git

使用下面这些命令进行基本的操作

 # 将服务器的内容拉取到本地，记得每次提交前都拉取一次服务器的内容
git pull

# 上面这个命令等同于下面这两个命令
git fetch
git rebase

# 提交自己的修改的内容
git commit -m '本次修改的标签' # 先保存自己修改的内容
git push # 将本地的内容推送到服务器

发布到网站

由 git 管理员完成