@ doqs/ analog (英语)
生活在你的Angular和 类似 应用. 一个由Markdown驱动的文档区域——路由、侧边栏、目录、索引、代码块、可选静态搜索直播Angular组件通过 ::demo[id] 和交互式游戏场 ::playground[id] ——而你的页眉,页脚,路线,主题和组件仍然属于你.
这是什么
Doqs 在已使用的角应用程序中添加一个文档区域 类似。Markdown文件成为路由,一个分组的侧边栏,一个目录,一个前/后链接和一个移动抽屉,作为静态HTML预发. 您的页眉、页脚、路由器、主题和组件都属于您; Doqs 没有全局设置 html 或者说 body 样式.
可选, 在启用之前, 每个选项都关闭 : Pagefind 全文搜索, 版本文档, API 参考页面来自您的 TypeScript, 您自己的独立 Angular 组件被放在 Markdown ::demo[id]和互动游乐场::playground[id]用于添加组件输入的控件、输出检查器、预览宽度、扩展视图(默认方式); expandedPreview: 'overlay-compatible' 用于挂起上盖的组件 <body>),重置和可复制的使用代码. 建于:点名,可访问标签,代码组,步骤和标题代码.
此读取器刻意短取. 导游们住在官方文件中,其Markdown来源是: 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 检查您计划中安装的版本.
安装
pnpm add @doqs/analog @analogjs/content @analogjs/router prismjs
第一个实例
运行应用程序根的集成助手 。 它创造了 src/doq.paths.ts 和两个Markdown页面,从不覆盖一个文件,并打印要连接的确切片段(--dry-run 预览; --mode docs-first 在 /:
pnpm exec doq init
pnpm exec doq doctor
连接为四个小编辑, 完整显示在 模拟配置 页面:
// src/doq.paths.ts (generated)
export const doqPaths = { contentDirectory: 'docs', basePath: '/docs' } as const;
// vite.config.ts
analog({
ssr: true,
static: true,
content: { highlighter: 'prism' },
prerender: { routes: async () => ['/', ...doqPrerenderRoutes(doqPaths)] },
}),
doqDeterministicMarkdown(), // from '@doqs/analog/vite'; recommended, see below
// src/app/app.config.ts
const doqConfig = defineDoqConfig({ ...doqPaths });
providers: [
provideFileRouter(withExtraRoutes(doqRoutes(doqConfig))),
provideContent(withMarkdownRenderer()),
provideDoq(doqConfig),
];
/* 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 :
::include{file="/_partials/prerequisites.md"}
::source{file="projects/lib/src/button.ts" region="usage" title="button.ts"}
See [[api:ButtonDirective]] for every input.
// projects/lib/src/button.ts
// #region doqs:usage
const config = provideButton({ size: 'md' });
// #endregion doqs:usage
源文件从配置的文本读取 sourceRoots 只有,从未执行,从未取走。 没有添加到浏览器捆绑中,不使用它的项目不需要配置. 见指南 内容作者 财务报告和审定财务报表 内容工具 输入 文档。 。 。 .
本地化(0.12)
配置独立作者的 Markdown 目录,用于每个地方 DoqPaths.i18n。默认语言保存其已有的URL;其他语言接收语言前缀路径。 提供信号备份 DoqI18nAdapter 结束 provideDoqI18n() 来翻译 Doqs 拥有的界面文本,并连接主机的活跃地块。 设定 ownsRouting 当主机拥有本地化的路由构成时;适配器的存在本身并不意味着拥有. 播放场控件及其验证、复制、对话框和宣布文本使用相同的 DOQ_DEFAULT_MESSAGES 目录. 本地化的 Pagefind 请求需要在生成的索引中本地化元数据, 并在缺失时关闭失败 。 参见官方中完整的Angular/Analog集成,存档组成,倒置,SSSR/SG和RTL等实例 多语种文档指南. 在生产建筑中验证(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 页面和在 文件/路线图/1.0-准备状态CSS 代号是 --host-docs-* 自定义属性.
链接
捐款
光谱驱动; 见 捐款额 财务报告和审定财务报表 一般事务人员(其他职等)麻省理工学院有执照.