kawapress 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,71 +1,30 @@
1
- <p align="center">
2
- <picture>
3
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ShenQingchuan/kawapress/main/docs/public/kawapress-logo-dark.png">
4
- <img src="https://raw.githubusercontent.com/ShenQingchuan/kawapress/main/docs/public/kawapress-logo.png" alt="KawaPress" width="180">
5
- </picture>
6
- </p>
1
+ # kawapress
7
2
 
8
- <h1 align="center">KawaPress</h1>
3
+ The KawaPress core: the CLI, the generator and the runtime, plus the nagi preset and its official plugins.
9
4
 
10
- <p align="center">
11
- <strong>A Vue-first static site generator for documentation and content-focused websites.</strong>
12
- </p>
5
+ [![npm version](https://img.shields.io/npm/v/kawapress?label=npm&color=42b883)](https://www.npmjs.com/package/kawapress) · [简体中文](https://github.com/kawapress/kawapress/blob/main/packages/kawapress/README.zh-CN.md)
13
6
 
14
- <p align="center">
15
- Write in Markdown. Develop with real SSR. Extend everything through public APIs.
16
- </p>
7
+ `kawapress` is part of [KawaPress](https://github.com/kawapress/kawapress), a Vue-first static site generator.
17
8
 
18
- <p align="center">
19
- <a href="https://www.npmjs.com/package/kawapress"><img src="https://img.shields.io/npm/v/kawapress?label=npm&color=42b883" alt="npm version"></a>
20
- <a href="https://github.com/ShenQingchuan/kawapress/actions/workflows/deploy-pages.yml"><img src="https://github.com/ShenQingchuan/kawapress/actions/workflows/deploy-pages.yml/badge.svg" alt="documentation build"></a>
21
- <a href="https://github.com/ShenQingchuan/kawapress/blob/main/LICENSE"><img src="https://img.shields.io/github/license/ShenQingchuan/kawapress" alt="MIT license"></a>
22
- <img src="https://img.shields.io/badge/Node.js-%E2%89%A522.12-339933?logo=nodedotjs&logoColor=white" alt="Node.js 22.12 or newer">
23
- </p>
9
+ ## Features
24
10
 
25
- <p align="center">
26
- <a href="https://shenqingchuan.github.io/kawapress/en/">Documentation</a>
27
- ·
28
- <a href="https://github.com/ShenQingchuan/kawapress/blob/main/README.zh-CN.md">简体中文</a>
29
- </p>
11
+ - **Real SSR in development.** Every first request is server-rendered, so SSR-only problems show up before you build.
12
+ - **Vue from end to end.** Markdown becomes Vue components, Vue Router handles navigation, and normal Vue SFCs work inside content.
13
+ - **Complete by default.** `kawapress/nagi` gives you a responsive docs layout, dark mode, local search, syntax highlighting, code groups and multilingual navigation.
14
+ - **AI-ready output.** Page-level Markdown plus `llms.txt` and `llms-full.txt`.
15
+ - **One extension model.** Generator plugins, runtime plugins and presets, with no private theme hooks.
30
16
 
31
- If you run into any problems while using KawaPress, please [open an issue](https://github.com/ShenQingchuan/kawapress/issues). Your feedback helps shape the project during its early development.
32
-
33
- ## Why KawaPress?
34
-
35
- KawaPress turns Markdown into pre-rendered Vue websites. It keeps the familiar simplicity of a documentation generator while giving themes and plugins the same public extension points used by the official experience.
36
-
37
- - **Real SSR during development** — every initial request is server-rendered, so SSR-only problems appear before build or deployment.
38
- - **A complete default experience** — the built-in nagi (凪) preset includes responsive documentation layouts, dark mode, local search, syntax highlighting, Twoslash, code groups, multilingual navigation, and more.
39
- - **Vue from end to end** — Markdown becomes Vue components, Vue Router handles navigation, and regular Vue SFCs fit naturally into content.
40
- - **AI-ready output** — nagi generates page-level Markdown, locale-aware `llms.txt` and `llms-full.txt`, plus built-in copy actions.
41
- - **One extension model** — Generator Plugins, Runtime Plugins, and Presets cover build-time behavior, the Vue runtime, themes, and reusable product setups without private theme hooks.
42
-
43
- KawaPress is an independent project. It is not a VitePress fork or a drop-in replacement, and it intentionally does not use VitePress configuration.
44
-
45
- ## Quick Start
46
-
47
- You need [Node.js](https://nodejs.org/) 22.12 or newer.
48
-
49
- Create a new site with the scaffolder:
17
+ ## Install
50
18
 
51
19
  ```sh
52
- npm create kawapress@latest my-kawapress-site
53
- cd my-kawapress-site
54
- npm run dev
20
+ npm install --save-dev kawapress
55
21
  ```
56
22
 
57
- `pnpm create kawapress my-kawapress-site` and `yarn create kawapress my-kawapress-site` do the same thing. The scaffolder asks for a site title and a default language, and can install dependencies for you.
23
+ `pnpm add --save-dev kawapress` and `yarn add --dev kawapress` work too.
58
24
 
59
- If you would rather see every file from the start, set the site up by hand:
25
+ ## Usage
60
26
 
61
- ```sh
62
- mkdir my-kawapress-site
63
- cd my-kawapress-site
64
- pnpm init
65
- pnpm add --save-dev kawapress
66
- ```
67
-
68
- Create `kawapress.config.ts`:
27
+ A basic site needs only this package. Create `kawapress.config.ts`:
69
28
 
70
29
  ```ts
71
30
  import { nagi } from 'kawapress/nagi'
@@ -75,82 +34,19 @@ export default nagi({
75
34
  })
76
35
  ```
77
36
 
78
- Create `index.md`:
79
-
80
- ```md
81
- ---
82
- layout: home
83
- title: My Docs
84
- ---
85
-
86
- # My Docs
87
-
88
- Welcome to my KawaPress site.
89
- ```
90
-
91
- Start the development server:
37
+ Then run:
92
38
 
93
39
  ```sh
94
- pnpm exec kawapress dev
40
+ pnpm exec kawapress dev # development server
41
+ pnpm exec kawapress build # static files in dist
95
42
  ```
96
43
 
97
- Build static files into `dist`:
98
-
99
- ```sh
100
- pnpm exec kawapress build
101
- ```
102
-
103
- The deployed output is static and does not require a Node.js server. npm and Yarn commands are available in the [Getting Started guide](https://shenqingchuan.github.io/kawapress/en/guide/getting-started).
104
-
105
- > If your site directly imports Vue APIs or Vue components, also install `vue` as a development dependency.
106
-
107
- ## What You Get
108
-
109
- | Area | Included capability |
110
- | --- | --- |
111
- | Authoring | Markdown, frontmatter, Vue in Markdown, file-based routing, data loaders |
112
- | Rendering | Shared development/build SSR semantics, hydration, Vue Router navigation |
113
- | Documentation UI | nagi layouts, responsive sidebar, page outline, dark mode, i18n |
114
- | Content | Shiki, Twoslash, code groups, code copy, containers, GitHub alerts |
115
- | Discovery | Lazy local search and locale-aware navigation |
116
- | AI consumption | Page `.md`, `llms.txt`, `llms-full.txt`, copy actions |
117
- | Styling | UnoCSS integration with sensible nagi defaults |
118
-
119
- The `kawapress` package includes nagi and its official plugins. A basic site only needs this one package; advanced users can compose the individual `@kawapress/*` packages directly.
120
-
121
- ## Extension Model
122
-
123
- KawaPress keeps extension boundaries explicit:
124
-
125
- - a **Generator Plugin** extends configuration, Markdown, page data, Vite, and build artifacts;
126
- - a **Runtime Plugin** extends the real Vue App and Vue Router in both SSR and the browser;
127
- - a **Preset** combines configuration and plugins into a ready-to-use experience such as nagi.
128
-
129
- A logical plugin is installed once and can provide both generator and runtime behavior. Learn more in the [Plugin System guide](https://shenqingchuan.github.io/kawapress/en/guide/plugin-system).
44
+ To start from a template instead, run `npm create kawapress@latest`.
130
45
 
131
46
  ## Documentation
132
47
 
133
- - [Getting Started](https://shenqingchuan.github.io/kawapress/en/guide/getting-started)
134
- - [What is KawaPress?](https://shenqingchuan.github.io/kawapress/en/guide/what-is-kawapress)
135
- - [Markdown Extensions](https://shenqingchuan.github.io/kawapress/en/guide/markdown-extensions)
136
- - [Internationalization](https://shenqingchuan.github.io/kawapress/en/guide/internationalization)
137
- - [Plugin System](https://shenqingchuan.github.io/kawapress/en/guide/plugin-system)
138
- - [Theme Customization](https://shenqingchuan.github.io/kawapress/en/guide/theme-customization)
139
-
140
- ## Contributing
141
-
142
- Issues and pull requests are welcome. For a large feature, please open an issue first so the direction can be agreed on before implementation.
143
-
144
- ```sh
145
- pnpm install
146
- pnpm lint
147
- pnpm typecheck
148
- pnpm test
149
- pnpm build
150
- ```
151
-
152
- KawaPress uses Node.js 22.12 or newer and pnpm 11.22.0 for repository development.
48
+ [Documentation](https://kawapress.dev/en/guide/getting-started) · [Report a problem](https://github.com/kawapress/kawapress/issues)
153
49
 
154
50
  ## License
155
51
 
156
- [MIT](https://github.com/ShenQingchuan/kawapress/blob/main/LICENSE) © KawaPress contributors
52
+ [MIT](https://github.com/kawapress/kawapress/blob/main/LICENSE) © KawaPress contributors
package/README.zh-CN.md CHANGED
@@ -1,156 +1,52 @@
1
- <p align="center">
2
- <picture>
3
- <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ShenQingchuan/kawapress/main/docs/public/kawapress-logo-dark.png">
4
- <img src="https://raw.githubusercontent.com/ShenQingchuan/kawapress/main/docs/public/kawapress-logo.png" alt="KawaPress" width="180">
5
- </picture>
6
- </p>
1
+ # kawapress
7
2
 
8
- <h1 align="center">KawaPress</h1>
3
+ KawaPress 核心:命令行、生成器和运行时,并内置 nagi 预设和全部官方插件。
9
4
 
10
- <p align="center">
11
- <strong>以 Vue 为核心,面向文档与内容型网站的静态站点生成器。</strong>
12
- </p>
5
+ [![npm version](https://img.shields.io/npm/v/kawapress?label=npm&color=42b883)](https://www.npmjs.com/package/kawapress) · [English](https://github.com/kawapress/kawapress/blob/main/packages/kawapress/README.md)
13
6
 
14
- <p align="center">
15
- 用 Markdown 安心写作,在真实 SSR 中开发,通过公开能力自由扩展。
16
- </p>
7
+ `kawapress` 是 [KawaPress](https://github.com/kawapress/kawapress) 的一部分。KawaPress 是一个以 Vue 为核心的静态站点生成器。
17
8
 
18
- <p align="center">
19
- <a href="https://www.npmjs.com/package/kawapress"><img src="https://img.shields.io/npm/v/kawapress?label=npm&color=42b883" alt="npm 版本"></a>
20
- <a href="https://github.com/ShenQingchuan/kawapress/actions/workflows/deploy-pages.yml"><img src="https://github.com/ShenQingchuan/kawapress/actions/workflows/deploy-pages.yml/badge.svg" alt="文档构建状态"></a>
21
- <a href="https://github.com/ShenQingchuan/kawapress/blob/main/LICENSE"><img src="https://img.shields.io/github/license/ShenQingchuan/kawapress" alt="MIT 许可"></a>
22
- <img src="https://img.shields.io/badge/Node.js-%E2%89%A522.12-339933?logo=nodedotjs&logoColor=white" alt="Node.js 22.12 或更高版本">
23
- </p>
9
+ ## 特性
24
10
 
25
- <p align="center">
26
- <a href="https://shenqingchuan.github.io/kawapress/">中文文档</a>
27
- ·
28
- <a href="https://github.com/ShenQingchuan/kawapress/blob/main/README.md">English</a>
29
- </p>
11
+ - **开发时就是真正的 SSR。** 每次首次请求都在服务端渲染,只在 SSR 下出现的问题,构建前就能发现。
12
+ - **从头到尾都是 Vue。** Markdown 变成 Vue 组件,导航交给 Vue Router,普通的 Vue 单文件组件也能直接写进内容。
13
+ - **默认就完整。** `kawapress/nagi` 提供自适应文档布局、深色模式、本地搜索、代码高亮、代码组和多语言导航。
14
+ - **面向 AI 的输出。** 每页一份 Markdown,外加 `llms.txt` 和 `llms-full.txt`。
15
+ - **一套扩展模型。** 生成器插件、运行时插件和预设,没有只给主题用的私有钩子。
30
16
 
31
- 使用 KawaPress 时遇到任何问题,欢迎到 [提交 Issue](https://github.com/ShenQingchuan/kawapress/issues) 反馈,一起参与本项目的早期建设。
32
-
33
- ## 为什么选择 KawaPress?
34
-
35
- KawaPress 会把 Markdown 编译成预渲染的 Vue 网站。它保留了文档生成器简单、轻快的写作方式,同时让官方主题和第三方扩展使用完全相同的公开能力。
36
-
37
- - **开发时也执行真实 SSR**:每次首次请求都会在服务端渲染。只在 SSR 中出现的问题,不必等到构建或上线后才发现。
38
- - **默认体验完整**:内置 nagi(凪)预设,包含响应式文档布局、深浅色模式、本地搜索、代码高亮、Twoslash、代码组和多语言导航等常用能力。
39
- - **从头到尾使用 Vue**:Markdown 会变成 Vue 组件,页面跳转交给 Vue Router;需要交互时,也可以自然地使用普通 Vue SFC。
40
- - **面向 AI 的文档产物**:nagi 默认生成每页 `.md`、各语言的 `llms.txt` 与 `llms-full.txt`,并提供复制正文和链接的操作。
41
- - **统一的扩展模型**:Generator Plugin、Runtime Plugin 与 Preset 分别覆盖生成阶段、Vue 运行时和能力组合,不依赖主题私有入口。
42
-
43
- KawaPress 是一个独立项目,不是 VitePress 的分支或配置兼容层,也不能直接使用 VitePress 配置。
44
-
45
- ## 快速开始
46
-
47
- 请先准备 [Node.js](https://nodejs.org/) 22.12 或更高版本。
48
-
49
- 用脚手架创建新站点:
17
+ ## 安装
50
18
 
51
19
  ```sh
52
- npm create kawapress@latest my-kawapress-site
53
- cd my-kawapress-site
54
- npm run dev
20
+ npm install --save-dev kawapress
55
21
  ```
56
22
 
57
- `pnpm create kawapress my-kawapress-site` 和 `yarn create kawapress my-kawapress-site` 的作用完全一样。脚手架会询问站点标题和默认语言,也可以顺便帮你安装依赖。
23
+ 也可以用 `pnpm add --save-dev kawapress` 或 `yarn add --dev kawapress`。
58
24
 
59
- 如果你更想从零看清每个文件,可以手动创建:
25
+ ## 使用
60
26
 
61
- ```sh
62
- mkdir my-kawapress-site
63
- cd my-kawapress-site
64
- pnpm init
65
- pnpm add --save-dev kawapress
66
- ```
67
-
68
- 创建 `kawapress.config.ts`:
27
+ 普通站点只需要这一个包。新建 `kawapress.config.ts`:
69
28
 
70
29
  ```ts
71
30
  import { nagi } from 'kawapress/nagi'
72
31
 
73
32
  export default nagi({
74
- title: 'My Docs',
33
+ title: '我的文档',
75
34
  })
76
35
  ```
77
36
 
78
- 创建 `index.md`:
79
-
80
- ```md
81
- ---
82
- layout: home
83
- title: My Docs
84
- ---
85
-
86
- # My Docs
87
-
88
- 欢迎来到我的 KawaPress 站点。
89
- ```
90
-
91
- 启动开发服务器:
37
+ 然后运行:
92
38
 
93
39
  ```sh
94
- pnpm exec kawapress dev
40
+ pnpm exec kawapress dev # 开发服务器
41
+ pnpm exec kawapress build # 把静态文件生成到 dist
95
42
  ```
96
43
 
97
- 构建静态文件到 `dist`:
98
-
99
- ```sh
100
- pnpm exec kawapress build
101
- ```
102
-
103
- 部署产物是普通静态文件,不需要在服务器上继续运行 Node.js。npm 和 Yarn 的完整命令可以查看[快速开始](https://shenqingchuan.github.io/kawapress/guide/getting-started)。
104
-
105
- > 如果站点会直接导入 Vue API 或 Vue 组件,还需要把 `vue` 安装为开发依赖。
106
-
107
- ## 默认包含什么?
108
-
109
- | 范围 | 内置能力 |
110
- | --- | --- |
111
- | 内容编写 | Markdown、Frontmatter、在 Markdown 中使用 Vue、文件路由、Data Loader |
112
- | 渲染 | 开发与构建共享 SSR 语义、Hydration、Vue Router 站内导航 |
113
- | 文档界面 | nagi 布局、响应式 Sidebar、本页目录、深浅色模式、多语言 |
114
- | 内容增强 | Shiki、Twoslash、代码组、代码复制、提示容器、GitHub Alerts |
115
- | 内容发现 | 按需加载的本地搜索与多语言导航 |
116
- | AI 读取 | 页面 `.md`、`llms.txt`、`llms-full.txt`、页面复制操作 |
117
- | 样式 | UnoCSS 集成与 nagi 默认配置 |
118
-
119
- `kawapress` 已经包含 nagi 和它使用的官方插件。普通文档站只需要安装这一个包;需要自行组合能力时,也可以直接使用独立的 `@kawapress/*` 包。
120
-
121
- ## 扩展模型
122
-
123
- KawaPress 把扩展边界分得很清楚:
124
-
125
- - **Generator Plugin** 负责配置、Markdown、页面数据、Vite 与构建产物;
126
- - **Runtime Plugin** 在 SSR 和浏览器中扩展真实的 Vue App 与 Vue Router;
127
- - **Preset** 把配置和一组插件组合成可以直接使用的产品体验,例如 nagi。
128
-
129
- 一个逻辑插件只需要安装一次,同时可以提供生成侧和运行侧能力。更多内容请查看[插件体系](https://shenqingchuan.github.io/kawapress/guide/plugin-system)。
44
+ 想从模板开始,可以运行 `npm create kawapress@latest`。
130
45
 
131
46
  ## 文档
132
47
 
133
- - [快速开始](https://shenqingchuan.github.io/kawapress/guide/getting-started)
134
- - [KawaPress 是什么?](https://shenqingchuan.github.io/kawapress/guide/what-is-kawapress)
135
- - [Markdown 语法扩展](https://shenqingchuan.github.io/kawapress/guide/markdown-extensions)
136
- - [国际化](https://shenqingchuan.github.io/kawapress/guide/internationalization)
137
- - [插件体系](https://shenqingchuan.github.io/kawapress/guide/plugin-system)
138
- - [主题定制](https://shenqingchuan.github.io/kawapress/guide/theme-customization)
139
-
140
- ## 参与贡献
141
-
142
- 欢迎提交 Issue 和 Pull Request。如果准备增加较大的功能,请先创建 Issue,把目标和方案聊清楚后再开始实现。
143
-
144
- ```sh
145
- pnpm install
146
- pnpm lint
147
- pnpm typecheck
148
- pnpm test
149
- pnpm build
150
- ```
151
-
152
- KawaPress 仓库使用 Node.js 22.12 或更高版本,以及 pnpm 11.22.0 进行开发。
48
+ [文档](https://kawapress.dev/guide/getting-started) · [反馈问题](https://github.com/kawapress/kawapress/issues)
153
49
 
154
- ## 开源许可
50
+ ## 许可证
155
51
 
156
- [MIT](https://github.com/ShenQingchuan/kawapress/blob/main/LICENSE) © KawaPress 贡献者
52
+ [MIT](https://github.com/kawapress/kawapress/blob/main/LICENSE) © KawaPress contributors
package/package.json CHANGED
@@ -1,17 +1,17 @@
1
1
  {
2
2
  "name": "kawapress",
3
3
  "type": "module",
4
- "version": "0.1.0",
4
+ "version": "0.2.1",
5
5
  "description": "A Vue-centric static site generator",
6
6
  "license": "MIT",
7
- "homepage": "https://shenqingchuan.github.io/kawapress/",
7
+ "homepage": "https://kawapress.dev/",
8
8
  "repository": {
9
9
  "type": "git",
10
- "url": "git+https://github.com/ShenQingchuan/kawapress.git",
10
+ "url": "git+https://github.com/kawapress/kawapress.git",
11
11
  "directory": "packages/kawapress"
12
12
  },
13
13
  "bugs": {
14
- "url": "https://github.com/ShenQingchuan/kawapress/issues"
14
+ "url": "https://github.com/kawapress/kawapress/issues"
15
15
  },
16
16
  "keywords": [
17
17
  "documentation",
@@ -81,6 +81,6 @@
81
81
  "tinyglobby": "^0.2.17",
82
82
  "vite": "^8.2.2",
83
83
  "vue": "^3.5.41",
84
- "@kawapress/preset-nagi": "0.1.0"
84
+ "@kawapress/preset-nagi": "^0.2.1"
85
85
  }
86
86
  }
package/src/api/config.ts CHANGED
@@ -1,38 +1,29 @@
1
1
  import type { DeadLinkConfig } from '../core/dead-links'
2
+ import type { ThemeConfig } from '../core/extension-points'
2
3
  import type { HeadConfig } from '../core/head'
3
4
  import type { LocaleConfig } from '../core/site'
4
5
  import type { KawaPressPlugin } from './plugin'
5
6
 
6
- export interface KawapressConfig<ThemeConfig extends object = object> {
7
+ export interface KawapressConfig {
7
8
  title?: string
8
9
  base?: string
9
10
  srcDir?: string
10
11
  publicDir?: string
11
12
  head?: HeadConfig[]
12
- themeConfig?: ThemeConfig
13
- locales?: Record<string, LocaleConfig<ThemeConfig>>
13
+ themeConfig?: Partial<ThemeConfig>
14
+ locales?: Record<string, LocaleConfig>
14
15
  plugins?: KawaPressPlugin[]
15
16
  /** Internal link checking. Defaults to `{ level: 'error' }`; `false` disables it. */
16
17
  deadLinks?: false | DeadLinkConfig
17
18
  }
18
19
 
19
- export function defineConfig<ThemeConfig extends object = object>(
20
- config: KawapressConfig<ThemeConfig>,
21
- ): KawapressConfig<ThemeConfig> {
20
+ export function defineConfig(config: KawapressConfig): KawapressConfig {
22
21
  return config
23
22
  }
24
23
 
25
- export type PresetConfig<
26
- ResolvedThemeConfig extends object,
27
- ThemeConfig extends object = Partial<ResolvedThemeConfig>,
28
- > = KawapressConfig<ThemeConfig>
24
+ export type KawapressPreset = (config?: KawapressConfig) => KawapressConfig
29
25
 
30
- export type KawapressPreset<ThemeConfig extends object = object>
31
- = (config?: KawapressConfig<ThemeConfig>) => KawapressConfig<ThemeConfig>
32
-
33
- export function definePreset<ThemeConfig extends object = object>(
34
- presetConfig: KawapressConfig<ThemeConfig>,
35
- ): KawapressPreset<ThemeConfig> {
26
+ export function definePreset(presetConfig: KawapressConfig): KawapressPreset {
36
27
  return (userConfig = {}) => ({
37
28
  ...presetConfig,
38
29
  ...userConfig,
package/src/api/plugin.ts CHANGED
@@ -1,9 +1,10 @@
1
1
  import type { MarkdownExit } from 'markdown-exit'
2
2
  import type { UserConfig } from 'vite'
3
3
  import type { App } from 'vue'
4
+ import type { PageData } from '../core/extension-points'
4
5
  import type { OutletItemInput, OutletName } from '../core/outlet'
5
6
  import type { Router } from '../core/router'
6
- import type { PageData, SiteConfig } from '../core/site'
7
+ import type { SiteConfig } from '../core/site'
7
8
 
8
9
  export type MaybePromise<T> = T | Promise<T>
9
10
 
@@ -1,5 +1,6 @@
1
1
  import type { ComputedRef } from 'vue'
2
- import type { LocaleLink, PageData, ResolvedSiteData, SiteData } from '../core/site'
2
+ import type { PageData, ThemeConfig } from '../core/extension-points'
3
+ import type { LocaleLink, ResolvedSiteData, SiteData } from '../core/site'
3
4
  import { site } from 'virtual:kawapress-site'
4
5
  import { computed } from 'vue'
5
6
  import { getLocaleIndex, resolveLocaleLinks, resolveSiteDataByPath } from '../core/locale'
@@ -13,16 +14,16 @@ export interface LocaleContext {
13
14
  localeLinks: ComputedRef<LocaleLink[]>
14
15
  }
15
16
 
16
- export function useSite<ThemeConfig extends object = object>(): ComputedRef<ResolvedSiteData<ThemeConfig>> {
17
+ export function useSite(): ComputedRef<ResolvedSiteData> {
17
18
  const route = useRoute()
18
19
  return computed(() => resolveSiteDataByPath(
19
- site as SiteData<ThemeConfig>,
20
+ site as SiteData,
20
21
  route.value.path,
21
22
  ))
22
23
  }
23
24
 
24
- export function useThemeConfig<ThemeConfig extends object = object>(): ComputedRef<ThemeConfig> {
25
- const resolvedSite = useSite<ThemeConfig>()
25
+ export function useThemeConfig(): ComputedRef<Partial<ThemeConfig>> {
26
+ const resolvedSite = useSite()
26
27
  return computed(() => resolvedSite.value.themeConfig)
27
28
  }
28
29
 
@@ -1,6 +1,6 @@
1
1
  import type { Component } from 'vue'
2
+ import type { PageData } from '../core/extension-points'
2
3
  import type { PageTable } from '../core/page-manifest'
3
- import type { PageData } from '../core/site'
4
4
 
5
5
  // path-level cache: same content for every request, safe under SSR concurrency
6
6
  const cache = new Map<string, PageData>()
@@ -1,7 +1,8 @@
1
1
  import type { MarkdownSfcBlocks } from '@mdit-vue/plugin-sfc'
2
2
  import type { MarkdownExit, Token } from 'markdown-exit'
3
3
  import type { LinkRecord } from '../core/dead-links'
4
- import type { PageData, PageHeader } from '../core/site'
4
+ import type { PageData } from '../core/extension-points'
5
+ import type { PageHeader } from '../core/site'
5
6
  import type { GeneratorPluginRunner } from '../plugin/generator-runner'
6
7
  import type { PageComponent, PageComponentEnv } from './page-components'
7
8
  import { componentPlugin } from '@mdit-vue/plugin-component'
@@ -0,0 +1,64 @@
1
+ import type { HeadConfig } from './head'
2
+ import type { PageHeader } from './site'
3
+
4
+ /**
5
+ * The types a plugin or a theme extends with `declare module 'kawapress'`.
6
+ *
7
+ * They are defined here and exported from the main entry with `export *`.
8
+ * Everything inside KawaPress imports them from this file, so the fields that
9
+ * packages add are the fields that every reader sees.
10
+ */
11
+
12
+ /**
13
+ * Theme configuration of a site. The interface is empty on purpose: a theme or
14
+ * a plugin adds the fields it understands from its own package, and every
15
+ * package that is imported contributes to the same type.
16
+ *
17
+ * ```ts
18
+ * declare module 'kawapress' {
19
+ * interface ThemeConfig {
20
+ * githubUrl?: string
21
+ * }
22
+ * }
23
+ * ```
24
+ *
25
+ * A field only exists in the type while the package that declares it is part of
26
+ * the program, so give every field an optional type: the site may not use it.
27
+ */
28
+
29
+ export interface ThemeConfig {}
30
+
31
+ /**
32
+ * Frontmatter of a page. KawaPress keeps the data open, so any key an author
33
+ * writes is allowed and typed `unknown`. A plugin that reads a key declares it
34
+ * from its own package, which gives every reader the exact type:
35
+ *
36
+ * ```ts
37
+ * declare module 'kawapress' {
38
+ * interface PageFrontmatter {
39
+ * comments?: boolean
40
+ * }
41
+ * }
42
+ * ```
43
+ *
44
+ * The keys are optional because the value comes from the author. Check it at
45
+ * runtime before trusting it.
46
+ */
47
+ export interface PageFrontmatter {
48
+ title?: string
49
+ description?: string
50
+ titleTemplate?: string | false
51
+ head?: HeadConfig[]
52
+ [key: string]: unknown
53
+ }
54
+
55
+ export interface PageData {
56
+ path: string
57
+ title: string
58
+ description?: string
59
+ titleTemplate?: string | false
60
+ /** `<head>` tags from frontmatter, rendered after site and locale tags. */
61
+ head?: HeadConfig[]
62
+ frontmatter: PageFrontmatter
63
+ headers: PageHeader[]
64
+ }
@@ -20,31 +20,31 @@ export function resolveLocaleIndex(path: string, localeKeys: Iterable<string>):
20
20
  }) ?? 'root'
21
21
  }
22
22
 
23
- export function getLocaleIndex<ThemeConfig extends object>(
24
- site: SiteData<ThemeConfig>,
23
+ export function getLocaleIndex(
24
+ site: SiteData,
25
25
  path: string,
26
26
  ): string {
27
27
  return resolveLocaleIndex(path, Object.keys(site.locales))
28
28
  }
29
29
 
30
- export function getLocaleHome<ThemeConfig extends object>(
31
- site: SiteData<ThemeConfig>,
30
+ export function getLocaleHome(
31
+ site: SiteData,
32
32
  localeIndex: string,
33
33
  ): string {
34
34
  return site.locales[localeIndex]?.link
35
35
  ?? (localeIndex === 'root' ? '/' : `/${localeIndex}`)
36
36
  }
37
37
 
38
- export function resolveSiteDataByPath<ThemeConfig extends object>(
39
- site: SiteData<ThemeConfig>,
38
+ export function resolveSiteDataByPath(
39
+ site: SiteData,
40
40
  path: string,
41
- ): ResolvedSiteData<ThemeConfig> {
41
+ ): ResolvedSiteData {
42
42
  const localeIndex = getLocaleIndex(site, path)
43
43
  const locale = site.locales[localeIndex]
44
44
  const themeConfig = {
45
45
  ...(site.themeConfig ?? {}),
46
46
  ...(locale?.themeConfig ?? {}),
47
- } as ThemeConfig
47
+ }
48
48
 
49
49
  return {
50
50
  title: locale?.title ?? site.title,
@@ -60,8 +60,8 @@ export function resolveSiteDataByPath<ThemeConfig extends object>(
60
60
  }
61
61
  }
62
62
 
63
- export function resolveLocaleLink<ThemeConfig extends object>(
64
- site: SiteData<ThemeConfig>,
63
+ export function resolveLocaleLink(
64
+ site: SiteData,
65
65
  currentPath: string,
66
66
  targetLocale: string,
67
67
  ): string {
@@ -78,8 +78,8 @@ export function resolveLocaleLink<ThemeConfig extends object>(
78
78
  return `${withBase(targetPath, site.base)}${suffix}`
79
79
  }
80
80
 
81
- export function resolveLocaleLinks<ThemeConfig extends object>(
82
- site: SiteData<ThemeConfig>,
81
+ export function resolveLocaleLinks(
82
+ site: SiteData,
83
83
  currentPath: string,
84
84
  ): LocaleLink[] {
85
85
  return Object.entries(site.locales).map(([localeIndex, locale]) => ({
@@ -1,5 +1,5 @@
1
1
  import type { Component } from 'vue'
2
- import type { PageData } from './site'
2
+ import type { PageData } from './extension-points'
3
3
 
4
4
  /** A Markdown page compiled to a Vue component, with the page data it carries. */
5
5
  export interface PageModule {
package/src/core/site.ts CHANGED
@@ -1,42 +1,43 @@
1
+ import type { PageData, ThemeConfig } from './extension-points'
1
2
  import type { HeadConfig } from './head'
2
3
  import { assertJsonSerializable } from './json'
3
4
 
4
5
  export type LocaleDirection = 'ltr' | 'rtl'
5
6
 
6
- export interface LocaleConfig<ThemeConfig extends object = object> {
7
+ export interface LocaleConfig {
7
8
  label: string
8
9
  lang?: string
9
10
  dir?: LocaleDirection
10
11
  link?: string
11
12
  title?: string
12
13
  head?: HeadConfig[]
13
- themeConfig?: ThemeConfig
14
+ themeConfig?: Partial<ThemeConfig>
14
15
  }
15
16
 
16
- export interface SiteConfig<ThemeConfig extends object = object> {
17
+ export interface SiteConfig {
17
18
  title?: string
18
19
  base?: string
19
20
  srcDir?: string
20
21
  publicDir?: string
21
22
  head?: HeadConfig[]
22
- themeConfig?: ThemeConfig
23
- locales?: Record<string, LocaleConfig<ThemeConfig>>
23
+ themeConfig?: Partial<ThemeConfig>
24
+ locales?: Record<string, LocaleConfig>
24
25
  }
25
26
 
26
27
  /** Raw site data exposed to the client via virtual module. */
27
- export interface SiteData<ThemeConfig extends object = object> {
28
+ export interface SiteData {
28
29
  title: string
29
30
  base: string
30
31
  head: HeadConfig[]
31
- themeConfig?: ThemeConfig
32
- locales: Record<string, LocaleConfig<ThemeConfig>>
32
+ themeConfig?: Partial<ThemeConfig>
33
+ locales: Record<string, LocaleConfig>
33
34
  }
34
35
 
35
36
  /** Site data resolved for the current route and locale. */
36
- export interface ResolvedSiteData<ThemeConfig extends object = object> {
37
+ export interface ResolvedSiteData {
37
38
  title: string
38
39
  base: string
39
- themeConfig: ThemeConfig
40
+ themeConfig: Partial<ThemeConfig>
40
41
  localeIndex: string
41
42
  label?: string
42
43
  lang?: string
@@ -64,17 +65,6 @@ export interface PageHeader {
64
65
  children: PageHeader[]
65
66
  }
66
67
 
67
- export interface PageData {
68
- path: string
69
- title: string
70
- description?: string
71
- titleTemplate?: string | false
72
- /** `<head>` tags from frontmatter, rendered after site and locale tags. */
73
- head?: HeadConfig[]
74
- frontmatter: Record<string, unknown>
75
- headers: PageHeader[]
76
- }
77
-
78
68
  export function assertPageDataSerializable(pageData: PageData): void {
79
69
  const route = typeof pageData.path === 'string'
80
70
  ? JSON.stringify(pageData.path)
@@ -35,6 +35,17 @@ const CORE_RUNTIME_DEPENDENCIES = ['@unhead/vue', '@unhead/vue/client']
35
35
  */
36
36
  const VUE_DEPENDENCY = 'vue'
37
37
 
38
+ /**
39
+ * Oldest browsers the shipped CSS is written for: the first releases with
40
+ * `light-dark()` (Chrome and Edge 123, Firefox 120, Safari 17.5). Every token,
41
+ * plugin and theme colour is a `light-dark()` value, so the minifier must leave
42
+ * it as written. With an older target lightningcss rewrites `light-dark()` inside
43
+ * a custom property into helper variables that only exist on rules declaring
44
+ * `color-scheme`, and a theme that overrides a token without one silently loses
45
+ * the colour in production. JavaScript keeps Vite's default target.
46
+ */
47
+ export const CSS_TARGET = ['chrome123', 'edge123', 'firefox120', 'safari17.5', 'ios17.5']
48
+
38
49
  export interface CreateBaseViteConfigOptions {
39
50
  /** Reuse a page loader created by the caller, for example to read its link registry. */
40
51
  pageLoader?: MarkdownPageLoader
@@ -52,6 +63,9 @@ export function createBaseViteConfig(
52
63
  publicDir: resolve(root, siteConfig.srcDir, siteConfig.publicDir),
53
64
  clearScreen: false,
54
65
  appType: 'custom',
66
+ build: {
67
+ cssTarget: CSS_TARGET,
68
+ },
55
69
  ...createDefineOverrides(),
56
70
  resolve: {
57
71
  alias: resolveVueAliases(root),
package/src/index.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  export { defineConfig, definePreset } from './api/config'
2
- export type { KawapressConfig, KawapressPreset, PresetConfig } from './api/config'
2
+ export type { KawapressConfig, KawapressPreset } from './api/config'
3
3
  export { createContentLoader, defineLoader } from './api/data'
4
4
  export type {
5
5
  ContentData,
@@ -43,6 +43,7 @@ export type {
43
43
  PageLinks,
44
44
  ResolvedDeadLinkConfig,
45
45
  } from './core/dead-links'
46
+ export * from './core/extension-points'
46
47
  export { normalizeFrontmatterSource } from './core/frontmatter'
47
48
  export type { HeadAttrs, HeadConfig, HeadTag } from './core/head'
48
49
  export { resolveHeadingTitle } from './core/heading-title'
@@ -64,7 +65,6 @@ export type {
64
65
  LocaleConfig,
65
66
  LocaleDirection,
66
67
  LocaleLink,
67
- PageData,
68
68
  PageHeader,
69
69
  ResolvedSiteData,
70
70
  SiteConfig,
@@ -7,7 +7,8 @@ import type {
7
7
  PageBuildArtifact,
8
8
  PageDataContext,
9
9
  } from '../api/plugin'
10
- import type { PageData, SiteConfig } from '../core/site'
10
+ import type { PageData } from '../core/extension-points'
11
+ import type { SiteConfig } from '../core/site'
11
12
  import { assertPageDataSerializable } from '../core/site'
12
13
  import {
13
14
  createPluginHandlerRegistry,
@@ -17,7 +17,7 @@ export interface BuildNodeEnvChange {
17
17
  * Pins `env.NODE_ENV` to "production" and reports what that replaced.
18
18
  *
19
19
  * The value of `NODE_ENV` at build time is baked into every shipped chunk, because
20
- * Vite replaces `process.env.NODE_ENV` with the literal string and Vue, vue-router
20
+ * Vite replaces `process.env.NODE_ENV` with the literal string and Vue
21
21
  * and devtools branch on it. The build therefore has to own this variable before
22
22
  * anything resolves a Vite config: loading the site config goes through
23
23
  * `runnerImport()`, which resolves a serve-like config first and defaults