newcomb-labs/engineering-journal-kb
GitHub: newcomb-labs/engineering-journal-kb
一个基于 Docusaurus 的工程日志与文档平台，用于集中化、可治理地沉淀知识并提供自动化内容管理。
Stars: 0 | Forks: 0
# Newcomb Labs — 工程日志
一个面向实验室、课堂笔记、案例研究、日志条目和治理文档的个人知识库与文档平台。
使用 **Docusaurus** 构建，并托管在 [chrisnewcomb.name](https://chrisnewcomb.name)。
## 内容板块
| 板块 | 说明 |
| --- | --- |
| `journal/` | 按日期记录的工程笔记、实验室笔记、架构决策与回顾 |
| `notes/class/` | 来自 BYU-Pathway Worldwide 课程的课堂笔记 |
| `personal/` | 信仰反思与个人写作 |
| `labs/` | 动手实验练习与逐步指南 |
| `case-studies/` | 故障排查记录与根因分析 |
| `decisions/` | 架构决策记录（ADR） |
| `governance/` | 仓库规范、内容契约、分类法与生命周期规则 |
| `engineering/` | 参考架构与自动化文档 |
| `operations/` | 运行手册与事件响应流程 |
| `library/` | 阅读笔记与参考资料 |
| `resources/` | 外部链接与精选参考 |
| `experiments/` | 探索性工作与概念验证 |
| `changelog/` | 站点与平台变更历史 |
| `drafts/` | 进行中的工作 |
| `templates/` | 所有 19 个分类的受控内容模板 |
## 技术栈
- **文档平台：** [Docusaurus 3.9](https://docusaurus.io)
- **托管：** GitHub Pages → Cloudflare CDN → `chrisnewcomb.name`
- **CI/CD：** GitHub Actions
- **代码检查：** MegaLinter（JS、CSS、Python、密钥与漏洞检查）
- **内容治理：** 自定义 Python 校验器与预提交钩子
- **拼写检查：** 带有自定义词典的 cspell
- **安全扫描：** Gitleaks、Secretlint、Trivy
## 内容治理
每个文档都需要包含受控的前置元数据块：
```
title: ""
description: ""
content_type: doc|journal|lab|case-study
type: doc|journal|lab|case-study
status: draft|active|deprecated
lifecycle: draft|active|deprecated
created_at: "YYYY-MM-DD"
last_reviewed: "YYYY-MM-DD"
owners:
- "@newcomb-labs"
tags:
- notes
primary_domain: networking|security|systems|...
category: journal|lab-notes|class-notes|...
```
完整的架构说明请参见 [治理文档](https://chrisnewcomb.name/docs/governance/repo-standards)。
## 生成内容
`generate_content_artifacts.py` 脚本会根据受控前置元数据生成确定性内容，确保每次提交后保持同步：
- **章节目录** — 每个 `index.md` 落地页都会自动生成目录，列出其文档范围内的条目
- **相关链接** — 内容文件会新增 `## 相关内容` 章节，基于标签、领域与分类的加权重叠计算生成
- **全站索引** — 位于 `/indexes/all-content` 的单一页面，按章节列出所有已发布文档
- **区域索引** — 位于 `_generated/indexes/` 的各章节索引
- **术语表** — 基于受控标签与术语构建的中心化术语表
- **内容清单** — 所有文档及其元数据的机器可读 JSON 清单
## 创建内容
使用内容脚手架 CLI：
```
# 新建日志条目
python3 scripts/new_content.py journal "My Entry Title"
# 新建课堂笔记
python3 scripts/new_content.py doc "My Notes Title" --category class-notes
# 新建实验笔记
python3 scripts/new_content.py journal "My Lab Title" --category lab-notes
# 新建 ADR
python3 scripts/new_content.py doc "ADR: My Decision" --category decisions
```
## 分支与提交规范
**分支命名：** `feat/`、`fix/`、`chore/`、`docs/`
**提交信息** 必须遵循 [Conventional Commits](https://www.conventionalcommits.org)：
```
feat(scope): description
fix(scope): description
docs(scope): description
chore(scope): description
```
**拉取请求** 必须包含 `type:*` 标签、`area:*` 标签，并关联对应问题。
## 本地开发
```
# 安装依赖
cd website && npm install
# 启动开发服务器
npm start
# 构建
npm run build
# 运行内容验证
python3 scripts/validate_content.py website/docs/...
# 运行预提交钩子
pre-commit run --all-files
```
## CI 工作流
所有 18 个 GitHub Actions 工作流均包含内联文档说明。关键流水线包括：
- **docs-ci** — 校验治理规则、检查 Markdown 格式、校验 Prettier、构建站点
- **content-validation** — 校验变更文件中的受控前置元数据
- **megalinter** — 对 JS、CSS、Python、YAML 进行代码检查与自动修复
- **spell-check** — 对 Markdown/MDX 执行 cspell 检查并监控旧版文档漂移
- **link-check** — 使用 lychee 扫描失效链接（PR、推送与每周调度）
- **conventional-commits** — 强制 PR 标题符合约定格式
- **pr-preview** — 为每个 PR 部署 Cloudflare Pages 预览
- **gitleaks** — 对每个 PR 和推送进行密钥扫描
所有 CI 工作流都会提交 `GITHUB_STEP_SUMMARY` 表格，以便快速查看结果。
## 版本
当前版本：`0.3.0` — 详见 [CHANGELOG.md](https://github.com/newcomb-labs/engineering-journal-kb/blob/main/CHANGELOG.md)
版本管理由 [Commitizen](https://commitizen-tools.github.io/commitizen/) 控制，
通过 `bumpversion.yml`（创建发布 PR）与 `release-tag.yml`（在合并时创建 Git 标签）实现。
标签：Docusaurus, Ruby, 个人知识管理, 内容模板, 变更日志, 可搜索知识库, 学习笔记, 实验室笔记, 工程文档, 技术写作, 搜索, 数据可视化, 文档系统, 架构决策记录, 案例研究, 治理文档, 知识库, 自动化文档, 课程笔记, 运行手册, 逆向工具, 静态站点生成