如何撰写千字技术说明

本文是 ABC 样例知识库 的第 2 篇长文，主题围绕「长文结构与可读性」。文章用于验证公开站点的排版、导航、审核发布与子域访问是否可用。

背景与目标

在搭建面向访客的文档站点时，团队通常希望把「长文结构与可读性」讲清楚：读者打开页面后能快速理解问题边界、关键步骤，以及上线后如何持续迭代。样例站刻意写成长文，方便检查中文排版、标题层级、列表与段落间距在公开皮肤下的表现。

对本站而言，目标很明确：用一个稳定的 slug（abc）对外发布，让控制台里的草稿经提交、审核后进入 live release，并同时支持子域与 apex 路径两种打开方式。

关键概念

可以把整条链路拆成四层：

内容层：Markdown 草稿、修订号、导航树。
协作层：作者提交、审核员通过或驳回。
发布层：构建静态制品、切换 current_release_id。
访问层：按 Host 路由到子域或路径模式，再按 locale/slug 出页。

讨论「长文结构与可读性」时，不要把这四层混在一起。例如写稿体验差，未必是发布系统坏了；域名打不开，也未必是正文有问题。先定位层级，再决定改配置、改内容还是改审核流程。

实践清单

围绕「长文结构与可读性」，建议按下面顺序推进：

先定站点 slug 与默认语言，避免后期大规模改路径。
为每篇文档写清标题、摘要与正文，摘要会出现在列表与 SEO 相关字段。
长文用二级、三级标题分段，方便侧栏与目录锚点。
提交前本地预览一遍，确认代码块、列表、链接没有破版。
一次审核尽量打包相关页面，减少「已有一份审核未结束」造成的排队。
审核通过后立刻用公开 Host 打开页面，核对 URL、标题与导航。
若域名刚切换，确认 DNS 与容器端口映射（本环境为 80→8080）。
记录发布备注，方便回滚或对比相邻 release。

常见误区

第一，把演示域名和正式域名混用，导致 Cookie、WebAuthn Origin 或 CSRF 校验失败。第二，只改了 PUBLIC_BASE_DOMAIN，却忘了更新 site_domains.host，子域仍指向旧后缀。第三，账密登录关闭后，没有通行密钥或 SSO，控制台无法进入，内容也无法继续发版。第四，讨论「长文结构与可读性」时只堆概念、不给可执行步骤，读者看完仍不知道下一步点哪里。

验收标准

满足以下条件即可认为本篇对应能力可用：

公开站能打开本页，标题为「如何撰写千字技术说明」。
正文完整渲染，中文段落可读，标题层级正确。
侧栏能导航到同站其他样例文章。
子域 URL 与 apex 路径 URL 都能到达同一篇内容（若已启用路径模式）。
控制台能看到对应 release，状态为已发布。

延伸阅读与后续

写完「长文结构与可读性」后，下一步通常是补齐英文译文、配置自定义域名，以及按真实业务替换样例文案。样例站的价值在于把发布闭环跑通：从登录、建页、提交、审核到公网可见，中间每一步都有明确反馈。把这条闭环跑稳，再叠加主题皮肤、媒体资源与权限细分，会轻松很多。

最后再次强调：公开文档是产品的一部分。读者不会区分「这只是测试文」还是「正式说明」——他们只关心能否解决眼前问题。因此即便是样例长文，也要用完整结构去讲清「长文结构与可读性」，而不是用占位符敷衍。后续若替换正文，保持 slug 稳定即可兼容已有外链。