@frontfactory/vitepress-theme 1.8.0 → 1.10.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/CHANGELOG.md +39 -0
- package/README.md +11 -391
- package/config.d.ts +4 -3
- package/config.js +58 -40
- package/dist/style.css +1 -1
- package/node/banner.d.ts +3 -0
- package/node/banner.js +14 -0
- package/node/blog.d.ts +11 -0
- package/node/blog.js +63 -0
- package/node/llms.js +4 -3
- package/node/og.js +5 -6
- package/node/options.d.ts +1 -0
- package/node/options.js +17 -0
- package/node/page-actions.d.ts +12 -0
- package/node/page-actions.js +34 -0
- package/node/pages.js +34 -14
- package/node/rss.js +13 -21
- package/package.json +1 -1
- package/src/blog/posts.data.ts +7 -4
- package/src/components/FfBackToTop.vue +6 -36
- package/src/components/FfBanner.vue +3 -2
- package/src/components/FfCopyStatus.vue +6 -14
- package/src/components/FfDocMeta.vue +299 -24
- package/src/components/FfFeedback.vue +4 -9
- package/src/components/FfHero.vue +14 -33
- package/src/components/FfHeroActions.vue +44 -0
- package/src/components/FfHeroCommand.vue +3 -2
- package/src/components/FfPost.vue +6 -4
- package/src/components/FfProgress.vue +6 -40
- package/src/composables/blog.ts +8 -11
- package/src/composables/copy.ts +29 -0
- package/src/composables/frame.ts +50 -0
- package/src/composables/options.ts +9 -1
- package/src/composables/tabs.ts +2 -35
- package/src/composables/transient.ts +27 -0
- package/src/content/Tabs.vue +27 -6
- package/src/internal.ts +1 -0
- package/src/layout/FfLayout.vue +3 -3
- package/src/styles/_base.scss +5 -9
- package/src/styles/_blocks.scss +4 -7
- package/src/styles/_blog.scss +4 -5
- package/src/styles/_code.scss +12 -20
- package/src/styles/_content.scss +153 -63
- package/src/styles/_doc.scss +26 -25
- package/src/styles/_home.scss +31 -61
- package/src/styles/_mixins.scss +87 -0
- package/src/styles/_motion.scss +12 -10
- package/src/styles/_nav.scss +12 -19
- package/src/styles/_sidebar.scss +5 -8
- package/src/styles/_tokens.scss +19 -4
- package/src/types.ts +31 -4
- package/types/components/FfHeroActions.vue.d.ts +19 -0
- package/types/composables/blog.d.ts +3 -4
- package/types/composables/copy.d.ts +6 -0
- package/types/composables/frame.d.ts +6 -0
- package/types/composables/tabs.d.ts +0 -5
- package/types/composables/transient.d.ts +6 -0
- package/types/internal.d.ts +1 -0
- package/types/types.d.ts +29 -4
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,45 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to this project will be documented in this file. See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
|
|
4
4
|
|
|
5
|
+
## [1.10.0](https://github.com/front-factory/vitepress-theme/compare/v1.9.0...v1.10.0) (2026-11-17)
|
|
6
|
+
|
|
7
|
+
### Features
|
|
8
|
+
|
|
9
|
+
* **page-actions:** show copy link by default ([459a121](https://github.com/front-factory/vitepress-theme/commit/459a1215e3317a9c2f2645db7c83b4808b5077f7))
|
|
10
|
+
|
|
11
|
+
### Bug Fixes
|
|
12
|
+
|
|
13
|
+
* **doc:** align last updated stamp with the edit link ([ae0a5a9](https://github.com/front-factory/vitepress-theme/commit/ae0a5a9594cd7c4238193ba535d0d128f886f8f2))
|
|
14
|
+
* **home:** space the hero colophon from the image on mobile ([436fb84](https://github.com/front-factory/vitepress-theme/commit/436fb84c319b90a564fd17441a2ce5cf693c74ce))
|
|
15
|
+
|
|
16
|
+
## [1.9.0](https://github.com/front-factory/vitepress-theme/compare/v1.8.0...v1.9.0) (2026-11-15)
|
|
17
|
+
|
|
18
|
+
### Features
|
|
19
|
+
|
|
20
|
+
* **doc-meta:** turn copy as Markdown into a page actions menu ([2e32e53](https://github.com/front-factory/vitepress-theme/commit/2e32e534330d6de309cacfc27ff10e6cf85dc6b5))
|
|
21
|
+
* **i18n:** add returnToTop and codeCopied labels ([0d9f925](https://github.com/front-factory/vitepress-theme/commit/0d9f925d6370c1b855f27626f8d5f0539d0cb2a2))
|
|
22
|
+
|
|
23
|
+
### Bug Fixes
|
|
24
|
+
|
|
25
|
+
* **a11y:** stop focus from reshaping elements ([382ce06](https://github.com/front-factory/vitepress-theme/commit/382ce062730c9ceeabe60246fb8da5afe6e9a506))
|
|
26
|
+
* **blog:** ignore posts with an unparsable date ([3211660](https://github.com/front-factory/vitepress-theme/commit/321166074e777ce994845f4cffe6da17db07e7c0))
|
|
27
|
+
* **blog:** resolve author avatar and link against the base ([511647e](https://github.com/front-factory/vitepress-theme/commit/511647eaf6a3ddd3801dd6bc10d9f6ca7bb333f9))
|
|
28
|
+
* **blog:** skip the post header on the blog index ([fc594ff](https://github.com/front-factory/vitepress-theme/commit/fc594ff7b26352c7ad5c534ee4696991384ad90f))
|
|
29
|
+
* **hero:** open external actions in a new tab ([da62b11](https://github.com/front-factory/vitepress-theme/commit/da62b11630428aa0cfb5a537ef7c188695cafd05))
|
|
30
|
+
* **layout:** read forwarded slots on each render ([0937b2c](https://github.com/front-factory/vitepress-theme/commit/0937b2cfbe338f62be5b6ee3cdd3d37a2a8db4ec))
|
|
31
|
+
* **motion:** keep pager title on the slow transition ([b275606](https://github.com/front-factory/vitepress-theme/commit/b2756067413e60abac433b31dc00b9257c27c1ed))
|
|
32
|
+
* **motion:** transition the feedback button hover ([8e851f6](https://github.com/front-factory/vitepress-theme/commit/8e851f62bbad9d3994a74748bdce31591484f9ea))
|
|
33
|
+
* **og:** name images after the rewritten page path ([9de4a0e](https://github.com/front-factory/vitepress-theme/commit/9de4a0eb860c2cd090ed89797815cf6095f6cfaa))
|
|
34
|
+
* **og:** omit image tags for pages without a source file ([20d80b6](https://github.com/front-factory/vitepress-theme/commit/20d80b69e41be764e49b73bad726555f13f26c2b))
|
|
35
|
+
* **tabs:** key tab buttons by index ([7d25828](https://github.com/front-factory/vitepress-theme/commit/7d2582870e22b8e77e15ab179ffad595dff3e61a))
|
|
36
|
+
* **tabs:** reset the selection only when the labels change ([d688e50](https://github.com/front-factory/vitepress-theme/commit/d688e505ef81ae39d6ce16bed4eac107e63406b2))
|
|
37
|
+
* **types:** type ffTransformHead with the theme config ([963a48a](https://github.com/front-factory/vitepress-theme/commit/963a48a0add5e911f90bfa73280d8f0eea403789))
|
|
38
|
+
|
|
39
|
+
### Performance
|
|
40
|
+
|
|
41
|
+
* **build:** read and parse pages once for all generators ([0a3220c](https://github.com/front-factory/vitepress-theme/commit/0a3220c9a68e69ccbd6d213377b70c5eebb28e43))
|
|
42
|
+
* **tabs:** read the slot once per render in the template ([054b33d](https://github.com/front-factory/vitepress-theme/commit/054b33dc8a9567b85d30a7abacb95874f5437c78))
|
|
43
|
+
|
|
5
44
|
## [1.8.0](https://github.com/front-factory/vitepress-theme/compare/v1.7.0...v1.8.0) (2026-11-04)
|
|
6
45
|
|
|
7
46
|
### Features
|
package/README.md
CHANGED
|
@@ -16,6 +16,8 @@ Try it live on StackBlitz — no installation required:
|
|
|
16
16
|
|
|
17
17
|
[](https://stackblitz.com/~/github.com/front-factory/vitepress-theme?startScript=dev:playground)
|
|
18
18
|
|
|
19
|
+
Or run it locally with `npm run dev:playground`.
|
|
20
|
+
|
|
19
21
|
## Install
|
|
20
22
|
|
|
21
23
|
```bash
|
|
@@ -48,400 +50,18 @@ import Theme from '@frontfactory/vitepress-theme'
|
|
|
48
50
|
export default Theme
|
|
49
51
|
```
|
|
50
52
|
|
|
51
|
-
`extends: baseConfig` is required: it swaps the components the theme replaces
|
|
52
|
-
|
|
53
|
-
painting in the built site, and reads each page's source for the copy-as-Markdown button.
|
|
54
|
-
|
|
55
|
-
The package ships its Vue and TypeScript sources as-is (`main`, `module` and `types` point at
|
|
56
|
-
`src/index.ts`) and relies on Vite to compile them, which `extends: baseConfig` sets up. Tooling that
|
|
57
|
-
type-checks outside Vite, such as `vue-tsc`, may need `skipLibCheck`. Importing
|
|
58
|
-
`@frontfactory/vitepress-theme/config` from `.vitepress/config.ts`, as above, also makes
|
|
59
|
-
`themeConfig.ff` known to TypeScript. `@frontfactory/vitepress-theme/style.css` is exported for
|
|
60
|
-
tooling that needs the stylesheet on its own; the theme entry already imports it.
|
|
61
|
-
|
|
62
|
-
## Rebranding
|
|
63
|
-
|
|
64
|
-
Every value is a `--ff-*` custom property. Point the accent at your own colour and the whole site
|
|
65
|
-
follows. For a ready-made accent instead, set `themeConfig.ff.preset` (see [Options](#options)).
|
|
66
|
-
|
|
67
|
-
```css
|
|
68
|
-
/* .vitepress/theme/custom.css, imported after the theme */
|
|
69
|
-
:root {
|
|
70
|
-
--ff-color-accent: #0071d7;
|
|
71
|
-
--ff-color-accent-hover: #0058a8;
|
|
72
|
-
--ff-color-accent-soft: rgb(0 113 215 / 9%);
|
|
73
|
-
}
|
|
74
|
-
|
|
75
|
-
.dark {
|
|
76
|
-
--ff-color-accent: #58baff;
|
|
77
|
-
--ff-color-accent-hover: #8ed0ff;
|
|
78
|
-
--ff-color-accent-contrast: #06121e;
|
|
79
|
-
}
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
| Token | Role |
|
|
83
|
-
|-----------------------------------------------|-----------------------------------------|
|
|
84
|
-
| `--ff-color-paper` | Page background |
|
|
85
|
-
| `--ff-color-surface` | Raised surfaces: code, cards, keys |
|
|
86
|
-
| `--ff-color-surface-alt` | Inline code, switches |
|
|
87
|
-
| `--ff-color-ink` | Body text |
|
|
88
|
-
| `--ff-color-ink-muted` | Secondary text |
|
|
89
|
-
| `--ff-color-ink-faint` | Labels and metadata |
|
|
90
|
-
| `--ff-color-rule` | Hairlines |
|
|
91
|
-
| `--ff-color-rule-strong` | Emphasised rules and borders |
|
|
92
|
-
| `--ff-color-accent` | The one brand colour |
|
|
93
|
-
| `--ff-color-success` / `-warning` / `-danger` | Status colours |
|
|
94
|
-
| `--ff-font-display` | Headings, titles, card and pager titles |
|
|
95
|
-
| `--ff-font-mono` | Labels, metadata, code |
|
|
96
|
-
| `--ff-size-hero` / `-h1` / `-h2` / `-h3` | Type scale |
|
|
97
|
-
| `--ff-layout-content` | Reading measure |
|
|
98
|
-
| `--ff-layout-wide` | Home and container width |
|
|
99
|
-
| `--ff-radius-sm` / `-md` | Corner radii |
|
|
100
|
-
| `--ff-rule-width` / `--ff-rule-accent-width` | Rule weights |
|
|
101
|
-
| `--ff-hero-glow-opacity` | Hero light washes, `0` (off) by default |
|
|
102
|
-
| `--ff-motion-duration` / `-slow` / `-enter` | Hover, slow and hero entrance timings |
|
|
103
|
-
| `--ff-motion-ease` | Easing shared by every transition |
|
|
104
|
-
|
|
105
|
-
`dist/style.css` lists them all, grouped, at the top of the file.
|
|
106
|
-
|
|
107
|
-
## Options
|
|
108
|
-
|
|
109
|
-
Theme options live under `themeConfig.ff`.
|
|
110
|
-
|
|
111
|
-
```ts
|
|
112
|
-
themeConfig: {
|
|
113
|
-
ff: {
|
|
114
|
-
// Dismissible bar above the navigation. Change the id to bring it back.
|
|
115
|
-
banner: {
|
|
116
|
-
id: 'v5',
|
|
117
|
-
text: 'Version 5 is out.',
|
|
118
|
-
link: '/whats-new',
|
|
119
|
-
linkText: 'Read the notes',
|
|
120
|
-
variant: 'accent', // 'ink' (default) | 'accent' | 'success' | 'warning' | 'danger' | 'rainbow'
|
|
121
|
-
gradient: true, // fade toward the variant's second shade; ignored by rainbow, always a gradient
|
|
122
|
-
icon: '🎉'
|
|
123
|
-
},
|
|
124
|
-
|
|
125
|
-
// Order of the search box and the nav menu links in the top bar. 'search-first' is the
|
|
126
|
-
// default theme's own order; 'menu-first' pins the menu against the title instead. No
|
|
127
|
-
// effect on the mobile bar, which always falls back to the hamburger.
|
|
128
|
-
navOrder: 'search-first',
|
|
129
|
-
|
|
130
|
-
// Pins the top bar while scrolling. Set to false to have the bar, and the banner above
|
|
131
|
-
// it, scroll away with the page.
|
|
132
|
-
navSticky: true,
|
|
133
|
-
|
|
134
|
-
// Ready-made accent for both schemes instead of the default indigo:
|
|
135
|
-
// 'emerald' | 'crimson' | 'violet' | 'amber'. Set on <html> before the first paint.
|
|
136
|
-
preset: 'emerald',
|
|
137
|
-
|
|
138
|
-
// Kicker printed above every page title. Set to false to drop it.
|
|
139
|
-
meta: {
|
|
140
|
-
section: true, // section name, read from the sidebar
|
|
141
|
-
readingTime: true,
|
|
142
|
-
wordsPerMinute: 200,
|
|
143
|
-
lastUpdated: true // needs `lastUpdated: true` in the site config
|
|
144
|
-
},
|
|
145
|
-
|
|
146
|
-
// Link columns in the site footer (home and page layouts).
|
|
147
|
-
footerColumns: [
|
|
148
|
-
{ title: 'Docs', items: [{ text: 'Guide', link: '/guide/' }] }
|
|
149
|
-
],
|
|
150
|
-
|
|
151
|
-
// Column of `themeConfig.socialLinks` icons, pinned to the right of those columns.
|
|
152
|
-
footerSocial: true,
|
|
153
|
-
|
|
154
|
-
backToTop: true,
|
|
155
|
-
|
|
156
|
-
// Thin reading-progress bar at the very top of the viewport. Off by default.
|
|
157
|
-
progress: true,
|
|
158
|
-
|
|
159
|
-
// "Was this page helpful?" widget under each doc page. `true`, or an object: `url` receives
|
|
160
|
-
// each vote through `navigator.sendBeacon`, `question` replaces the label. Every vote is
|
|
161
|
-
// also dispatched on `window` as an `ff:feedback` event.
|
|
162
|
-
feedback: { url: 'https://example.com/feedback' },
|
|
163
|
-
|
|
164
|
-
// "Copy as Markdown" button in the page kicker. Needs `ffTransformPageData`, see below.
|
|
165
|
-
copyMarkdown: true,
|
|
166
|
-
|
|
167
|
-
// Writes llms.txt and llms-full.txt at the end of the build. Needs `ffBuildEnd`, see below.
|
|
168
|
-
llms: true,
|
|
169
|
-
|
|
170
|
-
// Blog: `layout: blog` on the index page, a dated header on each post, an RSS feed.
|
|
171
|
-
blog: {
|
|
172
|
-
dir: 'blog', // default
|
|
173
|
-
authors: { ada: { name: 'Ada Lovelace', link: 'https://example.com/ada' } },
|
|
174
|
-
rss: { hostname: 'https://example.com' } // or true with `sitemap.hostname`
|
|
175
|
-
},
|
|
176
|
-
|
|
177
|
-
// Open Graph image per page (needs fonts) plus the og:* and twitter:card tags.
|
|
178
|
-
og: {
|
|
179
|
-
hostname: 'https://example.com', // else `sitemap.hostname`
|
|
180
|
-
fonts: [{ name: 'JetBrains Mono', path: 'fonts/JetBrainsMono-Bold.ttf', weight: 700 }]
|
|
181
|
-
},
|
|
182
|
-
|
|
183
|
-
// Version menu beside the site name; each item links to that version's docs.
|
|
184
|
-
versions: {
|
|
185
|
-
current: 'v2',
|
|
186
|
-
items: [{ text: 'v1', link: 'https://v1.example.com' }]
|
|
187
|
-
}
|
|
188
|
-
}
|
|
189
|
-
}
|
|
190
|
-
```
|
|
191
|
-
|
|
192
|
-
Per page, `docMeta: false` in the frontmatter drops the kicker, `section: Guide` overrides the
|
|
193
|
-
section name, `progress: false` hides the progress bar, `feedback: false` hides the feedback widget, and `wide: true` widens the text column to the full
|
|
194
|
-
band and hides the outline (wide tables, API listings).
|
|
195
|
-
|
|
196
|
-
A vote is sent as the JSON string `{ page, value, lang }` (`value` is `'yes'` or `'no'`, `page` the
|
|
197
|
-
source path), and also fires `ff:feedback` on `window` with that object in `detail`, so a site can
|
|
198
|
-
forward it to its own analytics:
|
|
199
|
-
|
|
200
|
-
```ts
|
|
201
|
-
window.addEventListener('ff:feedback', (event) => console.log(event.detail))
|
|
202
|
-
```
|
|
203
|
-
|
|
204
|
-
Banner text, hero title/tagline/quote, feature title/details, footer message/copyright and card icon
|
|
205
|
-
all render as HTML (`v-html`), not escaped text — a `<strong>` or a hand-written `<a>` in any of them
|
|
206
|
-
shows up as markup. The trust boundary is the config file itself: these strings are meant to come
|
|
207
|
-
from whoever writes `themeConfig.ff` in the VitePress config, not from a reader, a comment, or a CMS
|
|
208
|
-
field someone else can edit. If a site ever pipes such input into these fields, sanitize it before it
|
|
209
|
-
reaches the config — the theme does not.
|
|
210
|
-
|
|
211
|
-
### Copy as Markdown
|
|
212
|
-
|
|
213
|
-
`copyMarkdown` puts a button in the kicker that copies the page's Markdown source, frontmatter
|
|
214
|
-
removed. The source is read at build time by `ffTransformPageData`, which `extends: baseConfig`
|
|
215
|
-
already wires in. VitePress replaces a hook declared by the site instead of merging it, so a site
|
|
216
|
-
with its own `transformPageData` calls the helper from it and returns the result:
|
|
217
|
-
|
|
218
|
-
```ts
|
|
219
|
-
import baseConfig, { ffTransformPageData } from '@frontfactory/vitepress-theme/config'
|
|
220
|
-
|
|
221
|
-
export default defineConfig({
|
|
222
|
-
extends: baseConfig,
|
|
223
|
-
transformPageData(pageData, ctx) {
|
|
224
|
-
// ...your own changes to pageData...
|
|
225
|
-
|
|
226
|
-
return ffTransformPageData(pageData, ctx)
|
|
227
|
-
}
|
|
228
|
-
})
|
|
229
|
-
```
|
|
230
|
-
|
|
231
|
-
Without the option the helper does nothing, so no source text reaches the bundle.
|
|
232
|
-
|
|
233
|
-
### llms.txt
|
|
234
|
-
|
|
235
|
-
`llms: true` writes `llms.txt` (an index of the pages) and `llms-full.txt` (their Markdown) to the
|
|
236
|
-
output directory. Links are absolute when `sitemap.hostname` is set. `404.md` and pages with
|
|
237
|
-
`llms: false` in their frontmatter are skipped.
|
|
238
|
-
|
|
239
|
-
The files come from `ffBuildEnd`, wired in by `extends: baseConfig`. A site with its own `buildEnd`
|
|
240
|
-
(or `transformHead`) calls the helper from it, as for `ffTransformPageData`:
|
|
241
|
-
|
|
242
|
-
```ts
|
|
243
|
-
import baseConfig, { ffBuildEnd } from '@frontfactory/vitepress-theme/config'
|
|
244
|
-
|
|
245
|
-
export default defineConfig({
|
|
246
|
-
extends: baseConfig,
|
|
247
|
-
async buildEnd(siteConfig) {
|
|
248
|
-
await ffBuildEnd(siteConfig)
|
|
249
|
-
}
|
|
250
|
-
})
|
|
251
|
-
```
|
|
252
|
-
|
|
253
|
-
### Blog
|
|
254
|
-
|
|
255
|
-
Posts are Markdown pages under `blog.dir` (default `blog`) with a `date`. The index page, `blog/index.md`,
|
|
256
|
-
uses `layout: blog` and lists them newest first; each post gets a header with its date, author and tags.
|
|
257
|
-
|
|
258
|
-
```md
|
|
259
|
-
---
|
|
260
|
-
title: Hello, editorial
|
|
261
|
-
date: 2026-10-12
|
|
262
|
-
author: ada # a key of blog.authors, or a plain name
|
|
263
|
-
tags: [theme, design]
|
|
264
|
-
excerpt: Shown in the list and in the feed.
|
|
265
|
-
---
|
|
266
|
-
```
|
|
267
|
-
|
|
268
|
-
`rss` writes `feed.xml` at the end of the build (through `ffBuildEnd`) and adds the
|
|
269
|
-
`<link rel="alternate">` tag through `ffTransformHead`. It needs the optional peer dependency
|
|
270
|
-
`feed` (`npm install feed`) and an absolute address: `rss.hostname`, else `sitemap.hostname`.
|
|
271
|
-
|
|
272
|
-
### Open Graph images
|
|
273
|
-
|
|
274
|
-
`og` draws a 1200x630 PNG for each page into `og/` at the end of the build, and adds `og:image`,
|
|
275
|
-
`og:title`, `og:description` and `twitter:card: summary_large_image` to the page head
|
|
276
|
-
(`ffBuildEnd` and `ffTransformHead`). A page opts out with `og: false` in its frontmatter.
|
|
277
|
-
|
|
278
|
-
It needs the optional peer dependencies `satori` and `@resvg/resvg-js` (`npm install satori @resvg/resvg-js`),
|
|
279
|
-
at least one font file (TTF, OTF or WOFF, not WOFF2; `path` is relative to the source directory, the first
|
|
280
|
-
font of the list sets the family), and an absolute address (`og.hostname`, else `sitemap.hostname`).
|
|
281
|
-
`true` alone is rejected for lack of a font.
|
|
282
|
-
|
|
283
|
-
## Printing
|
|
284
|
-
|
|
285
|
-
No option needed. Printing a page drops the navigation, sidebar, outline, banner, back-to-top
|
|
286
|
-
control, progress bar, feedback widget and previous/next links, forces the light palette (code
|
|
287
|
-
included) even in dark mode, and prints the address after each external link.
|
|
288
|
-
|
|
289
|
-
## Translating
|
|
290
|
-
|
|
291
|
-
Every string the theme adds sits in `themeConfig.ff.labels`, so it is translated the same way as any
|
|
292
|
-
default-theme label: per locale. `{0}` is replaced by the value the label describes.
|
|
293
|
-
|
|
294
|
-
```ts
|
|
295
|
-
locales: {
|
|
296
|
-
root: { label: 'English', lang: 'en' },
|
|
297
|
-
fr: {
|
|
298
|
-
label: 'Français',
|
|
299
|
-
lang: 'fr',
|
|
300
|
-
themeConfig: {
|
|
301
|
-
returnToTopLabel: 'Retour en haut',
|
|
302
|
-
ff: {
|
|
303
|
-
banner: { id: 'v5', text: 'La version 5 est sortie.', linkText: 'Lire les notes' },
|
|
304
|
-
labels: {
|
|
305
|
-
bannerDismiss: 'Fermer l\u2019annonce',
|
|
306
|
-
readingTime: '{0} min de lecture',
|
|
307
|
-
lastUpdated: 'Mis à jour {0}',
|
|
308
|
-
heroInstall: 'Installation',
|
|
309
|
-
heroCopied: 'Copié',
|
|
310
|
-
heroCopyLabel: 'Copier {0}',
|
|
311
|
-
backToTop: 'Haut',
|
|
312
|
-
footerSocial: 'Nous suivre',
|
|
313
|
-
newTab: 's\u2019ouvre dans un nouvel onglet'
|
|
314
|
-
}
|
|
315
|
-
}
|
|
316
|
-
}
|
|
317
|
-
}
|
|
318
|
-
}
|
|
319
|
-
```
|
|
320
|
-
|
|
321
|
-
| Label | Default |
|
|
322
|
-
|-------------------|-------------------------|
|
|
323
|
-
| `bannerDismiss` | `Dismiss announcement` |
|
|
324
|
-
| `readingTime` | `{0} min read` |
|
|
325
|
-
| `lastUpdated` | `Updated {0}` |
|
|
326
|
-
| `heroInstall` | `Install` |
|
|
327
|
-
| `heroCopied` | `Copied` |
|
|
328
|
-
| `heroCopyLabel` | `Copy {0}` |
|
|
329
|
-
| `backToTop` | `Top` |
|
|
330
|
-
| `footerSocial` | `Follow` |
|
|
331
|
-
| `newTab` | `opens in a new tab` |
|
|
332
|
-
| `sponsors` | `Sponsors` |
|
|
333
|
-
| `sponsorsAction` | `Become a sponsor` |
|
|
334
|
-
| `feedbackQuestion`| `Was this page helpful?`|
|
|
335
|
-
| `feedbackYes` | `Yes` |
|
|
336
|
-
| `feedbackNo` | `No` |
|
|
337
|
-
| `feedbackThanks` | `Thanks for your feedback` |
|
|
338
|
-
| `copyMarkdown` | `Copy as Markdown` |
|
|
339
|
-
| `versionSwitcher` | `Version` |
|
|
340
|
-
| `blogBy` | `By {0}` |
|
|
341
|
-
| `blogEmpty` | `No posts yet` |
|
|
342
|
-
|
|
343
|
-
The banner's own `text` and `linkText` are content, not labels, so they stay under `ff.banner`. The
|
|
344
|
-
back-to-top tooltip reuses the default theme's `returnToTopLabel`, and the last-updated stamp is
|
|
345
|
-
formatted with `Intl.RelativeTimeFormat` in the page's own `lang`.
|
|
346
|
-
|
|
347
|
-
## Home page
|
|
348
|
-
|
|
349
|
-
Standard VitePress home frontmatter, read with an editorial hierarchy: `hero.name` becomes the
|
|
350
|
-
kicker, `hero.text` the headline. Two additions fill the page out.
|
|
351
|
-
|
|
352
|
-
The hero can also carry two soft washes of light, one accent and one neutral, behind the headline.
|
|
353
|
-
They are off by default — a site turns them on by raising `--ff-hero-glow-opacity`, which drives
|
|
354
|
-
both at once and takes any value between `0` and `1`:
|
|
355
|
-
|
|
356
|
-
```css
|
|
357
|
-
:root {
|
|
358
|
-
--ff-hero-glow-opacity: 1;
|
|
359
|
-
}
|
|
360
|
-
```
|
|
361
|
-
|
|
362
|
-
Their colours come from `--ff-color-accent-glow` and `--ff-color-accent-soft`, per scheme.
|
|
363
|
-
|
|
364
|
-
`hero.command` puts an install panel in the second column of the hero, carrying the command and the
|
|
365
|
-
actions, sized to the panel's own fixed box. The box and its "Install" heading only print when there
|
|
366
|
-
are actions to go with the command — with none, it's the bare command line, borderless outside its
|
|
367
|
-
own. Add `hero.image` (standard VitePress frontmatter, any `<img>` source including a gif) or fill
|
|
368
|
-
the `home-hero-image` slot, and that image claims the second column instead, split 50/50 with the
|
|
369
|
-
text rather than the panel's narrower share — the panel drops under the text on the left rather than
|
|
370
|
-
disappearing, always bare there since the actions already sit under the text either way. `hero.quote`
|
|
371
|
-
prints a short line under the tagline,
|
|
372
|
-
ruled and set in italics the same way a markdown blockquote is — inline HTML works, so a term inside
|
|
373
|
-
it can carry its own `<strong>`. `hero.meta` prints a colophon strip under the hero. `hero.command`,
|
|
374
|
-
`hero.quote` and `hero.meta` are all typed by the exported `HeroExtras` interface.
|
|
375
|
-
|
|
376
|
-
`hero.command` also takes an array of `{ label, value }` tabs instead of a single string — one
|
|
377
|
-
command per package manager, say — printing a tab strip above the line, styled like the theme's own
|
|
378
|
-
`::: code-group` tabs. The copy button always follows whichever tab is active:
|
|
379
|
-
|
|
380
|
-
```yaml
|
|
381
|
-
hero:
|
|
382
|
-
command:
|
|
383
|
-
- label: npm
|
|
384
|
-
value: npm install my-project
|
|
385
|
-
- label: pnpm
|
|
386
|
-
value: pnpm add my-project
|
|
387
|
-
- label: bun
|
|
388
|
-
value: bun add my-project
|
|
389
|
-
```
|
|
390
|
-
|
|
391
|
-
```yaml
|
|
392
|
-
---
|
|
393
|
-
layout: home
|
|
394
|
-
|
|
395
|
-
hero:
|
|
396
|
-
name: My project
|
|
397
|
-
text: A headline that carries the page.
|
|
398
|
-
tagline: One or two sentences of standfirst.
|
|
399
|
-
command: npm install my-project
|
|
400
|
-
quote: <strong>My project</strong> — what the name means, in one line.
|
|
401
|
-
meta:
|
|
402
|
-
- label: Licence
|
|
403
|
-
value: MIT
|
|
404
|
-
- label: Version
|
|
405
|
-
value: 1.4.x
|
|
406
|
-
- label: Dependencies
|
|
407
|
-
value: None
|
|
408
|
-
actions:
|
|
409
|
-
- theme: brand
|
|
410
|
-
text: Get started
|
|
411
|
-
link: /guide/
|
|
412
|
-
features:
|
|
413
|
-
- title: Numbered automatically
|
|
414
|
-
details: Feature cells count themselves.
|
|
415
|
-
---
|
|
416
|
-
```
|
|
417
|
-
|
|
418
|
-
## Markdown components
|
|
419
|
-
|
|
420
|
-
Registered globally, no import needed.
|
|
421
|
-
|
|
422
|
-
| Component | Use |
|
|
423
|
-
|--------------------------------------------------|---------------------------------------------------|
|
|
424
|
-
| `<Api name kind signature since deprecated>` | An API entry: ruled heading, monospaced signature |
|
|
425
|
-
| `<Callout type title>` | A `::: tip`-style note usable inside components |
|
|
426
|
-
| `<CardGrid :columns>` / `<Card title icon link>` | Card grids |
|
|
427
|
-
| `<Steps>` | Wraps an ordered list into a numbered rail |
|
|
428
|
-
| `<Tabs syncKey>` / `<Tab label>` | Tab groups; a shared `syncKey` links them |
|
|
429
|
-
| `<Badge text type>` | `new`, `beta`, `deprecated`, `since` variants |
|
|
430
|
-
| `<FileTree>` | A Markdown list drawn as a file tree |
|
|
431
|
-
| `<Timeline>` / `<TimelineItem date title>` | A vertical rail of dated entries |
|
|
432
|
-
| `<Kbd>` | A key |
|
|
53
|
+
`extends: baseConfig` is required: it swaps the components the theme replaces and wires the build
|
|
54
|
+
hooks the theme relies on.
|
|
433
55
|
|
|
434
|
-
##
|
|
56
|
+
## Documentation
|
|
435
57
|
|
|
436
|
-
The
|
|
437
|
-
between them, and the layout overrides here are written against the version in `peerDependencies`.
|
|
438
|
-
Keep the host project on the same alpha.
|
|
58
|
+
The playground is the reference. Each page below is the source of a page of the demo site:
|
|
439
59
|
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
60
|
+
- [Getting started](https://github.com/front-factory/vitepress-theme/blob/main/playground/guide/getting-started.md): install, wiring and the keys worth knowing.
|
|
61
|
+
- [Configuration](https://github.com/front-factory/vitepress-theme/blob/main/playground/guide/configuration.md): `themeConfig.ff` options, rebranding, translating, printing, page actions, llms.txt, blog and Open Graph images, plus the [home page](https://github.com/front-factory/vitepress-theme/blob/main/playground/guide/configuration.md#home-page) frontmatter.
|
|
62
|
+
- [Components](https://github.com/front-factory/vitepress-theme/blob/main/playground/guide/components.md): cards, callouts, tabs, timeline, file tree and the other markdown components.
|
|
63
|
+
- [Markdown](https://github.com/front-factory/vitepress-theme/blob/main/playground/guide/markdown.md): blocks, code, tables and the rest of the markdown styling.
|
|
64
|
+
- [Blog](https://github.com/front-factory/vitepress-theme/blob/main/playground/blog/index.md): a blog index and posts, as configured in the playground.
|
|
445
65
|
|
|
446
66
|
## Developing locally
|
|
447
67
|
|
package/config.d.ts
CHANGED
|
@@ -6,7 +6,7 @@ import type { ThemeConfig } from './src/types';
|
|
|
6
6
|
declare const config: UserConfig<ThemeConfig>;
|
|
7
7
|
|
|
8
8
|
/**
|
|
9
|
-
* Stores the page's Markdown source on `pageData.ffMarkdown` when `themeConfig.ff.copyMarkdown` is on.
|
|
9
|
+
* Stores the page's Markdown source on `pageData.ffMarkdown` when `themeConfig.ff.pageActions` enables the Markdown copy (or the deprecated `copyMarkdown` is on).
|
|
10
10
|
* Call it from your own `transformPageData` and return the result: a hook declared by the host
|
|
11
11
|
* replaces the one in this config.
|
|
12
12
|
*/
|
|
@@ -23,9 +23,10 @@ export declare function ffTransformPageData(
|
|
|
23
23
|
export declare function ffBuildEnd(siteConfig: SiteConfig<ThemeConfig>): Promise<void>;
|
|
24
24
|
|
|
25
25
|
/**
|
|
26
|
-
* Head entries added by the theme
|
|
26
|
+
* Head entries added by the theme: the accent preset and banner scripts, the link to the blog's RSS
|
|
27
|
+
* feed, and the Open Graph and Twitter tags (`og:*`, `twitter:card`). Call it from your own
|
|
27
28
|
* `transformHead` and merge the result with your entries.
|
|
28
29
|
*/
|
|
29
|
-
export declare function ffTransformHead(ctx: TransformContext): HeadConfig[];
|
|
30
|
+
export declare function ffTransformHead(ctx: TransformContext<ThemeConfig>): HeadConfig[];
|
|
30
31
|
|
|
31
32
|
export default config;
|
package/config.js
CHANGED
|
@@ -1,9 +1,13 @@
|
|
|
1
1
|
import { readFile } from 'node:fs/promises';
|
|
2
2
|
import { join, resolve } from 'node:path';
|
|
3
3
|
import { searchForWorkspaceRoot } from 'vite';
|
|
4
|
+
import { BANNER_DISMISSED_CLASS, bannerKey } from './node/banner.js';
|
|
4
5
|
import { generateLlms } from './node/llms.js';
|
|
5
6
|
import { generateOg } from './node/og.js';
|
|
6
|
-
import {
|
|
7
|
+
import { resolvePageActions } from './node/page-actions.js';
|
|
8
|
+
import {
|
|
9
|
+
hasSource, ogOptions, ogSlug, parseSource, readPages
|
|
10
|
+
} from './node/pages.js';
|
|
7
11
|
import { generateRss } from './node/rss.js';
|
|
8
12
|
|
|
9
13
|
const dir = import.meta.dirname;
|
|
@@ -31,7 +35,8 @@ const alias = Object.entries(overrides).map(([
|
|
|
31
35
|
|
|
32
36
|
/**
|
|
33
37
|
* Stores the page's Markdown source, frontmatter stripped, on `pageData.ffMarkdown` for the "copy as
|
|
34
|
-
* Markdown" button. Does nothing unless `themeConfig.ff.
|
|
38
|
+
* Markdown" button. Does nothing unless `themeConfig.ff.pageActions` enables it (or the deprecated
|
|
39
|
+
* `copyMarkdown` is on), so a site that does not
|
|
35
40
|
* use it ships no source text.
|
|
36
41
|
*
|
|
37
42
|
* A hook declared by the host replaces the one in this config instead of adding to it. A site that
|
|
@@ -42,7 +47,7 @@ const alias = Object.entries(overrides).map(([
|
|
|
42
47
|
* @param {import('vitepress').TransformPageContext} ctx
|
|
43
48
|
*/
|
|
44
49
|
export async function ffTransformPageData(pageData, { siteConfig }) {
|
|
45
|
-
if (!siteConfig.site.themeConfig?.ff
|
|
50
|
+
if (!resolvePageActions(siteConfig.site.themeConfig?.ff).markdown || !pageData.filePath) {
|
|
46
51
|
return;
|
|
47
52
|
}
|
|
48
53
|
|
|
@@ -50,7 +55,7 @@ export async function ffTransformPageData(pageData, { siteConfig }) {
|
|
|
50
55
|
const source = await readFile(join(siteConfig.srcDir, pageData.filePath), 'utf8');
|
|
51
56
|
|
|
52
57
|
return {
|
|
53
|
-
ffMarkdown: source
|
|
58
|
+
ffMarkdown: parseSource(source).body
|
|
54
59
|
};
|
|
55
60
|
} catch {
|
|
56
61
|
// Virtual or generated page: there is no source file to copy.
|
|
@@ -68,16 +73,23 @@ export async function ffTransformPageData(pageData, { siteConfig }) {
|
|
|
68
73
|
export async function ffBuildEnd(siteConfig) {
|
|
69
74
|
const ff = siteConfig.site.themeConfig?.ff;
|
|
70
75
|
|
|
71
|
-
if (ff?.llms) {
|
|
72
|
-
|
|
76
|
+
if (!ff?.llms && !ff?.blog?.rss && !ff?.og) {
|
|
77
|
+
return;
|
|
73
78
|
}
|
|
74
79
|
|
|
75
|
-
|
|
76
|
-
|
|
80
|
+
// Read once and shared: every generator needs the same parsed pages.
|
|
81
|
+
const pages = await readPages(siteConfig);
|
|
82
|
+
|
|
83
|
+
if (ff.llms) {
|
|
84
|
+
await generateLlms(siteConfig, pages);
|
|
77
85
|
}
|
|
78
86
|
|
|
79
|
-
if (ff?.
|
|
80
|
-
await
|
|
87
|
+
if (ff.blog?.rss) {
|
|
88
|
+
await generateRss(siteConfig, pages);
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
if (ff.og) {
|
|
92
|
+
await generateOg(siteConfig, pages);
|
|
81
93
|
}
|
|
82
94
|
}
|
|
83
95
|
|
|
@@ -102,13 +114,13 @@ export function ffTransformHead({ siteData, siteConfig, page, pageData }) {
|
|
|
102
114
|
}
|
|
103
115
|
|
|
104
116
|
if (ff?.banner?.id) {
|
|
105
|
-
const key = JSON.stringify(
|
|
117
|
+
const key = JSON.stringify(bannerKey(ff.banner.id));
|
|
106
118
|
|
|
107
119
|
head.push([
|
|
108
120
|
'script',
|
|
109
121
|
{},
|
|
110
122
|
`try{if(localStorage.getItem(${key}))` +
|
|
111
|
-
|
|
123
|
+
`document.documentElement.classList.add('${BANNER_DISMISSED_CLASS}')}catch(e){}`
|
|
112
124
|
]);
|
|
113
125
|
}
|
|
114
126
|
|
|
@@ -145,36 +157,42 @@ export function ffTransformHead({ siteData, siteConfig, page, pageData }) {
|
|
|
145
157
|
property: 'og:description',
|
|
146
158
|
content: description
|
|
147
159
|
}
|
|
148
|
-
],
|
|
149
|
-
[
|
|
150
|
-
'meta',
|
|
151
|
-
{
|
|
152
|
-
property: 'og:image',
|
|
153
|
-
content: `${hostname}${siteData.base}og/${ogSlug(page)}.png`
|
|
154
|
-
}
|
|
155
|
-
],
|
|
156
|
-
[
|
|
157
|
-
'meta',
|
|
158
|
-
{
|
|
159
|
-
property: 'og:image:width',
|
|
160
|
-
content: '1200'
|
|
161
|
-
}
|
|
162
|
-
],
|
|
163
|
-
[
|
|
164
|
-
'meta',
|
|
165
|
-
{
|
|
166
|
-
property: 'og:image:height',
|
|
167
|
-
content: '630'
|
|
168
|
-
}
|
|
169
|
-
],
|
|
170
|
-
[
|
|
171
|
-
'meta',
|
|
172
|
-
{
|
|
173
|
-
name: 'twitter:card',
|
|
174
|
-
content: 'summary_large_image'
|
|
175
|
-
}
|
|
176
160
|
]
|
|
177
161
|
);
|
|
162
|
+
|
|
163
|
+
// No source file, no image drawn: leave out the tags that point to it.
|
|
164
|
+
if (pageData.filePath && hasSource(siteConfig, pageData.filePath)) {
|
|
165
|
+
head.push(
|
|
166
|
+
[
|
|
167
|
+
'meta',
|
|
168
|
+
{
|
|
169
|
+
property: 'og:image',
|
|
170
|
+
content: `${hostname}${siteData.base}og/${ogSlug(page)}.png`
|
|
171
|
+
}
|
|
172
|
+
],
|
|
173
|
+
[
|
|
174
|
+
'meta',
|
|
175
|
+
{
|
|
176
|
+
property: 'og:image:width',
|
|
177
|
+
content: '1200'
|
|
178
|
+
}
|
|
179
|
+
],
|
|
180
|
+
[
|
|
181
|
+
'meta',
|
|
182
|
+
{
|
|
183
|
+
property: 'og:image:height',
|
|
184
|
+
content: '630'
|
|
185
|
+
}
|
|
186
|
+
],
|
|
187
|
+
[
|
|
188
|
+
'meta',
|
|
189
|
+
{
|
|
190
|
+
name: 'twitter:card',
|
|
191
|
+
content: 'summary_large_image'
|
|
192
|
+
}
|
|
193
|
+
]
|
|
194
|
+
);
|
|
195
|
+
}
|
|
178
196
|
}
|
|
179
197
|
|
|
180
198
|
return head;
|