@frontfactory/vitepress-theme 1.7.0 → 1.8.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 (93) hide show
  1. package/CHANGELOG.md +55 -0
  2. package/README.md +148 -5
  3. package/config.d.ts +26 -1
  4. package/config.js +165 -21
  5. package/dist/style.css +1 -1
  6. package/node/llms.js +31 -0
  7. package/node/og.js +159 -0
  8. package/node/pages.js +154 -0
  9. package/node/rss.js +81 -0
  10. package/package.json +42 -28
  11. package/src/blog/posts.data.ts +46 -0
  12. package/src/components/FfBackToTop.vue +18 -9
  13. package/src/components/FfBanner.vue +24 -6
  14. package/src/components/FfCopyStatus.vue +64 -0
  15. package/src/components/FfDocMeta.vue +41 -2
  16. package/src/components/FfFeature.vue +18 -7
  17. package/src/components/FfFeedback.vue +96 -0
  18. package/src/components/FfHero.vue +16 -6
  19. package/src/components/FfHeroCommand.vue +20 -34
  20. package/src/components/FfHomeSponsors.vue +2 -2
  21. package/src/components/FfNavBarTitle.vue +63 -0
  22. package/src/components/FfPost.vue +49 -0
  23. package/src/components/FfProgress.vue +69 -0
  24. package/src/components/FfVersionSwitcher.vue +20 -0
  25. package/src/composables/blog.ts +38 -0
  26. package/src/composables/options.ts +12 -1
  27. package/src/composables/tabs.ts +155 -0
  28. package/src/content/Api.vue +6 -2
  29. package/src/content/Badge.vue +26 -0
  30. package/src/content/Callout.vue +27 -0
  31. package/src/content/FileTree.vue +118 -0
  32. package/src/content/Tab.vue +11 -0
  33. package/src/content/Tabs.vue +74 -0
  34. package/src/content/Timeline.vue +19 -0
  35. package/src/content/TimelineItem.vue +37 -0
  36. package/src/content/timeline.ts +4 -0
  37. package/src/index.ts +37 -1
  38. package/src/internal.ts +7 -2
  39. package/src/layout/FfBlog.vue +62 -0
  40. package/src/layout/FfLayout.vue +17 -1
  41. package/src/styles/_base.scss +1 -5
  42. package/src/styles/_blocks.scss +25 -1
  43. package/src/styles/_blog.scss +131 -0
  44. package/src/styles/_breakpoints.scss +26 -0
  45. package/src/styles/_code.scss +5 -5
  46. package/src/styles/_content.scss +276 -7
  47. package/src/styles/_doc.scss +18 -5
  48. package/src/styles/_home.scss +37 -17
  49. package/src/styles/_motion.scss +12 -3
  50. package/src/styles/_nav.scss +81 -8
  51. package/src/styles/_print.scss +77 -0
  52. package/src/styles/_sidebar.scss +2 -2
  53. package/src/styles/_tokens.scss +73 -7
  54. package/src/styles/index.scss +2 -0
  55. package/src/types.ts +122 -0
  56. package/types/blog/posts.data.d.ts +14 -0
  57. package/types/components/FfBackToTop.vue.d.ts +3 -0
  58. package/types/components/FfBanner.vue.d.ts +3 -0
  59. package/types/components/FfCopyStatus.vue.d.ts +3 -0
  60. package/types/components/FfDocMeta.vue.d.ts +3 -0
  61. package/types/components/FfFeature.vue.d.ts +13 -0
  62. package/types/components/FfFeedback.vue.d.ts +3 -0
  63. package/types/components/FfFooter.vue.d.ts +3 -0
  64. package/types/components/FfHero.vue.d.ts +42 -0
  65. package/types/components/FfHeroCommand.vue.d.ts +9 -0
  66. package/types/components/FfHomeSponsors.vue.d.ts +19 -0
  67. package/types/components/FfNavBarTitle.vue.d.ts +17 -0
  68. package/types/components/FfPost.vue.d.ts +3 -0
  69. package/types/components/FfProgress.vue.d.ts +3 -0
  70. package/types/components/FfVersionSwitcher.vue.d.ts +3 -0
  71. package/types/composables/blog.d.ts +10 -0
  72. package/types/composables/link.d.ts +12 -0
  73. package/types/composables/options.d.ts +15 -0
  74. package/types/composables/relativeTime.d.ts +2 -0
  75. package/types/composables/tabs.d.ts +15 -0
  76. package/types/content/Api.vue.d.ts +27 -0
  77. package/types/content/Badge.vue.d.ts +21 -0
  78. package/types/content/Callout.vue.d.ts +24 -0
  79. package/types/content/Card.vue.d.ts +23 -0
  80. package/types/content/CardGrid.vue.d.ts +20 -0
  81. package/types/content/FileTree.vue.d.ts +6 -0
  82. package/types/content/Kbd.vue.d.ts +15 -0
  83. package/types/content/Steps.vue.d.ts +15 -0
  84. package/types/content/Tab.vue.d.ts +19 -0
  85. package/types/content/Tabs.vue.d.ts +7 -0
  86. package/types/content/Timeline.vue.d.ts +21 -0
  87. package/types/content/TimelineItem.vue.d.ts +21 -0
  88. package/types/content/timeline.d.ts +3 -0
  89. package/types/index.d.ts +25 -0
  90. package/types/internal.d.ts +9 -0
  91. package/types/layout/FfBlog.vue.d.ts +3 -0
  92. package/types/layout/FfLayout.vue.d.ts +23 -0
  93. package/types/types.d.ts +256 -0
package/CHANGELOG.md CHANGED
@@ -2,6 +2,61 @@
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.8.0](https://github.com/front-factory/vitepress-theme/compare/v1.7.0...v1.8.0) (2026-11-04)
6
+
7
+ ### Features
8
+
9
+ * **blog:** add a blog layout with rss feed ([6025542](https://github.com/front-factory/vitepress-theme/commit/60255428b91af2591e48f597c688b9be16547b89))
10
+ * **build:** generate llms.txt ([667dbda](https://github.com/front-factory/vitepress-theme/commit/667dbdaa1e4e8685aff3cda9fe1e01b5a441f24d))
11
+ * **build:** generate open graph images ([b6c2491](https://github.com/front-factory/vitepress-theme/commit/b6c249178798df1cadda134505e009d02d25a47a))
12
+ * **content:** add a Callout component ([928e3b0](https://github.com/front-factory/vitepress-theme/commit/928e3b0400e6ee2ab21e0851211270c647f18eab))
13
+ * **content:** add a FileTree component ([00fca33](https://github.com/front-factory/vitepress-theme/commit/00fca331a234b7d038efe490a52c37496387ab3c))
14
+ * **content:** add new, beta, deprecated and since badge variants ([f252ec6](https://github.com/front-factory/vitepress-theme/commit/f252ec640c34bb3fdb361ab8925fcf873b17c397))
15
+ * **content:** add Tabs and Tab components ([ecb0aff](https://github.com/front-factory/vitepress-theme/commit/ecb0aff234c620d927832e1d93f8ed77b994dada))
16
+ * **content:** add Timeline and TimelineItem components ([0ed25c0](https://github.com/front-factory/vitepress-theme/commit/0ed25c0e8f38f5226871178f33b5c31fbe898436))
17
+ * **doc:** add a copy-as-markdown button ([5de1450](https://github.com/front-factory/vitepress-theme/commit/5de1450a835b17ac42eb71f812569cb8755d12f2))
18
+ * **doc:** add a page feedback widget ([4efd586](https://github.com/front-factory/vitepress-theme/commit/4efd5861312f3d23f4e7926cb3c3940ddf5df072))
19
+ * **i18n:** route banner CTA and API tags through theme labels ([cfff3f9](https://github.com/front-factory/vitepress-theme/commit/cfff3f9408bbd59a376e454f3ed8abaa3ab3f024))
20
+ * **layout:** add a reading progress bar ([e524519](https://github.com/front-factory/vitepress-theme/commit/e5245199deb281c0e3101569d9be7a30cb4a6d83))
21
+ * **layout:** add a wide doc layout ([2cf68f8](https://github.com/front-factory/vitepress-theme/commit/2cf68f89dbb0c7ce6b0295fddf4b5ba3a4b9b276))
22
+ * **nav:** add a version switcher ([fd26deb](https://github.com/front-factory/vitepress-theme/commit/fd26deb1d3bd56950518485d1166416bca4d328a))
23
+ * **styles:** add print styles ([2ff9899](https://github.com/front-factory/vitepress-theme/commit/2ff9899f6c88c7c337dfd06d30145a12def94a65))
24
+ * **theme:** add accent presets ([97c38cc](https://github.com/front-factory/vitepress-theme/commit/97c38cc382045b2a3c62f09b4b06f920ac203d39))
25
+ * **timeline:** add a level prop for entry headings ([82476b9](https://github.com/front-factory/vitepress-theme/commit/82476b9a94f1e92c7c638e1dc3665af0400e2e7c))
26
+ * **tokens:** add an enter duration token for the hero animation ([13d9e19](https://github.com/front-factory/vitepress-theme/commit/13d9e19875075e3734a8c725751b25dded21020d))
27
+
28
+ ### Bug Fixes
29
+
30
+ * **a11y:** announce code block copies to screen readers ([83b45a3](https://github.com/front-factory/vitepress-theme/commit/83b45a38c83ecc2651b647afba56a4184829116d))
31
+ * **a11y:** expose the hero command switcher as tabs ([90bd51c](https://github.com/front-factory/vitepress-theme/commit/90bd51c25b4ae75f4d9ea749456067380cbec6ce))
32
+ * **a11y:** hand focus to the skip link when the banner is dismissed ([4c455f5](https://github.com/front-factory/vitepress-theme/commit/4c455f58de5b9247adcb1fd596899aed207254ba))
33
+ * **a11y:** include the current version in the version switcher name ([73ef48b](https://github.com/front-factory/vitepress-theme/commit/73ef48be2c306bd9086fda0ac4a01216d34956b9))
34
+ * **a11y:** link only the feature title, stretched over the card ([d55d946](https://github.com/front-factory/vitepress-theme/commit/d55d946c302273d27fc22ce2632da1dc9eff01fb))
35
+ * **a11y:** make doc link underline visible by default ([a45d78c](https://github.com/front-factory/vitepress-theme/commit/a45d78c539c0689d0962a1154ab0d96e887f900d))
36
+ * **a11y:** move focus to the thank-you line after a feedback vote ([990577b](https://github.com/front-factory/vitepress-theme/commit/990577b70d3f2a08485adbdb32a7c7ea0bb31955))
37
+ * align vite peer range with the one vitepress 2 requires ([e5da335](https://github.com/front-factory/vitepress-theme/commit/e5da3351a7106fd7ba9a0bb464be778dff192289))
38
+ * **blog:** annotate posts loader type to fix declaration build ([5a422c3](https://github.com/front-factory/vitepress-theme/commit/5a422c37002d7df04d87adc254e344109b5d7b1c))
39
+ * **code:** keep removed diff lines at full opacity for contrast ([0d1956c](https://github.com/front-factory/vitepress-theme/commit/0d1956cee66bc93e1369f8991b610ea796a26b92))
40
+ * **code:** keep the copy button fully opaque for non-text contrast ([a94e45b](https://github.com/front-factory/vitepress-theme/commit/a94e45b5b38f3482e9a09a7727e22394468542f7))
41
+ * **dark:** add shadow tokens with a dark scheme variant ([742b858](https://github.com/front-factory/vitepress-theme/commit/742b8584736088ff339cd4fdceed6bf11d3bb8ed))
42
+ * make vite a required peer dependency ([08b0df4](https://github.com/front-factory/vitepress-theme/commit/08b0df4f436b696ded556a6192874013fc426797))
43
+ * **motion:** honour reduced motion on the nav underline ([cf70693](https://github.com/front-factory/vitepress-theme/commit/cf706934a8295e1cac2b3f770b992cbf62fb6c49))
44
+ * observe banner height when it mounts after the layout ([27949c6](https://github.com/front-factory/vitepress-theme/commit/27949c6b14dda17b53a716f8dd4fd989d44a72af))
45
+ * resolve hero, banner and sponsors links against site base ([2f1ed04](https://github.com/front-factory/vitepress-theme/commit/2f1ed043c7b653e2a632cb495f362896a8886f41))
46
+ * **responsive:** align content breakpoints on 640px without overlap ([66d5e34](https://github.com/front-factory/vitepress-theme/commit/66d5e34032a9e5c4cfa061c390de0041a197f1ab))
47
+ * ship generated type declarations instead of raw sources ([6aafc8d](https://github.com/front-factory/vitepress-theme/commit/6aafc8d11184f58fd90f7fbbcb161580ca4fa127))
48
+
49
+ ### Performance
50
+
51
+ * only listen to scroll and measure the page when their option is on ([9a14af7](https://github.com/front-factory/vitepress-theme/commit/9a14af7a9397572eba7478726185145e9d634716))
52
+ * render the hero image slot once per render ([684d78e](https://github.com/front-factory/vitepress-theme/commit/684d78e8e35b29c002be0ccd0ca125cbb1dca2dc))
53
+ * stop the hero glow animation while the glow is disabled ([2ea95f5](https://github.com/front-factory/vitepress-theme/commit/2ea95f556cf9966b348b3c81f780297d93b6ea8d))
54
+
55
+ ### Dependencies
56
+
57
+ * **deps:** add feed as an optional peer dependency ([198d81e](https://github.com/front-factory/vitepress-theme/commit/198d81e9d44eba4c92e39b0c4f468f7c85262822))
58
+ * **deps:** add satori and resvg as optional peer dependencies ([5e8fefa](https://github.com/front-factory/vitepress-theme/commit/5e8fefa242b8b0b870e30af22294ee7f72aa840c))
59
+
5
60
  ## [1.7.0](https://github.com/front-factory/vitepress-theme/compare/v1.6.0...v1.7.0) (2026-10-11)
6
61
 
7
62
  ### Features
package/README.md CHANGED
@@ -50,7 +50,7 @@ export default Theme
50
50
 
51
51
  `extends: baseConfig` is required: it swaps the components the theme replaces, keeps the package out
52
52
  of dependency pre-bundling, and injects the inline script that keeps a dismissed banner from
53
- painting in the built site.
53
+ painting in the built site, and reads each page's source for the copy-as-Markdown button.
54
54
 
55
55
  The package ships its Vue and TypeScript sources as-is (`main`, `module` and `types` point at
56
56
  `src/index.ts`) and relies on Vite to compile them, which `extends: baseConfig` sets up. Tooling that
@@ -62,7 +62,7 @@ tooling that needs the stylesheet on its own; the theme entry already imports it
62
62
  ## Rebranding
63
63
 
64
64
  Every value is a `--ff-*` custom property. Point the accent at your own colour and the whole site
65
- follows.
65
+ follows. For a ready-made accent instead, set `themeConfig.ff.preset` (see [Options](#options)).
66
66
 
67
67
  ```css
68
68
  /* .vitepress/theme/custom.css, imported after the theme */
@@ -99,6 +99,8 @@ follows.
99
99
  | `--ff-radius-sm` / `-md` | Corner radii |
100
100
  | `--ff-rule-width` / `--ff-rule-accent-width` | Rule weights |
101
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 |
102
104
 
103
105
  `dist/style.css` lists them all, grouped, at the top of the file.
104
106
 
@@ -125,6 +127,14 @@ themeConfig: {
125
127
  // effect on the mobile bar, which always falls back to the hamburger.
126
128
  navOrder: 'search-first',
127
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
+
128
138
  // Kicker printed above every page title. Set to false to drop it.
129
139
  meta: {
130
140
  section: true, // section name, read from the sidebar
@@ -141,13 +151,55 @@ themeConfig: {
141
151
  // Column of `themeConfig.socialLinks` icons, pinned to the right of those columns.
142
152
  footerSocial: true,
143
153
 
144
- backToTop: true
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
+ }
145
188
  }
146
189
  }
147
190
  ```
148
191
 
149
- Per page, `docMeta: false` in the frontmatter drops the kicker, and `section: Guide` overrides the
150
- section name.
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
+ ```
151
203
 
152
204
  Banner text, hero title/tagline/quote, feature title/details, footer message/copyright and card icon
153
205
  all render as HTML (`v-html`), not escaped text — a `<strong>` or a hand-written `<a>` in any of them
@@ -156,6 +208,84 @@ from whoever writes `themeConfig.ff` in the VitePress config, not from a reader,
156
208
  field someone else can edit. If a site ever pipes such input into these fields, sanitize it before it
157
209
  reaches the config — the theme does not.
158
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
+
159
289
  ## Translating
160
290
 
161
291
  Every string the theme adds sits in `themeConfig.ff.labels`, so it is translated the same way as any
@@ -201,6 +331,14 @@ locales: {
201
331
  | `newTab` | `opens in a new tab` |
202
332
  | `sponsors` | `Sponsors` |
203
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` |
204
342
 
205
343
  The banner's own `text` and `linkText` are content, not labels, so they stay under `ff.banner`. The
206
344
  back-to-top tooltip reuses the default theme's `returnToTopLabel`, and the last-updated stamp is
@@ -284,8 +422,13 @@ Registered globally, no import needed.
284
422
  | Component | Use |
285
423
  |--------------------------------------------------|---------------------------------------------------|
286
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 |
287
426
  | `<CardGrid :columns>` / `<Card title icon link>` | Card grids |
288
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 |
289
432
  | `<Kbd>` | A key |
290
433
 
291
434
  ## Version
package/config.d.ts CHANGED
@@ -1,6 +1,31 @@
1
- import type { UserConfig } from 'vitepress';
1
+ import type {
2
+ HeadConfig, PageData, SiteConfig, TransformContext, TransformPageContext, UserConfig
3
+ } from 'vitepress';
2
4
  import type { ThemeConfig } from './src/types';
3
5
 
4
6
  declare const config: UserConfig<ThemeConfig>;
5
7
 
8
+ /**
9
+ * Stores the page's Markdown source on `pageData.ffMarkdown` when `themeConfig.ff.copyMarkdown` is on.
10
+ * Call it from your own `transformPageData` and return the result: a hook declared by the host
11
+ * replaces the one in this config.
12
+ */
13
+ export declare function ffTransformPageData(
14
+ pageData: PageData,
15
+ ctx: TransformPageContext<ThemeConfig>
16
+ ): Promise<{ ffMarkdown: string } | undefined>;
17
+
18
+ /**
19
+ * Writes the files generated at the end of the build (`llms.txt`, and the blog feed and Open Graph
20
+ * images once enabled). Call it from your own `buildEnd`: a hook declared by the host replaces the
21
+ * one in this config.
22
+ */
23
+ export declare function ffBuildEnd(siteConfig: SiteConfig<ThemeConfig>): Promise<void>;
24
+
25
+ /**
26
+ * Head entries added by the theme (accent preset, banner script). Call it from your own
27
+ * `transformHead` and merge the result with your entries.
28
+ */
29
+ export declare function ffTransformHead(ctx: TransformContext): HeadConfig[];
30
+
6
31
  export default config;
package/config.js CHANGED
@@ -1,5 +1,10 @@
1
- import { resolve } from 'node:path';
1
+ import { readFile } from 'node:fs/promises';
2
+ import { join, resolve } from 'node:path';
2
3
  import { searchForWorkspaceRoot } from 'vite';
4
+ import { generateLlms } from './node/llms.js';
5
+ import { generateOg } from './node/og.js';
6
+ import { ogOptions, ogSlug } from './node/pages.js';
7
+ import { generateRss } from './node/rss.js';
3
8
 
4
9
  const dir = import.meta.dirname;
5
10
  const pkg = '@frontfactory/vitepress-theme';
@@ -12,7 +17,8 @@ const overrides = {
12
17
  VPHero: 'src/components/FfHero.vue',
13
18
  VPFeature: 'src/components/FfFeature.vue',
14
19
  VPFooter: 'src/components/FfFooter.vue',
15
- VPHomeSponsors: 'src/components/FfHomeSponsors.vue'
20
+ VPHomeSponsors: 'src/components/FfHomeSponsors.vue',
21
+ VPNavBarTitle: 'src/components/FfNavBarTitle.vue'
16
22
  };
17
23
 
18
24
  const alias = Object.entries(overrides).map(([
@@ -23,6 +29,157 @@ const alias = Object.entries(overrides).map(([
23
29
  replacement: resolve(dir, file)
24
30
  }));
25
31
 
32
+ /**
33
+ * 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
35
+ * use it ships no source text.
36
+ *
37
+ * A hook declared by the host replaces the one in this config instead of adding to it. A site that
38
+ * defines its own `transformPageData` calls this from it and returns the result:
39
+ * `transformPageData: (pageData, ctx) => ffTransformPageData(pageData, ctx)`.
40
+ *
41
+ * @param {import('vitepress').PageData} pageData
42
+ * @param {import('vitepress').TransformPageContext} ctx
43
+ */
44
+ export async function ffTransformPageData(pageData, { siteConfig }) {
45
+ if (!siteConfig.site.themeConfig?.ff?.copyMarkdown || !pageData.filePath) {
46
+ return;
47
+ }
48
+
49
+ try {
50
+ const source = await readFile(join(siteConfig.srcDir, pageData.filePath), 'utf8');
51
+
52
+ return {
53
+ ffMarkdown: source.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '').trim()
54
+ };
55
+ } catch {
56
+ // Virtual or generated page: there is no source file to copy.
57
+ }
58
+ }
59
+
60
+ /**
61
+ * Writes the files generated at the end of the build: `llms.txt` and `llms-full.txt`, the blog's
62
+ * `feed.xml` and the Open Graph images in `og/`, each only when its `themeConfig.ff` option is on.
63
+ *
64
+ * Like every hook, a `buildEnd` declared by the host replaces ours: call this from it.
65
+ *
66
+ * @param {import('vitepress').SiteConfig} siteConfig
67
+ */
68
+ export async function ffBuildEnd(siteConfig) {
69
+ const ff = siteConfig.site.themeConfig?.ff;
70
+
71
+ if (ff?.llms) {
72
+ await generateLlms(siteConfig);
73
+ }
74
+
75
+ if (ff?.blog?.rss) {
76
+ await generateRss(siteConfig);
77
+ }
78
+
79
+ if (ff?.og) {
80
+ await generateOg(siteConfig);
81
+ }
82
+ }
83
+
84
+ /**
85
+ * Head entries this theme adds: the accent preset and the banner scripts, which have to run before
86
+ * the first paint, the link to the blog's RSS feed, and the Open Graph and Twitter tags. A host declaring its own `transformHead` calls this from it and merges the
87
+ * result into its own entries.
88
+ *
89
+ * @param {import('vitepress').TransformContext} ctx
90
+ * @returns {import('vitepress').HeadConfig[]}
91
+ */
92
+ export function ffTransformHead({ siteData, siteConfig, page, pageData }) {
93
+ const ff = siteData.themeConfig?.ff;
94
+ const head = [];
95
+
96
+ if (ff?.preset) {
97
+ head.push([
98
+ 'script',
99
+ {},
100
+ `document.documentElement.dataset.ffPreset=${JSON.stringify(ff.preset)}`
101
+ ]);
102
+ }
103
+
104
+ if (ff?.banner?.id) {
105
+ const key = JSON.stringify(`ff-banner-${ff.banner.id}`);
106
+
107
+ head.push([
108
+ 'script',
109
+ {},
110
+ `try{if(localStorage.getItem(${key}))` +
111
+ 'document.documentElement.classList.add(\'ff-banner-dismissed\')}catch(e){}'
112
+ ]);
113
+ }
114
+
115
+ if (ff?.blog?.rss) {
116
+ head.push([
117
+ 'link',
118
+ {
119
+ rel: 'alternate',
120
+ type: 'application/rss+xml',
121
+ title: siteData.title,
122
+ href: `${siteData.base}feed.xml`
123
+ }
124
+ ]);
125
+ }
126
+
127
+ // The image itself is drawn by `ffBuildEnd`; the two must agree on its address and on which pages
128
+ // have one.
129
+ if (ff?.og && page !== '404.md' && pageData.frontmatter.og !== false) {
130
+ const { hostname } = ogOptions(siteConfig);
131
+ const title = pageData.title || siteData.title;
132
+ const description = pageData.description || siteData.description;
133
+
134
+ head.push(
135
+ [
136
+ 'meta',
137
+ {
138
+ property: 'og:title',
139
+ content: title
140
+ }
141
+ ],
142
+ [
143
+ 'meta',
144
+ {
145
+ property: 'og:description',
146
+ content: description
147
+ }
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
+ ]
177
+ );
178
+ }
179
+
180
+ return head;
181
+ }
182
+
26
183
  /**
27
184
  * Base config for `extends`, per
28
185
  * https://vitepress.dev/guide/custom-theme#distributing-a-custom-theme.
@@ -36,7 +193,9 @@ const alias = Object.entries(overrides).map(([
36
193
  * (e.g. on StackBlitz), because `dir` then points inside `node_modules`. `transformHead` injects
37
194
  * the inline script that keeps a dismissed banner from painting — it needs the banner id from the
38
195
  * host's own themeConfig, which is only known once VitePress has resolved the merged config, so it
39
- * cannot be a static head entry here.
196
+ * cannot be a static head entry here. The accent preset goes the same way, so it is on <html> before
197
+ * the first paint. `transformPageData` feeds the copy-as-Markdown button; see `ffTransformPageData`. `buildEnd` writes the generated files; see
198
+ * `ffBuildEnd`.
40
199
  */
41
200
  const config = {
42
201
  vite: {
@@ -62,24 +221,9 @@ const config = {
62
221
  }
63
222
  }
64
223
  },
65
- transformHead({ siteData }) {
66
- const id = siteData.themeConfig?.ff?.banner?.id;
67
-
68
- if (!id) {
69
- return [];
70
- }
71
-
72
- const key = JSON.stringify(`ff-banner-${id}`);
73
-
74
- return [
75
- [
76
- 'script',
77
- {},
78
- `try{if(localStorage.getItem(${key}))` +
79
- 'document.documentElement.classList.add(\'ff-banner-dismissed\')}catch(e){}'
80
- ]
81
- ];
82
- }
224
+ transformPageData: ffTransformPageData,
225
+ transformHead: ffTransformHead,
226
+ buildEnd: ffBuildEnd
83
227
  };
84
228
 
85
229
  export default config;