@frontfactory/vitepress-theme 1.9.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 +11 -0
- package/README.md +11 -404
- package/config.js +7 -10
- package/dist/style.css +1 -1
- package/node/banner.d.ts +3 -0
- package/node/banner.js +14 -0
- package/node/blog.d.ts +8 -0
- package/node/blog.js +44 -0
- 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 +20 -8
- package/node/rss.js +10 -15
- package/package.json +1 -1
- package/src/blog/posts.data.ts +5 -3
- package/src/components/FfBackToTop.vue +5 -35
- package/src/components/FfBanner.vue +3 -2
- package/src/components/FfCopyStatus.vue +6 -14
- package/src/components/FfDocMeta.vue +8 -16
- package/src/components/FfFeedback.vue +4 -9
- package/src/components/FfPost.vue +2 -1
- package/src/components/FfProgress.vue +6 -40
- package/src/composables/blog.ts +8 -14
- package/src/composables/copy.ts +4 -11
- package/src/composables/frame.ts +50 -0
- package/src/composables/transient.ts +27 -0
- package/src/styles/_code.scss +6 -8
- package/src/styles/_doc.scss +12 -1
- package/src/styles/_home.scss +20 -12
- package/src/styles/_mixins.scss +24 -0
- package/src/types.ts +3 -2
- package/types/composables/blog.d.ts +3 -4
- package/types/composables/frame.d.ts +6 -0
- package/types/composables/transient.d.ts +6 -0
- package/types/types.d.ts +3 -2
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,17 @@
|
|
|
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
|
+
|
|
5
16
|
## [1.9.0](https://github.com/front-factory/vitepress-theme/compare/v1.8.0...v1.9.0) (2026-11-15)
|
|
6
17
|
|
|
7
18
|
### 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,413 +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
|
-
// Each item defaults to true; set it to false to hide just that item.
|
|
140
|
-
meta: {
|
|
141
|
-
section: true, // section name, read from the sidebar
|
|
142
|
-
readingTime: true, // reading-time estimate
|
|
143
|
-
wordsPerMinute: 200,
|
|
144
|
-
lastUpdated: true // needs `lastUpdated: true` in the site config
|
|
145
|
-
},
|
|
146
|
-
|
|
147
|
-
// Link columns in the site footer (home and page layouts).
|
|
148
|
-
footerColumns: [
|
|
149
|
-
{ title: 'Docs', items: [{ text: 'Guide', link: '/guide/' }] }
|
|
150
|
-
],
|
|
151
|
-
|
|
152
|
-
// Column of `themeConfig.socialLinks` icons, pinned to the right of those columns.
|
|
153
|
-
footerSocial: true,
|
|
154
|
-
|
|
155
|
-
backToTop: true,
|
|
156
|
-
|
|
157
|
-
// Thin reading-progress bar at the very top of the viewport. Off by default.
|
|
158
|
-
progress: true,
|
|
159
|
-
|
|
160
|
-
// "Was this page helpful?" widget under each doc page. `true`, or an object: `url` receives
|
|
161
|
-
// each vote through `navigator.sendBeacon`, `question` replaces the label. Every vote is
|
|
162
|
-
// also dispatched on `window` as an `ff:feedback` event.
|
|
163
|
-
feedback: { url: 'https://example.com/feedback' },
|
|
164
|
-
|
|
165
|
-
// Page actions menu in the page kicker (copy as Markdown, copy link, share). Copying the
|
|
166
|
-
// Markdown needs `ffTransformPageData`, see below.
|
|
167
|
-
pageActions: true,
|
|
168
|
-
|
|
169
|
-
// Writes llms.txt and llms-full.txt at the end of the build. Needs `ffBuildEnd`, see below.
|
|
170
|
-
llms: true,
|
|
171
|
-
|
|
172
|
-
// Blog: `layout: blog` on the index page, a dated header on each post, an RSS feed.
|
|
173
|
-
blog: {
|
|
174
|
-
dir: 'blog', // default
|
|
175
|
-
authors: { ada: { name: 'Ada Lovelace', link: 'https://example.com/ada' } },
|
|
176
|
-
rss: { hostname: 'https://example.com' } // or true with `sitemap.hostname`
|
|
177
|
-
},
|
|
178
|
-
|
|
179
|
-
// Open Graph image per page (needs fonts) plus the og:* and twitter:card tags.
|
|
180
|
-
og: {
|
|
181
|
-
hostname: 'https://example.com', // else `sitemap.hostname`
|
|
182
|
-
fonts: [{ name: 'JetBrains Mono', path: 'fonts/JetBrainsMono-Bold.ttf', weight: 700 }]
|
|
183
|
-
},
|
|
184
|
-
|
|
185
|
-
// Version menu beside the site name; each item links to that version's docs.
|
|
186
|
-
versions: {
|
|
187
|
-
current: 'v2',
|
|
188
|
-
items: [{ text: 'v1', link: 'https://v1.example.com' }]
|
|
189
|
-
}
|
|
190
|
-
}
|
|
191
|
-
}
|
|
192
|
-
```
|
|
193
|
-
|
|
194
|
-
Per page, `docMeta: false` in the frontmatter drops the kicker, `section: Guide` overrides the
|
|
195
|
-
section name, `progress: false` hides the progress bar, `feedback: false` hides the feedback widget, and `wide: true` widens the text column to the full
|
|
196
|
-
band and hides the outline (wide tables, API listings).
|
|
197
|
-
|
|
198
|
-
A vote is sent as the JSON string `{ page, value, lang }` (`value` is `'yes'` or `'no'`, `page` the
|
|
199
|
-
source path), and also fires `ff:feedback` on `window` with that object in `detail`, so a site can
|
|
200
|
-
forward it to its own analytics:
|
|
201
|
-
|
|
202
|
-
```ts
|
|
203
|
-
window.addEventListener('ff:feedback', (event) => console.log(event.detail))
|
|
204
|
-
```
|
|
205
|
-
|
|
206
|
-
Banner text, hero title/tagline/quote, feature title/details, footer message/copyright and card icon
|
|
207
|
-
all render as HTML (`v-html`), not escaped text — a `<strong>` or a hand-written `<a>` in any of them
|
|
208
|
-
shows up as markup. The trust boundary is the config file itself: these strings are meant to come
|
|
209
|
-
from whoever writes `themeConfig.ff` in the VitePress config, not from a reader, a comment, or a CMS
|
|
210
|
-
field someone else can edit. If a site ever pipes such input into these fields, sanitize it before it
|
|
211
|
-
reaches the config — the theme does not.
|
|
212
|
-
|
|
213
|
-
### Copy as Markdown
|
|
214
|
-
|
|
215
|
-
`pageActions: true` puts a split button in the kicker: the main part copies the page link, the
|
|
216
|
-
chevron opens a menu to copy the page's Markdown source (frontmatter removed) and to share on X,
|
|
217
|
-
LinkedIn, Bluesky and Mastodon. Pass an object (`copyMarkdown`, `copyLink`, `share`,
|
|
218
|
-
`mastodonInstance`) to pick the actions; the former `copyMarkdown: true` option still works but is
|
|
219
|
-
deprecated. The source is read at build time by `ffTransformPageData`, which `extends: baseConfig`
|
|
220
|
-
already wires in. VitePress replaces a hook declared by the site instead of merging it, so a site
|
|
221
|
-
with its own `transformPageData` calls the helper from it and returns the result:
|
|
222
|
-
|
|
223
|
-
```ts
|
|
224
|
-
import baseConfig, { ffTransformPageData } from '@frontfactory/vitepress-theme/config'
|
|
225
|
-
|
|
226
|
-
export default defineConfig({
|
|
227
|
-
extends: baseConfig,
|
|
228
|
-
transformPageData(pageData, ctx) {
|
|
229
|
-
// ...your own changes to pageData...
|
|
230
|
-
|
|
231
|
-
return ffTransformPageData(pageData, ctx)
|
|
232
|
-
}
|
|
233
|
-
})
|
|
234
|
-
```
|
|
235
|
-
|
|
236
|
-
Without the option the helper does nothing, so no source text reaches the bundle.
|
|
237
|
-
|
|
238
|
-
### llms.txt
|
|
239
|
-
|
|
240
|
-
`llms: true` writes `llms.txt` (an index of the pages) and `llms-full.txt` (their Markdown) to the
|
|
241
|
-
output directory. Links are absolute when `sitemap.hostname` is set. `404.md` and pages with
|
|
242
|
-
`llms: false` in their frontmatter are skipped.
|
|
243
|
-
|
|
244
|
-
The files come from `ffBuildEnd`, wired in by `extends: baseConfig`. A site with its own `buildEnd`
|
|
245
|
-
(or `transformHead`) calls the helper from it, as for `ffTransformPageData`:
|
|
246
|
-
|
|
247
|
-
```ts
|
|
248
|
-
import baseConfig, { ffBuildEnd } from '@frontfactory/vitepress-theme/config'
|
|
249
|
-
|
|
250
|
-
export default defineConfig({
|
|
251
|
-
extends: baseConfig,
|
|
252
|
-
async buildEnd(siteConfig) {
|
|
253
|
-
await ffBuildEnd(siteConfig)
|
|
254
|
-
}
|
|
255
|
-
})
|
|
256
|
-
```
|
|
257
|
-
|
|
258
|
-
### Blog
|
|
259
|
-
|
|
260
|
-
Posts are Markdown pages under `blog.dir` (default `blog`) with a `date`. The index page, `blog/index.md`,
|
|
261
|
-
uses `layout: blog` and lists them newest first; each post gets a header with its date, author and tags.
|
|
262
|
-
|
|
263
|
-
```md
|
|
264
|
-
---
|
|
265
|
-
title: Hello, editorial
|
|
266
|
-
date: 2026-10-12
|
|
267
|
-
author: ada # a key of blog.authors, or a plain name
|
|
268
|
-
tags: [theme, design]
|
|
269
|
-
excerpt: Shown in the list and in the feed.
|
|
270
|
-
---
|
|
271
|
-
```
|
|
272
|
-
|
|
273
|
-
`rss` writes `feed.xml` at the end of the build (through `ffBuildEnd`) and adds the
|
|
274
|
-
`<link rel="alternate">` tag through `ffTransformHead`. It needs the optional peer dependency
|
|
275
|
-
`feed` (`npm install feed`) and an absolute address: `rss.hostname`, else `sitemap.hostname`.
|
|
276
|
-
|
|
277
|
-
### Open Graph images
|
|
278
|
-
|
|
279
|
-
`og` draws a 1200x630 PNG for each page into `og/` at the end of the build, and adds `og:image`,
|
|
280
|
-
`og:title`, `og:description` and `twitter:card: summary_large_image` to the page head
|
|
281
|
-
(`ffBuildEnd` and `ffTransformHead`). A page opts out with `og: false` in its frontmatter.
|
|
282
|
-
|
|
283
|
-
It needs the optional peer dependencies `satori` and `@resvg/resvg-js` (`npm install satori @resvg/resvg-js`),
|
|
284
|
-
at least one font file (TTF, OTF or WOFF, not WOFF2; `path` is relative to the VitePress root (the folder holding `.vitepress`), the first
|
|
285
|
-
font of the list sets the family), and an absolute address (`og.hostname`, else `sitemap.hostname`).
|
|
286
|
-
`true` alone is rejected for lack of a font.
|
|
287
|
-
|
|
288
|
-
## Printing
|
|
289
|
-
|
|
290
|
-
No option needed. Printing a page drops the navigation, sidebar, outline, banner, back-to-top
|
|
291
|
-
control, progress bar, feedback widget and previous/next links, forces the light palette (code
|
|
292
|
-
included) even in dark mode, and prints the address after each external link.
|
|
293
|
-
|
|
294
|
-
## Translating
|
|
295
|
-
|
|
296
|
-
Every string the theme adds sits in `themeConfig.ff.labels`, so it is translated the same way as any
|
|
297
|
-
default-theme label: per locale. `{0}` is replaced by the value the label describes.
|
|
298
|
-
|
|
299
|
-
```ts
|
|
300
|
-
locales: {
|
|
301
|
-
root: { label: 'English', lang: 'en' },
|
|
302
|
-
fr: {
|
|
303
|
-
label: 'Français',
|
|
304
|
-
lang: 'fr',
|
|
305
|
-
themeConfig: {
|
|
306
|
-
returnToTopLabel: 'Retour en haut',
|
|
307
|
-
ff: {
|
|
308
|
-
banner: { id: 'v5', text: 'La version 5 est sortie.', linkText: 'Lire les notes' },
|
|
309
|
-
labels: {
|
|
310
|
-
bannerDismiss: 'Fermer l\u2019annonce',
|
|
311
|
-
readingTime: '{0} min de lecture',
|
|
312
|
-
lastUpdated: 'Mis à jour {0}',
|
|
313
|
-
heroInstall: 'Installation',
|
|
314
|
-
heroCopied: 'Copié',
|
|
315
|
-
heroCopyLabel: 'Copier {0}',
|
|
316
|
-
backToTop: 'Haut',
|
|
317
|
-
footerSocial: 'Nous suivre',
|
|
318
|
-
newTab: 's\u2019ouvre dans un nouvel onglet'
|
|
319
|
-
}
|
|
320
|
-
}
|
|
321
|
-
}
|
|
322
|
-
}
|
|
323
|
-
}
|
|
324
|
-
```
|
|
325
|
-
|
|
326
|
-
| Label | Default |
|
|
327
|
-
|-------------------|-------------------------|
|
|
328
|
-
| `bannerDismiss` | `Dismiss announcement` |
|
|
329
|
-
| `readingTime` | `{0} min read` |
|
|
330
|
-
| `lastUpdated` | `Updated {0}` |
|
|
331
|
-
| `heroInstall` | `Install` |
|
|
332
|
-
| `heroCopied` | `Copied` |
|
|
333
|
-
| `heroCopyLabel` | `Copy {0}` |
|
|
334
|
-
| `backToTop` | `Top` |
|
|
335
|
-
| `footerSocial` | `Follow` |
|
|
336
|
-
| `newTab` | `opens in a new tab` |
|
|
337
|
-
| `sponsors` | `Sponsors` |
|
|
338
|
-
| `sponsorsAction` | `Become a sponsor` |
|
|
339
|
-
| `feedbackQuestion`| `Was this page helpful?`|
|
|
340
|
-
| `feedbackYes` | `Yes` |
|
|
341
|
-
| `feedbackNo` | `No` |
|
|
342
|
-
| `feedbackThanks` | `Thanks for your feedback` |
|
|
343
|
-
| `copyMarkdown` | `Copy as Markdown` |
|
|
344
|
-
| `copyMarkdownHint` | `Page source` |
|
|
345
|
-
| `pageActions` | `More page actions` |
|
|
346
|
-
| `copyLink` | `Copy link` |
|
|
347
|
-
| `linkCopied` | `Link copied` |
|
|
348
|
-
| `share` | `Share` |
|
|
349
|
-
| `shareOn` | `Share on {0}` |
|
|
350
|
-
| `versionSwitcher` | `Version` |
|
|
351
|
-
| `blogBy` | `By {0}` |
|
|
352
|
-
| `blogEmpty` | `No posts yet` |
|
|
353
|
-
| `returnToTop` | `Return to top` |
|
|
354
|
-
| `codeCopied` | `Copied` |
|
|
355
|
-
|
|
356
|
-
The banner's own `text` and `linkText` are content, not labels, so they stay under `ff.banner`. The
|
|
357
|
-
back-to-top tooltip reuses the default theme's `returnToTopLabel` when set (otherwise `returnToTop`), and the last-updated stamp is
|
|
358
|
-
formatted with `Intl.RelativeTimeFormat` in the page's own `lang`.
|
|
359
|
-
|
|
360
|
-
## Home page
|
|
361
|
-
|
|
362
|
-
Standard VitePress home frontmatter, read with an editorial hierarchy: `hero.name` becomes the
|
|
363
|
-
kicker, `hero.text` the headline. Two additions fill the page out.
|
|
364
|
-
|
|
365
|
-
The hero can also carry two soft washes of light, one accent and one neutral, behind the headline.
|
|
366
|
-
They are off by default — a site turns them on by raising `--ff-hero-glow-opacity`, which drives
|
|
367
|
-
both at once and takes any value between `0` and `1`:
|
|
368
|
-
|
|
369
|
-
```css
|
|
370
|
-
:root {
|
|
371
|
-
--ff-hero-glow-opacity: 1;
|
|
372
|
-
}
|
|
373
|
-
```
|
|
374
|
-
|
|
375
|
-
Their colours come from `--ff-color-accent-glow` and `--ff-color-accent-soft`, per scheme.
|
|
376
|
-
|
|
377
|
-
`hero.command` puts an install panel in the second column of the hero, carrying the command and the
|
|
378
|
-
actions, sized to the panel's own fixed box. The box and its "Install" heading only print when there
|
|
379
|
-
are actions to go with the command — with none, it's the bare command line, borderless outside its
|
|
380
|
-
own. Add `hero.image` (standard VitePress frontmatter, any `<img>` source including a gif) or fill
|
|
381
|
-
the `home-hero-image` slot, and that image claims the second column instead, split 50/50 with the
|
|
382
|
-
text rather than the panel's narrower share — the panel drops under the text on the left rather than
|
|
383
|
-
disappearing, always bare there since the actions already sit under the text either way. `hero.quote`
|
|
384
|
-
prints a short line under the tagline,
|
|
385
|
-
ruled and set in italics the same way a markdown blockquote is — inline HTML works, so a term inside
|
|
386
|
-
it can carry its own `<strong>`. `hero.meta` prints a colophon strip under the hero. `hero.command`,
|
|
387
|
-
`hero.quote` and `hero.meta` are all typed by the exported `HeroExtras` interface.
|
|
388
|
-
|
|
389
|
-
`hero.command` also takes an array of `{ label, value }` tabs instead of a single string — one
|
|
390
|
-
command per package manager, say — printing a tab strip above the line, styled like the theme's own
|
|
391
|
-
`::: code-group` tabs. The copy button always follows whichever tab is active:
|
|
392
|
-
|
|
393
|
-
```yaml
|
|
394
|
-
hero:
|
|
395
|
-
command:
|
|
396
|
-
- label: npm
|
|
397
|
-
value: npm install my-project
|
|
398
|
-
- label: pnpm
|
|
399
|
-
value: pnpm add my-project
|
|
400
|
-
- label: bun
|
|
401
|
-
value: bun add my-project
|
|
402
|
-
```
|
|
403
|
-
|
|
404
|
-
```yaml
|
|
405
|
-
---
|
|
406
|
-
layout: home
|
|
407
|
-
|
|
408
|
-
hero:
|
|
409
|
-
name: My project
|
|
410
|
-
text: A headline that carries the page.
|
|
411
|
-
tagline: One or two sentences of standfirst.
|
|
412
|
-
command: npm install my-project
|
|
413
|
-
quote: <strong>My project</strong> — what the name means, in one line.
|
|
414
|
-
meta:
|
|
415
|
-
- label: Licence
|
|
416
|
-
value: MIT
|
|
417
|
-
- label: Version
|
|
418
|
-
value: 1.4.x
|
|
419
|
-
- label: Dependencies
|
|
420
|
-
value: None
|
|
421
|
-
actions:
|
|
422
|
-
- theme: brand
|
|
423
|
-
text: Get started
|
|
424
|
-
link: /guide/
|
|
425
|
-
features:
|
|
426
|
-
- title: Numbered automatically
|
|
427
|
-
details: Feature cells count themselves.
|
|
428
|
-
---
|
|
429
|
-
```
|
|
430
|
-
|
|
431
|
-
## Markdown components
|
|
432
|
-
|
|
433
|
-
Registered globally, no import needed.
|
|
434
|
-
|
|
435
|
-
| Component | Use |
|
|
436
|
-
|--------------------------------------------------|---------------------------------------------------|
|
|
437
|
-
| `<Api name kind signature since deprecated>` | An API entry: ruled heading, monospaced signature |
|
|
438
|
-
| `<Callout type title>` | A `::: tip`-style note usable inside components |
|
|
439
|
-
| `<CardGrid :columns>` / `<Card title icon link>` | Card grids |
|
|
440
|
-
| `<Steps>` | Wraps an ordered list into a numbered rail |
|
|
441
|
-
| `<Tabs syncKey>` / `<Tab label>` | Tab groups; a shared `syncKey` links them |
|
|
442
|
-
| `<Badge text type>` | `new`, `beta`, `deprecated`, `since` variants |
|
|
443
|
-
| `<FileTree>` | A Markdown list drawn as a file tree |
|
|
444
|
-
| `<Timeline>` / `<TimelineItem date title>` | A vertical rail of dated entries |
|
|
445
|
-
| `<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.
|
|
446
55
|
|
|
447
|
-
##
|
|
56
|
+
## Documentation
|
|
448
57
|
|
|
449
|
-
The
|
|
450
|
-
between them, and the layout overrides here are written against the version in `peerDependencies`.
|
|
451
|
-
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:
|
|
452
59
|
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
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.
|
|
458
65
|
|
|
459
66
|
## Developing locally
|
|
460
67
|
|
package/config.js
CHANGED
|
@@ -1,10 +1,12 @@
|
|
|
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';
|
|
7
|
+
import { resolvePageActions } from './node/page-actions.js';
|
|
6
8
|
import {
|
|
7
|
-
hasSource, ogOptions, ogSlug, readPages
|
|
9
|
+
hasSource, ogOptions, ogSlug, parseSource, readPages
|
|
8
10
|
} from './node/pages.js';
|
|
9
11
|
import { generateRss } from './node/rss.js';
|
|
10
12
|
|
|
@@ -45,12 +47,7 @@ const alias = Object.entries(overrides).map(([
|
|
|
45
47
|
* @param {import('vitepress').TransformPageContext} ctx
|
|
46
48
|
*/
|
|
47
49
|
export async function ffTransformPageData(pageData, { siteConfig }) {
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
if (
|
|
51
|
-
!(pageActions === true || pageActions?.copyMarkdown || copyMarkdown) ||
|
|
52
|
-
!pageData.filePath
|
|
53
|
-
) {
|
|
50
|
+
if (!resolvePageActions(siteConfig.site.themeConfig?.ff).markdown || !pageData.filePath) {
|
|
54
51
|
return;
|
|
55
52
|
}
|
|
56
53
|
|
|
@@ -58,7 +55,7 @@ export async function ffTransformPageData(pageData, { siteConfig }) {
|
|
|
58
55
|
const source = await readFile(join(siteConfig.srcDir, pageData.filePath), 'utf8');
|
|
59
56
|
|
|
60
57
|
return {
|
|
61
|
-
ffMarkdown: source
|
|
58
|
+
ffMarkdown: parseSource(source).body
|
|
62
59
|
};
|
|
63
60
|
} catch {
|
|
64
61
|
// Virtual or generated page: there is no source file to copy.
|
|
@@ -117,13 +114,13 @@ export function ffTransformHead({ siteData, siteConfig, page, pageData }) {
|
|
|
117
114
|
}
|
|
118
115
|
|
|
119
116
|
if (ff?.banner?.id) {
|
|
120
|
-
const key = JSON.stringify(
|
|
117
|
+
const key = JSON.stringify(bannerKey(ff.banner.id));
|
|
121
118
|
|
|
122
119
|
head.push([
|
|
123
120
|
'script',
|
|
124
121
|
{},
|
|
125
122
|
`try{if(localStorage.getItem(${key}))` +
|
|
126
|
-
|
|
123
|
+
`document.documentElement.classList.add('${BANNER_DISMISSED_CLASS}')}catch(e){}`
|
|
127
124
|
]);
|
|
128
125
|
}
|
|
129
126
|
|