Lightweight Charts™ 官方文档网站Docusaurus 构建、部署与面向 LLM 的 Markdown 导出指南【免费下载链接】lightweight-chartsPerformant financial charts built with HTML5 canvas项目地址: https://gitcode.com/gh_mirrors/li/lightweight-charts本指南以 website/README.md 为骨架结合仓库中 website/docusaurus.config.js、website/package.json 与 website/plugins/docs-markdown 等源码实现系统讲解 Lightweight Charts™ 官方文档网站的本地开发、静态构建、本地预览、发布部署以及专为 AI 助手/LLM 设计的 Markdown 导出机制与多版本维护流程。读完本文你将能够独立拉起该文档站点的开发环境、产出生产构建并为发布新版本与更新文档贡献代码。文档网站的定位与整体设计Lightweight Charts™ 的官方文档网站website/目录使用Docusaurus 2当前仓库依赖为docusaurus/core3.7.0见 website/package.json搭建其目标是让使用者无摩擦地使用该库The aim of this documentation is to make using the library frictionless.。整个文档体系遵循一条明确的分工原则API 参考文档由typings.d.ts自动生成。该类型声明文件是库构建过程的产物docusaurus-plugin-typedoc会基于它生成逐符号per-symbol的 API 页面配置见 website/docusaurus.config.js 中commonDocusaurusPluginTypedocConfig与typedocPluginForVersion。手写文档则聚焦于概念讲解、教程、交互式示例以及任何无法自动生成的内容例如website/docs/下的价格刻度、时间刻度、面板panes等主题文档以及website/tutorials/下的大量互动教程。从 website/docusaurus.config.js 可以看到站点的整体拓扑站点标题为 Lightweight Charts标语为 Small and fast financial charts部署于 GitHub PagesbaseUrl为/lightweight-charts/主导航包含Getting Starteddocs/intro、Tutorials/tutorials、API Referencedocs/api/index、Plugins/plugins以及版本下拉菜单文档侧边栏由 website/sidebars.js 定义教程侧边栏由 website/sidebars-tutorials.js 定义教程通过独立的content-docs实例挂在/tutorials路由下配置了 Algolia 站内搜索indexName: lightweight-charts与 Prism 代码高亮主题。本地开发pnpm start文档站点使用 pnpm 作为包管理器仓库根目录的 pnpm-workspace.yaml 将其组织为 monorepo文档站点是其中一个 workspace 包。启动本地开发服务器pnpm start该命令实际执行的是 website/package.json 中的start: pnpm build:demos cross-env TYPEDOC_WATCHtrue docusaurus start即先执行build:demos调用../scripts/plugins/build-demos.mjs构建教程中嵌入的可运行示例页面再以TYPEDOC_WATCHtrue环境变量启动 Docusaurus 开发服务器。该环境变量会开启 TypeDoc 的监听模式watch: typedocWatch使 API 参考页面在类型声明变化时自动重新生成。启动后会在浏览器中打开站点窗口大多数改动都会热更新生效无需重启服务器。一个必须注意的前提是API 文档只有在库已经构建、生成了typings.d.ts之后才会生成。也就是说在运行pnpm start之前需要先按 BUILDING.md 的指引完成库本身的构建确保根目录dist/typings.d.ts存在——Docusaurus 配置中的current-api插件正是以../dist/typings.d.ts作为 TypeDoc 的入口点见 website/docusaurus.config.js。生产构建pnpm build生成静态站点pnpm build对应脚本为build: pnpm build:demos node scripts/generate-versions-dts.js docusaurus build构建链路分三步build:demos预构建教程中嵌入的示例node scripts/generate-versions-dts.js为各已发布版本生成类型声明缓存website/scripts/generate-versions-dts.jsdocusaurus build执行完整的 Docusaurus 生产构建把静态内容输出到build目录。构建过程中的一个关键环节在 website/docusaurus.config.js 中配置加载时会从 unpkg 下载每个已发布版本的typings.d.ts到.previous-typings-cache/目录带 3 次重试与指数退避逻辑的downloadFile随后versions.map(typedocPluginForVersion)为每个历史版本各生成一套 API 参考页面写入website/versioned_docs/version-版本/api。同样pnpm build也依赖预先构建好的typings.d.ts否则 API 文档部分不会生成。本地预览构建产物pnpm serve构建完成后可以用pnpm serve在本地以接近 GitHub Pages 的方式预览静态站点。它实际运行的是仓库根目录的 scripts/serve-website.mjs而非docusaurus serve。之所以要替换是因为本站点配置了trailingSlash: false而docusaurus serve会对静态文件同样应用该配置导致/plugin-previews/slug/被 301 到无斜杠路径使得内嵌预览页的相对资源 URL./assets/main-*.js向上多解析一层目录而 404——页面能打开但图表永远不运行。GitHub Pages 直接伺服目录本身因此该脚本按同样的行为实现。该静态服务器默认端口 3010可用--port覆盖将构建产物伺服在http://localhost:3010/lightweight-charts/下BASE与docusaurus.config.js的baseUrl保持一致按 GitHub Pages 的解析顺序尝试 URL 命中路径本身 →index.html→ 相邻的.html文件Docusaurus 对无尾斜杠路由会写出plugins/slug.html拒绝任何逃逸出build目录的路径穿越未知路由回退到站点的404.html。README 中有一条重要提示使用pnpm serve本地预览时内嵌的.html示例无法正确显示但托管到线上后会正常工作因为本地伺服器不执行示例页所依赖的构建期资产重写。发布部署pnpm run deploy将站点发布到 GitHub PagesGIT_USERYour GitHub username GITHUB_ORGANIZATION_NAMEYour Github username or organization name USE_SSHtrue pnpm run deploy各环境变量的作用如下环境变量作用GIT_USER执行发布推送的 GitHub 用户名GITHUB_ORGANIZATION_NAMEGitHub 用户名或组织名用于构造发布目标地址USE_SSHtrue使用 SSH 协议推送而不是 HTTPS 凭据从 website/docusaurus.config.js 可以看到GITHUB_ORGANIZATION_NAME的默认值为tradingview站点 URL 与projectUrl均由organizationName推导而来因此自定义部署到自己的 GitHub Pages 时务必通过该环境变量覆盖默认组织。该命令会先把网站构建为静态文件同样依赖已构建的typings.d.ts然后将产物推送到仓库的gh-pages分支Docusaurus 的deploy命令行为。面向 LLM 的 Markdown 导出机制这是该文档站点最值得一提的设计每次完整构建都会把文档同步导出一份 Markdown 副本供 LLM 和其他以文本而非网页方式阅读文档的工具使用实现插件位于 website/plugins/docs-markdown。README 列出了四种导出产物page URL.md每页对应的纯 Markdown。导出时会对页面做清洗cleanup剥离 frontmatter 与 MDX 语法移除 ESM import 和{…}表达式、JSX 标签保留其子内容、将CodeBlock中的代码示例内联为围栏代码块、展开 content partial_xxx.mdx片段最多递归 3 层防环、并把每个链接重写为绝对 URL。llms.txt全部导出页面的索引按侧边栏顺序组织位于某个分区根部的页面会被提升hoist到该分区标题之下确保每页都归属正确的分组。docs_map.md与llms.txt相同的索引但在每页下面额外列出该页的各级标题H2–H4便于导航。lightweight-charts.d.ts已发布版本的 TypeScript 类型声明整体发布以替代逐符号的 API 参考页面API 参考不参与导出因为这份声明文件已在一份文件中覆盖了全部 API。从 website/plugins/docs-markdown/index.js 的源码可以看出其实现要点导出范围由EXPORTED_SECTIONS定义文档docsSidebar仅导出最新发布版本与教程tutorialsSidebar单一版本API 参考通过API_ROUTE_SEGMENT过滤排除postBuild阶段为每个页面写出route.md并附带一个站点地图页脚注明 Documentation for Lightweight Charts™ vX.Y.Z (latest released version) 并给出llms.txt、docs_map.md的链接——这样只读单页的 AI 助手也能知道当前持有哪个版本、并发现其余文档链接重写rewriteTarget/resolveRelativePath会同时尝试按源文件路径解析和按路由解析两种语义从而兼容带扩展名../a/b.md与不带扩展名./advanced的写法导出页之间的链接指向.md文件指向 API 参考或未导出版本的链接则保留为网页 URLMDX 组件会被还原为文本CodeBlock还原为围栏代码块chartOnly块会加上 Source of the interactive example shown on this page 引导语、iframe内嵌示例还原为可点击链接、CardLinkList还原为列表、TabItem保留其标签而Chart、BrowserOnly等无文本内容的组件则直接移除代码示例还会按站点同样的规则清理样式注释highlight-*、hide-*、remove-*等 magic comments并把主题色常量替换为具体色值见 website/plugins/docs-markdown/components.js 的cleanCodeSample。关键约束导出文件在postBuild阶段生成因此只存在于完整的pnpm build即npm run build产物中开发服务器运行时不会生成。添加一个新的文档版本文档站点采用 Docusaurus 版本化机制历史版本位于website/versioned_docs/version-版本/与website/versioned_sidebars/。新增版本执行pnpm docusaurus docs:version $VERSION其中$VERSION需要与lightweight-charts包在 npmunpkg上实际可用的某个版本号一致。例如为 3.7.0 建立文档版本pnpm docusaurus docs:version 3.7.0该命令会把当前docs/的内容快照为新的versioned_docs/version-3.7.0/并生成对应的版本化侧边栏。当前仓库中 website/versions.json 已列出 3.8、4.0、4.1、4.2、5.0、5.1、5.2 等历史版本配合 website/docusaurus.config.js 中为每个版本从 unpkg 下载类型声明生成 API 页的逻辑实现完整的多版本文档站。CI/CDCircleCI 流水线站点由 CircleCI 负责构建、测试、发布库以及部署网站涉及两个 Jobbuild-docusaurus-website在所有分支上运行用于在任何改动合并前提前暴露可能破坏网站构建的问题例如示例、链接或配置回归deploy-docusaurus-website仅在master分支运行执行线上部署。两个 Job 定义在仓库的 CircleCI 配置文件中与库本身的构建、测试、发布流水线共用同一套 CI 基础设施。常用 Docusaurus CLI 命令website/package.json 暴露了以下可直接使用的脚本命令作用pnpm docusaurus调用 Docusaurus CLI 入口pnpm swizzle覆盖/定制 Docusaurus 主题组件本仓库已 swizzle 了Logo等组件见 website/docusaurus.config.js 中src/theme/Logo的注释pnpm clear清空 Docusaurus 构建缓存docusaurus clearpnpm write-translations生成翻译用文案文件pnpm write-heading-ids为 Markdown 标题写入显式锚点 ID更多 CLI 用法构建、部署、版本管理等可参考 Docusaurus 官方 CLI 文档在仓库内你还可以直接阅读 website/docusaurus.config.js 和 scripts/serve-website.mjs 等配置文件来确认每个命令在本项目中的具体参数与行为。小结Lightweight Charts™ 的文档网站是一套库构建产物 自动生成 API 文档 手写概念教程 LLM 友好导出四层架构的完整实践开发pnpm start热更新开发需先构建库以生成typings.d.ts构建pnpm build产出静态站点含示例预构建、多版本类型声明与 API 页面生成预览pnpm serve以 GitHub Pages 语义本地伺服构建产物部署pnpm run deploy通过环境变量配置后推送到gh-pagesAI 友好每次构建自动导出page.md、llms.txt、docs_map.md与lightweight-charts.d.ts让 LLM 与自动化工具能以纯文本方式消费整套文档版本管理pnpm docusaurus docs:version $VERSION快照新版本CircleCI 负责构建校验与master分支的自动部署。对于希望为文档仓库做贡献的开发者建议按先构建库 → 再pnpm start→ 修改手写文档 → 观察热更新 → 提交前执行pnpm build验证 Markdown 导出与链接解析的顺序开展工作涉及多版本改动时务必同时检查versioned_docs/与versions.json的对应关系。【免费下载链接】lightweight-chartsPerformant financial charts built with HTML5 canvas项目地址: https://gitcode.com/gh_mirrors/li/lightweight-charts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考