@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.
Files changed (59) hide show
  1. package/CHANGELOG.md +39 -0
  2. package/README.md +11 -391
  3. package/config.d.ts +4 -3
  4. package/config.js +58 -40
  5. package/dist/style.css +1 -1
  6. package/node/banner.d.ts +3 -0
  7. package/node/banner.js +14 -0
  8. package/node/blog.d.ts +11 -0
  9. package/node/blog.js +63 -0
  10. package/node/llms.js +4 -3
  11. package/node/og.js +5 -6
  12. package/node/options.d.ts +1 -0
  13. package/node/options.js +17 -0
  14. package/node/page-actions.d.ts +12 -0
  15. package/node/page-actions.js +34 -0
  16. package/node/pages.js +34 -14
  17. package/node/rss.js +13 -21
  18. package/package.json +1 -1
  19. package/src/blog/posts.data.ts +7 -4
  20. package/src/components/FfBackToTop.vue +6 -36
  21. package/src/components/FfBanner.vue +3 -2
  22. package/src/components/FfCopyStatus.vue +6 -14
  23. package/src/components/FfDocMeta.vue +299 -24
  24. package/src/components/FfFeedback.vue +4 -9
  25. package/src/components/FfHero.vue +14 -33
  26. package/src/components/FfHeroActions.vue +44 -0
  27. package/src/components/FfHeroCommand.vue +3 -2
  28. package/src/components/FfPost.vue +6 -4
  29. package/src/components/FfProgress.vue +6 -40
  30. package/src/composables/blog.ts +8 -11
  31. package/src/composables/copy.ts +29 -0
  32. package/src/composables/frame.ts +50 -0
  33. package/src/composables/options.ts +9 -1
  34. package/src/composables/tabs.ts +2 -35
  35. package/src/composables/transient.ts +27 -0
  36. package/src/content/Tabs.vue +27 -6
  37. package/src/internal.ts +1 -0
  38. package/src/layout/FfLayout.vue +3 -3
  39. package/src/styles/_base.scss +5 -9
  40. package/src/styles/_blocks.scss +4 -7
  41. package/src/styles/_blog.scss +4 -5
  42. package/src/styles/_code.scss +12 -20
  43. package/src/styles/_content.scss +153 -63
  44. package/src/styles/_doc.scss +26 -25
  45. package/src/styles/_home.scss +31 -61
  46. package/src/styles/_mixins.scss +87 -0
  47. package/src/styles/_motion.scss +12 -10
  48. package/src/styles/_nav.scss +12 -19
  49. package/src/styles/_sidebar.scss +5 -8
  50. package/src/styles/_tokens.scss +19 -4
  51. package/src/types.ts +31 -4
  52. package/types/components/FfHeroActions.vue.d.ts +19 -0
  53. package/types/composables/blog.d.ts +3 -4
  54. package/types/composables/copy.d.ts +6 -0
  55. package/types/composables/frame.d.ts +6 -0
  56. package/types/composables/tabs.d.ts +0 -5
  57. package/types/composables/transient.d.ts +6 -0
  58. package/types/internal.d.ts +1 -0
  59. 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
  [![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](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, keeps the package out
52
- of dependency pre-bundling, and injects the inline script that keeps a dismissed banner from
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
- ## Version
56
+ ## Documentation
435
57
 
436
- The theme tracks the VitePress 2 alphas closely — the default theme is still being restructured
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
- If a change to the theme does not show up, suspect a stale Vite cache before suspecting the CSS: the
441
- stylesheet is a built file living outside the site root, so `.vitepress/cache` can keep serving an
442
- old copy. Delete it and restart. In the browser,
443
- `getComputedStyle(document.documentElement).getPropertyValue('--ff-layout-wide')` tells you which
444
- stylesheet you are actually looking at.
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 (accent preset, banner script). Call it from your own
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 { ogOptions, ogSlug } from './node/pages.js';
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.copyMarkdown` is on, so a site that does not
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?.copyMarkdown || !pageData.filePath) {
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.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '').trim()
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
- await generateLlms(siteConfig);
76
+ if (!ff?.llms && !ff?.blog?.rss && !ff?.og) {
77
+ return;
73
78
  }
74
79
 
75
- if (ff?.blog?.rss) {
76
- await generateRss(siteConfig);
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?.og) {
80
- await generateOg(siteConfig);
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(`ff-banner-${ff.banner.id}`);
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
- 'document.documentElement.classList.add(\'ff-banner-dismissed\')}catch(e){}'
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;