可观测性时序数据库后端指标监控【免费下载链接】cortexA horizontally scalable, highly available, multi-tenant, long term Prometheus.项目地址https://gitcode.com/gh_mirrors/cortex6/cortex点击查看免费下载本文基于仓库内提案文档 docs/proposals/version-documentation.md 展开结合 website/config.toml、网站导航模板与文档构建工具链系统梳理 Cortex 为官方文档引入“按版本浏览”能力的设计目标、URL 结构、内容范围与落地路径。读完本文你将掌握 Docssy 主题版本化菜单的配置入口、master 最近 3 个 minor 版本的版本保留策略以及 API / Configuration 两大文档区块如何被纳入统一的版本化前缀并了解该方案在仓库中的对应实现载体。背景文档缺乏版本管理带来的问题Cortex 是一个横向可扩展、高可用、多租户的长期 Prometheus 存储方案文档是当前贡献者与初次接触者获取信息的核心入口。但截至该提案提出时2020 年 3 月状态为 proposalCortex 文档没有做版本化所有页面都指向同一份“最新”内容用户无法区分某个配置项或 API 是在哪个版本引入、在哪个版本发生变更。这带来两个直接后果老版本用户看到的文档可能与自身运行版本不一致容易产生误导社区中大量“文档没写清楚”的提问实际上都可以通过查看对应版本的文档得到答案——只是没有合适的位置可查。提案的参考对象是 Prometheus 的文档站按版本组织页面让每个人在提问前都能找到“属于自己版本”的答案。提案目标三个可量化的诉求提案明确了本次文档版本化要达成的三个目标对指定页面做版本化Version specific pages of the documentation——不是全站无差别版本化而是有选择地将核心技术页面纳入版本体系提供切换版本的链接且版本必须体现在 URL 中the version must be in the URL——URL 结构本身携带版本信息便于收藏、引用与 SEO 归因保留 master 版本与最近 3 个 minor 版本文档默认展示最新的 minor 版本——即以1.x形式表达 minor 版本默认落点不是 master 而是最新的已发布 minor 版本。这三条诉求共同界定了方案的范围与边界版本化是“有选择的、带 URL 语义的、有保留窗口的”。现状盘点文档存放位置与站点构建方式提案对现状的描述与仓库当前结构一致文档全部存放在仓库根目录下的docs/目录按主题分子目录组织例如 docs/api/HTTP API 文档、docs/configuration/配置文档、docs/guides/、docs/blocks-storage/ 等。网站本身由Hugo构建使用Docsy主题。这一点在 website/config.toml 中有直接证据# Hugo allows theme composition (and inheritance). The precedence is from left to right. theme [github.com/google/docsy, github.com/google/docsy/dependencies]Docsy 主题原生提供了文档版本化的支持其核心机制包括版本下拉菜单version drop-down menu在导航栏渲染一个“Releases”下拉框列出所有可用版本params.versions/params.version配置段在config.toml中把 URL 与具体版本建立映射URL 内嵌版本路径每个版本的页面通过带版本段如/master/、/1.0/的独立 URL 访问。仓库的 website/config.toml 已经为这套机制预留了开关位# Menu title if your navbar has a versions selector to access old versions of your site. # This menu appears only if you have at least one [params.versions] set. version_menu Releases注释明确说明导航栏的版本选择器只有在配置了至少一个[params.versions]时才会出现——也就是说方案落地时只需在config.toml中补充[params.versions]配置段即可激活版本菜单。这一机制在前端模板中同样有据可查。website/layouts/_partials/navbar.html 中导航栏在检测到Site.Params.versions非空时会渲染版本选择器下拉框{{ if .Site.Params.versions }} li classnav-item dropdown d-none d-lg-block {{ partial navbar-version-selector.html . }} /li {{ end }}这意味着版本化能力在站点骨架层面已经“就位”缺的只是内容层面的版本化组织与params.versions配置本身。站点构建与本地预览了解版本化方案还需要知道站点如何构建与预览。仓库 docs/contributing/how-to-run-website-locally.md 给出了完整流程安装Hugoextended 版本具体版本号参考构建镜像中的HUGO_VERSIONnetlify.toml 中记录的是HUGO_VERSIONv0.94.2且发布目录为website/public安装 Node.js v14 及以上并在website/目录执行npm install安装embedmd工具用于把代码片段嵌入 Markdown 文档执行make BUILD_IN_CONTAINERfalse web-build完成初始化构建。日常迭代时运行 Makefile 中定义的make web-serve在本地启动 Hugo 服务默认监听http://localhost:1313/每次修改docs/下内容后执行make BUILD_IN_CONTAINERfalse web-pre重新生成站点内容。值得注意的是docs/中不少文档是由源码自动生成的例如 docs/configuration/config-file-reference.md 由 tools/doc-generator 依据代码中的配置定义生成对应 Makefile 中的make doc目标。这意味着版本化后每个版本分支中的这类“自动生成文档”需要随该版本的源码一起产出——这是版本化落地时不可忽视的一个工程细节。版本化方案设计版本保留策略master 最近 3 个 minor 版本方案的核心策略是同时保留master版本与最近 3 个已发布 minor 版本。每个 minor 版本以1.x形式表达例如1.0、1.1、1.2并且master代表开发中的最新内容文档访问默认指向最新的 minor 版本而不是 master每当发布新的 minor 版本最旧的 minor 版本从版本列表中移除维持“master 3”的窗口。这种策略与 Cortex 自身的版本节奏一致仓库根目录的 VERSION 文件记录了当前版本为1.21.1版本号体系即1.x.y的语义化版本格式minor 版本1.x正是提案中版本化 URL 的粒度。内容范围先版本化 API 与 Configuration 两大区块提案明确指出首批纳入版本化的只有两个路径及其全部子页面/docs/apis/—— 对应仓库中的 docs/api/涵盖 Push、Query、Ruler、Alertmanager 等全部 HTTP API 端点说明/docs/configuration/—— 对应仓库中的 docs/configuration/涵盖全部配置参数与示例。同时有一个重要的边界处理将v1.x Guarantees文档移出版本化目录。原因在于版本兼容性承诺如“跨 minor 版本升级应开箱即用”“未来版本保证能读取两年内的旧数据”属于跨版本的横向承诺不应该被绑定到某一个具体版本之下否则每个版本分支都要复制一份且容易互相矛盾。仓库中该文档位于 docs/configuration/v1-guarantees.md方案建议在版本化重构时将其迁出配置目录、作为不随版本变化的“站级”文档保留。URL 结构版本体现在路径中这是整个方案最具辨识度的部分。所有版本化页面统一挂在单一前缀之下提案示例使用/docs/running-cortex/并注明最终前缀仍待定版本段紧随前缀之后对master版本/docs/running-cortex/master/configuration/ /docs/running-cortex/master/api/对某个 minor 版本如1.0/docs/running-cortex/1.0/configuration/ /docs/running-cortex/1.0/apis/该设计的要点版本是 URL 的一等公民链接本身携带版本信息分享、收藏、引用时不会产生歧义路径结构平行configuration/与api(s)/在 master 与各 minor 版本下保持完全一致的相对位置便于迁移与自动化检查默认版本明确虽然master和1.0等版本都有独立 URL但站点默认展示最新 minor 版本避免普通访客被“开发中”内容干扰。落地时还需要把文档中所有指向旧链接的引用统一替换为新链接提案原文明确要求 change all the occurrences of older doc links with new links否则版本化后旧链接会变成死链——这是方案工作量中占比最大、也最容易被忽略的一步。Docssy 配置形态按 Docssy 主题的版本化机制与提案描述站点config.toml需要补充类似如下的配置以说明机制为主具体键值以 Docssy 对应版本约定为准[params.versions] [params.versions.master] url /docs/running-cortex/master/ [params.versions.v1.2] url /docs/running-cortex/1.2/ [params.versions.v1.1] url /docs/running-cortex/1.1/ [params.versions.v1.0] url /docs/running-cortex/1.0/结合 website/config.toml 中已就位的version_menu Releases与 website/layouts/_partials/navbar.html 的Site.Params.versions判断逻辑一旦该配置段出现导航栏即会自动渲染“Releases”下拉菜单用户可在 master 与各 minor 版本之间一键切换。落地执行清单综合提案内容与仓库现状完整落地路径可拆解为确定统一前缀将提案示例中的/docs/running-cortex/定为最终版本化前缀或另行决策迁移内容目录把 docs/api/ 与 docs/configuration/含全部子页面纳入该前缀下的版本化树移出 v1.x Guarantees将 docs/configuration/v1-guarantees.md 迁出配置目录作为不随版本变化的文档保留配置版本映射在 website/config.toml 中补充[params.versions]配置段激活版本下拉菜单替换旧链接全量扫描并更新文档中对 API / Configuration 页面的旧链接为新版本化 URL建立版本分支维护流程每个 minor 版本发布时生成对应版本的文档快照含由 tools/doc-generator 自动生成的配置参考文档同时淘汰最旧版本保持“master 3”窗口验证默认版本确认站点默认跳转到最新 minor 版本且各版本 URL 均可直接访问。总结Cortex 文档版本化提案以“版本体现在 URL、master 与最近 3 个 minor 版本共存、默认展示最新 minor 版本”为核心设计首批覆盖 API 与 Configuration 两大文档区块并将v1.x Guarantees这类跨版本承诺文档排除在版本化范围之外。仓库现状已经为这套方案铺好了地基站点使用 Hugo Docssy 构建website/config.toml 预留了version_menu Releases开关website/layouts/_partials/navbar.html 内置了版本选择器的渲染逻辑文档构建与本地预览流程Makefile、docs/contributing/how-to-run-website-locally.md、netlify.toml也已完备。剩下的核心工作在于内容迁移、版本分支维护与旧链接替换——这些正是提案为后续实现者划定的行动清单。赞分享可观测性时序数据库后端指标监控【免费下载链接】cortexA horizontally scalable, highly available, multi-tenant, long term Prometheus.项目地址https://gitcode.com/gh_mirrors/cortex6/cortex点击查看免费下载相关推荐Agones 官方网站升级全解析基于 Hugo 与 Docsy 的多语言、版本化文档平台架构Agones 官方网站升级全解析基于 Hugo 与 Docsy 的多语言、版本化文档平台架构 导读 本文以 Agones 官方博客 new agones s游戏开发云原生Agones 文档站点编辑与贡献指南基于 Hugo Docsy 的版本门控写作与本地预览实践Agones 文档站点编辑与贡献指南基于 Hugo Docsy 的版本门控写作与本地预览实践 本文是一份面向 Agones 贡献者的文档编辑与贡献实操指南游戏开发云原生在本地构建与运行 Kustomize 官方文档站点基于 Hugo 与 Docsy 的 site/ 开发部署指南在本地构建与运行 Kustomize 官方文档站点基于 Hugo 与 Docsy 的 site/ 开发部署指南 本篇指南面向希望参与 Kustomize 官方CLI开发工具云原生上一篇Scarab轻松管理《空洞骑士》模组的必备工具下一篇Fluvio 在金融领域的 10 大应用实践实时风险监控和交易数据处理终极指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考