Skip to content

Commit

Permalink
feat(docs): add the theme config document builder
Browse files Browse the repository at this point in the history
  • Loading branch information
WRXinYue committed Aug 30, 2024
1 parent 5d75bf9 commit 3e44dd0
Show file tree
Hide file tree
Showing 21 changed files with 599 additions and 171 deletions.
3 changes: 0 additions & 3 deletions docs/.valaxy/typed-router.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,6 @@ declare module 'vue-router/auto-routes' {
'/components/SakuraCard': RouteRecordInfo<'/components/SakuraCard', '/components/SakuraCard', Record<never, never>, Record<never, never>>,
'/components/SakuraCategories': RouteRecordInfo<'/components/SakuraCategories', '/components/SakuraCategories', Record<never, never>, Record<never, never>>,
'/components/SakuraCategory': RouteRecordInfo<'/components/SakuraCategory', '/components/SakuraCategory', Record<never, never>, Record<never, never>>,
'/components/SakuraDate': RouteRecordInfo<'/components/SakuraDate', '/components/SakuraDate', Record<never, never>, Record<never, never>>,
'/components/SakuraFooter': RouteRecordInfo<'/components/SakuraFooter', '/components/SakuraFooter', Record<never, never>, Record<never, never>>,
'/components/SakuraFooterNavigation': RouteRecordInfo<'/components/SakuraFooterNavigation', '/components/SakuraFooterNavigation', Record<never, never>, Record<never, never>>,
'/components/SakuraGlitchText': RouteRecordInfo<'/components/SakuraGlitchText', '/components/SakuraGlitchText', Record<never, never>, Record<never, never>>,
Expand Down Expand Up @@ -106,14 +105,12 @@ declare module 'vue-router/auto-routes' {
'/examples/': RouteRecordInfo<'/examples/', '/examples', Record<never, never>, Record<never, never>>,
'/examples/config': RouteRecordInfo<'/examples/config', '/examples/config', Record<never, never>, Record<never, never>>,
'/examples/gallery': RouteRecordInfo<'/examples/gallery', '/examples/gallery', Record<never, never>, Record<never, never>>,
'/guide/': RouteRecordInfo<'/guide/', '/guide', Record<never, never>, Record<never, never>>,
'/guide/installation': RouteRecordInfo<'/guide/installation', '/guide/installation', Record<never, never>, Record<never, never>>,
'/guide/update': RouteRecordInfo<'/guide/update', '/guide/update', Record<never, never>, Record<never, never>>,
'/layouts/': RouteRecordInfo<'/layouts/', '/layouts', Record<never, never>, Record<never, never>>,
'/layouts/404': RouteRecordInfo<'/layouts/404', '/layouts/404', Record<never, never>, Record<never, never>>,
'/layouts/archives': RouteRecordInfo<'/layouts/archives', '/layouts/archives', Record<never, never>, Record<never, never>>,
'/layouts/categories': RouteRecordInfo<'/layouts/categories', '/layouts/categories', Record<never, never>, Record<never, never>>,
'/layouts/default': RouteRecordInfo<'/layouts/default', '/layouts/default', Record<never, never>, Record<never, never>>,
'/layouts/home': RouteRecordInfo<'/layouts/home', '/layouts/home', Record<never, never>, Record<never, never>>,
'/layouts/links': RouteRecordInfo<'/layouts/links', '/layouts/links', Record<never, never>, Record<never, never>>,
'/layouts/post': RouteRecordInfo<'/layouts/post', '/layouts/post', Record<never, never>, Record<never, never>>,
Expand Down
97 changes: 97 additions & 0 deletions docs/components/TsdocTable.vue
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
<script setup lang="ts">
import { members } from 'virtual:tsdoc-module'
</script>

<template>
<div class="markdown-body">
<table class="table-container">
<thead>
<tr>
<th>属性名</th>
<th>类型</th>
<th>默认值</th>
<th>说明</th>
</tr>
</thead>
<tbody v-for="(member, memberIndex) in members" :key="memberIndex" class="member-table">
<tr>
<td>
<strong>{{ member.name }}</strong>
</td>
<td>
<template v-for="(type, typeIndex) in member.types" :key="typeIndex">
<code>
{{ type }}
</code>
<template v-if="typeIndex < member.types.length - 1">
|
</template>
</template>
</td>
<td>
<template v-if="member.jsDocTags?.find(tag => tag.tagName === 'default')">
<code>
{{ member.jsDocTags?.find(tag => tag.tagName === 'default')?.comment }}
</code>
</template>
<template v-else>
</template>
</td>
<td>
<template v-for="(tag, tagIndex) in member.jsDocTags" :key="tagIndex">
<span v-if="tag.tagName === 'zh'" lang="zh-CN">
{{ tag.comment }}
</span>
<span v-else-if="tag.tagName === 'en'" lang="en">
{{ tag.comment }}
</span>
</template>
<template v-if="!member.jsDocTags || !member.jsDocTags.length">
</template>
</td>
</tr>
<!-- children -->
<tr v-for="(memberItem, subIndex) in member.children" :key="subIndex" class="child-row">
<td style="padding-left: 20px;">
{{ memberItem.name }}
</td>
<td>
<template v-for="(type, typeIndex) in memberItem.types" :key="typeIndex">
<code>
{{ type }}
</code>
<template v-if="typeIndex < memberItem.types.length - 1">
|
</template>
</template>
</td>
<td>
<template v-if="memberItem.jsDocTags?.find(tag => tag.tagName === 'default')">
<code>
{{ memberItem.jsDocTags?.find(tag => tag.tagName === 'default')?.comment }}
</code>
</template>
<template v-else>
</template>
</td>
<td>
<template v-for="(tag, tagIndex) in memberItem.jsDocTags" :key="tagIndex">
<span v-if="tag.tagName === 'zh'" lang="zh-CN">
{{ tag.comment }}
</span>
<span v-if="tag.tagName === 'en'" lang="en">
{{ tag.comment }}
</span>
</template>
<template v-if="!memberItem.jsDocTags || !memberItem.jsDocTags.length">
</template>
</td>
</tr>
</tbody>
</table>
</div>
</template>
17 changes: 17 additions & 0 deletions docs/components/Version.vue
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
<script setup lang="ts">
import { version as SakuraVersion } from 'valaxy-theme-sakura/package.json'
import { version as ValaxyVersion } from 'valaxy/package.json'
defineProps<{
type?: 'sakura' | 'valaxy'
}>()
</script>

<template>
<template v-if="type === 'sakura'">
{{ SakuraVersion }}
</template>
<template v-if="type === 'valaxy'">
{{ ValaxyVersion }}
</template>
</template>
2 changes: 2 additions & 0 deletions docs/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -16,11 +16,13 @@
"valaxy-addon-git-log": "workspace:*",
"valaxy-addon-twikoo": "^0.0.3",
"valaxy-theme-sakura": "workspace:*",
"vite-plugin-tsdoc": "workspace:*",
"vue-toastification": "2.0.0-rc.5"
},
"devDependencies": {
"@iconify-json/simple-icons": "^1.1.92",
"nodemon": "^3.1.3",
"typedoc": "^0.26.6",
"typescript": "^5.3.3"
}
}
7 changes: 0 additions & 7 deletions docs/pages/components/SakuraDate.md

This file was deleted.

50 changes: 21 additions & 29 deletions docs/pages/components/SakuraNavbar.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,6 @@ categories:

<SakuraNavbarPG />

## 侧边导航栏 <SupTag>0.6.1</SupTag>

```vue
<template>
<SakuraNavbar :col="true" />
</template>
```

## 启用 `sticky`

```scss
Expand All @@ -44,30 +36,30 @@ categories:

### Attributes

| 属性名 | 类型 | 默认值 | 说明 |
| ---- | ---- | ---- | ---- |
| favicon | `boolean` | `undefined` | 导航栏图标, 默认为 `themeConfig.favicon` |
| title | `string \| string[]` | `undefined` | --- |
| invert | `boolean` | `false` | 滚动触发反转, 需开启 `autoHide` 选项 |
| autoHide | `boolean` | `false` | 是否自动隐藏导航栏 |
| animIn | `string` \| `string[]` | `animation-fade-in-left` | 进入动画效果 |
| animOut | `string` \| `string[]` | `animation-fade-in-left` | 离开动画效果 |
| 属性名 | 类型 | 默认值 | 说明 |
| -------- | ---------------------- | ------------------------ | ---------------------------------------- |
| favicon | `boolean` | `undefined` | 导航栏图标, 默认为 `themeConfig.favicon` |
| title | `string \| string[]` | `undefined` | --- |
| invert | `boolean` | `false` | 滚动触发反转, 需开启 `autoHide` 选项 |
| autoHide | `boolean` | `false` | 是否自动隐藏导航栏 |
| animIn | `string` \| `string[]` | `animation-fade-in-left` | 进入动画效果 |
| animOut | `string` \| `string[]` | `animation-fade-in-left` | 离开动画效果 |

### ThemeConfig

| 属性名 | 类型 | 默认值 | 说明 |
| ---- | ---- | ---- | ---- |
| favicon | `boolean` | `false` | 导航栏图标, 默认关闭 |
| navbar | `NavItem[]` | `undefined` | 导航栏 |
| navbarTitle | `string` \| `string[]` | `''` | 导航栏标题 |
| 属性名 | 类型 | 默认值 | 说明 |
| ----------- | ---------------------- | ----------- | -------------------- |
| favicon | `boolean` | `false` | 导航栏图标, 默认关闭 |
| navbar | `NavItem[]` | `undefined` | 导航栏 |
| navbarTitle | `string` \| `string[]` | `''` | 导航栏标题 |

**NavItem:**

| 属性名 | 类型 | 默认值 | 说明 |
| ---- | ---- | ---- | ---- |
| text | `string` | --- | 导航栏项的显示文本 |
| locale | `string` \| `number` | --- | 导航栏项的语言设置,用于国际化支持 |
| link | `string` | --- | 导航栏项的链接地址,点击后将被重定向到此URL |
| icon | `string` | --- | 导航栏项的图标,可以是图标的路径或图标库中的一个标识符 |
| isExternal | `boolean` | --- | 是否使用 a 标签跳转 |
| submenu | `NavItem[]` | --- | 二级菜单 |
| 属性名 | 类型 | 默认值 | 说明 |
| ---------- | -------------------- | ------ | ------------------------------------------------------ |
| text | `string` | --- | 导航栏项的显示文本 |
| locale | `string` \| `number` | --- | 导航栏项的语言设置,用于国际化支持 |
| link | `string` | --- | 导航栏项的链接地址,点击后将被重定向到此URL |
| icon | `string` | --- | 导航栏项的图标,可以是图标的路径或图标库中的一个标识符 |
| isExternal | `boolean` | --- | 是否使用 a 标签跳转 |
| submenu | `NavItem[]` | --- | 二级菜单 |
2 changes: 2 additions & 0 deletions docs/pages/config/theme.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ categories:

如下是主题配置(ThemeConfig)总览,具体效果可以看各个组件的配置说明

<TsdocTable />

<<< @/../theme/types/index.d.ts

## 示例
Expand Down
Empty file removed docs/pages/guide/index.md
Empty file.
17 changes: 11 additions & 6 deletions docs/pages/guide/installation.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ end: true
top: 100
---

<TsdocTable />

## 安装{lang="zh-CN"}

## installation {lang="en"}
Expand Down Expand Up @@ -34,13 +36,13 @@ To use Valaxy, your computer must have Node.js installed.
::: zh-CN
| 版本 | Node | valaxy |
| --- | --- | --- |
| 0.6.0 + | Node >= 18.12 | valaxy >= 0.18.5 |
| <Version type="sakura" /> + | Node >= 18.12 | valaxy >= <Version type="valaxy" /> |
:::

::: en
| version | Node | valaxy |
| --- | --- | --- |
| 0.6.0 + | Node >= 18.12 | valaxy >= 0.18.5 |
| <Version type="sakura" /> + | Node >= 18.12 | valaxy >= <Version type="valaxy" /> |
:::

### 创建 Valaxy 博客项目{lang="zh-CN"}
Expand Down Expand Up @@ -145,14 +147,14 @@ The theme will not be activated after installation. First, enable the `sakura` t
Open the `valaxy.config.ts` file in the root directory of the Valaxy project, and modify the positions indicated below to ensure that TypeScript's type checking and auto-completion features work correctly:
:::

~~~ts {2-4}
```ts {2-4}
import { defineValaxyConfig } from 'valaxy'
import type { ThemeUserConfig } from 'valaxy-theme-sakura'

export default defineValaxyConfig<ThemeUserConfig>({
theme: 'sakura'
})
~~~
```

::: zh-CN
::: tip
Expand All @@ -169,25 +171,27 @@ In simple terms, TypeScript can automatically complete code suggestions while yo
:::

:::zh-CN

> 主题名称自动根据 `valaxy-theme-xxx` 的格式获取,如本主题名为`valaxy-theme-sakura`,所以sakura就是这个主题的名称
在theme选项中填入 `sakura` 来实现主题切换
:::

:::en

> The theme name is automatically retrieved in the format `valaxy-theme-xxx`. For example, this theme is named `valaxy-theme-sakura`, so sakura is the name of this theme.
Fill in `sakura` in the theme option to switch themes.
:::

~~~ts {5}
```ts {5}
import { defineValaxyConfig } from 'valaxy'
import type { ThemeUserConfig } from 'valaxy-theme-sakura'

export default defineValaxyConfig<ThemeUserConfig>({
theme: 'sakura'
})
~~~
```

:::zh-CN
::: warning
Expand All @@ -200,6 +204,7 @@ Please ensure that you have correctly imported all the necessary types. Incorrec
:::

:::zh-CN

> 通过遵循上述步骤,您可以顺利地在您的项目中启用 sakura 主题,并利用 TypeScript 提供的类型安全和代码智能提示功能,享受到更加愉快的博客使用体验
如果创建 Valaxy 项目的时候没有安装依赖,那么我们就要手动安装依赖:
Expand Down
4 changes: 2 additions & 2 deletions docs/pages/layouts/404.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
title: 404 layout
title_zh-CN: 404布局 (404)
title_zh-CN: 404 布局
categories:
- layouts
---

## 404布局 404
## 404布局

一般情况下遇到不存在的页面会自动重定向到首页,除非您取消了重定向

Expand Down
16 changes: 0 additions & 16 deletions docs/pages/layouts/default.md

This file was deleted.

1 change: 1 addition & 0 deletions docs/styles/index.scss
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
@use 'valaxy/client/styles/mixins/index.scss' as *;
@use 'valaxy-theme-sakura/styles/themes/sakura/css-vars.scss' as *;
@use 'valaxy-theme-sakura/styles/markdown/prose.scss' as *;

:root {
--st-c-text-deeper: var(--st-c-brand);
Expand Down
1 change: 0 additions & 1 deletion docs/tsconfig.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,6 @@
"~/*": ["./*"]
},
"resolveJsonModule": true,
"types": ["element-plus/global"],
"strict": true,
"strictNullChecks": true,
"noUnusedLocals": true,
Expand Down
5 changes: 4 additions & 1 deletion docs/valaxy.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import { defineValaxyConfig } from 'valaxy'
import type { ThemeConfig } from 'valaxy-theme-sakura'
import { addonWaline } from 'valaxy-addon-waline'
import { addonGitLog } from 'valaxy-addon-git-log'
import tsdocPlugin from 'vite-plugin-tsdoc'

export default defineValaxyConfig<ThemeConfig>({
siteConfig: {
Expand Down Expand Up @@ -103,7 +104,6 @@ export default defineValaxyConfig<ThemeConfig>({
'config',
'theme',
'styles',
'tutorial', // TODO:
'layouts',
'components-custom',
'components-layout',
Expand Down Expand Up @@ -142,5 +142,8 @@ export default defineValaxyConfig<ThemeConfig>({
optimizeDeps: {
include: ['d3', 'monaco-editor'],
},
plugins: [
tsdocPlugin({ theme: 'sakura' }),
],
},
})
Loading

0 comments on commit 3e44dd0

Please sign in to comment.