feat: add api docs

demo/custom/package.json

@@ -16,6 +16,6 @@
     "valaxy-theme-custom": "file:./valaxy-theme-custom"
   },
   "devDependencies": {
-    "typescript": "^5.4.2"
+    "typescript": "^5.4.3"
   }
 }

demo/custom/valaxy-theme-custom/package.json

@@ -1,7 +1,7 @@
 {
   "name": "valaxy-theme-custom",
   "version": "0.0.0",
-  "packageManager": "pnpm@8.15.4",
+  "packageManager": "pnpm@8.15.5",
   "author": {
     "email": "me@yunyoujun.cn",
     "name": "YunYouJun",
@@ -22,6 +22,6 @@
   "types": "types/index.d.ts",
   "dependencies": {
     "@iconify-json/ant-design": "^1.1.15",
-    "@iconify-json/simple-icons": "^1.1.94"
+    "@iconify-json/simple-icons": "^1.1.96"
   }
 }

docs/.gitignore

@@ -8,3 +8,9 @@ public/feed.xml
 
 # valaxy rss
 public/feed.json
+
+# api docs
+pages/api
+
+# valaxy fuse
+public/valaxy-fuse-list.json

docs/package.json

@@ -20,9 +20,9 @@
     "valaxy-theme-press": "link:../packages/valaxy-theme-press"
   },
   "devDependencies": {
-    "@iconify-json/simple-icons": "^1.1.94",
+    "@iconify-json/simple-icons": "^1.1.96",
     "nodemon": "^3.1.0",
-    "vite": "^5.1.5",
+    "vite": "^5.2.4",
     "vitepress": "1.0.0-rc.45"
   }
 }

docs/pages/themes/write.md

@@ -158,6 +158,34 @@ export interface ValaxyConfig {
 
 :::
 
+### Client
+
+#### Toggle Dark
+
+- `isDark`: Whether dark mode is enabled
+- `toggleDark`: Toggle dark mode
+- `toggleDarkWithTransition`: Toggle dark mode with transition
+
+Example:
+
+```vue
+<script lang="ts" setup>
+import { isDark, toggleDarkWithTransition } from 'valaxy'
+</script>
+
+<template>
+  <button class="yun-icon-btn" @click="toggleDarkWithTransition">
+    <div i="ri-sun-line dark:ri-moon-line" />
+  </button>
+</template>
+```
+
+### Node
+
+#### Hooks
+
+- [钩子](/guide/custom/hooks.md)
+
 ## 开始编写
 
 ### App.vue

docs/pages/typedoc.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": [
+    "../../packages/valaxy/client",
+    "../../packages/valaxy/node"
+  ],
+  "plugin": [
+    "typedoc-plugin-markdown",
+    "typedoc-vitepress-theme"
+  ],
+  "out": "./api",
+  "docsRoot": ".",
+  "githubPages": false,
+  "excludePrivate": true,
+  "excludeProtected": true,
+  "excludeInternal": true,
+  "readme": "none",
+  "includes": "../../packages/valaxy"
+}

docs/valaxy.config.ts

@@ -3,6 +3,7 @@ import { defineValaxyConfig } from 'valaxy'
 import type { PressTheme } from 'valaxy-theme-press'
 import { addonAlgolia } from 'valaxy-addon-algolia'
 import { addonComponents } from 'valaxy-addon-components'
+import typedocSidebar from './pages/api/typedoc-sidebar.json'
 
 const COMMIT_ID = process.env.CF_PAGES_COMMIT_SHA || process.env.COMMIT_REF
 const commitRef = COMMIT_ID?.slice(0, 8) || 'dev'
@@ -13,6 +14,30 @@ const safelist = [
   'i-ri-github-line',
 ]
 
+export function getTypeDocSidebar() {
+  // replace .md to ''
+  function replaceMd(str: string) {
+    if (str.endsWith('/index.md'))
+      return str.slice(0, -9)
+    if (str.endsWith('.md'))
+      return str.slice(0, -3)
+  }
+
+  function formatSidebar(sidebar: PressTheme.SidebarItem[]): PressTheme.SidebarItem[] {
+    return sidebar.map((item) => {
+      if (item.link)
+        item.link = replaceMd(item.link)
+
+      if (item.items)
+        item.items = formatSidebar(item.items)
+
+      return item
+    })
+  }
+
+  return formatSidebar(typedocSidebar as PressTheme.SidebarItem[])
+}
+
 export default defineValaxyConfig<PressTheme.Config>({
   siteConfig: {
     title: 'Valaxy',
@@ -69,6 +94,10 @@ export default defineValaxyConfig<PressTheme.Config>({
       'theme',
       'addon',
       'dev',
+      {
+        text: 'API',
+        items: getTypeDocSidebar(),
+      },
     ],
     socialLinks: [
       { icon: 'i-ri-github-line', link: 'https://github.com/YunYouJun/valaxy' },
@@ -89,20 +118,7 @@ export default defineValaxyConfig<PressTheme.Config>({
       },
       {
         text: 'API',
-        items: [
-          {
-            text: 'Core',
-            link: '/api/',
-          },
-          {
-            text: 'Theme',
-            link: '/api/theme',
-          },
-          {
-            text: 'Addon',
-            link: '/api/addon',
-          },
-        ],
+        link: '/api/',
       },
       {
         text: 'nav.theme',

package.json

@@ -3,7 +3,7 @@
   "type": "module",
   "version": "0.18.5",
   "private": true,
-  "packageManager": "pnpm@8.15.4",
+  "packageManager": "pnpm@8.15.5",
   "description": "📄 Vite & Vue powered static blog generator.",
   "author": {
     "email": "me@yunyoujun.cn",
@@ -40,9 +40,10 @@
     "dev:lib": "pnpm -C packages/valaxy run dev",
     "dev": "pnpm -r --filter=./packages/** --parallel run dev",
     "devtools": "pnpm -C packages/devtools run dev",
+    "predocs": "typedoc --options docs/pages/typedoc.json",
     "docs": "pnpm -C docs run dev",
     "docs:dev": "pnpm -C docs run dev",
-    "docs:build": "pnpm -C docs run build",
+    "docs:build": "npm run predocs && pnpm -C docs run build",
     "docs:serve": "pnpm -C docs run serve",
     "docs:vitepress": "pnpm -C docs run vitepress:dev",
     "e2e": "playwright test",
@@ -76,13 +77,13 @@
     "@antfu/eslint-config": "2.8.0",
     "@iconify-json/logos": "^1.1.42",
     "@iconify-json/vscode-icons": "^1.1.33",
-    "@microsoft/api-extractor": "^7.42.3",
+    "@microsoft/api-extractor": "^7.43.0",
     "@playwright/test": "^1.42.1",
     "@types/debug": "^4.1.12",
     "@types/markdown-it-attrs": "^4.1.3",
     "@types/markdown-it-container": "^2.0.9",
     "@types/markdown-it-emoji": "^2.0.4",
-    "@types/node": "^20.11.25",
+    "@types/node": "^20.11.30",
     "@types/prompts": "^2.4.9",
     "@types/resolve": "^1.20.6",
     "bumpp": "^9.4.0",
@@ -99,9 +100,12 @@
     "stylelint-config-standard-scss": "^13.0.0",
     "tsup": "^8.0.2",
     "tsx": "^4.7.1",
-    "typescript": "^5.4.2",
+    "typedoc": "^0.25.12",
+    "typedoc-plugin-markdown": "4.0.0-next.23",
+    "typedoc-vitepress-theme": "1.0.0-next.3",
+    "typescript": "^5.4.3",
     "unbuild": "^2.0.0",
-    "vitest": "^1.3.1",
+    "vitest": "^1.4.0",
     "vue-tsc": "2.0.6",
     "zx": "^7.2.3"
   },

packages/create-valaxy/template-blog/package.json

@@ -16,6 +16,6 @@
     "valaxy-theme-yun": "0.18.5"
   },
   "devDependencies": {
-    "typescript": "^5.4.2"
+    "typescript": "^5.4.3"
   }
 }

packages/devtools/package.json

@@ -29,7 +29,7 @@
   },
   "dependencies": {
     "@rollup/pluginutils": "^5.1.0",
-    "axios": "^1.6.7",
+    "axios": "^1.6.8",
     "body-parser": "^1.20.2",
     "http-proxy-middleware": "^2.0.6",
     "picocolors": "^1.0.0",
@@ -42,9 +42,9 @@
     "@types/splitpanes": "^2.2.6",
     "gray-matter": "^4.0.3",
     "splitpanes": "^3.1.5",
-    "typescript": "^5.4.2",
+    "typescript": "^5.4.3",
     "unbuild": "^2.0.0",
-    "unplugin-vue-router": "^0.8.4",
-    "vite": "^5.1.5"
+    "unplugin-vue-router": "^0.8.5",
+    "vite": "^5.2.4"
   }
 }

packages/valaxy-theme-press/components/PressSidebarItem.vue

@@ -91,7 +91,7 @@ const htmlText = computed(() => t(props.item.text || ''))
       <component :is="textTag" v-else class="text ml-1" v-html="htmlText" />
 
       <button
-        v-if="item.collapsed != null"
+        v-if="item.collapsed != null && item.items"
         tabindex="0" role="button" aria-label="toggle section"
         class="caret folder-action inline-flex cursor-pointer"
         @click="onCaretClick" @keydown.enter="onCaretClick"

packages/valaxy-theme-yun/package.json

@@ -20,7 +20,7 @@
   "dependencies": {
     "@explosions/fireworks": "^0.0.2",
     "@iconify-json/ant-design": "^1.1.15",
-    "@iconify-json/simple-icons": "^1.1.94",
+    "@iconify-json/simple-icons": "^1.1.96",
     "animejs": "^3.2.2"
   },
   "devDependencies": {

packages/valaxy/node/plugins/markdown/markdownToVue.ts

@@ -86,6 +86,8 @@ export async function createMarkdownToVueRenderFn(
   ): Promise<MarkdownCompileResult> => {
     const file = id
     const relativePath = path.relative(srcDir, file)
+    // do not await, depend options.env
+    const deadLinks = scanDeadLinks(code, id)
 
     // only in build
     const cacheKey = JSON.stringify({ code, id })
@@ -113,7 +115,6 @@ export async function createMarkdownToVueRenderFn(
     // run it before vue and after md parse
     code = await transformEncrypt(code, id, pageData)
 
-    const deadLinks = scanDeadLinks(code, id)
     code = transformMarkdown(code, id, pageData)
 
     debug(`[render] ${file} in ${Date.now() - start}ms.`)

packages/valaxy/node/plugins/markdown/transform/dead-links.ts

@@ -7,7 +7,7 @@ import { EXTERNAL_URL_RE } from '../../../constants'
 import { treatAsHtml } from '../utils'
 
 export function createScanDeadLinks(options: ResolvedValaxyOptions) {
-  const srcDir = options.userRoot
+  const srcDir = path.resolve(options.userRoot, 'pages')
   const { ignoreDeadLinks } = options.config
   const publicDir = options.config.vite?.publicDir || 'public'