kawapress 0.2.1 → 0.3.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 +1 -1
- package/package.json +3 -2
- package/src/api/plugin.ts +4 -2
- package/src/client/components/KawaOutlet.vue +17 -12
- package/src/compiler/markdown.ts +9 -9
- package/src/core/outlet.ts +33 -11
- package/src/plugin/outlet-collector.ts +37 -22
- package/src/plugin/runtime-runner.ts +1 -1
- /package/{README.zh-CN.md → README-zh-CN.md} +0 -0
package/README.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
The KawaPress core: the CLI, the generator and the runtime, plus the nagi preset and its official plugins.
|
|
4
4
|
|
|
5
|
-
[](https://www.npmjs.com/package/kawapress) · [简体中文](https://github.com/kawapress/kawapress/blob/main/packages/kawapress/README
|
|
5
|
+
[](https://www.npmjs.com/package/kawapress) · [简体中文](https://github.com/kawapress/kawapress/blob/main/packages/kawapress/README-zh-CN.md)
|
|
6
6
|
|
|
7
7
|
`kawapress` is part of [KawaPress](https://github.com/kawapress/kawapress), a Vue-first static site generator.
|
|
8
8
|
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "kawapress",
|
|
3
3
|
"type": "module",
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "0.3.0",
|
|
5
5
|
"description": "A Vue-centric static site generator",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"homepage": "https://kawapress.dev/",
|
|
@@ -52,6 +52,7 @@
|
|
|
52
52
|
"kawapress": "./bin/kawapress.mjs"
|
|
53
53
|
},
|
|
54
54
|
"files": [
|
|
55
|
+
"README-zh-CN.md",
|
|
55
56
|
"bin",
|
|
56
57
|
"src/**/!(*.test.*)"
|
|
57
58
|
],
|
|
@@ -81,6 +82,6 @@
|
|
|
81
82
|
"tinyglobby": "^0.2.17",
|
|
82
83
|
"vite": "^8.2.2",
|
|
83
84
|
"vue": "^3.5.41",
|
|
84
|
-
"@kawapress/preset-nagi": "^0.
|
|
85
|
+
"@kawapress/preset-nagi": "^0.3.0"
|
|
85
86
|
}
|
|
86
87
|
}
|
package/src/api/plugin.ts
CHANGED
|
@@ -68,8 +68,10 @@ export function definePlugin(plugin: KawaPressPlugin): KawaPressPlugin {
|
|
|
68
68
|
export type RuntimePluginHandler<T> = (value: T) => MaybePromise<void>
|
|
69
69
|
|
|
70
70
|
export interface RuntimePluginAPI {
|
|
71
|
-
/** Places a component
|
|
72
|
-
|
|
71
|
+
/** Places a component before the theme's own content of an outlet. */
|
|
72
|
+
prependToOutlet: (outlet: OutletName, item: OutletItemInput) => void
|
|
73
|
+
/** Places a component after the theme's own content of an outlet. */
|
|
74
|
+
appendToOutlet: (outlet: OutletName, item: OutletItemInput) => void
|
|
73
75
|
vueApp: (handler: RuntimePluginHandler<App>) => void
|
|
74
76
|
router: (handler: RuntimePluginHandler<Router>) => void
|
|
75
77
|
}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
<script setup lang="ts">
|
|
2
|
-
import type {
|
|
2
|
+
import type { OutletName } from '../../core/outlet'
|
|
3
3
|
import { computed, onUnmounted } from 'vue'
|
|
4
|
-
import { assertOutletName,
|
|
4
|
+
import { assertOutletName, getOutletSlots } from '../../core/outlet'
|
|
5
5
|
import { recordRenderedOutlet, useOutletRegistry, useOutletRenderStore } from '../outlet'
|
|
6
6
|
|
|
7
7
|
const props = defineProps<{
|
|
@@ -9,14 +9,15 @@ const props = defineProps<{
|
|
|
9
9
|
}>()
|
|
10
10
|
|
|
11
11
|
defineSlots<{
|
|
12
|
-
/**
|
|
13
|
-
default?: (
|
|
12
|
+
/** The theme's own content. Plugin items render before and after it. */
|
|
13
|
+
default?: () => unknown
|
|
14
14
|
}>()
|
|
15
15
|
|
|
16
16
|
assertOutletName(props.name, '<KawaOutlet>')
|
|
17
17
|
|
|
18
18
|
const registry = useOutletRegistry('<KawaOutlet>')
|
|
19
|
-
|
|
19
|
+
// `slots` stays unset when the name check above throws; Vue still renders once after that.
|
|
20
|
+
const slots = computed(() => getOutletSlots(registry, props.name))
|
|
20
21
|
|
|
21
22
|
const renderStore = useOutletRenderStore()
|
|
22
23
|
renderStore?.mount(props.name)
|
|
@@ -26,11 +27,15 @@ recordRenderedOutlet(props.name)
|
|
|
26
27
|
</script>
|
|
27
28
|
|
|
28
29
|
<template>
|
|
29
|
-
<
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
30
|
+
<component
|
|
31
|
+
:is="item.component"
|
|
32
|
+
v-for="item in slots?.prepend"
|
|
33
|
+
:key="item.id"
|
|
34
|
+
/>
|
|
35
|
+
<slot />
|
|
36
|
+
<component
|
|
37
|
+
:is="item.component"
|
|
38
|
+
v-for="item in slots?.append"
|
|
39
|
+
:key="item.id"
|
|
40
|
+
/>
|
|
36
41
|
</template>
|
package/src/compiler/markdown.ts
CHANGED
|
@@ -37,8 +37,8 @@ interface MarkdownEnv extends PageComponentEnv {
|
|
|
37
37
|
sfcBlocks?: MarkdownSfcBlocks
|
|
38
38
|
/** Set by the LLMS plugin when it compiles Markdown for plain-text output. */
|
|
39
39
|
ssgMarkdown?: boolean
|
|
40
|
-
/** Set once the `doc.
|
|
41
|
-
|
|
40
|
+
/** Set once the `doc.under-title` outlet has been placed after the first H1. */
|
|
41
|
+
docUnderTitleOutletPlaced?: boolean
|
|
42
42
|
/** Page body after frontmatter removal, set by the frontmatter plugin. */
|
|
43
43
|
content?: string
|
|
44
44
|
/** Internal links of the page, with line numbers relative to the source file. */
|
|
@@ -86,7 +86,7 @@ export async function createMarkdownCompiler(options: MarkdownCompilerOptions =
|
|
|
86
86
|
installHeadingTitles(md)
|
|
87
87
|
installPageLinkCollector(md)
|
|
88
88
|
installLinkRenderer(md, options.base ?? '/')
|
|
89
|
-
|
|
89
|
+
installDocUnderTitleOutlet(md)
|
|
90
90
|
|
|
91
91
|
await options.pluginRunner?.runMarkdown(md)
|
|
92
92
|
return md
|
|
@@ -169,14 +169,14 @@ function installAsyncSfcRenderCompatibility(md: MarkdownExit): void {
|
|
|
169
169
|
}
|
|
170
170
|
}
|
|
171
171
|
|
|
172
|
-
const
|
|
172
|
+
const DOC_UNDER_TITLE_OUTLET = '<KawaOutlet name="doc.under-title" />'
|
|
173
173
|
|
|
174
174
|
/**
|
|
175
|
-
* Renders the `doc.
|
|
175
|
+
* Renders the `doc.under-title` outlet right after the first H1 of every page, so
|
|
176
176
|
* plugins can place interface pieces inside the Markdown body without the
|
|
177
177
|
* theme reaching into compiled content. Pages without an H1 get no outlet.
|
|
178
178
|
*/
|
|
179
|
-
function
|
|
179
|
+
function installDocUnderTitleOutlet(md: MarkdownExit): void {
|
|
180
180
|
const original = md.renderer.rules.heading_close
|
|
181
181
|
|
|
182
182
|
md.renderer.rules.heading_close = (tokens, index, options, env, renderer) => {
|
|
@@ -190,13 +190,13 @@ function installDocHeaderOutlet(md: MarkdownExit): void {
|
|
|
190
190
|
|| typeof env !== 'object'
|
|
191
191
|
|| env === null
|
|
192
192
|
|| renderEnv.ssgMarkdown
|
|
193
|
-
|| renderEnv.
|
|
193
|
+
|| renderEnv.docUnderTitleOutletPlaced
|
|
194
194
|
) {
|
|
195
195
|
return rendered
|
|
196
196
|
}
|
|
197
197
|
|
|
198
|
-
renderEnv.
|
|
199
|
-
return `${rendered}\n${
|
|
198
|
+
renderEnv.docUnderTitleOutletPlaced = true
|
|
199
|
+
return `${rendered}\n${DOC_UNDER_TITLE_OUTLET}\n`
|
|
200
200
|
}
|
|
201
201
|
}
|
|
202
202
|
|
package/src/core/outlet.ts
CHANGED
|
@@ -2,18 +2,26 @@ import type { Component } from 'vue'
|
|
|
2
2
|
|
|
3
3
|
/**
|
|
4
4
|
* Every outlet a theme can render. The list is the public contract between
|
|
5
|
-
* plugins (which
|
|
5
|
+
* plugins (which contribute interface pieces) and themes (which draw the
|
|
6
|
+
* default content of each outlet).
|
|
7
|
+
*
|
|
8
|
+
* A name is a scope plus a role: `layout` is the page frame, `doc` is the page
|
|
9
|
+
* being read. `start` and `end` follow the reading direction.
|
|
6
10
|
*/
|
|
7
11
|
export const OUTLET_NAMES = [
|
|
8
|
-
'header
|
|
9
|
-
'
|
|
10
|
-
'
|
|
11
|
-
'
|
|
12
|
+
'layout.header',
|
|
13
|
+
'layout.header.start',
|
|
14
|
+
'layout.header.end',
|
|
15
|
+
'layout.sidebar',
|
|
16
|
+
'layout.footer',
|
|
17
|
+
'doc',
|
|
18
|
+
'doc.under-title',
|
|
19
|
+
'doc.toc',
|
|
12
20
|
] as const
|
|
13
21
|
|
|
14
22
|
export type OutletName = typeof OUTLET_NAMES[number]
|
|
15
23
|
|
|
16
|
-
/** What a plugin passes to `api.
|
|
24
|
+
/** What a plugin passes to `api.prependToOutlet()` or `api.appendToOutlet()`. */
|
|
17
25
|
export interface OutletItemInput {
|
|
18
26
|
id: string
|
|
19
27
|
component: Component
|
|
@@ -27,10 +35,14 @@ export interface OutletItem extends OutletItemInput {
|
|
|
27
35
|
owner: string
|
|
28
36
|
}
|
|
29
37
|
|
|
30
|
-
/**
|
|
31
|
-
export
|
|
32
|
-
|
|
33
|
-
|
|
38
|
+
/** Items of one outlet: `prepend` renders before the theme content, `append` after it. */
|
|
39
|
+
export interface OutletSlots {
|
|
40
|
+
readonly prepend: readonly OutletItem[]
|
|
41
|
+
readonly append: readonly OutletItem[]
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/** Outlet items grouped by outlet name. Each side is in plugin install order. */
|
|
45
|
+
export type OutletRegistry = Readonly<Record<OutletName, OutletSlots>>
|
|
34
46
|
|
|
35
47
|
export function isOutletName(value: unknown): value is OutletName {
|
|
36
48
|
return typeof value === 'string'
|
|
@@ -50,11 +62,21 @@ export function assertOutletName(
|
|
|
50
62
|
)
|
|
51
63
|
}
|
|
52
64
|
|
|
65
|
+
const EMPTY_SLOTS: OutletSlots = Object.freeze({ prepend: [], append: [] })
|
|
66
|
+
|
|
67
|
+
export function getOutletSlots(
|
|
68
|
+
registry: OutletRegistry,
|
|
69
|
+
outlet: OutletName,
|
|
70
|
+
): OutletSlots {
|
|
71
|
+
return registry[outlet] ?? EMPTY_SLOTS
|
|
72
|
+
}
|
|
73
|
+
|
|
53
74
|
export function getOutletItems(
|
|
54
75
|
registry: OutletRegistry,
|
|
55
76
|
outlet: OutletName,
|
|
56
77
|
): readonly OutletItem[] {
|
|
57
|
-
|
|
78
|
+
const { prepend, append } = getOutletSlots(registry, outlet)
|
|
79
|
+
return [...prepend, ...append]
|
|
58
80
|
}
|
|
59
81
|
|
|
60
82
|
/** One registered item that no page ever rendered. */
|
|
@@ -6,31 +6,46 @@ import type {
|
|
|
6
6
|
} from '../core/outlet'
|
|
7
7
|
import { assertOutletName, OUTLET_NAMES } from '../core/outlet'
|
|
8
8
|
|
|
9
|
+
type OutletSide = 'prepend' | 'append'
|
|
10
|
+
type OutletAdder = (outlet: OutletName, item: OutletItemInput) => void
|
|
11
|
+
|
|
9
12
|
export interface OutletCollector {
|
|
10
13
|
/**
|
|
11
|
-
*
|
|
12
|
-
* caller so a plugin cannot claim items that belong to another plugin.
|
|
14
|
+
* The two registration functions of one plugin. The plugin name is bound once
|
|
15
|
+
* by the caller so a plugin cannot claim items that belong to another plugin.
|
|
13
16
|
*/
|
|
14
|
-
|
|
17
|
+
forPlugin: (pluginName: string) => {
|
|
18
|
+
prependToOutlet: OutletAdder
|
|
19
|
+
appendToOutlet: OutletAdder
|
|
20
|
+
}
|
|
15
21
|
/** Freezes the collected items into the registry handed to the Vue app. */
|
|
16
22
|
createRegistry: () => OutletRegistry
|
|
17
23
|
}
|
|
18
24
|
|
|
19
25
|
export function createOutletCollector(): OutletCollector {
|
|
20
|
-
const
|
|
26
|
+
const sides: Record<OutletSide, Map<OutletName, OutletItem[]>> = {
|
|
27
|
+
prepend: new Map(),
|
|
28
|
+
append: new Map(),
|
|
29
|
+
}
|
|
21
30
|
const outletsById = new Map<string, OutletName>()
|
|
22
31
|
|
|
23
|
-
function add(
|
|
32
|
+
function add(
|
|
33
|
+
side: OutletSide,
|
|
34
|
+
pluginName: string,
|
|
35
|
+
outlet: OutletName,
|
|
36
|
+
item: OutletItemInput,
|
|
37
|
+
): void {
|
|
38
|
+
const method = `${side}ToOutlet`
|
|
24
39
|
assertOutletName(
|
|
25
40
|
outlet,
|
|
26
|
-
`plugin ${JSON.stringify(pluginName)} calling api
|
|
41
|
+
`plugin ${JSON.stringify(pluginName)} calling api.${method}()`,
|
|
27
42
|
)
|
|
28
43
|
|
|
29
44
|
const localId = item?.id
|
|
30
45
|
if (typeof localId !== 'string' || localId.trim() === '') {
|
|
31
46
|
throw new Error(
|
|
32
|
-
`[${pluginName} / runtime /
|
|
33
|
-
+ `must be a non-empty string. Pass { id: 'my-item', component } to api
|
|
47
|
+
`[${pluginName} / runtime / ${method}] Item id for outlet ${JSON.stringify(outlet)} `
|
|
48
|
+
+ `must be a non-empty string. Pass { id: 'my-item', component } to api.${method}().`,
|
|
34
49
|
)
|
|
35
50
|
}
|
|
36
51
|
|
|
@@ -38,30 +53,30 @@ export function createOutletCollector(): OutletCollector {
|
|
|
38
53
|
const existingOutlet = outletsById.get(id)
|
|
39
54
|
if (existingOutlet) {
|
|
40
55
|
throw new Error(
|
|
41
|
-
`[${pluginName} / runtime /
|
|
56
|
+
`[${pluginName} / runtime / ${method}] Duplicate item id ${JSON.stringify(id)} `
|
|
42
57
|
+ `(already used for outlet ${JSON.stringify(existingOutlet)}). `
|
|
43
|
-
+ `Item ids must be unique per plugin; rename one of the
|
|
58
|
+
+ `Item ids must be unique per plugin; rename one of the outlet calls.`,
|
|
44
59
|
)
|
|
45
60
|
}
|
|
46
61
|
|
|
47
62
|
outletsById.set(id, outlet)
|
|
48
|
-
const items =
|
|
49
|
-
items.push({
|
|
50
|
-
|
|
51
|
-
owner: pluginName,
|
|
52
|
-
component: item.component,
|
|
53
|
-
})
|
|
54
|
-
itemsByOutlet.set(outlet, items)
|
|
63
|
+
const items = sides[side].get(outlet) ?? []
|
|
64
|
+
items.push({ id, owner: pluginName, component: item.component })
|
|
65
|
+
sides[side].set(outlet, items)
|
|
55
66
|
}
|
|
56
67
|
|
|
57
68
|
return {
|
|
58
|
-
|
|
59
|
-
add(pluginName, outlet, item)
|
|
60
|
-
|
|
69
|
+
forPlugin: pluginName => ({
|
|
70
|
+
prependToOutlet: (outlet, item) => add('prepend', pluginName, outlet, item),
|
|
71
|
+
appendToOutlet: (outlet, item) => add('append', pluginName, outlet, item),
|
|
72
|
+
}),
|
|
61
73
|
createRegistry() {
|
|
62
|
-
const registry = {} as Record<OutletName,
|
|
74
|
+
const registry = {} as Record<OutletName, OutletRegistry[OutletName]>
|
|
63
75
|
for (const name of OUTLET_NAMES) {
|
|
64
|
-
registry[name] = Object.freeze(
|
|
76
|
+
registry[name] = Object.freeze({
|
|
77
|
+
prepend: Object.freeze([...(sides.prepend.get(name) ?? [])]),
|
|
78
|
+
append: Object.freeze([...(sides.append.get(name) ?? [])]),
|
|
79
|
+
})
|
|
65
80
|
}
|
|
66
81
|
return Object.freeze(registry)
|
|
67
82
|
},
|
|
@@ -26,7 +26,7 @@ export async function createRuntimePluginRunner(
|
|
|
26
26
|
|
|
27
27
|
for (const plugin of plugins) {
|
|
28
28
|
const api: RuntimePluginAPI = {
|
|
29
|
-
|
|
29
|
+
...outletCollector.forPlugin(plugin.name),
|
|
30
30
|
vueApp: handler => vueAppHandlers.add(plugin.name, handler),
|
|
31
31
|
router: handler => routerHandlers.add(plugin.name, handler),
|
|
32
32
|
}
|
|
File without changes
|