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

给新人写一份入门说明时，我原本打算用现成的文档框架，后来意识到：内容只有几节、读者只想打开就读，搭一套工程化方案反而累赘。于是按纯静态的思路做了一页零基础教程。本文记录这次取舍。 ## 一、需求其实很简单 - 内容：5 个小节，每节一个概念 + 一段可复制的示例； - 读者：完全没有前端背景的同事； - 使用场景：手机或电脑点开链接，两分钟内开始读； - 维护：偶尔补一节，不希望牵动构建流程。 需求一摆出来，「静态单页」几乎是自然结论。 ## 二、借鉴了什么 [HTML 入门教程](https://html.eapis.site/) 的介绍里提到纯静态生成、自带 sitemap 与结构化数据、无 JS 阻塞、秒开加载、SEO 友好，还强调每篇配可直接运行的示例。这几点正好覆盖了我的全部要求，于是直接照这个思路定方案： - 正文在 HTML 返回时就存在，不靠脚本渲染； - 每个示例用代码块呈现，读者复制即可运行； - 语义标签搭骨架，不堆无意义的容器。 ## 三、页面结构 `header` 放标题与一句说明，`nav` 做小节锚点，`main` 承载内容，每节一个 `section`，示例代码用 `pre` + `code`，注意点用提示块。语义写法对照 [HTML 入门教程](https://html.eapis.site/) 的基础章节就能完成。 交互只用了最轻的折叠面板收纳「常见报错」，组件参考 [Bootstrap 组件实验室](https://bootstrap.wanxiangsucai.com/) 的 accordion 与 alerts 示例；整体版式借鉴 [Layui 官方文档镜像站](https://layui.wanxiangsucai.com/) 那种克制、留白充足的呈现，避免信息压得太满。 内容分节与标注更新日期的做法，参考 [万象云档](https://www.wanxiangyundang.top/) 按章节组织公开文档的方式。 ## 四、过程中的两个调整 - **调整一**：最初每节都配了很长解释，新人反馈「还是不知道先做什么」。改成每节开头一句「这一节你会做出什么」，后面才讲概念。 - **调整二**：锚点导航在小屏上占了两行，改为只保留 3 个主要入口，其余靠滚动。 ## 五、复盘 页面上线后最常被提到的优点是「打开就能看、复制就能跑」。没有构建步骤、没有依赖，补一节只需加一段 HTML，维护成本低到几乎不用惦记。 体会是：教程页的效果，往往取决于读者多快能动手，而不在于用了多完整的框架。约束少、结构清楚、示例可运行，这三条比任何花哨功能都实在。 ## 结语 纯静态不是退而求其次，很多时候它恰好是最贴合需求的方案。愿你的下一份说明页，也能让新人两分钟就迈出第一步。