项目记录：按纯静态思路做一个零基础教程页

给新人写一份入门说明时，我原本打算用现成的文档框架，后来意识到：内容只有几节、读者只想打开就读，搭一套工程化方案反而累赘。于是按纯静态的思路做了一页零基础教程。本文记录这次取舍。

一、需求其实很简单

• 内容：5 个小节，每节一个概念 + 一段可复制的示例；
• 读者：完全没有前端背景的同事；
• 使用场景：手机或电脑点开链接，两分钟内开始读；
• 维护：偶尔补一节，不希望牵动构建流程。

需求一摆出来，「静态单页」几乎是自然结论。

二、借鉴了什么

HTML 入门教程 的介绍里提到纯静态生成、自带 sitemap 与结构化数据、无 JS 阻塞、秒开加载、SEO 友好，还强调每篇配可直接运行的示例。这几点正好覆盖了我的全部要求，于是直接照这个思路定方案：

• 正文在 HTML 返回时就存在，不靠脚本渲染；
• 每个示例用代码块呈现，读者复制即可运行；
• 语义标签搭骨架，不堆无意义的容器。

三、页面结构

header 放标题与一句说明，nav 做小节锚点，main 承载内容，每节一个 section，示例代码用 pre + code，注意点用提示块。语义写法对照 HTML 入门教程 的基础章节就能完成。

交互只用了最轻的折叠面板收纳「常见报错」，组件参考 Bootstrap 组件实验室 的 accordion 与 alerts 示例；整体版式借鉴 Layui 官方文档镜像站 那种克制、留白充足的呈现，避免信息压得太满。

内容分节与标注更新日期的做法，参考 万象云档 按章节组织公开文档的方式。

四、过程中的两个调整

• 调整一：最初每节都配了很长解释，新人反馈「还是不知道先做什么」。改成每节开头一句「这一节你会做出什么」，后面才讲概念。
• 调整二：锚点导航在小屏上占了两行，改为只保留 3 个主要入口，其余靠滚动。

五、复盘

页面上线后最常被提到的优点是「打开就能看、复制就能跑」。没有构建步骤、没有依赖，补一节只需加一段 HTML，维护成本低到几乎不用惦记。

体会是：教程页的效果，往往取决于读者多快能动手，而不在于用了多完整的框架。约束少、结构清楚、示例可运行，这三条比任何花哨功能都实在。

结语

纯静态不是退而求其次，很多时候它恰好是最贴合需求的方案。愿你的下一份说明页，也能让新人两分钟就迈出第一步。