Skip to content

Commit dcbbbc1

Browse files
Reference Sections (FabricMC#503)
Co-authored-by: Miroma <its.miroma@proton.me>
1 parent 8848be5 commit dcbbbc1

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

49 files changed

+429
-105
lines changed

.vitepress/config/i18n.ts

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -209,6 +209,11 @@ export const getLocales = () => {
209209
label: resolver("outline"),
210210
},
211211

212+
references: {
213+
files: resolver("references.files"),
214+
resources: resolver("references.resources"),
215+
},
216+
212217
returnToTopLabel: resolver("return_to_top"),
213218

214219
search: {

.vitepress/config/index.ts

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import * as process from "node:process";
44
import { tabsMarkdownPlugin } from "vitepress-plugin-tabs";
55
import defineVersionedConfig from "vitepress-versioning-plugin";
66
import latestVersionPlugin from "../plugins/latestVersion";
7+
import transformFilesPlugin from "../plugins/transformFiles";
78
import { Fabric } from "../types.d";
89
import { getLocales } from "./i18n";
910
import { transformHead, transformItems } from "./transform";
@@ -137,7 +138,7 @@ export default defineVersionedConfig(
137138
},
138139

139140
vite: {
140-
plugins: [latestVersionPlugin()],
141+
plugins: [latestVersionPlugin(), transformFilesPlugin()],
141142
},
142143
},
143144
path.resolve(import.meta.dirname, "..")
Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
import matter from "gray-matter";
2+
import { Plugin } from "vitepress";
3+
4+
export default (): Plugin => {
5+
const name = "fabric-docs:transform-files";
6+
7+
return {
8+
name,
9+
enforce: "pre",
10+
11+
transform: {
12+
filter: { id: /\.md$/ },
13+
handler(src, id) {
14+
this.addWatchFile(id);
15+
16+
let { data, content } = matter(src);
17+
18+
// Add heading from frontmatter title
19+
if (data.title && data.layout !== "home") {
20+
content = `# ${data.title} {#h1}\n\n${content}`;
21+
}
22+
23+
// Find files referenced in the page
24+
const filePathRegex = /(?:^<<< *([^[{#\n]+))|(?:^@\[[^\]]*\]\(([^)]*)\))/gm;
25+
const matches = [...src.matchAll(filePathRegex)].map((m) => (m[1] ?? m[2]).trim());
26+
27+
matches.push(...(data.files ?? []));
28+
29+
data.files = [...new Set(matches)];
30+
31+
return {
32+
code: matter.stringify(content, data),
33+
};
34+
},
35+
},
36+
};
37+
};

.vitepress/theme/components/AuthorsComponent.vue

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
<script setup lang="ts">
2-
import { useBrowserLocation } from "@vueuse/core";
32
import { useData } from "vitepress";
43
import VPLink from "vitepress/dist/client/theme-default/components/VPLink.vue";
54
import { computed } from "vue";
@@ -29,7 +28,7 @@ const getImageSrc = (author: Author) =>
2928
af: "",
3029
maxage: "7d",
3130
url: `https://github.com/${author.name}.png?size=32`,
32-
default: `${useBrowserLocation().value.origin}/assets/avatater.png`,
31+
default: `https://docs.fabricmc.net/assets/avatater.png`,
3332
});
3433
</script>
3534

.vitepress/theme/components/NotFoundComponent.vue

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ const options = computed(() => {
1515
return options;
1616
});
1717
18-
const removeForEnglishRegex = new RegExp(String.raw`^${data.localeIndex.value}/|[.]md$`, "g");
18+
const getEnglish = computed(() => new RegExp(String.raw`^${data.localeIndex.value}/|[.]md$`, "g"));
1919
const urls = computed(() =>
2020
data.localeIndex.value === "root"
2121
? {
@@ -26,7 +26,7 @@ const urls = computed(() =>
2626
: {
2727
home: `/${data.localeIndex.value}/`,
2828
// TODO: hide if English=404
29-
english: data.page.value.relativePath.replace(removeForEnglishRegex, ""),
29+
english: data.page.value.relativePath.replace(getEnglish.value, ""),
3030
// TODO: link to file: https://developer.crowdin.com/api/v2/#operation/api.projects.files.getMany
3131
crowdin: `https://crowdin.com/project/fabricmc/${options.value.crowdinLocale}`,
3232
}
Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
<script setup lang="ts">
2+
import { useData } from "vitepress";
3+
import VPLink from "vitepress/dist/client/theme-default/components/VPLink.vue";
4+
import { computed } from "vue";
5+
import { Fabric } from "../../types";
6+
7+
const data = useData();
8+
9+
const options = computed(() => data.theme.value.references as Fabric.ReferencesOptions);
10+
11+
const resources = computed(() =>
12+
Object.entries(data.frontmatter.value.resources ?? {}).map(([href, title]) => {
13+
const newHref = new URL(href, "https://a.com").href.replace("https://a.com", "");
14+
return [newHref, title ?? newHref] as [string, string];
15+
})
16+
);
17+
18+
const files = computed(() => (data.frontmatter.value.files ?? []) as string[]);
19+
20+
const shortestUniquePaths = computed(() =>
21+
files.value.map((file, i) => {
22+
const parts = file.split("/");
23+
for (let len = 1; len <= parts.length; len++) {
24+
const current = parts.slice(-len).join("/");
25+
const isUnique = files.value.every(
26+
(other, j) => i === j || other.split("/").slice(-len).join("/") !== current
27+
);
28+
if (isUnique) return current;
29+
}
30+
return file;
31+
})
32+
);
33+
34+
const getImageSrc = (href: string) =>
35+
`https://www.google.com/s2/favicons?domain=${new URL(href, "https://docs.fabricmc.net").hostname}&sz=16`;
36+
37+
const getFileHref = (path: string) =>
38+
path.replace(/^@/, "https://github.com/FabricMC/fabric-docs/blob/-");
39+
40+
const getFileTitle = (path: string) =>
41+
path.replace(/^@[/]reference[/][^/]+[/]/, "").replace("com/example/docs", "...");
42+
</script>
43+
44+
<template>
45+
<h2 v-if="resources.length">{{ options.resources }}</h2>
46+
<VPLink v-for="[href, title] in resources" :key="href" :href>
47+
<img :src="getImageSrc(href)" alt="" width="16" height="16" />
48+
<span>{{ title }}</span>
49+
</VPLink>
50+
51+
<h2 v-if="files.length">{{ options.files }}</h2>
52+
<VPLink v-for="(f, i) in files" :key="f" :href="getFileHref(f)" :title="getFileTitle(f)">
53+
<code>{{ shortestUniquePaths[i] }}</code>
54+
</VPLink>
55+
56+
<div />
57+
</template>
58+
59+
<style scoped>
60+
div,
61+
h2 {
62+
margin-top: 20px;
63+
padding-top: 16px;
64+
border-top: 1px solid var(--vp-c-divider);
65+
font-size: 12px;
66+
font-weight: bold;
67+
color: var(--vp-c-text-2);
68+
letter-spacing: 0.06em;
69+
text-transform: uppercase;
70+
}
71+
72+
.VPLink {
73+
display: flex;
74+
align-items: flex-start;
75+
line-height: 1.5;
76+
margin-bottom: 4px;
77+
gap: 0.3em;
78+
transition: color 0.15s;
79+
font-size: 12px;
80+
color: var(--vp-c-text-2);
81+
}
82+
83+
.VPLink:has(code) {
84+
align-items: center;
85+
}
86+
87+
.VPLink:hover {
88+
color: var(--vp-c-text-1);
89+
}
90+
91+
img {
92+
margin-top: 1px;
93+
}
94+
95+
@media (min-width: 1280px) {
96+
.VPDocFooter > h2,
97+
.VPDocFooter > .VPLink {
98+
display: none;
99+
}
100+
}
101+
</style>

.vitepress/theme/components/VersionReminder.vue

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,6 @@ div {
5858
display: flex;
5959
flex-direction: row;
6060
gap: 16px;
61-
margin-top: 16px;
6261
padding: 16px;
6362
white-space: pre-wrap;
6463
}
@@ -91,11 +90,20 @@ span {
9190
}
9291
}
9392
93+
.content-container > div {
94+
margin-top: -24px;
95+
margin-bottom: 16px;
96+
}
97+
9498
@media (min-width: 1280px) {
9599
.content-container > div {
96100
display: none;
97101
}
98102
103+
div {
104+
margin-top: 16px;
105+
}
106+
99107
span {
100108
height: 20%;
101109
width: 20%;

.vitepress/theme/index.ts

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ import ChoiceComponent from "./components/ChoiceComponent.vue";
1111
import ColorSwatch from "./components/ColorSwatch.vue";
1212
import DownloadEntry from "./components/DownloadEntry.vue";
1313
import NotFoundComponent from "./components/NotFoundComponent.vue";
14+
import References from "./components/References.vue";
1415
import VersionReminder from "./components/VersionReminder.vue";
1516
import VersionSwitcher from "./components/VersionSwitcher.vue";
1617
import VideoPlayer from "./components/VideoPlayer.vue";
@@ -35,15 +36,12 @@ export default {
3536
app.component("VersionSwitcher", VersionSwitcher);
3637
},
3738
Layout: () => {
38-
const { page, frontmatter, theme } = useData();
39+
const { page, theme } = useData();
3940

4041
const children = {
41-
"doc-before": () => [
42-
frontmatter.value.title ? h("h1", { class: "vp-doc" }, frontmatter.value.title) : null,
43-
h(AuthorsComponent),
44-
h(VersionReminder),
45-
],
46-
"aside-outline-after": () => [h(VersionReminder), h(AuthorsComponent)],
42+
"doc-before": () => [h(VersionReminder), h(AuthorsComponent)],
43+
"doc-footer-before": () => h(References),
44+
"aside-outline-after": () => [h(VersionReminder), h(AuthorsComponent), h(References)],
4745
};
4846

4947
if (theme.value.env !== "github") {

.vitepress/theme/style.css

Lines changed: 7 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -55,11 +55,16 @@ pre {
5555
}
5656

5757
/* Sidebar Scrollbar - Styles scrollbars within the side navigation pane for improved visibility. */
58-
.VPSidebar {
59-
scrollbar-width: thin;
58+
.VPSidebar,
59+
.aside-container {
60+
scrollbar-width: thin !important;
6061
scrollbar-color: var(--vp-c-gray-1) var(--vp-c-bg-alt);
6162
}
6263

64+
.aside-container::-webkit-scrollbar {
65+
display: block;
66+
}
67+
6368
::-webkit-scrollbar {
6469
width: 12px;
6570
}
@@ -129,11 +134,3 @@ kbd:not(.DocSearch-Button-Key) {
129134
margin-left: auto;
130135
margin-right: auto;
131136
}
132-
133-
/* Style the <h1> heading generated from the frontmatter */
134-
h1.vp-doc {
135-
font-size: 32px;
136-
font-weight: 600;
137-
letter-spacing: -0.02em;
138-
line-height: 40px;
139-
}

.vitepress/types.d.ts

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,18 @@ export namespace Fabric {
131131
pooh: string;
132132
}
133133

134+
export interface ReferencesOptions {
135+
/**
136+
* @default "Files Referenced"
137+
*/
138+
files: string;
139+
140+
/**
141+
* @default "Sources & Resources"
142+
*/
143+
resources: string;
144+
}
145+
134146
export interface VersionOptions {
135147
reminder: {
136148
/**
@@ -177,6 +189,7 @@ export namespace Fabric {
177189
download: DownloadOptions;
178190
env: EnvOptions;
179191
notFound: NotFoundOptions;
192+
references: ReferencesOptions;
180193
sidebar: Sidebar;
181194
version: VersionOptions;
182195
}

0 commit comments

Comments
 (0)