learning-notes-html

name	learning-notes-html
description	写「为自己裁剪的学习笔记」并出成自足单文件、离线可看的 HTML——用外链策展法组织内容(领读+索引+外链+收口), 用单一强调色的极简设计系统排版(6 级字号、一条左边线、说明块共用骨架、图带外框),代码走 Shiki、图走 Mermaid/自制。 只要用户要写或改「学习笔记 / 课程章节笔记 / 讲义 / knowledge base 页面」——尤其是 AI 系统学习课程的后续章节(如 03 NumPy、04 Pandas 等)、 把参考资料消化成带图的教学页面、或提到「笔记基准线 / 按 02-Python 那套做 / 外链策展」——就用这个 skill,别自己临时发明排版或手搓代码高亮和 SVG。 黄金范本:<课程库根目录>\基础课程\02-Python基础.html。

学习笔记写作(基准线 + 外链策展 + 生产流水线)

把三样合成一套可复用的做法:怎么写(外链策展法)、长什么样(设计系统)、怎么产出(Shiki/Mermaid 流水线)。 目标产物:一篇自足单文件、离线双击即看的教学 HTML。黄金范本是 02-Python基础.html——拿不准长相时对照它。

这套是十几轮实战打磨出来的,每条规矩背后都有踩过的坑。别绕开、别即兴重造;要偏离先说清为什么。

reference,按需读

• references/writing-method.md —— 写什么。每篇固定六段、外链策展三件套、书体声音。动笔前先读。
• references/design-system.md —— 长什么样。6 级字号、一条左边线、框只有 3 类、图的分工。排版/改样式前读。
• references/production-pipeline.md —— 怎么产出。Shiki 高亮 + Mermaid/自制图 + 两个血泪坑。出代码块和图前读。
• references/index-page.md —— 整册总入口(MOC/落地页)的结构。开新库、或每做完一章回填总索引时读。
• references/theming.md —— 定制窗口:配色/UI/动效怎么随需要换而不动结构。要改皮或加 motion 时读。

assets/template.html = 能跑的成品骨架(全部 CSS + 页面结构 + 通用 JS),新章节从它起。 scripts/ = Shiki/Mermaid 预渲染脚本(convert-code.mjs / render-diagrams.html / inject-diagrams.mjs / replace-fig1.mjs)。

写一篇新章节的流程

1. 先内容,后排版。 按 writing-method.md 把这一篇的六段写出来:定位(卸包袱、明确不学什么)→ 心智地图(亲手画,外链替代不了)→ 外链策展(2–5 条精挑,每条带三件套,真核实链接)→ 收口(自己的话 + 常见误区表)→ 练习题 → 实例(能跑 + 改改看)。声音用书体,不用「你」。

出题环节走 course-authoring——它是出题标准的正本(题型、干扰项=真实误解、答案打散、解析拆穿干扰项)。本 skill 不另写一套出题标准,只负责把答案放折叠区(<details>)。两个 skill 触发词有重叠(如「讲义」):笔记结构/设计/产出归本 skill,纯出题让 course-authoring 主导。

2. 从模板起。 复制 assets/template.html,填面包屑、章首 recap、骨架清单;正文按小节铺开。每个概念节的固定节奏:

<p class="handoff">过渡句(朴素灰、不加粗)</p>
<h2 id="xxx"><span class="no">N</span><span>小节标题</span></h2>
<p class="one-liner">术语<span class="en">en</span>:一句话定义。</p>
<p>散文讲解,加粗领句省着用……</p>
<figure>…一张图…</figure>
<div class="code-block">…<pre>普通文本代码</pre></div>
<div class="callout go"><span class="label">去精读</span><p>外链三件套……</p></div>

概念节之间用 .handoff 过渡句串成一条线(承上启下,别让小节变孤岛)。右侧 .toc-sidebar 每个 a 的 data-toc-target 要等于对应 h2 的 id。

3. 代码交给 Shiki。 先在 HTML 里把代码按普通 <pre> 写好(缩进正确、注释对齐),再跑 scripts/convert-code.mjs 一次性高亮成纯墨黑灰。别手写高亮 span。

4. 图按本质选载体(见 pipeline):流程/关系→Mermaid 预渲染;辐射/概念→自制 SVG(复用工具类);报错→.trace 面板;索引格子→.idxgrid 表。Mermaid 必须 htmlLabels:false、渲染字体用本机的,否则截字。

5. 自检(浏览器里过一遍,别静态猜):

• 正文字号 = 7 种、字体 = 2 种、无 Arial。
• 正文/定义/说明块/过渡句左边缘对齐到一条线。
• 每张图有外框、不截字、不撞线、无黑块;整页彩色只有群青蓝一种(+代码的墨灰)。
• 无外部资源加载(script src / link css / CDN / img 计数为 0),离线双击可看。
• 六段齐、外链三件套齐、链接真的可达、心智地图在场、答案能折叠。

6. 交付给本人给绝对路径(用户常打不开在线链接,只认本地文件)。更新总索引(MOC),标好和前后篇的顺序。

会踩的坑(前人已替你踩过)

• 别用颜色分级——想加颜色前先试线/字号/小标签。整页只留一个强调色。
• 别在正文写 style="font-size"、别用 em 给行内代码——会滚出一堆怪字号。
• 别让左边缘参差——说明块用悬挂竖线把文字拉回 x=0,去底色、去 ↓→ 符号、列表去小圆点。
• 别手搓代码高亮和 SVG——一致性差、格式爆炸;交给 Shiki 和 Mermaid。
• 别把辐射图硬塞给 Mermaid(会挤成扇形)、别用深色黑块。
• 加粗要省,过渡句不加粗、不用中文斜体(合成假斜发丑)。