@frontfactory/vitepress-theme 1.7.0 → 1.9.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 (100) hide show
  1. package/CHANGELOG.md +83 -0
  2. package/README.md +163 -7
  3. package/config.d.ts +27 -1
  4. package/config.js +186 -21
  5. package/dist/style.css +1 -1
  6. package/node/blog.d.ts +3 -0
  7. package/node/blog.js +19 -0
  8. package/node/llms.js +32 -0
  9. package/node/og.js +158 -0
  10. package/node/pages.js +162 -0
  11. package/node/rss.js +78 -0
  12. package/package.json +42 -28
  13. package/src/blog/posts.data.ts +47 -0
  14. package/src/components/FfBackToTop.vue +19 -10
  15. package/src/components/FfBanner.vue +24 -6
  16. package/src/components/FfCopyStatus.vue +64 -0
  17. package/src/components/FfDocMeta.vue +325 -3
  18. package/src/components/FfFeature.vue +18 -7
  19. package/src/components/FfFeedback.vue +96 -0
  20. package/src/components/FfHero.vue +26 -35
  21. package/src/components/FfHeroActions.vue +44 -0
  22. package/src/components/FfHeroCommand.vue +22 -35
  23. package/src/components/FfHomeSponsors.vue +2 -2
  24. package/src/components/FfNavBarTitle.vue +63 -0
  25. package/src/components/FfPost.vue +50 -0
  26. package/src/components/FfProgress.vue +69 -0
  27. package/src/components/FfVersionSwitcher.vue +20 -0
  28. package/src/composables/blog.ts +41 -0
  29. package/src/composables/copy.ts +36 -0
  30. package/src/composables/options.ts +20 -1
  31. package/src/composables/tabs.ts +122 -0
  32. package/src/content/Api.vue +6 -2
  33. package/src/content/Badge.vue +26 -0
  34. package/src/content/Callout.vue +27 -0
  35. package/src/content/FileTree.vue +118 -0
  36. package/src/content/Tab.vue +11 -0
  37. package/src/content/Tabs.vue +95 -0
  38. package/src/content/Timeline.vue +19 -0
  39. package/src/content/TimelineItem.vue +37 -0
  40. package/src/content/timeline.ts +4 -0
  41. package/src/index.ts +37 -1
  42. package/src/internal.ts +8 -2
  43. package/src/layout/FfBlog.vue +62 -0
  44. package/src/layout/FfLayout.vue +20 -4
  45. package/src/styles/_base.scss +6 -14
  46. package/src/styles/_blocks.scss +29 -8
  47. package/src/styles/_blog.scss +130 -0
  48. package/src/styles/_breakpoints.scss +26 -0
  49. package/src/styles/_code.scss +11 -17
  50. package/src/styles/_content.scss +377 -18
  51. package/src/styles/_doc.scss +32 -29
  52. package/src/styles/_home.scss +47 -65
  53. package/src/styles/_mixins.scss +63 -0
  54. package/src/styles/_motion.scss +24 -13
  55. package/src/styles/_nav.scss +90 -24
  56. package/src/styles/_print.scss +77 -0
  57. package/src/styles/_sidebar.scss +7 -10
  58. package/src/styles/_tokens.scss +92 -11
  59. package/src/styles/index.scss +2 -0
  60. package/src/types.ts +148 -0
  61. package/types/blog/posts.data.d.ts +14 -0
  62. package/types/components/FfBackToTop.vue.d.ts +3 -0
  63. package/types/components/FfBanner.vue.d.ts +3 -0
  64. package/types/components/FfCopyStatus.vue.d.ts +3 -0
  65. package/types/components/FfDocMeta.vue.d.ts +3 -0
  66. package/types/components/FfFeature.vue.d.ts +13 -0
  67. package/types/components/FfFeedback.vue.d.ts +3 -0
  68. package/types/components/FfFooter.vue.d.ts +3 -0
  69. package/types/components/FfHero.vue.d.ts +42 -0
  70. package/types/components/FfHeroActions.vue.d.ts +19 -0
  71. package/types/components/FfHeroCommand.vue.d.ts +9 -0
  72. package/types/components/FfHomeSponsors.vue.d.ts +19 -0
  73. package/types/components/FfNavBarTitle.vue.d.ts +17 -0
  74. package/types/components/FfPost.vue.d.ts +3 -0
  75. package/types/components/FfProgress.vue.d.ts +3 -0
  76. package/types/components/FfVersionSwitcher.vue.d.ts +3 -0
  77. package/types/composables/blog.d.ts +10 -0
  78. package/types/composables/copy.d.ts +6 -0
  79. package/types/composables/link.d.ts +12 -0
  80. package/types/composables/options.d.ts +15 -0
  81. package/types/composables/relativeTime.d.ts +2 -0
  82. package/types/composables/tabs.d.ts +10 -0
  83. package/types/content/Api.vue.d.ts +27 -0
  84. package/types/content/Badge.vue.d.ts +21 -0
  85. package/types/content/Callout.vue.d.ts +24 -0
  86. package/types/content/Card.vue.d.ts +23 -0
  87. package/types/content/CardGrid.vue.d.ts +20 -0
  88. package/types/content/FileTree.vue.d.ts +6 -0
  89. package/types/content/Kbd.vue.d.ts +15 -0
  90. package/types/content/Steps.vue.d.ts +15 -0
  91. package/types/content/Tab.vue.d.ts +19 -0
  92. package/types/content/Tabs.vue.d.ts +7 -0
  93. package/types/content/Timeline.vue.d.ts +21 -0
  94. package/types/content/TimelineItem.vue.d.ts +21 -0
  95. package/types/content/timeline.d.ts +3 -0
  96. package/types/index.d.ts +25 -0
  97. package/types/internal.d.ts +10 -0
  98. package/types/layout/FfBlog.vue.d.ts +3 -0
  99. package/types/layout/FfLayout.vue.d.ts +23 -0
  100. package/types/types.d.ts +280 -0
package/CHANGELOG.md CHANGED
@@ -2,6 +2,89 @@
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.9.0](https://github.com/front-factory/vitepress-theme/compare/v1.8.0...v1.9.0) (2026-11-15)
6
+
7
+ ### Features
8
+
9
+ * **doc-meta:** turn copy as Markdown into a page actions menu ([2e32e53](https://github.com/front-factory/vitepress-theme/commit/2e32e534330d6de309cacfc27ff10e6cf85dc6b5))
10
+ * **i18n:** add returnToTop and codeCopied labels ([0d9f925](https://github.com/front-factory/vitepress-theme/commit/0d9f925d6370c1b855f27626f8d5f0539d0cb2a2))
11
+
12
+ ### Bug Fixes
13
+
14
+ * **a11y:** stop focus from reshaping elements ([382ce06](https://github.com/front-factory/vitepress-theme/commit/382ce062730c9ceeabe60246fb8da5afe6e9a506))
15
+ * **blog:** ignore posts with an unparsable date ([3211660](https://github.com/front-factory/vitepress-theme/commit/321166074e777ce994845f4cffe6da17db07e7c0))
16
+ * **blog:** resolve author avatar and link against the base ([511647e](https://github.com/front-factory/vitepress-theme/commit/511647eaf6a3ddd3801dd6bc10d9f6ca7bb333f9))
17
+ * **blog:** skip the post header on the blog index ([fc594ff](https://github.com/front-factory/vitepress-theme/commit/fc594ff7b26352c7ad5c534ee4696991384ad90f))
18
+ * **hero:** open external actions in a new tab ([da62b11](https://github.com/front-factory/vitepress-theme/commit/da62b11630428aa0cfb5a537ef7c188695cafd05))
19
+ * **layout:** read forwarded slots on each render ([0937b2c](https://github.com/front-factory/vitepress-theme/commit/0937b2cfbe338f62be5b6ee3cdd3d37a2a8db4ec))
20
+ * **motion:** keep pager title on the slow transition ([b275606](https://github.com/front-factory/vitepress-theme/commit/b2756067413e60abac433b31dc00b9257c27c1ed))
21
+ * **motion:** transition the feedback button hover ([8e851f6](https://github.com/front-factory/vitepress-theme/commit/8e851f62bbad9d3994a74748bdce31591484f9ea))
22
+ * **og:** name images after the rewritten page path ([9de4a0e](https://github.com/front-factory/vitepress-theme/commit/9de4a0eb860c2cd090ed89797815cf6095f6cfaa))
23
+ * **og:** omit image tags for pages without a source file ([20d80b6](https://github.com/front-factory/vitepress-theme/commit/20d80b69e41be764e49b73bad726555f13f26c2b))
24
+ * **tabs:** key tab buttons by index ([7d25828](https://github.com/front-factory/vitepress-theme/commit/7d2582870e22b8e77e15ab179ffad595dff3e61a))
25
+ * **tabs:** reset the selection only when the labels change ([d688e50](https://github.com/front-factory/vitepress-theme/commit/d688e505ef81ae39d6ce16bed4eac107e63406b2))
26
+ * **types:** type ffTransformHead with the theme config ([963a48a](https://github.com/front-factory/vitepress-theme/commit/963a48a0add5e911f90bfa73280d8f0eea403789))
27
+
28
+ ### Performance
29
+
30
+ * **build:** read and parse pages once for all generators ([0a3220c](https://github.com/front-factory/vitepress-theme/commit/0a3220c9a68e69ccbd6d213377b70c5eebb28e43))
31
+ * **tabs:** read the slot once per render in the template ([054b33d](https://github.com/front-factory/vitepress-theme/commit/054b33dc8a9567b85d30a7abacb95874f5437c78))
32
+
33
+ ## [1.8.0](https://github.com/front-factory/vitepress-theme/compare/v1.7.0...v1.8.0) (2026-11-04)
34
+
35
+ ### Features
36
+
37
+ * **blog:** add a blog layout with rss feed ([6025542](https://github.com/front-factory/vitepress-theme/commit/60255428b91af2591e48f597c688b9be16547b89))
38
+ * **build:** generate llms.txt ([667dbda](https://github.com/front-factory/vitepress-theme/commit/667dbdaa1e4e8685aff3cda9fe1e01b5a441f24d))
39
+ * **build:** generate open graph images ([b6c2491](https://github.com/front-factory/vitepress-theme/commit/b6c249178798df1cadda134505e009d02d25a47a))
40
+ * **content:** add a Callout component ([928e3b0](https://github.com/front-factory/vitepress-theme/commit/928e3b0400e6ee2ab21e0851211270c647f18eab))
41
+ * **content:** add a FileTree component ([00fca33](https://github.com/front-factory/vitepress-theme/commit/00fca331a234b7d038efe490a52c37496387ab3c))
42
+ * **content:** add new, beta, deprecated and since badge variants ([f252ec6](https://github.com/front-factory/vitepress-theme/commit/f252ec640c34bb3fdb361ab8925fcf873b17c397))
43
+ * **content:** add Tabs and Tab components ([ecb0aff](https://github.com/front-factory/vitepress-theme/commit/ecb0aff234c620d927832e1d93f8ed77b994dada))
44
+ * **content:** add Timeline and TimelineItem components ([0ed25c0](https://github.com/front-factory/vitepress-theme/commit/0ed25c0e8f38f5226871178f33b5c31fbe898436))
45
+ * **doc:** add a copy-as-markdown button ([5de1450](https://github.com/front-factory/vitepress-theme/commit/5de1450a835b17ac42eb71f812569cb8755d12f2))
46
+ * **doc:** add a page feedback widget ([4efd586](https://github.com/front-factory/vitepress-theme/commit/4efd5861312f3d23f4e7926cb3c3940ddf5df072))
47
+ * **i18n:** route banner CTA and API tags through theme labels ([cfff3f9](https://github.com/front-factory/vitepress-theme/commit/cfff3f9408bbd59a376e454f3ed8abaa3ab3f024))
48
+ * **layout:** add a reading progress bar ([e524519](https://github.com/front-factory/vitepress-theme/commit/e5245199deb281c0e3101569d9be7a30cb4a6d83))
49
+ * **layout:** add a wide doc layout ([2cf68f8](https://github.com/front-factory/vitepress-theme/commit/2cf68f89dbb0c7ce6b0295fddf4b5ba3a4b9b276))
50
+ * **nav:** add a version switcher ([fd26deb](https://github.com/front-factory/vitepress-theme/commit/fd26deb1d3bd56950518485d1166416bca4d328a))
51
+ * **styles:** add print styles ([2ff9899](https://github.com/front-factory/vitepress-theme/commit/2ff9899f6c88c7c337dfd06d30145a12def94a65))
52
+ * **theme:** add accent presets ([97c38cc](https://github.com/front-factory/vitepress-theme/commit/97c38cc382045b2a3c62f09b4b06f920ac203d39))
53
+ * **timeline:** add a level prop for entry headings ([82476b9](https://github.com/front-factory/vitepress-theme/commit/82476b9a94f1e92c7c638e1dc3665af0400e2e7c))
54
+ * **tokens:** add an enter duration token for the hero animation ([13d9e19](https://github.com/front-factory/vitepress-theme/commit/13d9e19875075e3734a8c725751b25dded21020d))
55
+
56
+ ### Bug Fixes
57
+
58
+ * **a11y:** announce code block copies to screen readers ([83b45a3](https://github.com/front-factory/vitepress-theme/commit/83b45a38c83ecc2651b647afba56a4184829116d))
59
+ * **a11y:** expose the hero command switcher as tabs ([90bd51c](https://github.com/front-factory/vitepress-theme/commit/90bd51c25b4ae75f4d9ea749456067380cbec6ce))
60
+ * **a11y:** hand focus to the skip link when the banner is dismissed ([4c455f5](https://github.com/front-factory/vitepress-theme/commit/4c455f58de5b9247adcb1fd596899aed207254ba))
61
+ * **a11y:** include the current version in the version switcher name ([73ef48b](https://github.com/front-factory/vitepress-theme/commit/73ef48be2c306bd9086fda0ac4a01216d34956b9))
62
+ * **a11y:** link only the feature title, stretched over the card ([d55d946](https://github.com/front-factory/vitepress-theme/commit/d55d946c302273d27fc22ce2632da1dc9eff01fb))
63
+ * **a11y:** make doc link underline visible by default ([a45d78c](https://github.com/front-factory/vitepress-theme/commit/a45d78c539c0689d0962a1154ab0d96e887f900d))
64
+ * **a11y:** move focus to the thank-you line after a feedback vote ([990577b](https://github.com/front-factory/vitepress-theme/commit/990577b70d3f2a08485adbdb32a7c7ea0bb31955))
65
+ * align vite peer range with the one vitepress 2 requires ([e5da335](https://github.com/front-factory/vitepress-theme/commit/e5da3351a7106fd7ba9a0bb464be778dff192289))
66
+ * **blog:** annotate posts loader type to fix declaration build ([5a422c3](https://github.com/front-factory/vitepress-theme/commit/5a422c37002d7df04d87adc254e344109b5d7b1c))
67
+ * **code:** keep removed diff lines at full opacity for contrast ([0d1956c](https://github.com/front-factory/vitepress-theme/commit/0d1956cee66bc93e1369f8991b610ea796a26b92))
68
+ * **code:** keep the copy button fully opaque for non-text contrast ([a94e45b](https://github.com/front-factory/vitepress-theme/commit/a94e45b5b38f3482e9a09a7727e22394468542f7))
69
+ * **dark:** add shadow tokens with a dark scheme variant ([742b858](https://github.com/front-factory/vitepress-theme/commit/742b8584736088ff339cd4fdceed6bf11d3bb8ed))
70
+ * make vite a required peer dependency ([08b0df4](https://github.com/front-factory/vitepress-theme/commit/08b0df4f436b696ded556a6192874013fc426797))
71
+ * **motion:** honour reduced motion on the nav underline ([cf70693](https://github.com/front-factory/vitepress-theme/commit/cf706934a8295e1cac2b3f770b992cbf62fb6c49))
72
+ * observe banner height when it mounts after the layout ([27949c6](https://github.com/front-factory/vitepress-theme/commit/27949c6b14dda17b53a716f8dd4fd989d44a72af))
73
+ * resolve hero, banner and sponsors links against site base ([2f1ed04](https://github.com/front-factory/vitepress-theme/commit/2f1ed043c7b653e2a632cb495f362896a8886f41))
74
+ * **responsive:** align content breakpoints on 640px without overlap ([66d5e34](https://github.com/front-factory/vitepress-theme/commit/66d5e34032a9e5c4cfa061c390de0041a197f1ab))
75
+ * ship generated type declarations instead of raw sources ([6aafc8d](https://github.com/front-factory/vitepress-theme/commit/6aafc8d11184f58fd90f7fbbcb161580ca4fa127))
76
+
77
+ ### Performance
78
+
79
+ * only listen to scroll and measure the page when their option is on ([9a14af7](https://github.com/front-factory/vitepress-theme/commit/9a14af7a9397572eba7478726185145e9d634716))
80
+ * render the hero image slot once per render ([684d78e](https://github.com/front-factory/vitepress-theme/commit/684d78e8e35b29c002be0ccd0ca125cbb1dca2dc))
81
+ * stop the hero glow animation while the glow is disabled ([2ea95f5](https://github.com/front-factory/vitepress-theme/commit/2ea95f556cf9966b348b3c81f780297d93b6ea8d))
82
+
83
+ ### Dependencies
84
+
85
+ * **deps:** add feed as an optional peer dependency ([198d81e](https://github.com/front-factory/vitepress-theme/commit/198d81e9d44eba4c92e39b0c4f468f7c85262822))
86
+ * **deps:** add satori and resvg as optional peer dependencies ([5e8fefa](https://github.com/front-factory/vitepress-theme/commit/5e8fefa242b8b0b870e30af22294ee7f72aa840c))
87
+
5
88
  ## [1.7.0](https://github.com/front-factory/vitepress-theme/compare/v1.6.0...v1.7.0) (2026-10-11)
6
89
 
7
90
  ### 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,10 +127,19 @@ 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.
139
+ // Each item defaults to true; set it to false to hide just that item.
129
140
  meta: {
130
141
  section: true, // section name, read from the sidebar
131
- readingTime: true,
142
+ readingTime: true, // reading-time estimate
132
143
  wordsPerMinute: 200,
133
144
  lastUpdated: true // needs `lastUpdated: true` in the site config
134
145
  },
@@ -141,13 +152,56 @@ themeConfig: {
141
152
  // Column of `themeConfig.socialLinks` icons, pinned to the right of those columns.
142
153
  footerSocial: true,
143
154
 
144
- backToTop: true
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
+ }
145
190
  }
146
191
  }
147
192
  ```
148
193
 
149
- Per page, `docMeta: false` in the frontmatter drops the kicker, and `section: Guide` overrides the
150
- section name.
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
+ ```
151
205
 
152
206
  Banner text, hero title/tagline/quote, feature title/details, footer message/copyright and card icon
153
207
  all render as HTML (`v-html`), not escaped text — a `<strong>` or a hand-written `<a>` in any of them
@@ -156,6 +210,87 @@ from whoever writes `themeConfig.ff` in the VitePress config, not from a reader,
156
210
  field someone else can edit. If a site ever pipes such input into these fields, sanitize it before it
157
211
  reaches the config — the theme does not.
158
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
+
159
294
  ## Translating
160
295
 
161
296
  Every string the theme adds sits in `themeConfig.ff.labels`, so it is translated the same way as any
@@ -201,9 +336,25 @@ locales: {
201
336
  | `newTab` | `opens in a new tab` |
202
337
  | `sponsors` | `Sponsors` |
203
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` |
204
355
 
205
356
  The banner's own `text` and `linkText` are content, not labels, so they stay under `ff.banner`. The
206
- back-to-top tooltip reuses the default theme's `returnToTopLabel`, and the last-updated stamp is
357
+ back-to-top tooltip reuses the default theme's `returnToTopLabel` when set (otherwise `returnToTop`), and the last-updated stamp is
207
358
  formatted with `Intl.RelativeTimeFormat` in the page's own `lang`.
208
359
 
209
360
  ## Home page
@@ -284,8 +435,13 @@ Registered globally, no import needed.
284
435
  | Component | Use |
285
436
  |--------------------------------------------------|---------------------------------------------------|
286
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 |
287
439
  | `<CardGrid :columns>` / `<Card title icon link>` | Card grids |
288
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 |
289
445
  | `<Kbd>` | A key |
290
446
 
291
447
  ## Version
package/config.d.ts CHANGED
@@ -1,6 +1,32 @@
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.pageActions` enables the Markdown copy (or the deprecated `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: 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
28
+ * `transformHead` and merge the result with your entries.
29
+ */
30
+ export declare function ffTransformHead(ctx: TransformContext<ThemeConfig>): HeadConfig[];
31
+
6
32
  export default config;
package/config.js CHANGED
@@ -1,5 +1,12 @@
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 {
7
+ hasSource, ogOptions, ogSlug, readPages
8
+ } from './node/pages.js';
9
+ import { generateRss } from './node/rss.js';
3
10
 
4
11
  const dir = import.meta.dirname;
5
12
  const pkg = '@frontfactory/vitepress-theme';
@@ -12,7 +19,8 @@ const overrides = {
12
19
  VPHero: 'src/components/FfHero.vue',
13
20
  VPFeature: 'src/components/FfFeature.vue',
14
21
  VPFooter: 'src/components/FfFooter.vue',
15
- VPHomeSponsors: 'src/components/FfHomeSponsors.vue'
22
+ VPHomeSponsors: 'src/components/FfHomeSponsors.vue',
23
+ VPNavBarTitle: 'src/components/FfNavBarTitle.vue'
16
24
  };
17
25
 
18
26
  const alias = Object.entries(overrides).map(([
@@ -23,6 +31,176 @@ const alias = Object.entries(overrides).map(([
23
31
  replacement: resolve(dir, file)
24
32
  }));
25
33
 
34
+ /**
35
+ * Stores the page's Markdown source, frontmatter stripped, on `pageData.ffMarkdown` for the "copy as
36
+ * Markdown" button. Does nothing unless `themeConfig.ff.pageActions` enables it (or the deprecated
37
+ * `copyMarkdown` is on), so a site that does not
38
+ * use it ships no source text.
39
+ *
40
+ * A hook declared by the host replaces the one in this config instead of adding to it. A site that
41
+ * defines its own `transformPageData` calls this from it and returns the result:
42
+ * `transformPageData: (pageData, ctx) => ffTransformPageData(pageData, ctx)`.
43
+ *
44
+ * @param {import('vitepress').PageData} pageData
45
+ * @param {import('vitepress').TransformPageContext} ctx
46
+ */
47
+ export async function ffTransformPageData(pageData, { siteConfig }) {
48
+ const { pageActions, copyMarkdown } = siteConfig.site.themeConfig?.ff ?? {};
49
+
50
+ if (
51
+ !(pageActions === true || pageActions?.copyMarkdown || copyMarkdown) ||
52
+ !pageData.filePath
53
+ ) {
54
+ return;
55
+ }
56
+
57
+ try {
58
+ const source = await readFile(join(siteConfig.srcDir, pageData.filePath), 'utf8');
59
+
60
+ return {
61
+ ffMarkdown: source.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '').trim()
62
+ };
63
+ } catch {
64
+ // Virtual or generated page: there is no source file to copy.
65
+ }
66
+ }
67
+
68
+ /**
69
+ * Writes the files generated at the end of the build: `llms.txt` and `llms-full.txt`, the blog's
70
+ * `feed.xml` and the Open Graph images in `og/`, each only when its `themeConfig.ff` option is on.
71
+ *
72
+ * Like every hook, a `buildEnd` declared by the host replaces ours: call this from it.
73
+ *
74
+ * @param {import('vitepress').SiteConfig} siteConfig
75
+ */
76
+ export async function ffBuildEnd(siteConfig) {
77
+ const ff = siteConfig.site.themeConfig?.ff;
78
+
79
+ if (!ff?.llms && !ff?.blog?.rss && !ff?.og) {
80
+ return;
81
+ }
82
+
83
+ // Read once and shared: every generator needs the same parsed pages.
84
+ const pages = await readPages(siteConfig);
85
+
86
+ if (ff.llms) {
87
+ await generateLlms(siteConfig, pages);
88
+ }
89
+
90
+ if (ff.blog?.rss) {
91
+ await generateRss(siteConfig, pages);
92
+ }
93
+
94
+ if (ff.og) {
95
+ await generateOg(siteConfig, pages);
96
+ }
97
+ }
98
+
99
+ /**
100
+ * Head entries this theme adds: the accent preset and the banner scripts, which have to run before
101
+ * 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
102
+ * result into its own entries.
103
+ *
104
+ * @param {import('vitepress').TransformContext} ctx
105
+ * @returns {import('vitepress').HeadConfig[]}
106
+ */
107
+ export function ffTransformHead({ siteData, siteConfig, page, pageData }) {
108
+ const ff = siteData.themeConfig?.ff;
109
+ const head = [];
110
+
111
+ if (ff?.preset) {
112
+ head.push([
113
+ 'script',
114
+ {},
115
+ `document.documentElement.dataset.ffPreset=${JSON.stringify(ff.preset)}`
116
+ ]);
117
+ }
118
+
119
+ if (ff?.banner?.id) {
120
+ const key = JSON.stringify(`ff-banner-${ff.banner.id}`);
121
+
122
+ head.push([
123
+ 'script',
124
+ {},
125
+ `try{if(localStorage.getItem(${key}))` +
126
+ 'document.documentElement.classList.add(\'ff-banner-dismissed\')}catch(e){}'
127
+ ]);
128
+ }
129
+
130
+ if (ff?.blog?.rss) {
131
+ head.push([
132
+ 'link',
133
+ {
134
+ rel: 'alternate',
135
+ type: 'application/rss+xml',
136
+ title: siteData.title,
137
+ href: `${siteData.base}feed.xml`
138
+ }
139
+ ]);
140
+ }
141
+
142
+ // The image itself is drawn by `ffBuildEnd`; the two must agree on its address and on which pages
143
+ // have one.
144
+ if (ff?.og && page !== '404.md' && pageData.frontmatter.og !== false) {
145
+ const { hostname } = ogOptions(siteConfig);
146
+ const title = pageData.title || siteData.title;
147
+ const description = pageData.description || siteData.description;
148
+
149
+ head.push(
150
+ [
151
+ 'meta',
152
+ {
153
+ property: 'og:title',
154
+ content: title
155
+ }
156
+ ],
157
+ [
158
+ 'meta',
159
+ {
160
+ property: 'og:description',
161
+ content: description
162
+ }
163
+ ]
164
+ );
165
+
166
+ // No source file, no image drawn: leave out the tags that point to it.
167
+ if (pageData.filePath && hasSource(siteConfig, pageData.filePath)) {
168
+ head.push(
169
+ [
170
+ 'meta',
171
+ {
172
+ property: 'og:image',
173
+ content: `${hostname}${siteData.base}og/${ogSlug(page)}.png`
174
+ }
175
+ ],
176
+ [
177
+ 'meta',
178
+ {
179
+ property: 'og:image:width',
180
+ content: '1200'
181
+ }
182
+ ],
183
+ [
184
+ 'meta',
185
+ {
186
+ property: 'og:image:height',
187
+ content: '630'
188
+ }
189
+ ],
190
+ [
191
+ 'meta',
192
+ {
193
+ name: 'twitter:card',
194
+ content: 'summary_large_image'
195
+ }
196
+ ]
197
+ );
198
+ }
199
+ }
200
+
201
+ return head;
202
+ }
203
+
26
204
  /**
27
205
  * Base config for `extends`, per
28
206
  * https://vitepress.dev/guide/custom-theme#distributing-a-custom-theme.
@@ -36,7 +214,9 @@ const alias = Object.entries(overrides).map(([
36
214
  * (e.g. on StackBlitz), because `dir` then points inside `node_modules`. `transformHead` injects
37
215
  * the inline script that keeps a dismissed banner from painting — it needs the banner id from the
38
216
  * 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.
217
+ * cannot be a static head entry here. The accent preset goes the same way, so it is on <html> before
218
+ * the first paint. `transformPageData` feeds the copy-as-Markdown button; see `ffTransformPageData`. `buildEnd` writes the generated files; see
219
+ * `ffBuildEnd`.
40
220
  */
41
221
  const config = {
42
222
  vite: {
@@ -62,24 +242,9 @@ const config = {
62
242
  }
63
243
  }
64
244
  },
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
- }
245
+ transformPageData: ffTransformPageData,
246
+ transformHead: ffTransformHead,
247
+ buildEnd: ffBuildEnd
83
248
  };
84
249
 
85
250
  export default config;