Quick Reference 备忘清单排版语法与贡献指南rehype 注释驱动的速查表构建全解析【免费下载链接】reference面向开发者的技术速查清单Cheat Sheets集合整理常见技术、工具与开发流程帮助快速查阅关键信息提高开发效率。项目地址: https://gitcode.com/GitHub_Trending/referen/reference本篇技术指南完整讲解 referen/referenceQuick Reference 备忘清单项目中最核心的规范文档——docs/quickreference.md它既是排版说明也是每一位贡献者编写速查表时必须遵循的样式与语法手册。读完本文你将掌握从零创建一份可编译、可上首页导航的 Markdown 速查清单的方法精通!--rehype:...--注释语法、卡片布局系统、表格与列表样式以及.refsrc站点配置能够像项目维护者一样写出排版精良、布局专业的备忘清单。文档定位为什么需要一份排版说明Quick Reference 项目面向开发者收集各类技术速查清单每一份清单都是docs目录下的一个 Markdown 文件如 docs/bash.md、docs/cron.md、docs/yaml.md。这些.md文件会被refs-cli编译成 HTML 静态页面。为了让所有清单在视觉上统一、美观且适配不同内容密度项目定义了一套基于 HTML 注释的排版语法。quickreference.md正是这套语法的活字典——它本身就是一个编译成形的排版示例页文中每个样式后面都跟着对应的源码写法读者可以对照预览效果与源码学习。从 package.json 可以看到整个构建链路的实现build脚本执行refs-cli npm run cpystart脚本执行npm run cpy refs-cli --watch其中cpy负责把 appicon 目录的 PNG 图标复制到dist/appicon而核心的 Markdown → HTML 转换由refs-cliwcj/reference的配套 CLI完成。入门本地编译预览克隆仓库并安装依赖将仓库克隆到本地后执行git clone gitgithub.com:jaywcjlove/reference.git进入仓库目录安装依赖并编译npm i # 安装依赖 npm run build # 编译输出 HTML编译产物 HTML 存放在仓库根目录下的dist目录中直接用浏览器打开dist/index.html即可静态预览整个站点。开发调试时使用监听模式npm run start # 监听 md 文件变更实时编译输出 HTMLnpm run start对应的脚本是npm run cpy refs-cli --watch见 package.json它会在监听docs/*.md变化的同时持续重新生成 HTML方便编写清单时边写边看。项目要求 Node.js 16.0.0见 package.json 的engines字段。如果使用 Netlify 部署netlify.toml 已配置好构建命令与发布目录[build] command npm run build publish dist若使用 Docker 部署Dockerfile 基于wcjiang/docker-static-website镜像将dist目录静态拷贝进镜像即可。仓库目录结构. ├── CONTRIBUTING.md # 贡献说明 ├── Dockerfile ├── LICENSE ├── README.md # Home(首页)内容用于生成首页导航 ├── dist # 编译后的静态资源目录 ├── docs # Markdown 文档(速查表)如 bash.md、yaml.md │ ├── bash.md │ ├── cron.md │ └── yaml.md ├── assets # LOGO 图标文件资源SVG ├── appicon # 应用图标PNG构建时复制到 dist/appicon ├── .refsrc.json # refs 站点配置可选 ├── package.json └── netlify.toml需要注意本仓库中首页导航图标统一存放在 assets 目录原文档写作/assets实际根目录下为assets/与docs/{name}.md一一对应例如docs/cron.md对应assets/cron.svg。添加一份备忘清单基础骨架一份最简单的备忘清单只包含四层结构页面大标题H1、介绍文本、分类标题H2、卡片H3备忘清单 (页面大标题) 这是您可以在当前清单上使用的样式参考备忘清单介绍 入门 (分类标题) --- ### 介绍 (卡片) 卡片内容其中 H1 使用下划线标题语法标识页面大标题紧跟其后的段落是整页介绍---分隔出 H2 分类标题###则是一个个卡片。将上述内容保存为docs/xxx.md编译后即可生成对应页面。参考真实示例 docs/cron.md其开头正是标题 介绍 分类的三段式结构。每个卡片盒子H3 部分会包含 H3 标题之下的所有内容卡片内可嵌套####子标题、pre代码块、table表格、ul列表等子项。首页导航与图标配置首页README.md存放在仓库根目录refs-cli根据其中的链接自动生成首页导航卡片。导航写法如下## Linux 命令 [Cron](https://link.gitcode.com/i/ec638ef495651792b7b1d3db54019c83)!--rehype:stylebackground: rgb(239 68 68/var(\-\-bg\-opacity));-- !--rehype:classhome-card--要点说明每个名称链接一行!--rehype:classhome-card--标记这组链接按卡片样式展示。首页导航图标存放在 assets 目录若清单定义为docs/cron.md则图标命名为cron.svg注意大小写一致放在assets目录重新编译后首页菜单即拥有图标。SVG 图标尺寸建议svg height1em width1em颜色使用继承值svg fillcurrentColor这样图标能随主题与文字颜色自动适配。首页提示配置给导航链接添加contributing类名会在卡片下方默认显示待完善需要您的参与[Django](https://link.gitcode.com/i/448e00a2aed852a9c2a5e38531c87e29)!--rehype:stylebackground: rgb(12 75 51/var(\-\-bg\-opacity));classcontributing--通过data-info可以替换默认提示文本[Django](https://link.gitcode.com/i/448e00a2aed852a9c2a5e38531c87e29)!--rehype:stylebackground: rgb(12 75 51/var(\-\-bg\-opacity));classtagdata-info看看还缺点儿什么--添加classtagdata-langPython后会在卡片右上角标记语言标签[Django](https://link.gitcode.com/i/448e00a2aed852a9c2a5e38531c87e29)!--rehype:stylebackground: rgb(12 75 51/var(\-\-bg\-opacity));classtagdata-langPython--上述模式在 README.md 中被大量使用例如 Flask、FastAPI、Flutter 等条目均带有contributing tagdata-lang...组合。实际编写新清单时建议先对照 README.md 中已有的导航写法复制修改并保持链接为从仓库根目录出发的相对路径如docs/xxx.md。refs-cli 命令帮助refs-cli是负责编译站点的命令行工具其完整帮助信息如下Usage: refs-cli [output-dir] [--help|h] 显示帮助信息 Options: --version, -v 显示版本号 --help, -h 显示帮助信息 --watch, -w 观看并编译 Markdown 文件 --output, -o 输出目录。默认dist --force, -f 强制文件重新生成 Example: $ npx refs-cli $ refs-cli --watch $ refs-cli --output website $ refs-cli refs-cliv0.0.1实际使用中npm run build等价于默认输出到dist的完整构建npm run start则对应--watch监听模式。站点配置.refsrc 配置文件将.refsrc.json存放在项目根目录即可配置站点标题、搜索、页脚等{ title: 文档网站名称, description: {{description}} 网站说明, keywords: 关键字,refs-cli,refs,cli, data-info: 需要你的参与, search: { label: 搜索, placeholder: 搜索备忘清单, cancel: 取消 }, editor: { label: 编辑 }, github: { url: https://github url }, home: { label: 首页, url: https://你的网站 }, footer: br /备案号支持HTML字符串, license: 支持 HTML 字符串 }各键含义title为站点名称description/keywords用于 SEO其中{{description}}是模板占位符data-info设置默认的待完善提示search配置搜索框文案editor配置编辑按钮文案github配置仓库链接home配置首页链接footer与license支持 HTML 字符串如备案号、版权信息。TOML 配置示例配置文件同样支持 TOML 格式将.refsrc.toml存放在项目根目录title Refs CLI 文档网站名称 description {{description}}. 网站说明 keywords 关键字,reference,refs-cli,cli>REF_URLhttp://ref.ecdata.cn/ REF_LABEL网站首页页脚添加内容支持 HTML 字符串REF_FOOTER备案号沪ICP备20220000000号-1修改版权信息支持 HTML 字符串LICENSECopyright (c) b2022/b 小弟调调™在 Markdown 中引入图片备忘清单支持 Markdown 与 HTML 两种图片写法注意 URL 末尾追加?#sss1查询参数可避免缓存问题[](https://link.gitcode.com/i/544383d804092a6c6d980f92b6a71768) img srcicons/favicon.svg?#sss1 altalt text height95 width95 /alt text img srcassets/quickreference.svg?#sss1 altalt text height95 width95 /项目根目录的 icons 存放站点图标如favicon.svg、触摸图标等assets 存放各清单的首页导航 SVG 图标如assets/quickreference.svg。核心rehype 注释语法这是整个排版体系的灵魂。备忘清单采用HTML 注释语法来标识网站布局与样式目的是让源码在 GitHub 上也能保持正常、无瑕疵的预览。基本写法在某个 Markdown 元素下方或后面添加 HTML 注释以!--rehype:开始、--结束内容采用 URL 参数的字符拼接方式### 卡片标题 !--rehype:wrap-classcol-span-2-- 卡片 Markdown 内容展示下面注释语法为文字内容改变样式 !--rehype:stylecolor: red;--语法结构!--rehype: keyvalue keyvalue -- 标识开始 参数 分隔符() 参数 标识结束示例## H2 部分 !--rehype:body-classcols-2-- ### H3 部分 !--rehype:wrap-classrow-span-2--三行占位 红色标题的组合示例### 标题 !--rehype:wrap-classrow-span-3stylecolor:red;--四个核心参数参数说明body-style包裹所有卡片外壳的样式body-class用于卡片栏布局添加类名wrap-style卡片栏添加 CSS 样式wrap-class用于卡片占位添加类名文字颜色_我是红色_!--rehype:stylecolor: red;-- **加粗红色**!--rehype:stylecolor: red;--给文字含斜体、加粗下方添加stylecolor: red;注释即可将文字渲染为红色。文字大小**加粗变大红色** !--rehype:stylecolor: red;font-size: 18px--样式注释支持多个 CSS 属性用分号连接例如同时设置颜色与字号。强制换行wrap-text如果代码块内容太长在其注释中加wrap-text类即可强制换行避免横向溢出\js function () {} \ !--rehype:classNamewrap-text--展示表格表头show-header在表格下方添加show-header类表头行将被展示出来| Key | value | | ---- | ---- | | 键 | 值 | !--rehype:classNameshow-header--代码行高亮代码块 meta 位置使用{1,4-5}指定高亮行jsx {1,4-5} import React from react; import ./Student.css; export const Student ( div classNameStudent/div ); 即jsx {1,4-5}表示高亮第 1 行与第 4~5 行。行高亮可以同时与代码行号showLineNumbers一起使用。Tooltips 提示给文本添加!--rehype:tooltips--注释即可生成鼠标悬停提示鼠标移动到上面有提示 _Tooltips 的提示内容_!--rehype:tooltips--卡片背景颜色wrap-style可设置整张卡片H3 部分的背景### H3 部分(卡片)背景颜色 !--rehype:wrap-stylebackground: #8dffd42e;--标题背景色在 H3 标题下面添加!--rehype:stylebackground:#e91e63;--可让标题显示为红色背景#d7a100对应黄色背景标题。快捷键样式shortcuts表格首列加shortcuts类首列将以快捷键键帽样式展示| Key | value | | ---- | ---- | | 快捷键 | 说明 | | 快捷键 | 说明 | !--rehype:classNameshortcuts--表格尾列加shortcuts-last类尾列以快捷键样式展示| Key | value | | ---- | ---- | | 说明 | 快捷键 | | 说明 | 快捷键 | !--rehype:classNameshortcuts-last--代码行号showLineNumbers在代码块语言标识后追加showLineNumbers即可显示行号jsx showLineNumbers export const Student div学生/div; const school div学校/div; 内置类样式汇总| 类 | 说明 | | :- | - | |shortcuts| 快捷键样式 | |wrap-text| 超出换行 | |show-header| 展示表头 | |style-none| 隐藏ul列表样式 | |style-list|table单元格行展示 |颜色标签在 Markdown 中可以直接使用这些标签内联着色| 语法 | 效果 | | :- | - | |yel| 黄色 | |red| 红色 | |pur| 紫色 | |code或| 绿色代码 | |del或~~删除~~| 删除线样式 |HTML 代码实时预览在代码块 meta 位置添加preview标识HTML 代码将被执行预览html preview b这里是你的 HTML 代码/b 编译后该代码块不仅展示源码还会在页面中实际渲染出预览效果参见 HTML 相关说明。隐藏卡片标题在 H3 标题下添加display:none样式可隐藏标题配合padding-top: 0收紧间距### 隐藏卡片标题 !--rehype:styledisplay:none;wrap-stylepadding-top: 0;--注释类配置总表类说明!--rehype:classNamewrap-text--强制换行!--rehype:classNameshow-header--展示表格表头!--rehype:classNameshortcuts--首列快捷键样式!--rehype:classNameshortcuts-last--尾列快捷键样式!--rehype:classNameauto-wrap--隐藏表头强制小尺寸自动换行!--rehype:classNamestyle-list-arrow--列表箭头样式展示表格!--rehype:classNamestyle-list--列表样式展示表格!--rehype:classNameleft-align--表格末尾列左对齐!--rehype:classNamestyle-none--li无标记样式!--rehype:classNamestyle-timeline--时间轴样式!--rehype:classNamestyle-arrow--箭头标记KaTeX 数学渲染备忘清单支持 KaTeX 数学公式渲染基于 KaTeX 生成KaTeX c \pm\sqrt{a^2 b^2} L \frac{1}{2} \rho v^2 S C_L 还可以单行内联展示KaTeX:c \pm\sqrt{a^2 b^2}即用反引号包裹KaTeX:数学公式即会渲染为数学公式。布局系统卡片栏布局H2 级别H2 标题下的多个 H3 卡片默认按3栏布局展示H2 部分 --- ### 卡片 1 (H3 部分) ### 卡片 2 (H3 部分) ### 卡片 3 (H3 部分)通过body-class可调整栏数H2 部分 --- !--rehype:body-classcols-2-- ### 卡片 1 (H3 部分) ### 卡片 2 (H3 部分) ### 卡片 3 (H3 部分)支持的栏数类类说明cols-11 栏卡片布局cols-22 栏卡片布局cols-33 栏卡片布局cols-44 栏卡片布局cols-55 栏卡片布局cols-{1~6}1~6 栏卡片布局占位布局的 style 写法wrap-style写法与wrap-class等价。放在 H3 标题下的注释可设置行占位### H3 部分 !--rehype:wrap-stylegrid-row: span 2/span 2;--上面与!--rehype:wrap-classrow-span-2--相同设置 2 行占位布局。放在 H2 标题下的注释可设置栏数## H2 部分 !--rehype:body-stylegrid-template-columns: repeat(2,minmax(0,1fr));--上面与!--rehype:body-classcols-2--相同设置 2 栏布局。行/列合并占位| 类型 | 类 | 说明 | | :-- | -- | -- | | 合并列|col-span-2| 2 列占位 | | |col-span-3| 3 列占位 | | |col-span-4| 4 列占位 | | |col-span-{2~10}| {2~10} 列占位 | | 合并行|row-span-2| 2 行占位 | | |row-span-3| 3 行占位 | | |row-span-4| 4 行占位 | | |row-span-{2~10}| {2~10} 行占位 |经典合并布局示例原文档用 ASCII 图展示了 9 种经典布局核心规则是在需要变宽/变高的卡片标题下添加对应的col-span-N/row-span-N注释。以下逐一给出可复制的源码模板布局 1首卡片跨整行col-span-3### H3 Title 1 !--rehype:wrap-classcol-span-3-- ### Title 2 ### Title 3 ### Title 4布局 2卡片 1 占两行row-span-2### Title 1 !--rehype:wrap-classrow-span-2-- ### Title 2 ### Title 3 ### Title 4 ### Title 5布局 3卡片 2 占两行### Title 1 ### Title 2 !--rehype:wrap-classrow-span-2-- ### Title 3 ### Title 4 ### Title 5布局 4卡片 3 占两行### Title 1 ### Title 2 ### Title 3 !--rehype:wrap-classrow-span-2-- ### Title 4 ### Title 5布局 5卡片 5 跨两列col-span-2### Title 1 ### Title 2 ### Title 3 ### Title 4 ### Title 5 !--rehype:wrap-classcol-span-2--布局 6卡片 2 跨两列### Title 1 ### Title 2 !--rehype:wrap-classcol-span-2-- ### Title 3 ### Title 4 ### Title 5布局 7卡片 4 跨两列### Title 1 ### Title 2 ### Title 3 ### Title 4 !--rehype:wrap-classcol-span-2-- ### Title 5布局 84 栏 首卡片跨整行H2 部分 ---- !--rehype:body-classcols-4-- ### Title 1 !--rehype:wrap-classcol-span-4-- ### Title 2 ### Title 3 ### Title 4 ### Title 5即在H2 部分标题添加cols-4设置 4 栏再给Title 1添加col-span-4合并整行。布局 9同时跨列与跨行### Title 1 !--rehype:wrap-classcol-span-2 row-span-2-- ### Title 2 ### Title 3 ### Title 4 ### Title 5 ### Title 6注意当col-span与row-span需要组合使用时多个类之间使用空格间隔例如col-span-2 row-span-2。列表的栏数cols-N列表同样可以使用cols-4等类实现多列展示- Item 1 - Item 2 - Item 3 - Item 4 - Item 5 - Item 6 - Item 7 - Item 8 !--rehype:classNamecols-4--表格样式进阶原文档提供了丰富的表格样式组合配合表格类注释即可获得不同展示形态。基本表格含 H4 子标题表格可嵌套在####子标题下构成日期、时间等分组#### Date :- | :- :- | :- %m/%d/%Y | 06/05/2013 %A, %B %e, %Y | Sunday, June 5, 2013 %b %e %a | Jun 5 Sun #### Time (H4) :- | :- :- | :- %H:%M | 23:05 %I:%M %p | 11:05 PM快捷键表格shortcuts:- | :- :- | :- V | Vector P | Pencil T | Text L | Line R | Rectangle O | Oval U | Rounded !--rehype:classNameshortcuts--展示标题show-header| Prefix | Example | What | | ---- | ---- | ---- | // | //hr[classedge] | Anywhere ./ | ./a | Relative / | /html/body/div | Root !--rehype:classNameshow-header--列表样式展示表格style-list 系列style-list将表格渲染为列表形式在style-list-arrow基础上还可追加circle圆圈、circlefill实心圆圈、square方形、squarefill实心方形标记:- | :- :- | :- visualEffectState.inactive | 后台应一直显示为非激活状态。 titleBarStyle _string_ _(win/mac)_ | 窗口标题栏样式。默认值 _(default)_ titleBarStyle.default | 分别返回 _mac_ 或者 _win_ 的标准标题栏 !--rehype:classNamestyle-list--!--rehype:classNamestyle-list-arrow circle-- !--rehype:classNamestyle-list-arrow circlefill-- !--rehype:classNamestyle-list-arrow square-- !--rehype:classNamestyle-list-arrow squarefill-- !--rehype:classNamestyle-list-arrow--隐藏表头 小尺寸自动换行auto-wrap:- | :- :- | :- visualEffectState.inactive | 后台应一直显示为非激活状态。 titleBarStyle _string_ _(win/mac)_ | 窗口标题栏样式。默认值 _(default)_ !--rehype:classNameauto-wrap--表格末尾列左对齐left-align表格默认末尾列右对齐添加left-align类改为左对齐| Prefix | What | | ---- | ---- | | // | Anywhere | ./ | Relative !--rehype:classNameshow-header left-align--多个类之间同样用空格分隔这里同时启用了show-header与left-align。强制 code 不换行code-nowrap添加code-nowrap类代码单元格内容强制不换行| Command | Description | | ---- | ---- | | adb remount | Remounts file system with read/write access | | adb reboot bootloader | Reboots the device into fastboot | !--rehype:classNameshow-header code-nowrap--列表样式进阶列表步骤style-timelinestyle-timeline将列表渲染为带步骤编号与连线的时间轴式操作流程非常适合展示 git 命令等分步操作- **重命名为 new_name** bash $ git branch -m new_name推送和重置$ git push origin -u new_name删除远程分支$ git push origin --delete old### 没有标记style-none cols-3 style-none 组合实现多列且无项目符号的列表常用于导航、链接墙等 text - Item 1 - Item 2 - ... !--rehype:classNamecols-3 style-none--圆圈标记style-round与箭头标记style-arrow- Item 1 - Item 2 - Item 3 !--rehype:classNamestyle-round--- Item 1 - Item 2 - Item 3 !--rehype:classNamestyle-arrow--实战建议与源码印证从已有清单复制骨架参考 docs/cron.md首页导航示例正是cron.md - cron.svg、docs/bash.md、docs/yaml.md 等成熟清单其目录结构、卡片划分与注释使用方式可以直接套用。首页导航联动新增docs/xxx.md后需在 README.md 相应分类下添加导航链接并把assets/xxx.svg图标放入 assets 目录重新编译首页才会出现带图标的入口。样式验证quickreference.md本身就是每个样式的验收样例把想用的注释语法先粘贴进去预览效果再应用到自己的清单中是最稳妥的做法。构建验证通过npm run build后检查dist目录输出或直接npm run start用监听模式实时验证排版。文档范围本指南覆盖的语法均可在 docs/quickreference.md 中找到对应示例更细粒度的贡献流程可参考 CONTRIBUTING.md。掌握以上注释语法与布局规则后你就能为 referen/reference 项目编写排版精良、信息密度高的技术速查清单让每一份备忘清单在 GitHub 预览与编译后的网页中都保持一致的出色体验。【免费下载链接】reference面向开发者的技术速查清单Cheat Sheets集合整理常见技术、工具与开发流程帮助快速查阅关键信息提高开发效率。项目地址: https://gitcode.com/GitHub_Trending/referen/reference创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考