npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@cc-dev-kit-test/console-components-lib-publisher

v1.0.0-preview.0

Published

--- name: lib-publisher zhName: 文档构建发布 sort: 3 tags: dev-kit: true documentation: true ---

Downloads

4

Readme


name: lib-publisher zhName: 文档构建发布 sort: 3 tags: dev-kit: true documentation: true

@alicloud/console-components-lib-publisher

@alicloud/console-components-lib-publisher是 console-components 提供的物料开发者工具包。 它提供了以下脚本,来辅助物料开发、协作:

  • cc-extract-api 它做了以下 3 件事情:
    • 使用api-extractor,读取lib/index.d.ts(即tsc的输出),提取 ts 代码中的类型、注释信息。输出到cc-dev-out/api-extractor/目录。
    • 然后,dev-kit/api-documenter会将上述输出信息加工成 json 数据,作为 API 文档的数据。输出到cc-dev-out/api-json/目录。因此,业务组件的 API 文档由源码转化而成,而不是人工维护,避免文档腐化
    • lib/index.d.ts为入口,将.d.ts声明文件打包(类似于 webpack 打包 js 模块),输出到cc-dev-out/index.d.ts,在此过程中,被声明为@internal@alpha的 ts 类型、接口成员会被过滤掉。你可以利用这一点来避免不稳定的 ts 接口暴露给用户,提高封装性。详见api-extractor 文档
  • cc-build-doc 将 markdown 文档打包成一个 js bundle。
    • 构建成 js bundle 的好处是便于分发和扩展。各种基于 markdown 的扩展(demo 嵌入、ts Interface 渲染、图片内联、目录生成)在构建阶段就已经被处理完毕,文档站点无需关注文档功能的编译和实现,文档站点可以将一篇文档当做一个普通 React 组件来加载、渲染。未来我们向 markdown 语法加入更多扩展的时候,文档站点没有感知。

      详细的文档扩展能力说明,请参考 👉文档能力

    • 一般的用法是将 markdown 构建成 bundle 以后,放在 npm 包中一起发布,文档站点通过 npm cdn(比如 unpkg)来加载文档。
  • cc-doc-local-dev 本地开发、预览。
    • 既然已经可以将 markdown 文档打包成一个 js bundle,自然也就很容易实现本地开发模式(使用webpack-dev-server)。在这个模式下你可以快速预览渲染后的文档。我们会监听 markdown 文件的变更、src 代码的变更、demo 代码的变更,并自动刷新。

      目前,对 Typescript Interface 代码的修改,不会导致文档中渲染的 Interface 表格的热刷新。需要重新执行npm run prepare && npm run doc:local-dev

  • cc-publish-preview 将当前的物料发布成一个预览包。
    • 预览包包括物料本身的运行代码,以及物料的文档 bundle
    • 通过临时 npm 账号将当前 package 发布到@cc-dev-kit-test/${实际包名}
    • 预览包发布成功以后,你会立刻得到一个 URL 分享链接。将 URL 分享给你的 UI 评阅者,评阅者用浏览器打开就能看到当前物料的文档。得益于文档的 Codesandbox Demo 能力、API 文档能力,这份文档能够快速地让评阅者了解、试用你开发的物料,无需切换代码分支、启动开发服务器等耗时的操作。
    • 请阅读 👉文档评审

以上脚本工具都在物料包根目录(即 package.json 所在的目录)运行。使用他们的项目范例:最小示例Wind 物料的使用方式

本工具包只负责开发期的信息提取、构建、发布;运行时的加载、样式和功能放在@alicloud/console-components-lib-documenter包中。

为什么要选择打包文档

站点与文档扩展能力解耦

为了增强文档的表现能力和阅读体验,我们基于普通 Markdown 文档做了很多扩展。你编写的文档不局限于文本、HTML 的表现能力,它还能嵌入外部的非文本内容(提取源码中的 Interface 并渲染到文档上)、交互性内容(用户可编辑、试验的 Demo)。我们还会解析文档结构,自动生成文档目录。

如果将这些扩展交给文档站点来实现,会出现两个问题:

  • 单一职责:文档站点就需要做很多文档粒度的事情(解析文档文本中的扩展语法指令、根据指令对文档进行转换、渲染),代码混杂在一起,无法专注于文档编排的本职工作。
  • 文档不可复用:只有我们自己的文档站点能够渲染这种文档,因为一般的站点没有实现这些文档扩展。举个例子,目前 xconsole 的站点就有嵌入 console-components 文档的需求,因为 console-components 是 xconsole 设计规范的官方实现。

这就是为什么我们要把文档能力从站点解耦出来,提炼出@alicloud/console-components-lib-publisher工具包,它负责在开发构建期间辅助文档的编写和发布。与之对应的,@alicloud/console-components-lib-documenter负责在运行期间辅助文档的加载和渲染。

这个工具究竟实现了哪些文档功能,已经在 👉文档能力进行了详细说明。本篇文档只阐述文档打包相关的重要特性。

解耦以后,@alicloud/console-components-lib-publisher在构建期解析文档文本,根据其中的指令对文档进行转换、渲染,输出成 JavaScript bundle,它导出一个 React 组件。文档站点只需要加载这个 bundle,然后像渲染普通 React 组件一样,将它渲染出来,就能够让用户看到表现形式丰富的文档。文档站点不需要知道这些表现能力是如何实现,专注于站点应用的实现,比如导航目录编排、页面搜索、文档分类等。

@alicloud/gatsby-theme-console-doc就是这样一个文档站点框架,帮助开发者快速配置出一个功能丰富的文档站点。本站点就是使用这个框架来配置出来的。

另一方面,其他文档站点(即使不使用我们提供的站点框架)也能渲染我们的文档,因为它已经被转换成一个普通的 React 组件。

文档可动态加载

通过加载 js bundle 的方式来加载文档,意味着你无需为文档站点实现任何后端数据服务。 你将文档站点构建好以后,部署到 cdn(比如使用免费的 unpkg)。静态站点在运行时从 cdn 加载文档 bundle。 当文档更新以后,你只需要重新构建、部署 cdn,你的文档站点就会加载到最新的文档,无需重新构建发布。 这样就在保持站点静态化(不依赖后端数据服务)的同时,做到了文档站点的实时更新。

承载本地图片

我们书写 markdown 文档的时候经常有一个痛点:由于 markdown 是文本格式,它不能直接承载图片,因此往往需要借助图床。但是图床嵌入图片的方式会遇到以下困扰:

  • 操作太麻烦:上传到图床、拷贝 url、在 markdown 中插入图片![altText](https://url.com)
  • 很难找到可靠(且免费)的图床,大部分免费的平台无法保证图片长期有效。如果图床突然删除了你的图片,你很可能再也找不回来(如果你自己没有备份的话)
  • 便携性(portability)差:文档与平台绑定。虽然很多文档、博客平台提供了图床(比如语雀),但是把图片放在平台图床会让你的文档与图片在存储上分离,变得难以迁移

于此相反的是 Word 文档格式、PDF 格式,它们本身是二进制格式,能直接承载图片,不会有上述的困扰。

@alicloud/console-components-lib-publisher选择了 js bundle 作为文档的分发形式。js bundle 是一种非常便携的分发格式(类似于 PDF 文档)。利用 webpack 的一些 loader,它可以将本地的图片打包到 js bundle 中。因此,你的文本、demo 代码、图片等资源都一起存在本地仓库,本地仓库是"single source of truth",可以通过 git 来存管和追踪。

.开头的 url 视为相对路径,指向本地图片,会被打包到 js bundle 中(data-url 编码)。并且我们自动帮你做了图片压缩,以便减小 bundle size。 示例:![aliyun](./assets/aliyun.png)

其他的 url 视为普通外链 url,不会被打包。 示例:![aliyun](https://img.alicdn.com/tfs/TB1Ly5oS3HqK1RjSZFPXXcwapXa-238-54.png)