Add a dark theme, a two level outline and a writing guide

.vitepress/config/community.ts

@@ -26,7 +26,7 @@ export function community(words: Words, prefix = '', videos: 'youtube' | 'bilibi
         text: words.connect,
         items: [
           row('Discord', LINKS.discord, 'icon-[simple-icons--discord]', '#5865F2'),
-          row('X', LINKS.x, 'icon-[simple-icons--x]', '#000000')
+          row('X', LINKS.x, 'icon-[simple-icons--x]')
         ]
       },
       {

.vitepress/config/en.ts

@@ -89,6 +89,7 @@ export const config = defineConfig({
       next: 'Next page'
     },
     outline: {
+      level: [2, 3],
       label: 'On this page'
     },
     lastUpdated: {

.vitepress/config/goravel-code.ts

@@ -1,36 +1,46 @@
 import type { ThemeOptions } from 'vitepress'
 
-const INK = '#101820'
-const GREY = '#68747d'
-const CYAN = '#0077b3'
-const RED = '#b02b2b'
+interface Palette {
+  ink: string
+  grey: string
+  cyan: string
+  red: string
+}
+
+// These palettes mirror the light and dark values of the theme tokens in
+// .vitepress/theme/goravel.css: ink -> --g-ink, grey -> --g-grey,
+// cyan -> --g-cyan-text, red -> --g-red-text. Keep them in step.
+const LIGHT: Palette = { ink: '#101820', grey: '#636f78', cyan: '#0074ae', red: '#b02b2b' }
+const DARK: Palette = { ink: '#e6edf2', grey: '#8a99a5', cyan: '#5cc4f7', red: '#f59393' }
 
 const rule = (scope: string[], foreground: string) => ({ scope, settings: { foreground } })
 
-export const goravelCode: ThemeOptions = {
-  name: 'goravel',
-  type: 'light',
+const theme = (type: 'light' | 'dark', { ink, grey, cyan, red }: Palette) => ({
+  name: `goravel-${type}`,
+  type,
   // transparent, so a callout's lighter ground shows through
-  colors: { 'editor.background': '#00000000', 'editor.foreground': INK },
+  colors: { 'editor.background': '#00000000', 'editor.foreground': ink },
   tokenColors: [
-    { settings: { foreground: INK } },
-    rule(['comment', 'punctuation.definition.comment', 'string.comment'], GREY),
-    rule(['keyword', 'storage', 'constant.language', 'variable.language'], INK),
-    rule(['entity.name.function', 'support.function', 'entity.name.command'], CYAN),
-    rule(['string', 'constant.numeric', 'constant.character'], GREY),
-    rule(['punctuation', 'keyword.operator', 'meta.brace'], GREY),
-    rule(['markup.inserted', 'meta.diff.header.to-file'], CYAN),
-    rule(['markup.deleted', 'meta.diff.header.from-file'], RED),
+    { settings: { foreground: ink } },
+    rule(['comment', 'punctuation.definition.comment', 'string.comment'], grey),
+    rule(['keyword', 'storage', 'constant.language', 'variable.language'], ink),
+    rule(['entity.name.function', 'support.function', 'entity.name.command'], cyan),
+    rule(['string', 'constant.numeric', 'constant.character'], grey),
+    rule(['punctuation', 'keyword.operator', 'meta.brace'], grey),
+    rule(['markup.inserted', 'meta.diff.header.to-file'], cyan),
+    rule(['markup.deleted', 'meta.diff.header.from-file'], red),
     // narrower scopes that override the grey and cyan rules above
     rule(
       [
         'entity.name.type', 'entity.name.class', 'entity.name.package', 'entity.name.import.go',
         'support.type', 'support.class', 'storage.type.numeric.go', 'storage.type.string.go',
         'storage.type.boolean.go', 'storage.type.byte.go', 'storage.type.error.go',
         'variable', 'meta.definition.variable', 'punctuation.definition.variable.php',
-        'string.unquoted.argument.shell', 'constant.other.option'
+        'string.unquoted.argument.shell', 'constant.other.option', 'entity.name.tag.yaml'
       ],
-      INK
+      ink
     )
   ]
-}
+})
+
+export const goravelCode: ThemeOptions = { light: theme('light', LIGHT), dark: theme('dark', DARK) }

.vitepress/config/shared.ts

@@ -40,14 +40,29 @@ function liftFileNames(md: MarkdownRenderer) {
   const fence = md.renderer.rules.fence!
   md.renderer.rules.fence = (tokens, idx, options, env, self) => {
     const token = tokens[idx]
-    const path = token.content.match(/^(?:\/\/|#|--) ?([\w.@-]+(?:\/[\w.@-]+)*\.\w+)\n/)
+    // a demo holds markdown, not one code block, so its first line is never a file name
+    if (/^md\s+demo\b/.test(token.info.trim())) return fence(tokens, idx, options, env, self)
+    const path = token.content.match(/^(?:\/\/|#|--) ?((?:[\w.@-]+\/)*[\w.@-]*\.\w+)\n/)
     // line highlights like {2,4} count from the first line, so a block using them keeps it
     if (!path || /\{[\d,-]+\}/.test(token.info)) return fence(tokens, idx, options, env, self)
     token.content = token.content.slice(path[0].length)
     return fence(tokens, idx, options, env, self).replace(/<span class="lang">[^<]*<\/span>/, `<span class="lang">${path[1]}</span>`)
   }
 }
 
+// a fence opened as ````md demo shows its source and then renders it, so an example is written once;
+// the rendered headings are kept out of the outline
+function renderDemos(md: MarkdownRenderer) {
+  const fence = md.renderer.rules.fence!
+  md.renderer.rules.fence = (tokens, idx, options, env, self) => {
+    const source = fence(tokens, idx, options, env, self)
+    if (!/^md\s+demo\b/.test(tokens[idx].info.trim())) return source
+    // a demo teaches syntax, so a link in it is illustrative; keep it out of the page's dead-link check
+    // (VitePress's link plugin pushes into env.links)
+    return source + md.render(tokens[idx].content, { ...env, links: [] }).replace(/<h([1-6])(?![^>]*\bclass=)/g, '<h$1 class="ignore-header"')
+  }
+}
+
 // a percentage in the packages table's coverage column gets a bar beside it when the page is built
 function drawCoverageBars(md: MarkdownRenderer) {
   const close = md.renderer.rules.td_close ?? ((tokens, idx, options, _env, self) => self.renderToken(tokens, idx, options))
@@ -66,9 +81,9 @@ export const shared = defineConfig({
   rewrites: {
     'en/:rest*': ':rest*'
   },
+  srcExclude: ['**/README.md', '**/AGENTS.md'],
 
-  // there is no dark design
-  appearance: false,
+  appearance: true,
   lastUpdated: true,
   cleanUrls: false,
   metaChunk: true,
@@ -117,6 +132,7 @@ export const shared = defineConfig({
       md.use(deflist)
       markCustomContainerTitles(md)
       liftFileNames(md)
+      renderDemos(md)
       drawCoverageBars(md)
     },
     languages: ['go']

.vitepress/config/zh_CN.ts

@@ -74,6 +74,7 @@ export const config = defineConfig({
       next: "下一页"
     },
     outline: {
+      level: [2, 3],
       label: "页面导航"
     },
     lastUpdated: {

.vitepress/theme/Layout.vue

@@ -1,7 +1,6 @@
 <script setup lang="ts">
 import DefaultTheme from 'vitepress/theme-without-fonts'
 import DocMeta from './components/DocMeta.vue'
-import MethodIndex from './components/MethodIndex.vue'
 import NotFound from './components/NotFound.vue'
 import DocsFooterLinks from './components/DocsFooterLinks.vue'
 
@@ -11,7 +10,6 @@ const { Layout } = DefaultTheme
 <template>
   <Layout>
     <template #doc-before><DocMeta /></template>
-    <template #aside-outline-after><MethodIndex /></template>
     <template #not-found><NotFound /></template>
     <template #layout-bottom><DocsFooterLinks /></template>
   </Layout>

.vitepress/theme/components/Brand.vue

@@ -10,7 +10,7 @@ defineProps<{ laravel?: boolean; goravel?: boolean; no?: boolean }>()
   </span>
 </template>
 
-<style>
+<style scoped>
 .brand {
   display: inline-flex;
   align-items: center;
@@ -22,7 +22,7 @@ defineProps<{ laravel?: boolean; goravel?: boolean; no?: boolean }>()
 .brand-mark {
   width: 14px;
   height: 14px;
-  color: #ff2d20;
+  color: var(--g-laravel);
 }
 
 .brand-state {

.vitepress/theme/components/NavBar.vue

@@ -15,9 +15,9 @@ import SelectMenu from './SelectMenu.vue'
 defineProps<{ isScreenOpen: boolean }>()
 defineEmits<{ (e: 'toggle-screen'): void }>()
 
-const { theme, localeIndex } = useData()
+const { theme, localeIndex, isDark } = useData()
 const { hasSidebar } = useSidebar()
-const { languages, currentLang } = useI18n()
+const { tr, languages, currentLang } = useI18n()
 const route = useRoute()
 
 const home = computed(() => (localeIndex.value === 'root' ? '/' : `/${localeIndex.value}/`))
@@ -67,6 +67,9 @@ const onFocusOut = useDismiss(navRoot, () => (menuOpen.value = false))
     <div class="utils">
       <SelectMenu v-if="hasSidebar" :label="version" :options="VERSIONS" />
       <SelectMenu class="lang" :label="currentLang.label!" :options="languages" />
+      <button type="button" class="theme" :aria-label="tr('Switch theme')" @click="isDark = !isDark">
+        <span class="sun icon-[lucide--sun]" /><span class="moon icon-[lucide--moon]" />
+      </button>
       <VPSocialLinks class="social" :links="theme.socialLinks ?? []" />
     </div>
 
@@ -178,7 +181,7 @@ const onFocusOut = useDismiss(navRoot, () => (menuOpen.value = false))
   padding: 0 var(--g-shell-inset);
   border-bottom: 1px solid var(--g-line);
   background: var(--g-white);
-  box-shadow: 0 24px 40px -24px rgba(16, 24, 32, 0.12);
+  box-shadow: 0 24px 40px -24px rgba(var(--g-shadow), 0.12);
 }
 
 .group {
@@ -300,6 +303,37 @@ const onFocusOut = useDismiss(navRoot, () => (menuOpen.value = false))
   margin-left: 20px;
 }
 
+.theme {
+  display: grid;
+  place-items: center;
+  width: var(--g-control);
+  height: var(--g-control);
+  margin: 0 -8px 0 -6px;
+  border-radius: 2px;
+  color: var(--g-grey);
+}
+
+.theme:hover {
+  color: var(--g-ink);
+}
+
+.theme span {
+  width: 17px;
+  height: 17px;
+}
+
+.moon {
+  display: none;
+}
+
+:global(.dark .bar .theme .sun) {
+  display: none;
+}
+
+:global(.dark .bar .theme .moon) {
+  display: block;
+}
+
 .social {
   margin-left: 2px;
 }