TinyCAD 手册
tinycad.net

为 TinyCAD 手册做贡献

本手册通过 GitHub Pages 发布。如果您发现错误、缺失的步骤、含糊不清的 屏幕截图或过时的信息,可以通过拉取请求(PR)提出修正。

本指南介绍两种工作流程:

  • 在浏览器中快速编辑(适合小幅文字修正)
  • 本地编辑并预览(适合较大的更改)

开始之前

您需要:

  • 一个 GitHub 帐户
  • 本地编辑所需:Git、Node.js、Ruby 和 Bundler

仓库详情:

  • 源代码仓库: https://github.com/matt123p/TinyCAD-docs
  • 已发布的网站: 此仓库通过 GitHub Pages 发布的内容
  • 文档源文件夹: docs/
  • v4 页面: docs/v4/

选项 A:在 GitHub 中快速编辑(无需本地配置)

此方法适用于修正拼写错误、简短说明或更新链接。

1) 在 GitHub 上打开页面源文件

  1. 前往 TinyCAD 文档仓库: https://github.com/matt123p/TinyCAD-docs
  2. 在 docs/v4/ 中找到您要编辑的页面。
  3. 打开 Markdown 文件(例如 Rulers.md)。

2) 开始编辑

  1. 点击铅笔图标(编辑此文件(Edit this file))。
  2. 如果出现提示,GitHub 会帮助您自动创建一个分支仓库。
  3. 使用 Markdown 进行修改。

3) 提交更改

  1. 向下滚动到提交更改(Commit changes)。
  2. 使用清晰的提交说明,例如: docs(v4): clarify ruler units in Rulers
  3. 选择为此提交创建新分支(Create a new branch for this commit)。
  4. 点击提出更改(Propose changes)。

4) 创建拉取请求

  1. 点击比较并创建拉取请求(Compare & pull request)。
  2. 将基础仓库设为 matt123p/TinyCAD-docs,并将基础分支设为 main。
  3. 填写 PR 标题和说明(请参阅下方模板)。
  4. 提交 PR。

如果您需要编辑多个文件、检查链接或预览格式,请使用此方法。

1) 创建分支仓库并克隆

  1. 在 GitHub 上为 matt123p/TinyCAD-docs 创建分支仓库。
  2. 克隆您的分支仓库:
git clone https://github.com/<your-username>/TinyCAD-docs.git
cd TinyCAD-docs
  1. 添加上游远程仓库:
git remote add upstream https://github.com/matt123p/TinyCAD-docs.git

2) 安装依赖项

此仓库提供了 npm 脚本,可代您运行 Bundler 和 Jekyll:

npm install
npm run bundle:install

3) 为您的更改创建分支

git checkout -b docs/v4-fix-rulers

分支命名示例:

  • docs/fix-typo-...
  • docs/v4-update-...
  • docs/add-...

4) 进行编辑

大多数面向用户的页面位于:

  • docs/v4/*.md(v4 手册页面)
  • docs/v3/*.md(v3 手册页面)
  • docs/_data/navigation.yml(左侧导航)

如果您添加了新页面,也请更新导航,以便用户找到该页面。

5) 在本地预览网站

npm run serve

然后打开终端中显示的本地 URL(通常为 http://127.0.0.1:4000)。

请检查:

  • 标题层级清晰易读
  • 内部链接有效
  • 导航中包含新增或重命名的页面
  • 图片能够正确加载

6) 提交并推送

git add .
git commit -m "docs(v4): improve Rulers instructions"
git push -u origin docs/v4-fix-rulers

7) 创建 PR

  1. 在 GitHub 上打开您的分支仓库。
  2. 针对您的分支,点击比较并创建拉取请求(Compare & pull request)。
  3. 将目标设为 matt123p/TinyCAD-docs:main。
  4. 完成 PR 标题和说明,然后提交。

写作质量检查清单

创建 PR 前,请快速确认:

  • 范围明确(每个 PR 聚焦一个主题或问题)
  • 说明符合当前 TinyCAD 的实际行为
  • 语言清晰简洁
  • 链接目标有效
  • 必要时已将页面添加到导航中
  • 保留现有风格和术语

可复用的浏览器/桌面应用标签页组

如果页面需要分别说明如何在浏览器版 TinyCAD 和桌面应用中操作,请使用 共享的标签页组组件,而不是自行设计页面专用标记。

<div class="manual-tabset" data-tabset="product-mode" data-tabset-label="Choose your TinyCAD product" data-default-tab="Browser" markdown="1">

### Browser

Browser-specific content.

### Desktop App

Desktop-specific content.

</div>

说明:

  • data-tabset 是同步/存储键。请使用相同的值,以便同一页面上的多个 标签页组保持同步。
  • data-default-tab 用于设置首次访问时选中的标签页。
  • 各标签页标题应使用相同的级别(上方示例中的 ###)。

建议的 PR 模板

将以下内容复制并粘贴到 PR 说明中:

## Summary
-

## What changed
-

## Why
-

## Validation
- [ ] Previewed locally with `npm run serve`
- [ ] Checked navigation and links
- [ ] Confirmed formatting on rendered page

## Screenshots (if relevant)
-

使您的分支仓库保持最新

如果您的 PR 挂起了一段时间,请将分支与最新的 main 同步:

git fetch upstream
git checkout main
git merge upstream/main
git push origin main

git checkout docs/v4-fix-rulers
git merge main
git push

常见问题及修复方法

  • PR 显示了无关的文件更改
    • 从已更新的 main 创建一个全新分支,并只拣选您的提交。
  • 缺少导航项
    • 更新 docs/_data/navigation.yml,并确保 URL 与页面永久链接路径一致。
  • 页面显示异常
    • 检查标题级别、列表缩进以及围栏代码块标记。
  • 本地链接有效,但在 Pages 上无效
    • 优先使用此仓库中其他位置采用的相对链接,并保持页面名称一致。

提交之后

维护者可能会要求您进行更新。请将后续提交添加到同一分支/PR; PR 会自动更新。获批并合并后,GitHub Pages 重新构建完成时,您的更改 就会显示在已发布的手册中。

感谢您为改进 TinyCAD 文档所做的贡献。