@frontfactory/vitepress-theme 1.6.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 (95) hide show
  1. package/CHANGELOG.md +214 -0
  2. package/README.md +160 -8
  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 +49 -26
  11. package/src/blog/posts.data.ts +46 -0
  12. package/src/components/FfBackToTop.vue +33 -10
  13. package/src/components/FfBanner.vue +42 -8
  14. package/src/components/FfCopyStatus.vue +64 -0
  15. package/src/components/FfDocMeta.vue +50 -46
  16. package/src/components/FfFeature.vue +18 -7
  17. package/src/components/FfFeedback.vue +96 -0
  18. package/src/components/FfFooter.vue +11 -5
  19. package/src/components/FfHero.vue +20 -10
  20. package/src/components/FfHeroCommand.vue +24 -27
  21. package/src/components/FfHomeSponsors.vue +2 -2
  22. package/src/components/FfNavBarTitle.vue +63 -0
  23. package/src/components/FfPost.vue +49 -0
  24. package/src/components/FfProgress.vue +69 -0
  25. package/src/components/FfVersionSwitcher.vue +20 -0
  26. package/src/composables/blog.ts +38 -0
  27. package/src/composables/options.ts +19 -14
  28. package/src/composables/relativeTime.ts +59 -0
  29. package/src/composables/tabs.ts +155 -0
  30. package/src/content/Api.vue +6 -2
  31. package/src/content/Badge.vue +26 -0
  32. package/src/content/Callout.vue +27 -0
  33. package/src/content/FileTree.vue +118 -0
  34. package/src/content/Tab.vue +11 -0
  35. package/src/content/Tabs.vue +74 -0
  36. package/src/content/Timeline.vue +19 -0
  37. package/src/content/TimelineItem.vue +37 -0
  38. package/src/content/timeline.ts +4 -0
  39. package/src/index.ts +37 -1
  40. package/src/internal.ts +7 -2
  41. package/src/layout/FfBlog.vue +62 -0
  42. package/src/layout/FfLayout.vue +17 -1
  43. package/src/styles/_base.scss +20 -5
  44. package/src/styles/_blocks.scss +25 -1
  45. package/src/styles/_blog.scss +131 -0
  46. package/src/styles/_breakpoints.scss +26 -0
  47. package/src/styles/_code.scss +5 -5
  48. package/src/styles/_content.scss +280 -12
  49. package/src/styles/_doc.scss +18 -5
  50. package/src/styles/_home.scss +37 -17
  51. package/src/styles/_motion.scss +22 -2
  52. package/src/styles/_nav.scss +81 -8
  53. package/src/styles/_print.scss +77 -0
  54. package/src/styles/_sidebar.scss +2 -2
  55. package/src/styles/_tokens.scss +75 -9
  56. package/src/styles/index.scss +2 -0
  57. package/src/types.ts +140 -2
  58. package/types/blog/posts.data.d.ts +14 -0
  59. package/types/components/FfBackToTop.vue.d.ts +3 -0
  60. package/types/components/FfBanner.vue.d.ts +3 -0
  61. package/types/components/FfCopyStatus.vue.d.ts +3 -0
  62. package/types/components/FfDocMeta.vue.d.ts +3 -0
  63. package/types/components/FfFeature.vue.d.ts +13 -0
  64. package/types/components/FfFeedback.vue.d.ts +3 -0
  65. package/types/components/FfFooter.vue.d.ts +3 -0
  66. package/types/components/FfHero.vue.d.ts +42 -0
  67. package/types/components/FfHeroCommand.vue.d.ts +9 -0
  68. package/types/components/FfHomeSponsors.vue.d.ts +19 -0
  69. package/types/components/FfNavBarTitle.vue.d.ts +17 -0
  70. package/types/components/FfPost.vue.d.ts +3 -0
  71. package/types/components/FfProgress.vue.d.ts +3 -0
  72. package/types/components/FfVersionSwitcher.vue.d.ts +3 -0
  73. package/types/composables/blog.d.ts +10 -0
  74. package/types/composables/link.d.ts +12 -0
  75. package/types/composables/options.d.ts +15 -0
  76. package/types/composables/relativeTime.d.ts +2 -0
  77. package/types/composables/tabs.d.ts +15 -0
  78. package/types/content/Api.vue.d.ts +27 -0
  79. package/types/content/Badge.vue.d.ts +21 -0
  80. package/types/content/Callout.vue.d.ts +24 -0
  81. package/types/content/Card.vue.d.ts +23 -0
  82. package/types/content/CardGrid.vue.d.ts +20 -0
  83. package/types/content/FileTree.vue.d.ts +6 -0
  84. package/types/content/Kbd.vue.d.ts +15 -0
  85. package/types/content/Steps.vue.d.ts +15 -0
  86. package/types/content/Tab.vue.d.ts +19 -0
  87. package/types/content/Tabs.vue.d.ts +7 -0
  88. package/types/content/Timeline.vue.d.ts +21 -0
  89. package/types/content/TimelineItem.vue.d.ts +21 -0
  90. package/types/content/timeline.d.ts +3 -0
  91. package/types/index.d.ts +25 -0
  92. package/types/internal.d.ts +9 -0
  93. package/types/layout/FfBlog.vue.d.ts +3 -0
  94. package/types/layout/FfLayout.vue.d.ts +23 -0
  95. package/types/types.d.ts +256 -0
@@ -0,0 +1,21 @@
1
+ type __VLS_Props = {
2
+ /** Date or period, printed as a small monospaced label above the title. */
3
+ date?: string;
4
+ /** Heading of the entry. */
5
+ title?: string;
6
+ };
7
+ declare const __VLS_template: () => {
8
+ __VLS_Slots: {
9
+ default?: (props: {}) => any;
10
+ };
11
+ };
12
+ type __VLS_Slots = ReturnType<typeof __VLS_template>['__VLS_Slots'];
13
+ declare const __VLS_base: import("vue").DefineComponent<__VLS_Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, false, {}, any>;
14
+ declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
15
+ declare const _default: typeof __VLS_export;
16
+ export default _default;
17
+ type __VLS_WithSlots<T, S> = T & {
18
+ new (): {
19
+ $slots: S;
20
+ };
21
+ };
@@ -0,0 +1,3 @@
1
+ import type { InjectionKey, Ref } from 'vue';
2
+ /** Heading level `<Timeline>` hands down to its `<TimelineItem>` titles. */
3
+ export declare const TIMELINE_LEVEL: InjectionKey<Ref<number>>;
@@ -0,0 +1,25 @@
1
+ import type { Theme } from 'vitepress';
2
+ import '../dist/style.css';
3
+ /**
4
+ * Editorial VitePress theme.
5
+ *
6
+ * It keeps the default theme underneath — search, i18n, mobile navigation and every markdown
7
+ * feature stay untouched — and replaces the whole surface: type, rules, numbering, hero, feature
8
+ * grid and footer.
9
+ */
10
+ declare const theme: Theme;
11
+ export default theme;
12
+ export { default as Api } from './content/Api.vue';
13
+ export { default as Badge } from './content/Badge.vue';
14
+ export { default as Callout } from './content/Callout.vue';
15
+ export { default as Card } from './content/Card.vue';
16
+ export { default as CardGrid } from './content/CardGrid.vue';
17
+ export { default as FileTree } from './content/FileTree.vue';
18
+ export { default as Kbd } from './content/Kbd.vue';
19
+ export { default as Steps } from './content/Steps.vue';
20
+ export { default as Tab } from './content/Tab.vue';
21
+ export { default as Tabs } from './content/Tabs.vue';
22
+ export { default as Timeline } from './content/Timeline.vue';
23
+ export { default as TimelineItem } from './content/TimelineItem.vue';
24
+ export { defaultLabels, useLabels, useThemeOptions } from './composables/options';
25
+ export type { BannerConfig, BlogAuthor, BlogConfig, BlogRssConfig, FeedbackConfig, FooterColumn, FooterLink, HeroCommandTab, HeroExtras, HeroMetaItem, MetaConfig, OgConfig, OgFont, ThemeConfig, ThemeLabels, ThemeOptions, VersionsConfig } from './types';
@@ -0,0 +1,9 @@
1
+ export { default as VPBadge } from 'vitepress/dist/client/theme-default/components/VPBadge.vue';
2
+ export { default as VPFlyout } from 'vitepress/dist/client/theme-default/components/VPFlyout.vue';
3
+ export { default as VPIcon } from 'vitepress/dist/client/theme-default/components/VPIcon.vue';
4
+ export { default as VPImage } from 'vitepress/dist/client/theme-default/components/VPImage.vue';
5
+ export { default as VPLink } from 'vitepress/dist/client/theme-default/components/VPLink.vue';
6
+ export { default as VPSponsors } from 'vitepress/dist/client/theme-default/components/VPSponsors.vue';
7
+ export { useLangs } from 'vitepress/dist/client/theme-default/composables/langs.js';
8
+ export { useLayout } from 'vitepress/dist/client/theme-default/composables/layout.js';
9
+ export { normalizeLink } from 'vitepress/dist/client/theme-default/support/utils.js';
@@ -0,0 +1,3 @@
1
+ declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
2
+ declare const _default: typeof __VLS_export;
3
+ export default _default;
@@ -0,0 +1,23 @@
1
+ declare const __VLS_template: () => {
2
+ __VLS_Slots: {
3
+ [x: string]: ((props: any) => any) | undefined;
4
+ } & {
5
+ 'layout-top'?: (props: {}) => any;
6
+ } & {
7
+ 'doc-before'?: (props: {}) => any;
8
+ } & {
9
+ 'doc-footer-before'?: (props: {}) => any;
10
+ } & {
11
+ 'layout-bottom'?: (props: {}) => any;
12
+ };
13
+ };
14
+ type __VLS_Slots = ReturnType<typeof __VLS_template>['__VLS_Slots'];
15
+ declare const __VLS_base: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
16
+ declare const __VLS_export: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
17
+ declare const _default: typeof __VLS_export;
18
+ export default _default;
19
+ type __VLS_WithSlots<T, S> = T & {
20
+ new (): {
21
+ $slots: S;
22
+ };
23
+ };
@@ -0,0 +1,256 @@
1
+ import type { DefaultTheme } from 'vitepress/theme';
2
+ export interface BannerConfig {
3
+ /** Stable id — changing it brings the banner back for readers who dismissed the previous one. */
4
+ id: string;
5
+ /** Text shown in the banner. Inline HTML is allowed. */
6
+ text: string;
7
+ /** Optional link the whole banner points to. */
8
+ link?: string;
9
+ /** Label of the trailing call to action. Defaults to `Read more`. */
10
+ linkText?: string;
11
+ /**
12
+ * Colour the banner is built from. Defaults to `ink`, the theme's original flat bar.
13
+ * `rainbow` strings the status hues together and is always a gradient.
14
+ */
15
+ variant?: 'ink' | 'accent' | 'success' | 'warning' | 'danger' | 'rainbow';
16
+ /** Paint the background as a gradient toward the variant's colour instead of flat. Ignored by `rainbow`, which is always a gradient. */
17
+ gradient?: boolean;
18
+ /** Icon or emoji printed before the text, e.g. `'🎉'`. */
19
+ icon?: string;
20
+ }
21
+ export interface FooterLink {
22
+ text: string;
23
+ link: string;
24
+ rel?: string;
25
+ target?: string;
26
+ }
27
+ export interface FooterColumn {
28
+ title: string;
29
+ items: FooterLink[];
30
+ }
31
+ export interface MetaConfig {
32
+ /** Estimated reading time. Defaults to `true`. */
33
+ readingTime?: boolean;
34
+ /** Words read per minute used by the estimate. Defaults to `200`. */
35
+ wordsPerMinute?: number;
36
+ /** Section the page belongs to, taken from the sidebar. Defaults to `true`. */
37
+ section?: boolean;
38
+ /** Relative last-updated stamp. Defaults to `true`, and needs `lastUpdated` in the site config. */
39
+ lastUpdated?: boolean;
40
+ }
41
+ /**
42
+ * Every user-facing string this theme adds on top of the default one. They sit in `themeConfig`,
43
+ * so a multi-language site declares them per locale like any other default-theme label.
44
+ *
45
+ * `{0}` in a label is replaced by the value it describes.
46
+ */
47
+ export interface ThemeLabels {
48
+ /** Accessible name of the banner dismiss button. Defaults to `Dismiss announcement`. */
49
+ bannerDismiss?: string;
50
+ /** Reading-time estimate; `{0}` is the number of minutes. Defaults to `{0} min read`. */
51
+ readingTime?: string;
52
+ /** Last-updated stamp; `{0}` is the relative time. Defaults to `Updated {0}`. */
53
+ lastUpdated?: string;
54
+ /** Heading of the hero install panel. Defaults to `Install`. */
55
+ heroInstall?: string;
56
+ /** Hero copy button once the command is on the clipboard. Defaults to `Copied`. */
57
+ heroCopied?: string;
58
+ /** Accessible name of the hero copy button; `{0}` is the command. Defaults to `Copy {0}`. */
59
+ heroCopyLabel?: string;
60
+ /** Visible text of the back-to-top control. Defaults to `Top`. */
61
+ backToTop?: string;
62
+ /** Heading of the footer social column. Defaults to `Follow`. */
63
+ footerSocial?: string;
64
+ /** Hidden hint after links that open in a new tab. Defaults to `opens in a new tab`. */
65
+ newTab?: string;
66
+ /** Heading of the sponsors section. Defaults to `Sponsors`. */
67
+ sponsors?: string;
68
+ /** Sponsors section action button, when the site sets `actionLink` but no `actionText`. Defaults to `Become a sponsor`. */
69
+ sponsorsAction?: string;
70
+ /** API tag stating the version a symbol appeared in; `{0}` is the version. Defaults to `since {0}`. */
71
+ apiSince?: string;
72
+ /** API tag marking a deprecated symbol. Defaults to `deprecated`. */
73
+ apiDeprecated?: string;
74
+ /** Banner call to action when the banner has a link but no `linkText`. Defaults to `Read more`. */
75
+ bannerCta?: string;
76
+ /** Question asked by the feedback widget. Defaults to `Was this page helpful?`. */
77
+ feedbackQuestion?: string;
78
+ /** Positive answer of the feedback widget. Defaults to `Yes`. */
79
+ feedbackYes?: string;
80
+ /** Negative answer of the feedback widget. Defaults to `No`. */
81
+ feedbackNo?: string;
82
+ /** Message shown once a vote is cast. Defaults to `Thanks for your feedback`. */
83
+ feedbackThanks?: string;
84
+ /** Button copying the page as Markdown. Defaults to `Copy as Markdown`. */
85
+ copyMarkdown?: string;
86
+ /** Accessible name of the version menu, followed by the current version. Defaults to `Version`. */
87
+ versionSwitcher?: string;
88
+ /** Author line of a post; `{0}` is the name. Defaults to `By {0}`. */
89
+ blogBy?: string;
90
+ /** Message of a blog index without any post. Defaults to `No posts yet`. */
91
+ blogEmpty?: string;
92
+ }
93
+ /** One author of the blog, declared in `ff.blog.authors` and referred to by key from a post. */
94
+ export interface BlogAuthor {
95
+ name: string;
96
+ /** Page the author's name links to. */
97
+ link?: string;
98
+ /** Small portrait printed before the name. */
99
+ avatar?: string;
100
+ }
101
+ /** RSS feed of the blog, set with `ff.blog.rss`. Needs the optional `feed` package. */
102
+ export interface BlogRssConfig {
103
+ /** Absolute site address the feed links to. Defaults to `sitemap.hostname`. */
104
+ hostname?: string;
105
+ copyright?: string;
106
+ }
107
+ /** Blog settings, `ff.blog`. A post is a Markdown page under `dir` with a `date` in its frontmatter. */
108
+ export interface BlogConfig {
109
+ /** Directory of the posts, relative to the source root. Defaults to `blog`. */
110
+ dir?: string;
111
+ /** Authors by key; a post's `author` is such a key, or a plain name. */
112
+ authors?: Record<string, BlogAuthor>;
113
+ /** Writes `feed.xml` at the end of the build. Off by default. */
114
+ rss?: boolean | BlogRssConfig;
115
+ }
116
+ /** One font handed to the Open Graph image renderer. */
117
+ export interface OgFont {
118
+ /** Family name, also used to draw the text. The first font of the list is the one used. */
119
+ name: string;
120
+ /** TTF, OTF or WOFF file (not WOFF2), relative to the site's source directory. */
121
+ path: string;
122
+ weight?: number;
123
+ style?: 'normal' | 'italic';
124
+ }
125
+ /** Open Graph images, set with `ff.og`. Needs the optional `satori` and `@resvg/resvg-js` packages. */
126
+ export interface OgConfig {
127
+ fonts: OgFont[];
128
+ /** Absolute site address the image URLs point to. Defaults to `sitemap.hostname`. */
129
+ hostname?: string;
130
+ }
131
+ /** Options of the page feedback widget, when `ff.feedback` is an object instead of `true`. */
132
+ export interface FeedbackConfig {
133
+ /** Endpoint that receives each vote as a `sendBeacon` POST. Without it, only the `ff:feedback` event fires. */
134
+ url?: string;
135
+ /** Question to ask, instead of the `feedbackQuestion` label. */
136
+ question?: string;
137
+ }
138
+ /** Version menu of the navigation bar, set with `ff.versions`. */
139
+ export interface VersionsConfig {
140
+ /** Version of the site being read; it is the text of the menu button. */
141
+ current: string;
142
+ /** Other versions, each pointing at its own copy of the docs. */
143
+ items: FooterLink[];
144
+ }
145
+ /** One entry of the colophon strip printed under the hero. */
146
+ export interface HeroMetaItem {
147
+ label: string;
148
+ value: string;
149
+ }
150
+ /** One tab of a multi-command install panel, e.g. npm vs. pnpm vs. bun. */
151
+ export interface HeroCommandTab {
152
+ label: string;
153
+ value: string;
154
+ }
155
+ /**
156
+ * The two additions this theme makes to the standard `layout: home` hero frontmatter. Both are
157
+ * optional; everything else on `hero` stays the default theme's.
158
+ */
159
+ export interface HeroExtras {
160
+ /**
161
+ * Install line, printed in a panel. Beside the headline when the hero carries no image;
162
+ * under it, carrying the command only, when an image claims that column instead. An array of
163
+ * `{ label, value }` prints a tab strip above the line instead of a single command — one tab
164
+ * per package manager, say — and the copy button follows whichever tab is active.
165
+ */
166
+ command?: string | HeroCommandTab[];
167
+ /**
168
+ * A short line under the tagline, set off with the same rule-and-italic treatment as a
169
+ * markdown blockquote. Inline HTML is allowed, so a term inside it can be marked up, e.g.
170
+ * `<strong>Charpente</strong> /ʃaʁ.pɑ̃t/ — French for…`.
171
+ */
172
+ quote?: string;
173
+ /** Colophon strip under the hero. */
174
+ meta?: HeroMetaItem[];
175
+ }
176
+ /**
177
+ * Text fields documented as accepting inline HTML (banner text, hero and feature copy, footer
178
+ * message) are rendered as-is. They come from the site's own config and frontmatter, so they are
179
+ * trusted: never feed them user-submitted content.
180
+ */
181
+ export interface ThemeOptions {
182
+ /** Dismissible announcement bar above the navigation. */
183
+ banner?: BannerConfig;
184
+ /** Kicker line printed above every page title. */
185
+ meta?: MetaConfig | false;
186
+ /** Link columns added to the site footer. */
187
+ footerColumns?: FooterColumn[];
188
+ /**
189
+ * Column of `themeConfig.socialLinks` icons, pinned to the right of the footer columns.
190
+ * Defaults to `true`, and shows nothing when the site declares no social link.
191
+ */
192
+ footerSocial?: boolean;
193
+ /** Floating back-to-top control. Defaults to `true`. */
194
+ backToTop?: boolean;
195
+ /**
196
+ * Thin reading-progress bar pinned to the top of the viewport. Off by default; a page opts out
197
+ * with `progress: false` in its frontmatter.
198
+ */
199
+ progress?: boolean;
200
+ /**
201
+ * "Was this page helpful?" widget under each doc page. Off by default; a page opts out with
202
+ * `feedback: false` in its frontmatter. Each vote is sent to `url` with `navigator.sendBeacon`
203
+ * as a JSON string `{ page, value: 'yes' | 'no', lang }`, and always dispatched on `window` as
204
+ * an `ff:feedback` CustomEvent carrying the same object in `detail`.
205
+ */
206
+ feedback?: boolean | FeedbackConfig;
207
+ /**
208
+ * Button in the page kicker that copies the page's Markdown source. Off by default. The source
209
+ * is injected by `ffTransformPageData`, which a site defining its own `transformPageData` must
210
+ * call from it.
211
+ */
212
+ copyMarkdown?: boolean;
213
+ /**
214
+ * Writes `llms.txt` and `llms-full.txt` to the output directory at the end of the build. Off by
215
+ * default; a page opts out with `llms: false` in its frontmatter.
216
+ */
217
+ llms?: boolean;
218
+ /**
219
+ * Blog: `layout: blog` on the index page lists the posts of `dir`, each post gets a dated
220
+ * header, and `rss` writes a feed at build time.
221
+ */
222
+ blog?: BlogConfig;
223
+ /**
224
+ * One 1200x630 PNG per page in `og/`, with the matching `og:image` and `twitter:card` tags.
225
+ * Off by default; a page opts out with `og: false` in its frontmatter. It needs fonts, so it
226
+ * is an object (`true` alone is rejected at build time).
227
+ */
228
+ og?: boolean | OgConfig;
229
+ /** Version menu in the navigation bar, after the other controls. */
230
+ versions?: VersionsConfig;
231
+ /** Order of the search box and the nav menu links in the top bar. Defaults to `search-first`. */
232
+ navOrder?: 'search-first' | 'menu-first';
233
+ /**
234
+ * Pins the navigation bar to the top of the viewport while scrolling. Defaults to `true`; set
235
+ * to `false` to have it scroll away with the page instead.
236
+ */
237
+ navSticky?: boolean;
238
+ /**
239
+ * Ready-made accent, in both schemes, instead of the default indigo. Set on `<html>` by an
240
+ * inline head script, so it paints from the first frame and reaches teleported overlays.
241
+ */
242
+ preset?: 'emerald' | 'crimson' | 'violet' | 'amber';
243
+ /** Overrides for the strings this theme adds. Declare them per locale to translate them. */
244
+ labels?: ThemeLabels;
245
+ }
246
+ export interface ThemeConfig extends DefaultTheme.Config {
247
+ ff?: ThemeOptions;
248
+ }
249
+ declare module 'vitepress/theme' {
250
+ namespace DefaultTheme {
251
+ interface Config {
252
+ ff?: ThemeOptions;
253
+ }
254
+ }
255
+ }
256
+ export type { DefaultTheme };