# @timmo001/docs-kit 中文文档

规范地址：https://npmcn.com/package/%40timmo001/docs-kit/

版本：0\.9\.33
npm 元数据更新时间：2026-11-02T16:37:18.028Z
中文译文更新时间：2026-11-02T16:53:12.075Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：89.8 kB，18 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：3 个
- peer 依赖：blume 2\.2\.6
- 首次发布：2026-10-07T13:09:25.869Z
- 最新版本发布：2026-11-02T16:37:17.633Z
- 已发布版本数：49（近 12 个月 49 个）

## 中文简介

timmo001文档站点的共享品牌、布局和配置

## 安装

```sh
npm install @timmo001/docs-kit
```

也可以使用：`pnpm add @timmo001/docs-kit`、`yarn add @timmo001/docs-kit`、`bun add @timmo001/docs-kit`

## README

# @timmo001 / docs-kit

为我的文档站点共享品牌、布局和配置。

根导出呈现品牌图像，不依赖于文档工具。这个 `blume` Export持有 [布卢姆](https://github.com/haydenbleasel/blume) 组成部分：一个配置助手，一个 主页横幅，标题GitHub链接和布局样式表。如果网站 离开Blume后，根导出保留下来，新工具有了自己的入口点。

## 安装

```sh
bun add -E @timmo001/docs-kit
```

这个 `blume` 出口需要 `blume` 版本 `peerDependencies`.

## 布卢姆

### 配置

`docsConfig` 从站点详细信息返回完整的Blume配置。通过什么 否则布鲁姆就和他们一起接受；它将覆盖它所替换的默认值，并且 `markdown`， `navigation` 和 `seo` 合并一层深。

```ts
import { docsConfig } from "@timmo001/docs-kit/blume";
import { defineConfig } from "blume";

export default defineConfig(
  docsConfig({
    title: "Triage",
    description: "Pull request triage from the terminal.",
    site: "triage.timmo.dev",
    github: { owner: "timmo001", repo: "triage" },
    navigation: {
      sidebar: ["/", "/getting-started"],
    },
  }),
);
```

默认值:

-   浅色和深色标志来自 `public/logo-light.svg` 和 `public/logo-dark.svg`， 以标题作为徽标文本。
-   内容 `src/content/docs`，最后修改日期从git和外部链接 在新选项卡中打开。
-   GitHub的高对比度的代码主题，因为默认的错过WCAG AA on 注释和关键字。集 `markdown.code.theme` 去改变他们。
-   Cloudflare部署到 `https://<site>`.
-   `llms.txt`， MCP端点为 `/mcp`， WebMCP和代理的可读性。问 AI和页面反馈关闭。
-   GitHub `branch` 设置为 `main` 和 `dir` 来 `docs`，加上头存储库 链接。
-   生成的共享卡使用 `src/assets/logo.svg`，以及组织标志，网址为 `/logo.png` (见 [品牌形象](https://npmcn.com/package/%40timmo001/docs-kit/#readme-brand-images)）。

### 组件

布卢姆读取 `components.ts` 在不运行它的情况下，在那里导入组件 直接:

```ts
import HeaderSearch from "@timmo001/docs-kit/blume/header-search.astro";
import HomeBanner from "@timmo001/docs-kit/blume/home-banner.astro";
import { defineComponents } from "blume";

export default defineComponents({
  layout: {
    PageHeader: HomeBanner,
    Search: HeaderSearch,
  },
});
```

-   `HomeBanner` 显示标识、标题和描述，横跨首页的顶部 页面并隐藏页面本身的标题和引页。其他页面什么也没有呈现。
-   `HeaderSearch` 保持Blume的搜索，并在它之后添加GitHub链接 Config有一个存储库。

两者都使用有作用域的CSS，所以它们不依赖于顺风扫描 `node_modules`.

### 主题

导入布局样式从网站的 `theme.css`：

```css
@import "@timmo001/docs-kit/blume/theme.css";
```

这样可以在大屏幕上扩大内容栏，并保持“在此页上” 铁轨旁边的内容。横幅的全宽布局依赖于这些 列。

然后导入应用程序的基础主题的网站文档，如Base， 玻璃、测量、石板、桥梁或障碍：

```css
@import "@timmo001/docs-kit/blume/themes/bridge.css";
```

它将Blume的颜色、半径和字体设置为浅色、深色和黑色 更暗，所以离开 `theme.accent` 的 `blume.config.ts`． 字体是堆叠的， 加载主题的字体文件 `theme.css` 还有，比如 `@import "@fontsource-variable/inter";`． 使用Base直到应用程序有一个主题 自己的。

`HeaderSearch` 在blme的明暗切换旁边增加了一个模式选择器 浅色，深色和深色。为了让读者也能选择主题，导入每一个 主题后的站点默认设置，并将主题传递给 `HeaderSearch` 从一个 包装组件:

```css
@import "@timmo001/docs-kit/blume/themes/base.css";
@import "@timmo001/docs-kit/blume/themes/all.css";
```

```astro
---
import HeaderSearch from "@timmo001/docs-kit/blume/header-search.astro";

const themes = [
  { id: "base", name: "Base" },
  { id: "bridge", name: "Bridge" },
];
---

<HeaderSearch {...Astro.props} themes={themes} defaultTheme="base" />
```

设置这些 `theme.css` 改变横幅：

```css
.home-banner {
  --home-banner-logo-size: 20rem;
  --home-banner-height: 30rem;
  --home-banner-background: #e4e4e7;
  --home-banner-background-dark: #09090b;
}
```

## 品牌形象

`writeBrandImages` 从带有。的方形SVG徽标渲染png `viewBox`:打开 图形和GitHub社交预览卡，512px徽标和苹果触摸图标。 留下一个输出以跳过它。

```ts
import { writeBrandImages } from "@timmo001/docs-kit";

await writeBrandImages({
  logo: "src/assets/logo.svg",
  title: "Triage",
  tagline: ["Pull request triage", "from the terminal."],
  site: "triage.timmo.dev",
  background: "#18181b",
  accent: "#d97706",
  outputs: {
    socialPreview: "../.github/social-preview.png",
    logo: "public/logo.png",
    appleTouchIcon: "public/apple-touch-icon.png",
  },
});
```

Blume制作了自己的每页分享卡，所以一个Blume网站只需要 `og` 用于 文档外的链接。GitHub不读取社交预览 库;在存储库设置下上传它。

## 开发

看到 [库的自述](https://github.com/timmo001/groundwork#development).

## 常见问题

### @timmo001/docs-kit 是什么？

timmo001文档站点的共享品牌、布局和配置

### 如何安装 @timmo001/docs-kit？

在项目目录运行 npm install @timmo001/docs-kit，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：blume（2\.2\.6）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @timmo001/docs-kit 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/timmo001\_\_docs-kit 是否存在。

### @timmo001/docs-kit 支持 ESM 还是 CommonJS？

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

### @timmo001/docs-kit 可以商用吗？

@timmo001/docs-kit 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @timmo001/docs-kit 还在维护吗？

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