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 🙏

© 2026 – Pkg Stats / Ryan Hefner

@show-docs/docusaurus-theme-scalar

v0.2.11

Published

Md 的 frontmatter 写 scalar: true(spec 地址由 oas3: / aas3: 给)时把该页整页换成一个 iframe,框里用 Scalar 渲染那份 API 文档

Readme

@show-docs/docusaurus-theme-scalar

用 Scalar 的 @scalar/api-reference 渲染 API 文档的 Docusaurus 主题插件。frontmatter 写 scalar: true(渲染哪份文档由 spec 键 oas3: / aas3: 给)时,该文档页整页换成一个同源 iframe,Scalar 在 component-page 那条通用框内路由 (/__component-frame)的一份独立文档里渲染那份文档。

oas3: 摆 OpenAPI、aas3: 摆 AsyncAPI 3 —— 两把键的读法(取第一把非空的、两把都写时告警) 走 component-page 那份共用判据,三条 API 层同一份说明,记在 跨 iframe 协议的「规则表」那一节,这里不抄第二份。 本层只多说一句:Scalar 自己按文档根上那一格(openapi: / asyncapi:)分派,AsyncAPI 3 那份也渲染。

安装

那一格框、两侧的握手与框内那份文档都由 theme-component-page 提供;本层另外那一条插件前提 (编本包那几份未编译 .tsx 的那条 babel 规则)坏在哪一格、由谁认领,记在 plugin-compile-source 的 README,这里不抄第二份。 三个包一起安装:

pnpm add @show-docs/docusaurus-plugin-compile-source @show-docs/docusaurus-theme-component-page @show-docs/docusaurus-theme-scalar

本层不依赖 @show-docs/docusaurus-theme-iframe(那一层只管「整页交给一个外部站点的 URL」 那一把键),装上或卸载它都不影响这一层。

使用

注册插件

// docusaurus.config.mjs
export default {
  plugins: [
    '@show-docs/docusaurus-plugin-compile-source',
    '@show-docs/docusaurus-theme-scalar',
    // 提供 `DocItem` 那一份判表:写在各层之后 = 层栈最外 = 最先判
    '@show-docs/docusaurus-theme-component-page'
  ]
};

本层在自己的 loadContent() 里交回一对条目({ componentPage: { components, rules } }:组件 @theme/ScalarView 登记成 scalar,规则 { key: 'scalar', match: 'boolean', render: 'iframe' }), 不必再抄进站点配置。站点 plugins 里那一列的先后不决定同一页多把键时谁赢 —— 那个顺序看 站点 component-page 的 rules 那一列(写法见 component-page 的 README)。

写 frontmatter

---
title: 订单 API
scalar: true
oas3: /openapi.yaml
---

scalar 只写布尔 true:它说的是「这一层接这一页」。要渲染哪份文档由 spec 键给(OpenAPI 写 oas3:,AsyncAPI 3 写 aas3:)—— static/openapi.yaml 对应 /openapi.yaml,也可以写完整 URL(跨域时对方需允许 CORS)。命中后整页换成 iframe,不保留文档正文外壳,也不渲染别的层挂在 正文上方那些东西。框里只接文档地址这一种入参,不支持传入内联文档。

那两把键的读法住在 components/scalar-spec.ts(机制层不认识它们)。AsyncAPI 3 那一版见 AsyncAPI 示例。

配置

本包没有插件选项。Scalar 的渲染参数集中在 components/scalar-ui.tsx:界面语言为简体中文 (localization.locale: 'zh-cn'),并关闭了 Test Request、Ask AI、暗色切换、正文顶上那一格 下载等入口。语言值要使用 Scalar 内置的小写连字符 id(例如 zh-cn,不是 zh-CN)。

渲染方式

  • 命中页只输出 <iframe class="component-frame" src="/__component-frame/">:那一格框由 component-page 提供,地址里不带本页的信息(这一页的 frontmatter 与命中的值随握手送进框里), 所以每一条命中页上的框长得一模一样。
  • Scalar 那套运行时代码(连 Vue)与它那份静态样式表走框内那一份文档里的 import(),父文档既不 import 它,也不下载它。样式表那条还要经过构建期那一步「从全站那一份 css 里摘出来单独一个产物」 (见下面「已知限制」与维护者文档的「样式」一节)—— iframe 隔得住 DOM, 隔不住写进每个页面 <link> 的构建期产物。
  • 框内那份文档只做客户端渲染,静态 HTML 里没有渲染结果。
  • 亮暗模式跟随站点开关;直接打开那条框内路由时用的是它自己加载时的模式,之后不再跟随站点。 Scalar 判亮暗不看属性,换的是框内 <body> 上互斥的两个类名(dark-mode / light-mode)。

路由与深链

  • 可分享的地址是外层文档页:/theme-scalar/docs/scalar-demo#tag/orders/POST/orders。hash 不参与请求文件,整页 加载返回 200。
  • hash 段由框内与框外的消息双向同步;Scalar 的格式是 #tag/<tag>/<METHOD>/<path>,# 后面没有 前导斜杠。
  • AsyncAPI 3 那一版的 hash 是按通道走的:#channel/<通道 id>,进到某条操作再往下一段 #channel/<通道 id>/operation/<操作 id>(同样没有前导斜杠)。
  • 那条框内路由 /__component-frame/ 是三条层共用的,单独打开它只会停在「正在从这一页的文档里 取数据…」那一格(没有外层就没人送数据),不该作为分享地址。
  • 产物中每条接口没有独立的 HTML。

已知限制

  • 厂商那份样式表(实测 277,962 字节)已在构建期摘成独立产物,只在框内那份文档里被 <link>; 外层页面不为它多下载一份(每页省下约 359 KB),全站那一份只剩本包自己写的一条规则。 实测数据见 维护者文档 的「样式」一节。
  • 站点保留 300px 宽的文档侧栏;Scalar 左栏需要 iframe 宽度至少 1024px 才展开。视口 1280px 时 iframe 只有 980px,整套 API 导航会收成「打开菜单」抽屉。
  • 正文按需挂载:视口下方尚未滚动到的章节不在 DOM 中。
  • iframe 内容对搜索引擎和抓取工具不可见。
  • 页面上的 # 由 Scalar 占用,正文标题锚点不适用。
  • 写了 scalar: true 却没给 oas3: / aas3::命中还是命中、框照挂,框里摆本层那句「这一页没给 Scalar 要渲染的文档」的说明(不是 Scalar 自己那句「取不到文档」)。
  • spec 地址必须能从浏览器访问;外网地址需要配置 CORS。

相关文档