1. 项目概述一个为写作者打造的“数字工作台”如果你经常写作无论是技术博客、小说、学术论文还是日常笔记大概率都经历过这样的困扰文档散落在电脑各处格式五花八门想找个去年的草稿得翻半天想同步到手机上看又得折腾云盘更别提版本管理了改了几稿之后自己都分不清哪个是最新的。这些问题看似琐碎却实实在在地消耗着创作的心力。lechmazur/writing这个项目就是一位资深写作者项目作者 lechmazur为了解决这些痛点为自己、也为所有写作者打造的一个“数字工作台”。它不是一个臃肿的写作软件而是一套基于纯文本Markdown和 Git 版本控制的、高度可定制的工作流解决方案。简单来说它把程序员管理代码的那套高效、严谨的方法论优雅地应用到了写作领域。你所有的文章、笔记、草稿都以.md文件的形式存放在一个结构清晰的文件夹里然后用 Git 进行版本追踪和备份再配合一些自动化脚本和工具实现写作、管理、发布的全流程自动化。这个项目的核心价值在于“掌控感”和“流畅度”。它不把你锁定在任何专有格式或云端服务里你的所有文字资产就是一堆普通的文本文件未来几十年都能打开。同时它通过自动化工具把整理、格式化、发布这些繁琐的“家务活”都交给电脑让你能真正专注于思考和创作本身。接下来我会带你深入拆解这个项目的设计哲学、核心工具链以及如何从零开始搭建属于你自己的“写作系统”。2. 核心设计哲学为什么是“文本Git自动化”在深入具体操作之前理解背后的设计哲学至关重要。这决定了你是否能真正用好这套系统而不是仅仅照搬几个命令。2.1 纯文本的永恒性项目的基石是纯文本特别是 Markdown 格式。Markdown 是一种轻量级标记语言用简单的符号如#表示标题-表示列表就能定义格式。它的最大优势是“人机两读”人类看着清晰机器解析容易。相比 Word 的.docx或 Pages 的.pages一个.md文件在任何设备、任何操作系统上用最简单的文本编辑器都能打开和编辑且不会因为软件版本变迁而无法读取。这保证了你的作品具有最长的生命周期和最强的可移植性。注意虽然 Markdown 是核心但项目并不排斥其他纯文本格式比如.txt用于快速记录灵感.yaml或.toml用于管理元数据如文章标签、发布时间。一切皆文本这是灵活性的根源。2.2 Git 带来的版本时空机Git 是程序员的标配用于管理代码的每一次更改。把它用于写作简直是降维打击。每一次你完成一个段落、修改一个措辞都可以做一次“提交”commit并附上一句说明比如“重写了引言部分”或“修正了第五章的逻辑漏洞”。这样你的整个写作过程就被完整地记录下来了。你可以随时回溯到历史上的任何一个版本查看当时的思路或者找回被误删的精彩段落。这彻底解决了“稿子改乱了怎么办”的焦虑。更重要的是Git 的“分支”branch功能为写作提供了强大的实验场。你可以创建一个feature-rewrite-chapter3分支大胆地重写第三章而不用担心影响主线main分支的稳定性。写完后如果满意就合并进来不满意就丢弃这个分支主线内容毫发无损。2.3 自动化从“手工劳作”到“智能流水线”写作的核心是创造但围绕写作有大量重复性工作将 Markdown 转换成美观的 PDF 或 HTML、按照特定规则整理文件、生成文章索引列表、同步到博客平台等。lechmazur/writing项目提倡用脚本Shell, Python 等将这些工作自动化。比如一个简单的脚本可以遍历所有 Markdown 文件提取标题和摘要自动生成一个“文章目录”页面。另一个脚本可以调用pandoc工具一键将当前文章转换为并排双栏的 PDF 格式方便打印审阅。自动化脚本是你的私人助理。一旦设置好你只需要一个命令就能完成过去需要手动点击、拖拽、复制粘贴十分钟的工作。这不仅仅是节省时间更是保持心流状态不被中断的关键。3. 环境与工具链搭建理解了“为什么”我们来看“怎么做”。搭建这套系统你需要准备一些基础工具。别担心它们大多是免费、开源且跨平台的。3.1 核心三件套编辑器、终端与 Git文本编辑器/IDE这是你的主战场。推荐使用对 Markdown 和纯文本有良好支持的编辑器。VS Code绝大多数人的首选。免费、开源、插件生态极其丰富。必装插件Markdown All in One增强编辑体验、Markdown Preview Enhanced实时预览、Paste Image方便粘贴图片到 Markdown 中并自动处理路径。Vim / Neovim如果你熟悉命令行Vim 系列编辑器在纯文本编辑效率上无出其右配合一些插件也能成为强大的写作环境。Sublime Text轻量快速颜值高也是一个经典选择。 我的选择是 VS Code因为它平衡了易用性和强大功能插件系统能完美适配后续的自动化需求。终端Terminal这是你运行 Git 命令和自动化脚本的地方。macOS 和 Linux 系统自带终端Terminal, bash, zsh。Windows 用户强烈推荐使用Windows Terminal配合WSL2Windows Subsystem for Linux这样你就能在 Windows 上获得一个完整的 Linux 命令行环境工具安装和脚本运行会更顺畅。Git版本控制的核心。去 Git 官网下载并安装。安装后需要在终端里配置你的用户名和邮箱这是你提交记录的“身份证”。git config --global user.name 你的名字 git config --global user.email 你的邮箱3.2 扩展工具集让工作流飞起来Pandoc被誉为“文档转换的瑞士军刀”。它可以将 Markdown 转换成 PDF、Word、HTML、EPUB 等数十种格式。是自动化输出环节的绝对核心。安装后一个命令pandoc my-article.md -o my-article.pdf就能完成转换。Make一个经典的构建自动化工具。你可以编写一个Makefile文件在里面定义各种任务比如make pdf生成 PDFmake clean清理临时文件。这样你就不需要记住复杂的 pandoc 命令参数只需运行简单的make命令。Python/Node.js如果你需要更复杂的自动化逻辑比如从网络 API 获取数据插入文章或者进行复杂的文本分析那么一门脚本语言是必要的。Python 在数据处理和脚本编写上非常友好有丰富的库如frontmatter用于解析 Markdown 文件头部的元数据。Node.js 同样强大尤其在处理与现代 Web 技术栈相关的任务时。3.3 项目结构初始化工具准备好后我们来创建你的写作仓库。打开终端执行以下命令# 1. 创建一个专门用于写作的目录并进入 mkdir -p ~/Documents/my-writing-world cd ~/Documents/my-writing-world # 2. 初始化 Git 仓库 git init # 3. 创建基础目录结构这是一种常见且高效的组织方式 mkdir -p drafts # 存放草稿 mkdir -p posts # 存放已完成的文章 mkdir -p notes # 存放碎片化笔记、灵感 mkdir -p resources # 存放图片、附件等资源 mkdir -p scripts # 存放自动化脚本 mkdir -p templates # 存放 Pandoc 模板等 # 4. 创建必要的配置文件 touch README.md # 项目说明 touch .gitignore # 告诉 Git 哪些文件不需要跟踪如临时文件、大型PDF现在你的“数字工作台”的骨架就搭好了。接下来我们往里面填充血肉。4. 核心工作流实操详解让我们跟随一篇文章从诞生到发布的完整生命周期看看这套系统如何运作。4.1 阶段一灵感捕获与草稿管理灵感稍纵即逝。我通常在notes/目录下用日期和关键词快速创建一个笔记文件# 在 notes 目录下创建一个以日期开头的笔记方便排序和查找 cd ~/Documents/my-writing-world/notes touch $(date %Y-%m-%d)-ai-writing-workflow-ideas.md然后立刻用 VS Code 打开它开始记录。内容可能是零散的要点、一段突然想到的开头、一个需要查证的疑问。格式完全自由关键是先记下来。当某个笔记里的想法逐渐成熟足以发展成一篇文章时我就把它移动到drafts/目录下并给它起一个更正式的文件名比如how-i-organize-my-writing-with-git.md。这时我会在文件顶部添加一个YAML Front Matter区块用于记录文章的元数据--- title: 我是如何用 Git 和自动化脚本管理写作的 date: 2023-10-27 slug: organize-writing-with-git tags: [写作, 效率, Git, 自动化] status: draft # 状态标记为草稿 abstract: 本文分享了如何借鉴软件开发流程构建一个基于纯文本和版本控制的个人写作系统以实现高效、有序的创作与管理。 ---这个 Front Matter 非常重要它使得你的文章不再是“裸”的文本而是携带了结构化信息的数据。后续的自动化脚本可以轻松读取这些信息用于生成目录、筛选特定标签的文章等。4.2 阶段二沉浸式写作与版本控制进入写作状态后我专注于在编辑器中敲字。我会频繁地使用 Git 来保存进度# 在写作仓库的根目录下 # 1. 查看当前有哪些改动 git status # 2. 将改动添加到暂存区可以理解为准备打包 git add drafts/how-i-organize-my-writing-with-git.md # 3. 提交打包好的改动并附上清晰的说明 git commit -m feat: 完成了引言和核心设计哲学部分我遵循一种称为“约定式提交”的习惯在提交信息开头使用feat:、fix:、docs:等前缀让历史记录一目了然。例如feat:新增了一个章节或核心内容。fix:修正了错别字或逻辑错误。docs:只更新了注释或元数据。style:调整了格式如空格、换行不影响内容。这个阶段Git 就像我的“安全网”和“时间胶囊”让我可以毫无心理负担地尝试各种写法。4.3 阶段三格式化与多格式输出文章写完了status从draft改为completed接下来需要把它变成可以分享的格式。这就是 Pandoc 和自动化脚本大显身手的时候。首先在templates/目录下我可以准备一个自定义的 LaTeX 模板比如eisvogel.latex这是一个非常流行的 Pandoc PDF 模板让生成的 PDF 拥有漂亮的排版、页眉页脚和代码高亮。然后在scripts/目录下我创建一个名为build.sh的 Shell 脚本#!/bin/bash # scripts/build.sh ARTICLE$1 # 通过命令行参数传入文章文件名如 ./scripts/build.sh my-article.md if [ -z $ARTICLE ]; then echo 请指定要构建的文章文件例如: ./scripts/build.sh posts/my-article.md exit 1 fi # 获取文章基础名不含路径和扩展名 BASENAME$(basename $ARTICLE .md) # 使用 Pandoc 生成 PDF echo 正在生成 PDF... pandoc $ARTICLE \ --templatetemplates/eisvogel.latex \ --pdf-enginexelatex \ --listings \ # 为代码块启用 listings 包 -V CJKmainfontSource Han Serif SC \ # 指定中文字体 -o output/${BASENAME}.pdf # 使用 Pandoc 生成独立的 HTML 文件 echo 正在生成 HTML... pandoc $ARTICLE \ --self-contained \ # 将 CSS 样式内嵌 --csstemplates/style.css \ # 使用自定义 CSS -o output/${BASENAME}.html echo 构建完成输出文件在 output/ 目录下。给脚本执行权限并运行chmod x scripts/build.sh ./scripts/build.sh posts/how-i-organize-my-writing-with-git.md几秒钟后output/目录下就会同时出现一份排版精美的 PDF 和一份可以直接在浏览器中打开的 HTML 文件。你可以把 PDF 发给编辑或用于打印把 HTML 部署到自己的静态网站。4.4 阶段四发布与同步对于博客作者最后一步是发布。如果使用静态网站生成器如 Hugo, Jekyll, Hexo这个过程也可以自动化。通常你的posts/目录可以直接作为这些生成器的内容源。我可以写另一个脚本deploy.sh它负责将status: completed的文章从drafts/移动到posts/。运行静态网站生成器命令如hugo重新生成网站。将生成的静态文件推送到 GitHub Pages 或你的服务器。#!/bin/bash # scripts/deploy.sh # 1. 重新生成网站 cd /path/to/your/hugo/site hugo --minify # 2. 部署到 GitHub Pages (假设使用 gh-pages 分支) git add . git commit -m 更新文章$(date %Y-%m-%d) git push origin main # 或者使用 rsync 同步到自己的服务器 # rsync -avz public/ useryourserver.com:/var/www/html/至此从灵感到发布一个完整的、自动化的写作闭环就形成了。你只需要关心写作本身其他的事情都交给了可靠的工具和脚本。5. 高级技巧与个性化定制基础工作流跑通后你可以根据自己的需求进行深度定制这才是体现这套系统威力的地方。5.1 利用 Git Hooks 实现自动化质检Git 有一个强大的功能叫“钩子”hooks可以在特定事件如提交前、推送前自动触发脚本。我们可以用它来做一些自动检查。例如在.git/hooks/pre-commit如果没有就新建中写入#!/bin/bash # .git/hooks/pre-commit # 检查本次提交的 Markdown 文件中是否有拼写错误需要安装 aspell FILES$(git diff --cached --name-only --diff-filterACM | grep \.md$) if [ -n $FILES ]; then echo 运行拼写检查... for FILE in $FILES; do # 使用 aspell 检查英文拼写 aspell list --langen $FILE | sort -u # 你可以在这里加入中文检查逻辑如使用 cspell done # 如果发现错误可以在这里让提交失败exit 1 fi这样每次你执行git commit时它会自动检查你将要提交的 Markdown 文件提示可能的拼写错误帮助你提升稿件质量。5.2 构建全局文章索引与知识图谱你的文章和笔记越来越多如何快速找到相关内容可以写一个 Python 脚本定期扫描所有 Markdown 文件解析 Front Matter 中的标题、标签、摘要生成一个全局索引页面一个index.md文件或者甚至是一个可视化的知识图谱利用 Graphviz 生成关系图。这个脚本可以遍历posts/和notes/目录。用frontmatter库读取每个文件的元数据。按照标签、日期进行分类聚合。生成一个包含超链接的、按时间或主题排序的目录页。分析文章间的标签关联绘制出知识关联图。这个自动生成的索引页就是你个人写作世界的“导航地图”价值巨大。5.3 集成外部数据源写作常常需要引用数据。你可以编写脚本自动从公开 API如天气数据、股票数据、学术数据库获取最新信息并格式化成 Markdown 表格或图表插入到你的草稿中。例如一个每日复盘笔记的模板可以自动填充当天的天气和主要新闻标题。6. 常见问题与避坑指南在实际使用中你可能会遇到以下问题6.1 图片管理问题问题Markdown 中插入的图片路径在本地预览、生成 PDF、发布到网站时可能不一致导致图片无法显示。解决方案建立统一的资源管理策略。绝对路径与相对路径在 Markdown 中始终使用相对路径引用图片例如。这样文件在仓库内移动时相对关系保持不变。集中存放将所有图片、附件都放在resources/目录下并按文章或日期建立子文件夹如resources/2023-10-writing-workflow/。自动化处理使用 VS Code 的Paste Image插件截图粘贴时自动将图片保存到指定目录如resources/下的当天日期文件夹并在光标处生成正确的相对路径链接。这是提升体验的关键一步。6.2 Git 仓库体积膨胀问题如果存放了大量图片、生成的 PDF 等二进制文件Git 仓库会变得非常庞大克隆和同步速度变慢。解决方案严格使用.gitignore在.gitignore文件中忽略所有自动生成的、非源文件的内容。例如# 忽略输出目录 output/ # 忽略临时文件 *.tmp *.log # 忽略大型媒体文件考虑用 Git LFS 或单独存储 # *.pdf # *.zip对于必须版本控制的大文件使用 Git LFS如果确实需要跟踪某些大型 PDF 或视频可以使用 Git Large File Storage (LFS) 来管理避免主仓库膨胀。分离存储将最终成品如发布的 PDF、网站构建产物存储在专门的地方如云盘、对象存储而 Git 仓库只管理“源文件”Markdown、脚本、模板。6.3 跨设备同步与协作问题如何在办公室电脑、家里电脑和手机之间同步写作进度解决方案远程 Git 仓库将你的本地 Git 仓库推送到一个远程托管服务上如GitHub、GitLab或Gitee国内访问快。这样每台设备都克隆这个远程仓库通过git pull和git push来同步。这是最核心、最可靠的同步方式。移动端编辑在手机或平板上可以使用支持 Git 的 Markdown 编辑器如iA Writer支持 Working Copy 集成、1WriteriOS或MarkorAndroid。它们可以直接从 GitHub 等平台拉取和推送更新实现移动端轻量编辑。协作如果与他人合著Git 的分支和合并请求Pull Request功能就是天然的协作工具。每人可以在自己的分支上写作定期合并到主分支并通过 PR 进行内容评审。6.4 Pandoc 转换中文 PDF 乱码或排版错误问题这是中文用户最常见的问题。解决方案确保正确配置中文字体和 PDF 引擎。安装中文字体系统需安装中文字体如思源宋体、霞鹜文楷。在 macOS 和 Linux 下通常已安装Windows 用户可能需要手动安装。指定 PDF 引擎和字体在 Pandoc 命令中必须使用xelatex或lualatex引擎因为它们支持 Unicode 和系统字体。同时用-V CJKmainfont参数指定中文字体。pandoc input.md -o output.pdf \ --pdf-enginexelatex \ -V CJKmainfontSource Han Serif SC # 思源宋体简体使用预配置的模板像eisvogel这样的模板对中文支持较好。如果问题依旧可以手动编辑 LaTeX 模板在导言区添加\usepackage{xeCJK}等宏包进行更精细的控制。这套基于lechmazur/writing理念构建的系统其魅力在于它不是一个僵化的软件而是一个可生长、可定制的工作流。开始时你可能只需要 Git 来管理版本。随着需求增加你会逐渐加入自动化脚本、自定义模板、外部工具集成。它最终会演变成完全贴合你个人思维习惯和创作流程的“外脑”。最重要的是你对自己的数字创作资产拥有 100% 的所有权和掌控力这在这个数据和服务极易被锁定的时代显得尤为珍贵。