如何在本地 p5.js-website 中预览 contributor_docs 的文档修改效果？-育师

如何在本地 p5.js-website 中预览 contributor_docs 的文档修改效果？

【免费下载链接】p5.jsp5.js is a client-side JS platform that empowers artists, designers, students, and anyone to learn to code and express themselves creatively on the web. It is based on the core principles of Processing. Looking for p5.js 2.0? http://beta.p5js.org项目地址: https://gitcode.com/GitHub_Trending/p5/p5.js

你在 p5.js 仓库的contributor_docs/目录下修改（或新写）了 Markdown 文档，想确认它在网站上真实的显示效果——页面布局、字体样式、文档列表里的标题与副标题——而不是只盯着 Markdown 源码看。这些 contributor 文档最终发布在 p5.js 官网的contribute/路径下（v1 与 v2 站点各自有一版内容），但网站本身是独立的 p5.js-website 仓库，源码并不在本仓库里。官方的做法是在本地运行 p5.js-website，并让它从你本地 p5.js 仓库的某个分支导入文档来构建页面。下面这条流程来自本仓库的 contributor 文档编写指南。

先交代一个影响操作的前提：p5.js 仓库的 v1.x 与 v2.x 分支保存的是不同的文档，本文步骤对应网站的2.0分支，也就是 p5.js v2 站点。

准备：把改动提交到本地分支

预览流程的工作方式是“指定一个 p5.js 仓库路径 + 分支名，由网站构建过程去克隆它”，因此你的改动必须满足：

已提交（commit）到你 p5.js 仓库 fork 的某个本地分支上；
不需要推送到 GitHub，但必须提交——未提交的改动不会被网站构建过程取到。

可选：先用编辑器快速预览

如果只想确认 Markdown 结构，可以先用编辑器的 Markdown 渲染功能（文档以 VS Code 为例）：

打开要预览的.md文件；
打开命令面板（F1或cmd-shift-p/ctrl-shift-p）；
输入Markdown: open preview。

这个快速预览的局限是：p5.js 网站的页面布局和样式（颜色、字体、行宽等）都不会应用，不能用来核对最终视觉效果，只是省一次本地构建。

在本地 p5.js-website 中跑完整预览

文档假设的本地文件夹结构是：p5.js 仓库与 p5.js-website 仓库并排放在同一父目录下（分别叫p5.js和p5.js-website）。

1. 克隆 p5.js-website 并安装依赖

把 p5.js-website 仓库克隆到 p5.js 仓库旁边的文件夹，然后在它里面打开终端，检出2.0分支并安装依赖：

git checkout 2.0 npm install

npm install只为 p5.js-website 项目本身安装依赖，不会改动你的 p5.js 仓库。

2. 构建 contributor 文档并启动预览

在 p5.js-website 目录下执行下面这条命令。注意文档特别强调：这是一行命令，不是两行：

P5_REPO_URL=path/to/your/p5/repo P5_BRANCH=your-branch-goes-here npm run build:contributor-docs && npm run dev

其中两个环境变量需要你替换：

P5_REPO_URL：指向你本地 p5.js 仓库的路径；
P5_BRANCH：你的改动所在的本地分支名。

文档给出的示例：p5.js 仓库就放在当前p5.js-website文件夹的旁边（../p5.js），分支名叫my-amazing-branch：

P5_REPO_URL=../p5.js P5_BRANCH=my-amazing-branch npm run build:contributor-docs && npm run dev

这一条命令会依次做三件事：

从你指定分支的contributor_docs/目录导入.md文件，构建为网站的.mdx页面；
启动网站的开发预览服务器；
在控制台打印出本地网站的访问 URL。

3. 核对预览结果

在浏览器访问控制台打印出的 URL，进入contribute/路径，按文档给出的规则核对：

你的文档应出现在 contributor 文档列表中，标题取自文件里第一个 level 1（H1）标题，而不是文件名；
直接访问某个文档的 URL 路径是contribute/文件名（不含扩展名）/，例如myFile.md对应contribute/myFile/——开发模式下末尾的斜杠/必须保留；
列表页展示的副标题来自文件第一行的 HTML 注释（必须在 H1 标题之前）。例如 contributor_docs/unit_testing.md 首行注释是 "Guide to writing tests for p5.js source code."，因此该页在网站上以 "Unit Testing" 为标题、以这句注释为描述显示。

替代路径：构建已经推到 GitHub 的分支

如果改动已经推到了远端分支，也可以让网站直接基于远端仓库构建：把上面命令里的P5_REPO_URL从本地路径改成你自己 fork 仓库的 URL（文档中该位置的占位形式是https://github.com/yourUsername/p5.js.git，替换为你 fork 的实际地址即可），P5_BRANCH保持不变，仍然是单行命令：

P5_REPO_URL=your-fork-repo-url P5_BRANCH=your-branch-goes-here npm run build:contributor-docs && npm run dev

本地路径方式适合还在迭代中的改动；远端方式适合预览已经 push 出去的工作，二者不需要在同一次操作里混用。

文档不显示时怎么排查

如果改动后的文件没有出现在contribute/的列表里，文档给出的检查顺序是：

先确认标题：页面标题取自文件第一个 level 1 标题而非文件名，你可能没认出自己的条目；
检查 p5.js-website 文件结构中src/content/contributor-docs/en目录下是否生成了对应的.mdx文件；没有的话，确认你的.md文件是否已提交在你指定的分支上、位置是否正确，并查看build:contributor-docs过程的日志；
回看上一次npm run build:contributor-docs运行的日志，确认其中有对你文件的提及；
如果日志显示.mdx文件确实生成了，就在网站里直接输入该文档的 URL（如contribute/myFile/）访问，确认页面本身可打开；
确认日志显示你的仓库确实被克隆了：网站构建过程有缓存机制，最近克隆过的仓库不会被再次克隆。删除 p5.js-website 仓库中的in/p5.js/文件夹可以强制构建过程重新克隆。