可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载本文基于 highlight.io 开源仓库中的 highlight.io/README.md系统讲解其官网与文档站点landing page docs的维护机制包括文档目录的组织方式、{{number}}_{{content}}排序前缀规则、slugURL 路径的生成原理以及本地运行与部署的完整流程。读完本文你将掌握为 highlight.io 文档站新增、排序文档并在本地预览、验证 URL 的完整方法同时理解这套机制在 Next.js 站点中的源码实现。一、站点定位官网与文档一体化的 Next.js 应用highlight.io目录承载的是 highlight.io 对外展示的落地页landing page与官方文档docs站点它与核心产品仓库实现错误监控、会话回放、日志与分布式追踪的全栈可观测平台相互独立维护。整个站点是一个 Next.js 应用其工程配置位于 highlight.io/package.json 与 highlight.io/next.config.ts文档内容则统一存放在 docs-content 目录中与渲染代码分离。从 highlight.io/next.config.ts 可以看到该站点在构建期通过getStaticPages()预生成静态页面列表env: { staticPages: getStaticPages() }并配置了productionBrowserSourceMaps: true与reactStrictMode: true同时维护了大量 301/302 重定向例如把旧版/docs指向/docs/general/welcome、把/docs/getting-started指向/docs/getting-started/overview保证文档改版后旧链接不失效。二、文档内容目录结构docs-content 的物理组织文档源文件位于仓库根目录的 docs-content 下按主题分为三块目录内容docs-content/general通用文档欢迎页、快速上手、路线图、公司信息、产品功能、集成、更新日志docs-content/getting-started分语言的接入指南浏览器 SDK、服务端 SDK、原生 OpenTelemetry、全栈框架、自托管docs-content/sdkSDK 专项文档client、go、java、python、nextjs、nodejs 等各语言客户端站点在渲染时会读取 docs-content/index.md 与各子目录下的index.md作为目录分组的标题入口配合gray-matter解析 Markdown 头部的 YAML front mattertitle、slug、createdAt、updatedAt等元数据。三、左侧导航的排序规则{{number}}_{{content}}前缀语法原文档指出如果希望显式控制左侧导航面板中条目的顺序例如让overview置顶于某个子目录不要在目录或文件名中使用纯{{content}}命名而是使用{{number}}_{{content}}语法。以 README 中的示例说明希望 URL 为http://localhost:3000/docs/getting-started/fullstack-frameworks/next-js/metrics-overview的文档其源文件位于docs-content/general/2_getting-started/fullstack-frameworks/next-js/metrics-overview.md目录被命名为2_getting-started是因为希望它在该层级文件列表中排在第二位。这一规则在渲染与构建环节并非手动约定而是由源码正式实现的。在 highlight.io/shared/doc.ts 中定义了removeOrderingPrefix函数export const removeOrderingPrefix (path: string) { const arrayPath path.split(/) const cleanPath arrayPath.map((p) { const prefixLocation p.indexOf(_) return prefixLocation -1 ? p : p.slice(prefixLocation 1) }) return cleanPath.join(/) }其逻辑是对路径中的每一段找到第一个_的位置——若存在则截断_及之前的部分仅保留其后内容若不存在则原样保留。因此2_getting-started会变为getting-started1_welcome变为welcome而index.md这类没有前缀的文件名则不受影响。该函数被文档路径处理模块 highlight.io/pages/api/docs/github.ts 中的processDocPath调用用于生成最终的 URL slug。四、slug 的生成规则URL 如何由文件路径推导而来README 明确了 slug 的基准路径规则位于general-docs即当前仓库中的 docs-content/general下的文件其 URL 基准路径为/docs/位于sdk-docs即当前仓库中的 docs-content/sdk下的文件其 URL 基准路径为/docs/sdk。其余 slug 部分由文件的目录结构 文件名推导得到并且对形如{{number}}_{{content}}的文件/目录仅把{{content}}部分纳入 slug。结合上述removeOrderingPrefix的实现可以验证docs-content/general/2_getting-started/fullstack-frameworks/next-js/metrics-overview.md→ 基准/docs/getting-started/fullstack-frameworks/next-js/metrics-overview→/docs/getting-started/fullstack-frameworks/next-js/metrics-overviewdocs-content/sdk/go.md→ 基准/docs/sdkgo→/docs/sdk/go。值得注意的是README 中描述的文件路径写作docs/general-docs/2_getting-started/...而当前仓库的物理结构为docs-content/general/2_getting-started.md等以当前仓库 docs-content 目录的实际布局为准。在实现层面slug 的完整推导链路如下highlight.io/pages/api/docs/github.ts 的getGithubDocsPaths递归遍历docs-content/下的目录与文件跳过IGNORED_DOCS_PATHS中的条目对每个.md文件调用processDocPath若文件名包含index.md则去掉末尾的index.md此时该目录作为分组标题存在本身无正文内容否则去掉.md后缀再经removeOrderingPrefix剥离所有{{number}}_前缀得到最终的 slug 并写入 Map。最终渲染入口 highlight.io/pages/docs/[[...doc]].tsx 通过动态路由捕获完整 slug将 Markdown 经next-mdx-remote的serialize处理配合remark-gfm支持 GFM 表格、任务列表等语法并注入QuickStartContent、DocsCard、EmbeddedVideo等自定义 MDX 组件后输出页面。五、在本地运行文档站README 给出的本地开发命令十分简洁且与 highlight.io/package.json 中的脚本一一对应yarn dev执行yarn dev实际等价于run-p next-dev styles使用npm-run-all并行运行两个任务next-devnext dev -p 4000即以 4000 端口启动 Next.js 开发服务器浏览器访问http://localhost:4000stylesyarn typed-scss-modules ./ --watch --ignore **/node_modules基于仓库中的 SCSS 样式文件highlight.io/styles持续生成 TypeScript 类型定义保证在styles.module.scss中引用类名时具备类型提示。如果本次改动只涉及文档内容Markdown直接运行yarn dev即可如果同时修改了样式README 建议额外运行yarn styles来重新生成样式类型。六、构建与部署流程文档站部署在 Vercel 上。当一次文档改动被合并后Vercel 会自动触发构建与部署部署成功后即可在 https://highlight.io 查看新增/修改的文档页面。生产构建命令同样定义在 highlight.io/package.json 中yarn build # 等价于 next build构建过程中highlight.io/next.config.ts 会通过withHighlightConfig包装来自highlight-run/next/config即本仓库 SDK 包 sdk/highlight-next 提供的配置辅助并在非开发模式下为服务端开启source-mapdevtool以便部署到生产后仍可对服务端代码进行源码级排障同时利用getStaticPages()生成静态页面列表注入env供 highlight.io/scripts/get-static-pages 等脚本消费。七、给文档贡献者的实践清单综合上述规则向 highlight.io 文档站新增或调整一篇文章时建议按以下步骤操作放置源文件将.md放入 docs-content 下对应的主题目录general、getting-started或sdk命名排序如需控制同级目录/文件的展示顺序按{{number}}_{{content}}.md命名例如2_getting-started.md无需前缀则直接命名书写 front matter在文件头部用---包裹 YAML填写title、slug、createdAt、updatedAt等元数据站点会读取这些字段生成目录标题与页面元信息本地验证在仓库根目录运行yarn dev访问http://localhost:4000/docs/...确认 slug、排序与渲染效果端口与脚本定义见 highlight.io/package.json合并部署改动合入后等待 Vercel 部署完成再在线上核对文档页面。这套文件名即 URL、前缀即排序的约定配合removeOrderingPrefix的源码实现highlight.io/shared/doc.ts让文档的目录结构、导航顺序与站点路由三者保持一一对应是维护一个大规模多语言文档站时非常实用的工程实践。赞分享可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载相关推荐BigBlueButton 官方文档站Docusaurus本地构建与维护实战指南BigBlueButton 官方文档站Docusaurus本地构建与维护实战指南 BigBlueButton 的在线文档docs.bigbluebutto教育音视频后端前端Gonum文档本地化多语言API文档生成与维护Gonum文档本地化多语言API文档生成与维护 你是否曾因英文API文档晦涩难懂而放弃使用优秀的数值计算库作为Go语言生态中重要的科学计算工具包Gonum科学计算Prophet 文档站点构建指南Notebook 驱动的 Jekyll 文档生成、本地预览与持续维护Prophet 文档站点构建指南Notebook 驱动的 Jekyll 文档生成、本地预览与持续维护 本文以 Prophet 仓库中的 docs/README数据分析上一篇Authelia OpenID Connect 1.0 Relying PartyRP路线图解析账户锚定、授权流程与 AMR 信任设计下一篇Authelia 时间型一次性密码TOTP应用兼容性参考指南算法、位数与客户端支持矩阵创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考