Docgeni 会在构建时自动生成文档站点（默认输出到 .docgeni/site），你不必从零搭建 Angular 工程。若需扩展站点能力，在 .docgeni 下准备三个可选目录即可，分别对应三类自定义：

.docgeni/
├── public/       → 站点外观与静态资源（配置项 publicDir，默认路径 public）
├── components/   → Markdown 自定义内置组件（配置项 componentsDir）
└── app/          → 全站级 Angular 配置（如 providers）

自动生成的站点目录

执行 docgeni build 或 docgeni serve 时，若未配置 siteProjectName，Docgeni 会在 .docgeni/site 生成一个完整的 Angular 应用（结构与 Angular CLI 生成的 application 项目 类似，随 Angular 版本可能略有差异）：

.docgeni/site/
├── angular.json
├── karma.conf.js
├── .browserslistrc
├── tsconfig*.json
└── src/
    ├── index.html          # 入口 HTML，body 内为 <dg-root>
    ├── main.ts             # bootstrapApplication 启动
    ├── main.server.ts      # 启用 SSR/SSG 时存在
    ├── server.ts
    ├── styles.scss
    ├── .gitignore          # 默认忽略 app/content、assets/content
    ├── environments/
    ├── assets/
    └── app/
        ├── app.config.ts
        ├── app.config.server.ts
        └── content/        # 文档与示例构建产物，请勿手改

自定义 public 目录

通过 同名文件覆盖 定制生成站点：将 publicDir 下的文件拷贝到 .docgeni/site 并覆盖默认值（默认目录 .docgeni/public）。可覆盖项如下：

.docgeni/public/
├── assets/
│   └── images/
│       └── logo.png
├── favicon.ico
├── .browserslistrc
├── index.html
├── styles.scss
└── tsconfig.json

自定义根应用 providers

向文档站点的 Angular 应用注入全局 providers，例如在所有组件示例中共享 Service，或为文档演示提供全局单例。

在 .docgeni/app/module.ts 中 export default { providers: [...] }，Docgeni 会合并进站点的 app.config.ts。仅支持 providers，不支持 imports；第三方模块请在对应示例或内置组件中自行 import。

示例：

ts
import { SomeService } from './some.service';

export default {
    providers: [SomeService],
};

Docgeni 会将上述 providers 合并进站点 app.config.ts 的 providers 数组，示例里即可正常注入 SomeService。

自定义内置组件

在文档中使用自定义 HTML 标签（如 <my-badge>），与 Alert、Tabs 等内置组件用法类似，常用于展示设计令牌、色板、图标，或封装团队反复使用的文档块。

在 .docgeni/components（或 componentsDir 配置的路径）下添加组件即可。Tabs、Embed 等更多内置能力见 内置组件。

典型结构：

.docgeni/components/
├── color/
│   ├── color.component.ts
│   └── color.component.html
└── module.ts          # 可选，为内置组件统一 import 第三方模块

组件需继承 DocgeniBuiltInComponent，推荐使用 Signal input()：

ts
import { ChangeDetectionStrategy, Component, effect, input } from '@angular/core';
import { DocgeniBuiltInComponent } from '@docgeni/template';

@Component({
    selector: 'my-color',
    templateUrl: './color.component.html',
    standalone: true,
    changeDetection: ChangeDetectionStrategy.OnPush,
})
export class MyColorComponent extends DocgeniBuiltInComponent {
    readonly color = input<string>('');

    private readonly colorEffect = effect(() => {
        if (this.color()) {
            this.hostElement.style.color = this.color();
        }
    });
}

export default {
    selector: 'my-color',
    component: MyColorComponent,
};

Markdown 中写法：

html
<my-color color="red">Color</my-color>

完全自定义站点（不推荐）

当 publicDir 与 .docgeni/app 仍无法满足需求时，可在 monorepo 中用 Angular CLI 新建 application，并在配置中设置 siteProjectName，让 Docgeni 把文档与示例输出到该项目的 src/app/content 等目录。

第一步：创建站点项目

bash
ng generate application site --style=scss

在 .docgenirc.js 中配置：

ts
export default {
    siteProjectName: 'site', // 与 angular.json 中 projects 的 key 一致
};

第二步：改为独立应用启动

删除 site/src/app 下脚手架自带的示例组件，使用 Standalone + bootstrapApplication（与 Docgeni 生成的站点一致）。

ts
import { bootstrapApplication } from '@angular/platform-browser';
import { appConfig } from './app/app.config';
import { RootComponent } from './app/content/index';

bootstrapApplication(RootComponent, appConfig).catch((err) => console.error(err));

ts
import { ApplicationConfig, importProvidersFrom } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideAnimations } from '@angular/platform-browser/animations';
import { DocgeniTemplateModule } from '@docgeni/template';
import { DOCGENI_SITE_PROVIDERS, IMPORT_MODULES } from './content/index';

export const appConfig: ApplicationConfig = {
    providers: [
        provideRouter([]),
        provideAnimations(),
        importProvidersFrom(DocgeniTemplateModule, ...IMPORT_MODULES),
        ...DOCGENI_SITE_PROVIDERS,
    ],
};

第三步：忽略 content 目录

在 site/src/.gitignore 中加入：

app/content
assets/content

第四步：入口 HTML 与样式

• index.html：将 app-root 改为 dg-root
• styles.scss：引入 @import '@docgeni/template/styles/index.scss';

html
<!doctype html>
<html lang="zh-cn">
  <head>
    <meta charset="utf-8" />
    <title>Docgeni</title>
    <base href="/" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="icon" type="image/x-icon" href="favicon.ico" />
  </head>
  <body>
    <dg-root></dg-root>
  </body>
</html>

scss
@import '@docgeni/template/styles/index.scss';

若出现 TypeScript 严格模式报错，可在 tsconfig.app.json 的 compilerOptions 中设置 "strict": false 作为临时方案。

最后执行 docgeni serve --port 4600（或项目中的 npm run start:docs）预览。