kawapress 0.1.0 → 0.2.0

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
@@ -126,7 +126,7 @@ KawaPress keeps extension boundaries explicit:
126
126
  - a **Runtime Plugin** extends the real Vue App and Vue Router in both SSR and the browser;
127
127
  - a **Preset** combines configuration and plugins into a ready-to-use experience such as nagi.
128
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).
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/plugins/plugin-system).
130
130
 
131
131
  ## Documentation
132
132
 
@@ -134,7 +134,8 @@ A logical plugin is installed once and can provide both generator and runtime be
134
134
  - [What is KawaPress?](https://shenqingchuan.github.io/kawapress/en/guide/what-is-kawapress)
135
135
  - [Markdown Extensions](https://shenqingchuan.github.io/kawapress/en/guide/markdown-extensions)
136
136
  - [Internationalization](https://shenqingchuan.github.io/kawapress/en/guide/internationalization)
137
- - [Plugin System](https://shenqingchuan.github.io/kawapress/en/guide/plugin-system)
137
+ - [Plugin System](https://shenqingchuan.github.io/kawapress/en/plugins/plugin-system)
138
+ - [Official Plugins](https://shenqingchuan.github.io/kawapress/en/plugins/overview)
138
139
  - [Theme Customization](https://shenqingchuan.github.io/kawapress/en/guide/theme-customization)
139
140
 
140
141
  ## Contributing
package/README.zh-CN.md CHANGED
@@ -126,7 +126,7 @@ KawaPress 把扩展边界分得很清楚:
126
126
  - **Runtime Plugin** 在 SSR 和浏览器中扩展真实的 Vue App 与 Vue Router;
127
127
  - **Preset** 把配置和一组插件组合成可以直接使用的产品体验,例如 nagi。
128
128
 
129
- 一个逻辑插件只需要安装一次,同时可以提供生成侧和运行侧能力。更多内容请查看[插件体系](https://shenqingchuan.github.io/kawapress/guide/plugin-system)。
129
+ 一个逻辑插件只需要安装一次,同时可以提供生成侧和运行侧能力。更多内容请查看[插件体系](https://shenqingchuan.github.io/kawapress/plugins/plugin-system)。
130
130
 
131
131
  ## 文档
132
132
 
@@ -134,7 +134,8 @@ KawaPress 把扩展边界分得很清楚:
134
134
  - [KawaPress 是什么?](https://shenqingchuan.github.io/kawapress/guide/what-is-kawapress)
135
135
  - [Markdown 语法扩展](https://shenqingchuan.github.io/kawapress/guide/markdown-extensions)
136
136
  - [国际化](https://shenqingchuan.github.io/kawapress/guide/internationalization)
137
- - [插件体系](https://shenqingchuan.github.io/kawapress/guide/plugin-system)
137
+ - [插件体系](https://shenqingchuan.github.io/kawapress/plugins/plugin-system)
138
+ - [官方插件总览](https://shenqingchuan.github.io/kawapress/plugins/overview)
138
139
  - [主题定制](https://shenqingchuan.github.io/kawapress/guide/theme-customization)
139
140
 
140
141
  ## 参与贡献
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "kawapress",
3
3
  "type": "module",
4
- "version": "0.1.0",
4
+ "version": "0.2.0",
5
5
  "description": "A Vue-centric static site generator",
6
6
  "license": "MIT",
7
7
  "homepage": "https://shenqingchuan.github.io/kawapress/",
@@ -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.0"
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