# @doqs/analog 中文文档

规范地址：https://npmcn.com/package/%40doqs/analog/

版本：0\.15\.0
npm 元数据更新时间：2026-11-02T10:52:22.179Z
中文译文更新时间：2026-11-13T00:21:58.806Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40doqs/analog
原文对照：https://npmcn.com/package/%40doqs/analog/?lang=original
项目主页：https://github.com/Andersseen/doqs#readme
源码仓库：https://github.com/Andersseen/doqs

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：973 kB，41 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^20\.19\.0 \|\| ^22\.12\.0 \|\| \>=24\.0\.0
- 运行依赖：1 个
- peer 依赖：rxjs ^7\.8\.0，pagefind ^1\.5\.0，typescript ^5\.5\.0 \|\| ^6\.0\.0，@angular/core ^21\.2\.2 \|\| ^22\.0\.0，@angular/common ^21\.2\.2 \|\| ^22\.0\.0，@angular/router ^21\.2\.2 \|\| ^22\.0\.0，@analogjs/content ^2\.9\.2，@angular/platform-browser ^21\.2\.2 \|\| ^22\.0\.0
- 首次发布：2026-10-21T19:06:45.461Z
- 最新版本发布：2026-11-02T10:52:21.797Z
- 近 30 天下载量：2677（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

Analog.js 可编译的Markdown文档 UI

## 安装

```sh
npm install @doqs/analog
```

也可以使用：`pnpm add @doqs/analog`、`yarn add @doqs/analog`、`bun add @doqs/analog`

## README

![Doqs — Documentation that belongs in your app](https://raw.githubusercontent.com/Andersseen/doqs/main/docs/assets/readme-banner.svg)

# @ doqs/ analog (英语)

**生活在你的Angular和 [类似](https://analogjs.org/) 应用.** 一个由Markdown驱动的文档区域——路由、侧边栏、目录、索引、代码块、可选静态搜索直播Angular组件通过 `::demo[id]` 和交互式游戏场 `::playground[id]` ——而你的页眉,页脚,路线,主题和组件仍然属于你.

[![npm](https://img.shields.io/npm/v/@doqs/analog?style=flat-square&logo=npm&label=npm&color=B83410)](https://www.npmjs.com/package/@doqs/analog) [![License: MIT](https://img.shields.io/badge/license-MIT-22C55E?style=flat-square)](https://github.com/Andersseen/doqs/blob/main/LICENSE) [![Repository](https://img.shields.io/badge/GitHub-Andersseen%2Fdoqs-181717?style=flat-square&logo=github)](https://github.com/Andersseen/doqs)

## 这是什么

Doqs 在已使用的角应用程序中添加一个文档区域 [类似](https://analogjs.org/)。Markdown文件成为路由,一个分组的侧边栏,一个目录,一个前/后链接和一个移动抽屉,作为静态HTML预发. 您的页眉、页脚、路由器、主题和组件都属于您; Doqs 没有全局设置 `html` 或者说 `body` 样式.

可选, 在启用之前, 每个选项都关闭 : Pagefind 全文搜索, 版本文档, API 参考页面来自您的 TypeScript, 您自己的独立 Angular 组件被放在 Markdown `::demo[id]`和互动游乐场`::playground[id]`用于添加组件输入的控件、输出检查器、预览宽度、扩展视图(默认方式); `expandedPreview: 'overlay-compatible'` 用于挂起上盖的组件 `<body>`),重置和可复制的使用代码. 建于:点名,可访问标签,代码组,步骤和标题代码.

此读取器刻意短取. 导游们住在官方文件中,其Markdown来源是: [`apps/site/src/content/docs`](https://github.com/Andersseen/doqs/tree/main/apps/site/src/content/docs);网站本身是一个 Doqs 应用程序.

## 支助环境

| 所需经费 | 范围 |
| --- | --- |
| 节点.js | `^20.19.0 || ^22.12.0 || >=24.0.0` |
| 角质 | `^21.2.2 || ^22.0.0` |
| `@analogjs/content` | `^2.9.2` |
| `pagefind` (仅搜索,可选) | `^1.5.0` |
| `typescript` (仅API生成,可选) | `^5.5.0 || ^6.0.0` |

校验:Angular 21.2 有TypeScript 5.9 有Angular 22.2 有TypeScript 6.0 有Analog 2.9.2和无区变化检测. 生产文件页将水合其预先交付的DOM到位;包装的初始化消费者在嵌入的Angular 21、Angular 21 docs-first和Angular 22上通过直接负载、导航和后向/后向. `doq doctor --build` 也检测到一个脚本需要Angular JIT编译器的构造,即变化日志所描述的间歇性的上游Analog构建种族. Zone.js: 带有 `zone.js` 财务报告和审定财务报表 `provideZoneChangeDetection()` 过了消费者的旅程(未在Angular 22上测试)。 有焦点的Linux Firefox/WebKit和Windows Chromium浏览器行程通过主机CI(Spec 0021). 屏幕阅读器输出和WCAG兼容性没有得到核实. 不经过测试,不扩大同伴范围; `doq doctor` 检查您计划中安装的版本.

## 安装

```sh
pnpm add @doqs/analog @analogjs/content @analogjs/router prismjs
```

## 第一个实例

运行应用程序根的集成助手 。 它创造了 `src/doq.paths.ts` 和两个Markdown页面,从不覆盖一个文件,并打印要连接的确切片段(`--dry-run` 预览; `--mode docs-first` 在 `/`:

```sh
pnpm exec doq init
pnpm exec doq doctor
```

连接为四个小编辑, 完整显示在 [模拟配置](https://github.com/Andersseen/doqs/blob/main/apps/site/src/content/docs/analog-configuration.md) 页面:

```ts
// src/doq.paths.ts (generated)
export const doqPaths = { contentDirectory: 'docs', basePath: '/docs' } as const;
```

```ts
// vite.config.ts
analog({
  ssr: true,
  static: true,
  content: { highlighter: 'prism' },
  prerender: { routes: async () => ['/', ...doqPrerenderRoutes(doqPaths)] },
}),
doqDeterministicMarkdown(), // from '@doqs/analog/vite'; recommended, see below
```

```ts
// src/app/app.config.ts
const doqConfig = defineDoqConfig({ ...doqPaths });
providers: [
  provideFileRouter(withExtraRoutes(doqRoutes(doqConfig))),
  provideContent(withMarkdownRenderer()),
  provideDoq(doqConfig),
];
```

```css
/* src/styles.css */
@import '@doqs/analog/styles.css';
```

添加 Markdown 文件为 `title`, (中文(简体) ), `description`, (中文(简体) ), `group` 财务报告和审定财务报表 `order` 以下前题 `src/content/docs`,则 `pnpm build`。 。 。 .

### 决定马克下( 建议)

Analog 使 Markdown 文件同时进行,同时标题 ID 来自于一个共享的 spotger ,因此有了同步的突出显示器 2 文件可以互换重复头部后缀(`usage-1`编号 :`usage-2`),而建筑在跑步上各有不同. `doqDeterministicMarkdown()` 通过Analog自己的钩子使文件一次一个. 它包含上游问题;它没有解决它。 它是选入的,因为 Doqs 无法编辑您的 Vite 配置,并且 `doq init` 财务报告和审定财务报表 `doq doctor` 都指着它.

## 内容作者( 可选)

保持实例与真实源链接,并停止在页面之间复制文本. 自己目录中的作者页面,以 `doq.content.json` 并让 `doq content generate` 在内容目录下方写入普通的 Markdown :

```md
::include{file="/_partials/prerequisites.md"}

::source{file="projects/lib/src/button.ts" region="usage" title="button.ts"}

See [[api:ButtonDirective]] for every input.
```

```ts
// projects/lib/src/button.ts
// #region doqs:usage
const config = provideButton({ size: 'md' });
// #endregion doqs:usage
```

源文件从配置的文本读取 `sourceRoots` 只有,从未执行,从未取走。 没有添加到浏览器捆绑中,不使用它的项目不需要配置. 见指南 _内容作者_ 财务报告和审定财务报表 _内容工具_ 输入 [文档](https://github.com/Andersseen/doqs/tree/main/apps/site/src/authoring/docs)。 。 。 .

## 本地化(0.12)

配置独立作者的 Markdown 目录,用于每个地方 `DoqPaths.i18n`。默认语言保存其已有的URL;其他语言接收语言前缀路径。 提供信号备份 `DoqI18nAdapter` 结束 `provideDoqI18n()` 来翻译 Doqs 拥有的界面文本,并连接主机的活跃地块。 设定 `ownsRouting` 当主机拥有本地化的路由构成时;适配器的存在本身并不意味着拥有. 播放场控件及其验证、复制、对话框和宣布文本使用相同的 `DOQ_DEFAULT_MESSAGES` 目录. 本地化的 Pagefind 请求需要在生成的索引中本地化元数据, 并在缺失时关闭失败 。 参见官方中完整的Angular/Analog集成,存档组成,倒置,SSSR/SG和RTL等实例 [多语种文档指南](https://github.com/Andersseen/doqs/blob/main/apps/site/src/content/docs/guides/versioned-documentation.md#localized-documentation). 在生产建筑中验证(Showcase A:英文、西班牙文、阿拉伯文;真实的Pagefind索引;RTL;粘性TOC;Chrimium;Firefox;WebKit)。 限制:现场SSR为缺失的一页回答HTTP 200,因为Analog 2.9忽略了 `RESPONSE_INIT` (静态托管回答404);屏幕阅读器和Windows浏览器未经测试. 这不是1.0项准备状态索赔.

## 在一个现有网站采用(0.11)

-   导入配置从 `@doqs/analog/config` (单位:千美元)`defineDoqConfig`, (中文(简体) ), `provideDoq`, (中文(简体) ), `doqPrerenderRoutes`类型 : 它只导入 `@angular/core`,所以它也装入 `vite.config.ts` 或者一个脚本,如果主条目没有.
-   `landmark: 'host'` 当你的外壳已经有一个 `<main>`; 默认 `'document'` 让Doqs来做 只有一个 `main` 无论是哪种方式.
-   `unmatched: 'continue'` 允许主机页面将其URL保留在 Doqs 前缀以下,因此页面一次迁移一个.

见指南 _在已有的图书馆网站中采用 Doqs_ 在正式文件中.

## 命令行工具

| 二进制 | 目的 |
| --- | --- |
| `doq` | `doq init` 脚手架; `doq doctor` 诊断整合情况`--json`, (中文(简体) ), `--build`, (中文(简体) ), `--strict`(中文(简体) ) |
| `doq-search` | `doq-search index <siteDir>` 带有 Pagefind 的索引预降输出( 构建后) |
| `doq` (内容) | `doq content generate`, (中文(简体) ), `check` 财务报告和审定财务报表 `watch` 页:1 `::source{}`, (中文(简体) ), `::include{}` 财务报告和审定财务报表 `[[api:Name]]` 写入普通的 Markdown 页面 |
| `doq-api` | `doq-api generate` 财务报告和审定财务报表 `doq-api check` 从一个公开的 TypeScript API 写入和校验参考页面 |

## 公共软件包表面

`@doqs/analog` (浏览器和服务器), `@doqs/analog/config` (仅配置,其首选导入),节点 `@doqs/analog/vite`, (中文(简体) ), `@doqs/analog/search-index`, (中文(简体) ), `@doqs/analog/api-reference` 财务报告和审定财务报表 `@doqs/analog/content`,以及 `@doqs/analog/styles.css`出口、预期稳定性和兼容性政策 [公共 API](https://github.com/Andersseen/doqs/blob/main/apps/site/src/content/docs/reference/public-api.md) 页面和在 [文件/路线图/1.0-准备状态](https://github.com/Andersseen/doqs/blob/main/docs/roadmap/1.0-readiness.md)CSS 代号是 `--host-docs-*` 自定义属性.

## 链接

-   [更改日志](https://npmcn.com/package/%40doqs/analog/CHANGELOG.md)
-   [来源和问题](https://github.com/Andersseen/doqs)
-   [npm 软件包](https://www.npmjs.com/package/@doqs/analog)

## 捐款

光谱驱动; 见 [捐款额](https://github.com/Andersseen/doqs/blob/main/CONTRIBUTING.md) 财务报告和审定财务报表 [一般事务人员(其他职等)](https://github.com/Andersseen/doqs/blob/main/AGENTS.md)麻省理工学院有执照.

## 常见问题

### @doqs/analog 是什么？

Analog\.js 可编译的Markdown文档 UI

### 如何安装 @doqs/analog？

在项目目录运行 npm install @doqs/analog，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：rxjs（^7\.8\.0）、@angular/core（^21\.2\.2 \|\| ^22\.0\.0）、@angular/common（^21\.2\.2 \|\| ^22\.0\.0）、@angular/router（^21\.2\.2 \|\| ^22\.0\.0）、@analogjs/content（^2\.9\.2）、@angular/platform-browser（^21\.2\.2 \|\| ^22\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 doq、doq-api、doq-search，可以用 npx doq 直接运行。

### @doqs/analog 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @doqs/analog 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @doqs/analog 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^20\.19\.0 \|\| ^22\.12\.0 \|\| \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @doqs/analog 可以商用吗？

@doqs/analog 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @doqs/analog 的下载量有多少？

根据 npm 官方下载统计，@doqs/analog 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,677 次，日均约 89 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @doqs/analog 还在维护吗？

最新版本 0\.15\.0 发布于 2026/11/02（11 天前）；至今共发布 12 个版本，其中过去 12 个月发布了 12 个；首次发布于 2026/10/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。