尧图网页设计 
Vector 网站开发实战指南本地构建、CUE 文档生成与 Markdown 质量检查【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector本指南面向需要为 Vector 开源项目高性能可观测性数据管道贡献网站与文档的开发者系统讲解website/目录下的开发约定、本地运行方法、CUE 结构化文档的生成与校验流程以及 Markdown 风格检查的落地方式。读完本文你将掌握从改一个 Markdown 文件到在 http://localhost:1313 看到效果再到通过 CI 级检查的完整开发闭环。适用范围与开发约定本指南针对website/目录下的变更即 website/AGENTS.md 所约束的范围。该目录承载着 Vector 官方站点与全部文档资产其整体架构与前置依赖在 website/README.md 中有详细说明核心要点如下目标分支网站变更应定向提交到master分支若需在正常发布节奏之外上线网站改动可将提交 cherry-pick 到当前发布分支如v0.15。双站点机制当前发布分支用于构建生产站点而master通常包含尚未发布的 nightly 变更对应独立的 nightly 站点供使用未发布功能的用户参考。技术栈站点由 Hugo 静态站点生成器构建配置位于 website/config.toml文档大量依赖 CUE 语言提供的结构化数据见下文交互功能主要使用 Alpine.js配合 Tailwind CSS、Sass 与少量 React 组件。本地运行网站两条命令起步在仓库根目录执行以下命令即可启动本地站点make generate-docs cd website make serve第一步make generate-docs会先生成组件文档、VRL 函数文档与示例配置详见文档生成流水线一节若本次改动未涉及 schema 或 VRL 文档该步骤可省略。第二步cd website进入网站目录后执行make serve其内部依次执行清理、依赖安装yarn、Cargo 数据拷贝与结构化数据构建最终启动 Hugo 开发服务器。站点启动后访问http://localhost:1313即可浏览。本地开发的三个细节热重载范围修改 Markdown 源、Sass/CSS 或 JavaScript 时Hugo 会自动重新构建并热刷新当前页面但若修改的是结构化数据源CUE需要停止服务器后重新执行make serve。服务器绑定参数website/Makefile中通过环境变量控制监听地址与端口默认SERVER_BIND127.0.0.1、SERVER_PORT1313可按需覆盖。本地生产构建若需排查仅在生产环境出现的异常可在website/目录下执行make run-production-site-locally它会完成生产构建后用python3 -m http.server在本地提供站点服务。构建 CUE 文档结构化数据的核心流水线Vector 文档中有关组件、VRLVector Remap Language等大量内容依赖 CUE 结构化数据。在website/目录下执行make cue-build其底层调用vdev build docs-json将 website/cue 目录下全部.cue源文件编译为单一 JSON 文件website/data/docs.json随后与 Hugo 模板系统配合生成 HTML。用脚本命令深入 CUE 数据仓库中的 scripts/cue.sh 是 CUE 相关操作的统一入口支持build、check、fmt、list、vet、eval、export七种模式常用场景# 打印整份文档的 JSON 输出 scripts/cue.sh export # 以 CUE 格式打印 kubernetes_logs 源的子树 scripts/cue.sh eval -e components.sources.kubernetes_logs # 校验文档正确性 scripts/cue.sh check构建过程中cmd_build会先删除旧的docs.json否则 CUE 会报错再通过cue export --all-errors导出到目标文件。此外站点页面还会依赖 Cargo.lock 中的依赖版本信息——每次构建时该文件被复制为website/data/cargo-lock.toml供 Hugo 模板读取。CUE 编写建议来自仓库文档的经验总结小步迭代逐步校验一次新增大量 CUE 逻辑再统一校验极易遇到难以定位的错误。建议借助watchexec在website/目录下运行watchexec make cue-build每次保存即触发构建反馈周期约 25 秒。严格注意缩进CUE 多行字符串...的缩进必须保持一致错误的缩进会改变字符串实际内容。例如闭合引号的缩进层级错误会导致内容偏差。Markdown 质量检查check-markdown 的前世今生在根目录编辑完 Markdown 后运行make check-markdown该目标定义于根 Makefile实际调用vdev check markdown。其实现位于 vdev/src/commands/check/markdown.rs先通过git ls-files *.md收集仓库中全部受版本控制的 Markdown 文件再调用markdownlint-cli2执行风格校验。这意味着只有已被 git 跟踪的 Markdown 文件才会被检查新建文件需先加入版本控制。与 Markdown 检查配套的还有make fix-markdown可自动修复大部分风格问题check-prettier则负责 JS/TS/YAML/JSON 文件的格式化检查。整套check-*目标是仓库 CI 质量门禁的一部分建议本地提交前完整跑一遍。链路检查防止文档出现坏链Vector 网站的 CI 构建预览或生产都会对站内链接做全量检查任何坏链都会导致构建失败。相关配置如下website/.htmltest.yml默认检查配置CheckExternal: false即不检查外部链接——这是为了避免构建受外部站点可用性影响例如 Cloudflare 故障会导致构建失败代价是外部坏链可能长期潜伏。website/.htmltest.external.yml外部链接检查配置CheckExternal: true并忽略 github.com、localhost、maxmind.com 等因限流或误报需要排除的域名。在website/目录下执行以下命令可复现 CI 的完整构建与检查# 生产构建 内部链接检查 make local-production-build # 预览构建 内部链接检查 make local-preview-build # 构建后额外执行外部链接检查 make local-production-build make run-external-link-checker后两条命令会使用.htmltest.external.yml配置对站内全部外部链接做抽查仓库维护者应周期性在本地执行以避免链接漂移累积。文档生成流水线generate-docs 到底做了什么根 Makefile 将generate-docs定义为四个子目标的组合generate-component-docs先编译 Vector 二进制通过vector generate-schema导出配置 schema再由vdev build component-docs生成各组件文档最后执行scripts/cue.sh fmt统一格式。generate-vector-vrl-docs由vector-vrl-doc-builder从源码编译或使用已安装版本基于 Rust 源码生成 VRL 函数文档到docs/generated/。generate-vrl-docs转调website/Makefile中的同名目标将 VRL 文档输出到website/cue/reference/remap/functions。generate-example-configs调用vdev build component-examples生成各组件的示例配置到website/generated/example-configs。CI 中还会运行make check-generated-docs见 Makefile通过vdev check generated-docs与vdev check component-examples校验机器生成内容是否与当前源码一致防止提交过期文档。常见维护任务补充新增 Vector 版本由cargo vdev release prepare自动化完成主要包括将新版本加入 website/cue/reference/versions.cue 的versions列表保持逆序、生成cue/reference/releases/{VERSION}.cue、并在 website/content/en/releases 新增{version}.md发布说明文件需设置title与递增的weight因为 Hugo 无法按语义版本排序。Docker 方式运行若不想在本地安装 Hugo、CUE、Node.js、Rust 等依赖可在website/目录下执行docker compose build docker compose up后访问 http://localhost:1313仓库以卷方式挂载Markdown/CSS/JS 改动支持热重载。注意该方式标注为实验性质暂未由 CI 强制。页面反索引若需阻止某页面被搜索索引可在其 front matter 中添加noindex: true。重定向管理通配风格的重定向定义在 website/static/_redirects单页重定向则通过页面 front matter 的aliases字段实现。小结Vector 网站的日常开发遵循一条清晰的质量链路改文档 → 本地make serve预览 → 改 CUE 后make cue-build重新生成结构化数据 → 根目录make check-markdown过风格检查 → 通过local-production-build复现 CI 链路检查。本文所涉命令均可在当前仓库中直接验证website/AGENTS.md、website/Makefile、根 Makefile、scripts/cue.sh、vdev/src/commands/check/markdown.rs熟练掌握这套流程即可高效、合规地为 Vector 贡献网站与文档改动。【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Vector 网站开发实战指南：本地构建、CUE 文档生成与 Markdown 质量检查
Vector 网站开发实战指南本地构建、CUE 文档生成与 Markdown 质量检查【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector本指南面向需要为 Vector 开源项目高性能可观测性数据管道贡献网站与文档的开发者系统讲解website/目录下的开发约定、本地运行方法、CUE 结构化文档的生成与校验流程以及 Markdown 风格检查的落地方式。读完本文你将掌握从改一个 Markdown 文件到在 http://localhost:1313 看到效果再到通过 CI 级检查的完整开发闭环。适用范围与开发约定本指南针对website/目录下的变更即 website/AGENTS.md 所约束的范围。该目录承载着 Vector 官方站点与全部文档资产其整体架构与前置依赖在 website/README.md 中有详细说明核心要点如下目标分支网站变更应定向提交到master分支若需在正常发布节奏之外上线网站改动可将提交 cherry-pick 到当前发布分支如v0.15。双站点机制当前发布分支用于构建生产站点而master通常包含尚未发布的 nightly 变更对应独立的 nightly 站点供使用未发布功能的用户参考。技术栈站点由 Hugo 静态站点生成器构建配置位于 website/config.toml文档大量依赖 CUE 语言提供的结构化数据见下文交互功能主要使用 Alpine.js配合 Tailwind CSS、Sass 与少量 React 组件。本地运行网站两条命令起步在仓库根目录执行以下命令即可启动本地站点make generate-docs cd website make serve第一步make generate-docs会先生成组件文档、VRL 函数文档与示例配置详见文档生成流水线一节若本次改动未涉及 schema 或 VRL 文档该步骤可省略。第二步cd website进入网站目录后执行make serve其内部依次执行清理、依赖安装yarn、Cargo 数据拷贝与结构化数据构建最终启动 Hugo 开发服务器。站点启动后访问http://localhost:1313即可浏览。本地开发的三个细节热重载范围修改 Markdown 源、Sass/CSS 或 JavaScript 时Hugo 会自动重新构建并热刷新当前页面但若修改的是结构化数据源CUE需要停止服务器后重新执行make serve。服务器绑定参数website/Makefile中通过环境变量控制监听地址与端口默认SERVER_BIND127.0.0.1、SERVER_PORT1313可按需覆盖。本地生产构建若需排查仅在生产环境出现的异常可在website/目录下执行make run-production-site-locally它会完成生产构建后用python3 -m http.server在本地提供站点服务。构建 CUE 文档结构化数据的核心流水线Vector 文档中有关组件、VRLVector Remap Language等大量内容依赖 CUE 结构化数据。在website/目录下执行make cue-build其底层调用vdev build docs-json将 website/cue 目录下全部.cue源文件编译为单一 JSON 文件website/data/docs.json随后与 Hugo 模板系统配合生成 HTML。用脚本命令深入 CUE 数据仓库中的 scripts/cue.sh 是 CUE 相关操作的统一入口支持build、check、fmt、list、vet、eval、export七种模式常用场景# 打印整份文档的 JSON 输出 scripts/cue.sh export # 以 CUE 格式打印 kubernetes_logs 源的子树 scripts/cue.sh eval -e components.sources.kubernetes_logs # 校验文档正确性 scripts/cue.sh check构建过程中cmd_build会先删除旧的docs.json否则 CUE 会报错再通过cue export --all-errors导出到目标文件。此外站点页面还会依赖 Cargo.lock 中的依赖版本信息——每次构建时该文件被复制为website/data/cargo-lock.toml供 Hugo 模板读取。CUE 编写建议来自仓库文档的经验总结小步迭代逐步校验一次新增大量 CUE 逻辑再统一校验极易遇到难以定位的错误。建议借助watchexec在website/目录下运行watchexec make cue-build每次保存即触发构建反馈周期约 25 秒。严格注意缩进CUE 多行字符串...的缩进必须保持一致错误的缩进会改变字符串实际内容。例如闭合引号的缩进层级错误会导致内容偏差。Markdown 质量检查check-markdown 的前世今生在根目录编辑完 Markdown 后运行make check-markdown该目标定义于根 Makefile实际调用vdev check markdown。其实现位于 vdev/src/commands/check/markdown.rs先通过git ls-files *.md收集仓库中全部受版本控制的 Markdown 文件再调用markdownlint-cli2执行风格校验。这意味着只有已被 git 跟踪的 Markdown 文件才会被检查新建文件需先加入版本控制。与 Markdown 检查配套的还有make fix-markdown可自动修复大部分风格问题check-prettier则负责 JS/TS/YAML/JSON 文件的格式化检查。整套check-*目标是仓库 CI 质量门禁的一部分建议本地提交前完整跑一遍。链路检查防止文档出现坏链Vector 网站的 CI 构建预览或生产都会对站内链接做全量检查任何坏链都会导致构建失败。相关配置如下website/.htmltest.yml默认检查配置CheckExternal: false即不检查外部链接——这是为了避免构建受外部站点可用性影响例如 Cloudflare 故障会导致构建失败代价是外部坏链可能长期潜伏。website/.htmltest.external.yml外部链接检查配置CheckExternal: true并忽略 github.com、localhost、maxmind.com 等因限流或误报需要排除的域名。在website/目录下执行以下命令可复现 CI 的完整构建与检查# 生产构建 内部链接检查 make local-production-build # 预览构建 内部链接检查 make local-preview-build # 构建后额外执行外部链接检查 make local-production-build make run-external-link-checker后两条命令会使用.htmltest.external.yml配置对站内全部外部链接做抽查仓库维护者应周期性在本地执行以避免链接漂移累积。文档生成流水线generate-docs 到底做了什么根 Makefile 将generate-docs定义为四个子目标的组合generate-component-docs先编译 Vector 二进制通过vector generate-schema导出配置 schema再由vdev build component-docs生成各组件文档最后执行scripts/cue.sh fmt统一格式。generate-vector-vrl-docs由vector-vrl-doc-builder从源码编译或使用已安装版本基于 Rust 源码生成 VRL 函数文档到docs/generated/。generate-vrl-docs转调website/Makefile中的同名目标将 VRL 文档输出到website/cue/reference/remap/functions。generate-example-configs调用vdev build component-examples生成各组件的示例配置到website/generated/example-configs。CI 中还会运行make check-generated-docs见 Makefile通过vdev check generated-docs与vdev check component-examples校验机器生成内容是否与当前源码一致防止提交过期文档。常见维护任务补充新增 Vector 版本由cargo vdev release prepare自动化完成主要包括将新版本加入 website/cue/reference/versions.cue 的versions列表保持逆序、生成cue/reference/releases/{VERSION}.cue、并在 website/content/en/releases 新增{version}.md发布说明文件需设置title与递增的weight因为 Hugo 无法按语义版本排序。Docker 方式运行若不想在本地安装 Hugo、CUE、Node.js、Rust 等依赖可在website/目录下执行docker compose build docker compose up后访问 http://localhost:1313仓库以卷方式挂载Markdown/CSS/JS 改动支持热重载。注意该方式标注为实验性质暂未由 CI 强制。页面反索引若需阻止某页面被搜索索引可在其 front matter 中添加noindex: true。重定向管理通配风格的重定向定义在 website/static/_redirects单页重定向则通过页面 front matter 的aliases字段实现。小结Vector 网站的日常开发遵循一条清晰的质量链路改文档 → 本地make serve预览 → 改 CUE 后make cue-build重新生成结构化数据 → 根目录make check-markdown过风格检查 → 通过local-production-build复现 CI 链路检查。本文所涉命令均可在当前仓库中直接验证website/AGENTS.md、website/Makefile、根 Makefile、scripts/cue.sh、vdev/src/commands/check/markdown.rs熟练掌握这套流程即可高效、合规地为 Vector 贡献网站与文档改动。【免费下载链接】vectorA high-performance observability data pipeline.项目地址: https://gitcode.com/GitHub_Trending/vect/vector创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考