@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/node/rss.js ADDED
@@ -0,0 +1,78 @@
1
+ import { mkdir, writeFile } from 'node:fs/promises';
2
+ import { join } from 'node:path';
3
+ import { blogDir, hasValidDate } from './blog.js';
4
+ import { hostnameOf } from './pages.js';
5
+
6
+ /**
7
+ * Writes `feed.xml`, an RSS 2.0 feed of the blog posts (dated pages under the blog directory,
8
+ * newest first). `feed` is an optional peer dependency, so it is only loaded here, when the feed is
9
+ * actually requested.
10
+ *
11
+ * @param {import('vitepress').SiteConfig} siteConfig
12
+ * @param {Awaited<ReturnType<typeof import('./pages.js').readPages>>} allPages Pages read once by the caller.
13
+ */
14
+ export async function generateRss(siteConfig, allPages) {
15
+ const ff = siteConfig.site.themeConfig.ff;
16
+ const rss = typeof ff.blog.rss === 'object' ? ff.blog.rss : {};
17
+ const hostname = hostnameOf(siteConfig, rss.hostname);
18
+
19
+ if (!hostname) {
20
+ throw new Error(
21
+ '[vitepress-theme] `ff.blog.rss` needs an absolute address: set `ff.blog.rss.hostname` or `sitemap.hostname`.'
22
+ );
23
+ }
24
+
25
+ let Feed;
26
+
27
+ try {
28
+ ({ Feed } = await import('feed'));
29
+ } catch {
30
+ throw new Error('[vitepress-theme] `ff.blog.rss` needs the `feed` package: run `npm install feed`.');
31
+ }
32
+
33
+ const { title, description, lang, base } = siteConfig.site;
34
+ const authors = ff.blog.authors ?? {};
35
+ const dir = blogDir(ff);
36
+ const site = `${hostname}${base}`;
37
+ const feed = new Feed({
38
+ title,
39
+ description,
40
+ id: site,
41
+ link: site,
42
+ language: lang,
43
+ copyright: rss.copyright ?? '',
44
+ feedLinks: {
45
+ rss: `${site}feed.xml`
46
+ }
47
+ });
48
+
49
+ const posts = allPages
50
+ .filter(({ page, data }) => page.startsWith(`${dir}/`) && page !== `${dir}/index.md` && hasValidDate(data.date))
51
+ .sort((a, b) => new Date(b.data.date) - new Date(a.data.date));
52
+
53
+ for (const { url, title: name, data } of posts) {
54
+ const author = authors[data.author] ?? (data.author ? {
55
+ name: data.author
56
+ } : null);
57
+
58
+ feed.addItem({
59
+ title: name,
60
+ id: `${hostname}${url}`,
61
+ link: `${hostname}${url}`,
62
+ description: data.excerpt,
63
+ date: new Date(data.date),
64
+ author: author ? [
65
+ author
66
+ ] : undefined,
67
+ category: (Array.isArray(data.tags) ? data.tags : []).map((tag) => ({
68
+ name: tag
69
+ }))
70
+ });
71
+ }
72
+
73
+ await mkdir(siteConfig.outDir, {
74
+ recursive: true
75
+ });
76
+
77
+ await writeFile(join(siteConfig.outDir, 'feed.xml'), feed.rss2());
78
+ }
package/package.json CHANGED
@@ -1,14 +1,17 @@
1
1
  {
2
2
  "name": "@frontfactory/vitepress-theme",
3
- "version": "1.7.0",
3
+ "version": "1.9.0",
4
4
  "description": "Editorial VitePress theme — hairline rules, numbered sections and monospaced metadata.",
5
5
  "type": "module",
6
6
  "scripts": {
7
- "build": "sass --style=compressed --no-source-map --pkg-importer=node --load-path=node_modules src/styles/index.scss dist/style.css",
8
- "dev": "npm run build -- --watch",
9
- "dev:playground": "npm run build && vitepress dev playground",
10
- "build:playground": "npm run build && vitepress build playground",
7
+ "build": "npm run build:css && npm run build:types",
8
+ "build:css": "sass --style=compressed --no-source-map --pkg-importer=node --load-path=node_modules src/styles/index.scss dist/style.css",
9
+ "dev": "npm run build:css -- --watch",
10
+ "dev:playground": "npm run build:css && vitepress dev playground",
11
+ "build:playground": "npm run build:css && vitepress build playground",
12
+ "build:types": "vue-tsc -p tsconfig.build.json",
11
13
  "typecheck": "vue-tsc --noEmit",
14
+ "test:e2e": "playwright test tests/a11y.spec.ts",
12
15
  "lint:js": "eslint .",
13
16
  "lint:css": "stylelint \"src/**/*.scss\"",
14
17
  "lint": "npm run lint:js && npm run lint:css",
@@ -19,12 +22,10 @@
19
22
  "engines": {
20
23
  "node": ">=24"
21
24
  },
22
- "main": "./src/index.ts",
23
- "module": "./src/index.ts",
24
- "types": "./src/index.ts",
25
+ "types": "./types/index.d.ts",
25
26
  "exports": {
26
27
  ".": {
27
- "types": "./src/index.ts",
28
+ "types": "./types/index.d.ts",
28
29
  "default": "./src/index.ts"
29
30
  },
30
31
  "./config": {
@@ -35,36 +36,47 @@
35
36
  "./package.json": "./package.json"
36
37
  },
37
38
  "devDependencies": {
38
- "@commitlint/cli": "^21.2.3",
39
- "@commitlint/config-conventional": "^21.2.3",
40
- "@eslint/js": "^10.0.1",
41
- "@front-factory/eslint-config": "^2.5.0",
42
- "@front-factory/stylelint-config": "^1.12.1",
39
+ "@axe-core/playwright": "^4.14.0",
40
+ "@commitlint/cli": "^21.2.4",
41
+ "@commitlint/config-conventional": "^21.2.4",
42
+ "@front-factory/eslint-config": "^3.0.0",
43
+ "@front-factory/stylelint-config": "^2.0.0",
43
44
  "@magnesium/theme": "^5.3.0",
45
+ "@playwright/test": "^1.64.1",
46
+ "@resvg/resvg-js": "^2.6.2",
44
47
  "@semantic-release/changelog": "^7.0.0",
45
48
  "@semantic-release/git": "^11.0.1",
46
- "@semantic-release/github": "^12.0.10",
47
49
  "conventional-changelog-conventionalcommits": "^9.3.1",
48
- "eslint": "^10.12.0",
49
- "eslint-plugin-vue": "^10.11.1",
50
- "globals": "^17.13.0",
50
+ "eslint": "^10.14.0",
51
+ "eslint-plugin-vue": "^10.12.0",
52
+ "feed": "^6.0.0",
51
53
  "husky": "^9.1.7",
52
- "sass": "^1.105.1",
54
+ "sass": "^1.107.1",
55
+ "satori": "^0.63.2",
53
56
  "semantic-release": "^25.0.9",
54
- "stylelint": "^16.26.1",
55
- "typescript": "^5.9.3",
56
- "typescript-eslint": "^8.71.1",
57
- "vitepress": "^2.0.0-alpha.20",
58
- "vue": "^3.5.43",
59
- "vue-tsc": "^3.3.13"
57
+ "stylelint": "^17.16.0",
58
+ "typescript": "^6.0.3",
59
+ "typescript-eslint": "^8.72.1",
60
+ "vitepress": "^2.0.0-alpha.21",
61
+ "vue": "^3.5.44",
62
+ "vue-tsc": "^3.3.14"
60
63
  },
61
64
  "peerDependencies": {
62
- "vite": ">=5",
65
+ "@resvg/resvg-js": "^2.6.2",
66
+ "feed": "^6.0.0",
67
+ "satori": "^0.63.2",
68
+ "vite": "^8.2.1",
63
69
  "vitepress": "^2.0.0-alpha.20",
64
70
  "vue": "^3.5.0"
65
71
  },
66
72
  "peerDependenciesMeta": {
67
- "vite": {
73
+ "@resvg/resvg-js": {
74
+ "optional": true
75
+ },
76
+ "feed": {
77
+ "optional": true
78
+ },
79
+ "satori": {
68
80
  "optional": true
69
81
  }
70
82
  },
@@ -91,9 +103,11 @@
91
103
  "files": [
92
104
  "src",
93
105
  "dist/style.css",
106
+ "types",
94
107
  "CHANGELOG.md",
95
108
  "config.js",
96
- "config.d.ts"
109
+ "config.d.ts",
110
+ "node"
97
111
  ],
98
112
  "publishConfig": {
99
113
  "access": "public",
@@ -0,0 +1,47 @@
1
+ import { createContentLoader, type LoaderModule } from 'vitepress';
2
+ import type { ThemeConfig } from '../types.ts';
3
+ import { blogDir, hasValidDate } from '../../node/blog.js';
4
+
5
+ export interface Post {
6
+ url: string
7
+ title: string
8
+ /** ISO date, as written in the frontmatter. */
9
+ date: string
10
+ author?: string
11
+ tags: string[]
12
+ excerpt?: string
13
+ }
14
+
15
+ declare const data: Post[];
16
+
17
+ export { data };
18
+
19
+ // A data loader runs in Node, outside any component, so it cannot call `useData()`. VitePress puts
20
+ // the resolved config on `globalThis` before it evaluates a loader file (`createContentLoader`
21
+ // reads it the same way), which is where the blog directory is read from.
22
+ const { site } = (globalThis as unknown as { VITEPRESS_CONFIG: { site: { themeConfig?: ThemeConfig } } })
23
+ .VITEPRESS_CONFIG;
24
+ const dir = blogDir(site.themeConfig?.ff);
25
+
26
+ // Annotated so the emitted declaration doesn't reference VitePress's private `GlobOptions` (TS4082).
27
+ const loader: LoaderModule<Post[]> = createContentLoader([
28
+ `${dir}/**/*.md`,
29
+ `!${dir}/index.md`
30
+ ], {
31
+ includeSrc: true,
32
+ transform(raw) {
33
+ return raw
34
+ .filter(({ frontmatter }) => hasValidDate(frontmatter.date))
35
+ .map(({ url, src, frontmatter }): Post => ({
36
+ url,
37
+ title: frontmatter.title || /^#\s+(.+)$/m.exec(src ?? '')?.[1].trim() || url,
38
+ date: new Date(frontmatter.date).toISOString(),
39
+ author: frontmatter.author,
40
+ tags: Array.isArray(frontmatter.tags) ? frontmatter.tags.map(String) : [],
41
+ excerpt: frontmatter.excerpt
42
+ }))
43
+ .sort((a, b) => b.date.localeCompare(a.date));
44
+ }
45
+ });
46
+
47
+ export default loader;
@@ -1,6 +1,6 @@
1
1
  <script setup lang="ts">
2
2
  import {
3
- computed, onMounted, onUnmounted, ref
3
+ computed, onMounted, ref, watchEffect
4
4
  } from 'vue';
5
5
  import { useData } from 'vitepress';
6
6
  import { useLabels, useThemeOptions } from '../composables/options';
@@ -11,7 +11,7 @@ const labels = useLabels();
11
11
 
12
12
  // The visible text is the accessible name; the tooltip reuses the default theme's own option,
13
13
  // so a site that already localised its mobile return-to-top link gets this one for free.
14
- const title = computed(() => theme.value.returnToTopLabel ?? 'Return to top');
14
+ const title = computed(() => theme.value.returnToTopLabel ?? labels.value.returnToTop);
15
15
 
16
16
  const enabled = computed(() => options.value.backToTop !== false);
17
17
 
@@ -40,16 +40,25 @@ function toTop() {
40
40
  });
41
41
  }
42
42
 
43
+ // Listens only while the control is enabled, and follows the option if it changes (locale switch).
44
+ // The effect is stopped with the component, which runs its cleanup.
43
45
  onMounted(() => {
44
- update();
45
- window.addEventListener('scroll', onScroll, {
46
- passive: true
47
- });
48
- });
46
+ watchEffect((onCleanup) => {
47
+ if (!enabled.value) {
48
+ return;
49
+ }
50
+
51
+ update();
52
+ window.addEventListener('scroll', onScroll, {
53
+ passive: true
54
+ });
49
55
 
50
- onUnmounted(() => {
51
- cancelAnimationFrame(frame);
52
- window.removeEventListener('scroll', onScroll);
56
+ onCleanup(() => {
57
+ cancelAnimationFrame(frame);
58
+ frame = 0;
59
+ window.removeEventListener('scroll', onScroll);
60
+ });
61
+ });
53
62
  });
54
63
  </script>
55
64
 
@@ -1,8 +1,9 @@
1
1
  <script setup lang="ts">
2
2
  import {
3
- computed, onMounted, onUnmounted, ref
3
+ computed, onMounted, onUnmounted, ref, watch
4
4
  } from 'vue';
5
5
  import { useLabels, useThemeOptions } from '../composables/options';
6
+ import { normalizeLink } from '../internal';
6
7
 
7
8
  const options = useThemeOptions();
8
9
  const labels = useLabels();
@@ -38,19 +39,36 @@ function dismiss() {
38
39
  // Private mode or full quota: the banner is dismissed for this page view only.
39
40
  }
40
41
 
42
+ // Read before hiding: a mouse click leaves no visible focus, so only a keyboard user is moved.
43
+ const keyboard = document.activeElement?.matches(':focus-visible') ?? false;
44
+
41
45
  document.documentElement.classList.add(DISMISSED);
42
46
  height();
47
+
48
+ // The banner goes `display: none` under the focused close button. Hand focus to the next stop,
49
+ // VitePress' skip link, instead of letting it drop to <body>.
50
+ if (keyboard) {
51
+ document.querySelector<HTMLElement>('.VPSkipLink')?.focus();
52
+ }
43
53
  }
44
54
 
45
- onMounted(() => {
55
+ // The banner can appear or go away after mount (locale switch, `v-if`), so the observer follows the
56
+ // element rather than being wired once.
57
+ watch(el, (node) => {
58
+ observer?.disconnect();
59
+ observer = undefined;
46
60
  height();
47
61
 
48
- if (el.value) {
62
+ if (node) {
49
63
  observer = new ResizeObserver(height);
50
- observer.observe(el.value);
64
+ observer.observe(node);
51
65
  }
66
+ }, {
67
+ flush: 'post'
52
68
  });
53
69
 
70
+ onMounted(height);
71
+
54
72
  onUnmounted(() => {
55
73
  observer?.disconnect();
56
74
  document.documentElement.style.removeProperty('--vp-layout-top-height');
@@ -68,7 +86,7 @@ onUnmounted(() => {
68
86
  <component
69
87
  :is="banner.link ? 'a' : 'div'"
70
88
  class="ff-banner-body"
71
- :href="banner.link"
89
+ :href="banner.link ? normalizeLink(banner.link) : undefined"
72
90
  >
73
91
  <span
74
92
  v-if="banner.icon"
@@ -83,7 +101,7 @@ onUnmounted(() => {
83
101
  v-if="banner.link"
84
102
  class="ff-banner-cta"
85
103
  >
86
- {{ banner.linkText ?? 'Read more' }}
104
+ {{ banner.linkText ?? labels.bannerCta }}
87
105
  <span aria-hidden="true">&#8594;</span>
88
106
  </span>
89
107
  </component>
@@ -0,0 +1,64 @@
1
+ <script setup lang="ts">
2
+ import {
3
+ onMounted, onUnmounted, ref
4
+ } from 'vue';
5
+ import { useLabels } from '../composables/options';
6
+
7
+ const labels = useLabels();
8
+ const message = ref('');
9
+
10
+ // VitePress confirms a code block copy with a CSS `::before` only, which screen readers never
11
+ // hear. Its click handler adds `.copied` once the clipboard write succeeds, so the class is what
12
+ // gets watched rather than the click itself.
13
+ const BUTTON = 'div[class*="language-"] > button.copy';
14
+
15
+ let timer: ReturnType<typeof setTimeout> | undefined;
16
+
17
+ function announce() {
18
+ message.value = labels.value.codeCopied;
19
+
20
+ clearTimeout(timer);
21
+ timer = setTimeout(() => (message.value = ''), 2000);
22
+ }
23
+
24
+ function onClick(event: MouseEvent) {
25
+ const button = (event.target as Element | null)?.closest?.(BUTTON);
26
+
27
+ if (!button) {
28
+ return;
29
+ }
30
+
31
+ // Cleared first, so a second copy within two seconds is announced again.
32
+ message.value = '';
33
+
34
+ const observer = new MutationObserver(() => {
35
+ if (button.classList.contains('copied')) {
36
+ observer.disconnect();
37
+ announce();
38
+ }
39
+ });
40
+
41
+ observer.observe(button, {
42
+ attributeFilter: [
43
+ 'class'
44
+ ]
45
+ });
46
+
47
+ // A failed write never adds the class: stop watching once the confirmation window is over.
48
+ setTimeout(() => observer.disconnect(), 2000);
49
+ }
50
+
51
+ onMounted(() => window.addEventListener('click', onClick));
52
+
53
+ onUnmounted(() => {
54
+ window.removeEventListener('click', onClick);
55
+ clearTimeout(timer);
56
+ });
57
+ </script>
58
+
59
+ <template>
60
+ <span
61
+ class="visually-hidden"
62
+ aria-live="polite"
63
+ >{{ message }}</span>
64
+ </template>