@frontfactory/vitepress-theme 1.0.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/LICENSE.md ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Front Factory
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,260 @@
1
+ # @frontfactory/vitepress-theme
2
+
3
+ Editorial VitePress theme — hairline rules, numbered sections and monospaced metadata. One accent
4
+ token to make it yours.
5
+
6
+ It extends the VitePress default theme rather than forking it: search, i18n, mobile navigation and
7
+ every markdown feature keep working, while the whole surface is redrawn.
8
+
9
+ ## Install
10
+
11
+ ```bash
12
+ npm install @frontfactory/vitepress-theme
13
+ ```
14
+
15
+ Requires Node 20+, `vitepress` 2 and `vue` 3.5 in the host project. Nothing else — the stylesheet is
16
+ shipped compiled, so Sass is not needed downstream.
17
+
18
+ ## Use
19
+
20
+ ```ts
21
+ // .vitepress/config.ts
22
+ import { defineConfig } from 'vitepress'
23
+ import baseConfig from '@frontfactory/vitepress-theme/config'
24
+
25
+ export default defineConfig({
26
+ extends: baseConfig,
27
+ title: 'My project',
28
+ themeConfig: {
29
+ nav: [{ text: 'Guide', link: '/guide/' }]
30
+ }
31
+ })
32
+ ```
33
+
34
+ ```ts
35
+ // .vitepress/theme/index.ts
36
+ import Theme from '@frontfactory/vitepress-theme'
37
+
38
+ export default Theme
39
+ ```
40
+
41
+ `extends: baseConfig` is required: it swaps the components the theme replaces, keeps the package out
42
+ of dependency pre-bundling, and injects the inline script that keeps a dismissed banner from
43
+ painting in the built site.
44
+
45
+ ## Rebranding
46
+
47
+ Every value is a `--ff-*` custom property. Point the accent at your own colour and the whole site
48
+ follows.
49
+
50
+ ```css
51
+ /* .vitepress/theme/custom.css, imported after the theme */
52
+ :root {
53
+ --ff-color-accent: #0071d7;
54
+ --ff-color-accent-hover: #0058a8;
55
+ --ff-color-accent-soft: rgb(0 113 215 / 9%);
56
+ }
57
+
58
+ .dark {
59
+ --ff-color-accent: #58baff;
60
+ --ff-color-accent-hover: #8ed0ff;
61
+ --ff-color-accent-contrast: #06121e;
62
+ }
63
+ ```
64
+
65
+ | Token | Role |
66
+ |-----------------------------------------------|-----------------------------------------|
67
+ | `--ff-color-paper` | Page background |
68
+ | `--ff-color-surface` | Raised surfaces: code, cards, keys |
69
+ | `--ff-color-surface-alt` | Inline code, switches |
70
+ | `--ff-color-ink` | Body text |
71
+ | `--ff-color-ink-muted` | Secondary text |
72
+ | `--ff-color-ink-faint` | Labels and metadata |
73
+ | `--ff-color-rule` | Hairlines |
74
+ | `--ff-color-rule-strong` | Emphasised rules and borders |
75
+ | `--ff-color-accent` | The one brand colour |
76
+ | `--ff-color-success` / `-warning` / `-danger` | Status colours |
77
+ | `--ff-font-display` | Headings, titles, card and pager titles |
78
+ | `--ff-font-mono` | Labels, metadata, code |
79
+ | `--ff-size-hero` / `-h1` / `-h2` / `-h3` | Type scale |
80
+ | `--ff-layout-content` | Reading measure |
81
+ | `--ff-layout-wide` | Home and container width |
82
+ | `--ff-radius-sm` / `-md` | Corner radii |
83
+ | `--ff-rule-width` / `--ff-rule-accent-width` | Rule weights |
84
+
85
+ `dist/style.css` lists them all, grouped, at the top of the file.
86
+
87
+ ## Options
88
+
89
+ Theme options live under `themeConfig.ff`.
90
+
91
+ ```ts
92
+ themeConfig: {
93
+ ff: {
94
+ // Dismissible bar above the navigation. Change the id to bring it back.
95
+ banner: {
96
+ id: 'v5',
97
+ text: 'Version 5 is out.',
98
+ link: '/whats-new',
99
+ linkText: 'Read the notes'
100
+ },
101
+
102
+ // Kicker printed above every page title. Set to false to drop it.
103
+ meta: {
104
+ section: true, // section name, read from the sidebar
105
+ readingTime: true,
106
+ wordsPerMinute: 200,
107
+ lastUpdated: true // needs `lastUpdated: true` in the site config
108
+ },
109
+
110
+ // Link columns in the site footer (home and page layouts).
111
+ footerColumns: [
112
+ { title: 'Docs', items: [{ text: 'Guide', link: '/guide/' }] }
113
+ ],
114
+
115
+ backToTop: true
116
+ }
117
+ }
118
+ ```
119
+
120
+ Per page, `docMeta: false` in the frontmatter drops the kicker, and `section: Guide` overrides the
121
+ section name.
122
+
123
+ ## Translating
124
+
125
+ Every string the theme adds sits in `themeConfig.ff.labels`, so it is translated the same way as any
126
+ default-theme label: per locale. `{0}` is replaced by the value the label describes.
127
+
128
+ ```ts
129
+ locales: {
130
+ root: { label: 'English', lang: 'en' },
131
+ fr: {
132
+ label: 'Français',
133
+ lang: 'fr',
134
+ themeConfig: {
135
+ returnToTopLabel: 'Retour en haut',
136
+ ff: {
137
+ banner: { id: 'v5', text: 'La version 5 est sortie.', linkText: 'Lire les notes' },
138
+ labels: {
139
+ bannerDismiss: 'Fermer l\u2019annonce',
140
+ readingTime: '{0} min de lecture',
141
+ lastUpdated: 'Mis à jour {0}',
142
+ heroInstall: 'Installation',
143
+ heroCopy: 'Copier',
144
+ heroCopied: 'Copié',
145
+ heroCopyLabel: 'Copier {0}',
146
+ backToTop: 'Haut'
147
+ }
148
+ }
149
+ }
150
+ }
151
+ }
152
+ ```
153
+
154
+ | Label | Default |
155
+ |-------------------|-------------------------|
156
+ | `bannerDismiss` | `Dismiss announcement` |
157
+ | `readingTime` | `{0} min read` |
158
+ | `lastUpdated` | `Updated {0}` |
159
+ | `heroInstall` | `Install` |
160
+ | `heroCopy` | `Copy` |
161
+ | `heroCopied` | `Copied` |
162
+ | `heroCopyLabel` | `Copy {0}` |
163
+ | `backToTop` | `Top` |
164
+
165
+ The banner's own `text` and `linkText` are content, not labels, so they stay under `ff.banner`. The
166
+ back-to-top tooltip reuses the default theme's `returnToTopLabel`, and the last-updated stamp is
167
+ formatted with `Intl.RelativeTimeFormat` in the page's own `lang`.
168
+
169
+ ## Home page
170
+
171
+ Standard VitePress home frontmatter, read with an editorial hierarchy: `hero.name` becomes the
172
+ kicker, `hero.text` the headline. Two additions fill the page out.
173
+
174
+ `hero.command` puts an install panel in the second column of the hero, carrying the command and the
175
+ actions. It is used only when the page has no `hero.image` and nothing filled the `home-hero-image`
176
+ slot — an image still takes that column. `hero.meta` prints a colophon strip under the hero. Both
177
+ are typed by the exported `HeroExtras` interface.
178
+
179
+ ```yaml
180
+ ---
181
+ layout: home
182
+
183
+ hero:
184
+ name: My project
185
+ text: A headline that carries the page.
186
+ tagline: One or two sentences of standfirst.
187
+ command: npm install my-project
188
+ meta:
189
+ - label: Licence
190
+ value: MIT
191
+ - label: Version
192
+ value: 1.4.x
193
+ - label: Dependencies
194
+ value: None
195
+ actions:
196
+ - theme: brand
197
+ text: Get started
198
+ link: /guide/
199
+ features:
200
+ - title: Numbered automatically
201
+ details: Feature cells count themselves.
202
+ ---
203
+ ```
204
+
205
+ ## Markdown components
206
+
207
+ Registered globally, no import needed.
208
+
209
+ | Component | Use |
210
+ |--------------------------------------------------|---------------------------------------------------|
211
+ | `<Api name kind signature since deprecated>` | An API entry: ruled heading, monospaced signature |
212
+ | `<CardGrid :columns>` / `<Card title icon link>` | Card grids |
213
+ | `<Steps>` | Wraps an ordered list into a numbered rail |
214
+ | `<Kbd>` | A key |
215
+
216
+ ## Version
217
+
218
+ The theme tracks the VitePress 2 alphas closely — the default theme is still being restructured
219
+ between them, and the layout overrides here are written against the version in `peerDependencies`.
220
+ Keep the host project on the same alpha.
221
+
222
+ If a change to the theme does not show up, suspect a stale Vite cache before suspecting the CSS: the
223
+ stylesheet is a built file living outside the site root, so `.vitepress/cache` can keep serving an
224
+ old copy. Delete it and restart. In the browser,
225
+ `getComputedStyle(document.documentElement).getPropertyValue('--ff-layout-wide')` tells you which
226
+ stylesheet you are actually looking at.
227
+
228
+ ## Developing locally
229
+
230
+ ```bash
231
+ npm install
232
+ npm run dev # rebuilds dist/style.css on change
233
+ npm run dev:playground # builds the stylesheet, then serves the demo site
234
+ npm run typecheck # vue-tsc over the components and the config types
235
+ ```
236
+
237
+ `src/index.ts` imports `dist/style.css`, so the stylesheet has to exist before anything can start;
238
+ both playground scripts build it first. Run `npm run dev` alongside to keep it rebuilding on change.
239
+
240
+ The playground under `playground/` exercises the whole surface: home, doc pages, every markdown
241
+ feature and every component.
242
+
243
+ To try it against a real site, link it:
244
+
245
+ ```bash
246
+ # in this repo
247
+ npm link
248
+
249
+ # in the docs repo
250
+ npm link @frontfactory/vitepress-theme
251
+ ```
252
+
253
+ ## Publishing
254
+
255
+ `npm publish` runs the stylesheet build through `prepack`. The package ships Vue and TypeScript
256
+ sources plus the compiled CSS; the host project compiles the components with its own Vite.
257
+
258
+ ## Licence
259
+
260
+ MIT
package/config.d.ts ADDED
@@ -0,0 +1,6 @@
1
+ import type { UserConfig } from 'vitepress'
2
+ import type { ThemeConfig } from './src/types'
3
+
4
+ declare const config: UserConfig<ThemeConfig>
5
+
6
+ export default config
package/config.js ADDED
@@ -0,0 +1,54 @@
1
+ import { resolve } from 'node:path'
2
+
3
+ const dir = import.meta.dirname
4
+ const pkg = '@frontfactory/vitepress-theme'
5
+
6
+ /**
7
+ * Default theme components this theme replaces wholesale. VitePress resolves them by path, so the
8
+ * swap happens through a Vite alias.
9
+ */
10
+ const overrides = {
11
+ VPHero: 'src/components/FfHero.vue',
12
+ VPFeature: 'src/components/FfFeature.vue',
13
+ VPFooter: 'src/components/FfFooter.vue'
14
+ }
15
+
16
+ const alias = Object.entries(overrides).map(([name, file]) => ({
17
+ find: new RegExp(`^.*\\/${name}\\.vue$`),
18
+ replacement: resolve(dir, file)
19
+ }))
20
+
21
+ /**
22
+ * Base config for `extends`, per
23
+ * https://vitepress.dev/guide/custom-theme#distributing-a-custom-theme.
24
+ *
25
+ * Swaps the components the theme replaces, keeps the package out of dependency pre-bundling and
26
+ * SSR externalisation, and lets Vite serve a locally linked checkout. `transformHead` injects the
27
+ * inline script that keeps a dismissed banner from painting — it needs the banner id from the
28
+ * host's own themeConfig, which is only known once VitePress has resolved the merged config, so it
29
+ * cannot be a static head entry here.
30
+ */
31
+ const config = {
32
+ vite: {
33
+ resolve: { alias },
34
+ optimizeDeps: { exclude: [pkg] },
35
+ ssr: { noExternal: [pkg] },
36
+ server: { fs: { allow: [dir] } }
37
+ },
38
+ transformHead({ siteData }) {
39
+ const id = siteData.themeConfig?.ff?.banner?.id
40
+
41
+ if (!id) return []
42
+
43
+ return [
44
+ [
45
+ 'script',
46
+ {},
47
+ `try{if(localStorage.getItem('ff-banner-${id}'))` +
48
+ `document.documentElement.classList.add('ff-banner-dismissed')}catch(e){}`
49
+ ]
50
+ ]
51
+ }
52
+ }
53
+
54
+ export default config