@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.
- package/CHANGELOG.md +83 -0
- package/README.md +163 -7
- package/config.d.ts +27 -1
- package/config.js +186 -21
- package/dist/style.css +1 -1
- package/node/blog.d.ts +3 -0
- package/node/blog.js +19 -0
- package/node/llms.js +32 -0
- package/node/og.js +158 -0
- package/node/pages.js +162 -0
- package/node/rss.js +78 -0
- package/package.json +42 -28
- package/src/blog/posts.data.ts +47 -0
- package/src/components/FfBackToTop.vue +19 -10
- package/src/components/FfBanner.vue +24 -6
- package/src/components/FfCopyStatus.vue +64 -0
- package/src/components/FfDocMeta.vue +325 -3
- package/src/components/FfFeature.vue +18 -7
- package/src/components/FfFeedback.vue +96 -0
- package/src/components/FfHero.vue +26 -35
- package/src/components/FfHeroActions.vue +44 -0
- package/src/components/FfHeroCommand.vue +22 -35
- package/src/components/FfHomeSponsors.vue +2 -2
- package/src/components/FfNavBarTitle.vue +63 -0
- package/src/components/FfPost.vue +50 -0
- package/src/components/FfProgress.vue +69 -0
- package/src/components/FfVersionSwitcher.vue +20 -0
- package/src/composables/blog.ts +41 -0
- package/src/composables/copy.ts +36 -0
- package/src/composables/options.ts +20 -1
- package/src/composables/tabs.ts +122 -0
- package/src/content/Api.vue +6 -2
- package/src/content/Badge.vue +26 -0
- package/src/content/Callout.vue +27 -0
- package/src/content/FileTree.vue +118 -0
- package/src/content/Tab.vue +11 -0
- package/src/content/Tabs.vue +95 -0
- package/src/content/Timeline.vue +19 -0
- package/src/content/TimelineItem.vue +37 -0
- package/src/content/timeline.ts +4 -0
- package/src/index.ts +37 -1
- package/src/internal.ts +8 -2
- package/src/layout/FfBlog.vue +62 -0
- package/src/layout/FfLayout.vue +20 -4
- package/src/styles/_base.scss +6 -14
- package/src/styles/_blocks.scss +29 -8
- package/src/styles/_blog.scss +130 -0
- package/src/styles/_breakpoints.scss +26 -0
- package/src/styles/_code.scss +11 -17
- package/src/styles/_content.scss +377 -18
- package/src/styles/_doc.scss +32 -29
- package/src/styles/_home.scss +47 -65
- package/src/styles/_mixins.scss +63 -0
- package/src/styles/_motion.scss +24 -13
- package/src/styles/_nav.scss +90 -24
- package/src/styles/_print.scss +77 -0
- package/src/styles/_sidebar.scss +7 -10
- package/src/styles/_tokens.scss +92 -11
- package/src/styles/index.scss +2 -0
- package/src/types.ts +148 -0
- package/types/blog/posts.data.d.ts +14 -0
- package/types/components/FfBackToTop.vue.d.ts +3 -0
- package/types/components/FfBanner.vue.d.ts +3 -0
- package/types/components/FfCopyStatus.vue.d.ts +3 -0
- package/types/components/FfDocMeta.vue.d.ts +3 -0
- package/types/components/FfFeature.vue.d.ts +13 -0
- package/types/components/FfFeedback.vue.d.ts +3 -0
- package/types/components/FfFooter.vue.d.ts +3 -0
- package/types/components/FfHero.vue.d.ts +42 -0
- package/types/components/FfHeroActions.vue.d.ts +19 -0
- package/types/components/FfHeroCommand.vue.d.ts +9 -0
- package/types/components/FfHomeSponsors.vue.d.ts +19 -0
- package/types/components/FfNavBarTitle.vue.d.ts +17 -0
- package/types/components/FfPost.vue.d.ts +3 -0
- package/types/components/FfProgress.vue.d.ts +3 -0
- package/types/components/FfVersionSwitcher.vue.d.ts +3 -0
- package/types/composables/blog.d.ts +10 -0
- package/types/composables/copy.d.ts +6 -0
- package/types/composables/link.d.ts +12 -0
- package/types/composables/options.d.ts +15 -0
- package/types/composables/relativeTime.d.ts +2 -0
- package/types/composables/tabs.d.ts +10 -0
- package/types/content/Api.vue.d.ts +27 -0
- package/types/content/Badge.vue.d.ts +21 -0
- package/types/content/Callout.vue.d.ts +24 -0
- package/types/content/Card.vue.d.ts +23 -0
- package/types/content/CardGrid.vue.d.ts +20 -0
- package/types/content/FileTree.vue.d.ts +6 -0
- package/types/content/Kbd.vue.d.ts +15 -0
- package/types/content/Steps.vue.d.ts +15 -0
- package/types/content/Tab.vue.d.ts +19 -0
- package/types/content/Tabs.vue.d.ts +7 -0
- package/types/content/Timeline.vue.d.ts +21 -0
- package/types/content/TimelineItem.vue.d.ts +21 -0
- package/types/content/timeline.d.ts +3 -0
- package/types/index.d.ts +25 -0
- package/types/internal.d.ts +10 -0
- package/types/layout/FfBlog.vue.d.ts +3 -0
- package/types/layout/FfLayout.vue.d.ts +23 -0
- 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,
|
|
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
|
|
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 {
|
|
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 {
|
|
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
|
-
|
|
66
|
-
|
|
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;
|