docs: update docs

2024-08-18 09:58:02 +08:00 · 2024-08-18 09:58:02 +08:00 · de6ebed284
commit de6ebed284
parent edc0297c0c
6 changed files with 197 additions and 18 deletions
--- a/docs/.vuepress/config.ts
+++ b/docs/.vuepress/config.ts
@ -2,6 +2,7 @@ import * as path from 'node:path'
 import { type UserConfig, defineUserConfig } from 'vuepress'
 import { viteBundler } from '@vuepress/bundler-vite'
 import { addViteOptimizeDepsInclude, addViteSsrExternal } from '@vuepress/helper'
+import { peerDependencies } from '../package.json'
 import { theme } from './theme.js'

 export default defineUserConfig({
@ -27,6 +28,10 @@ export default defineUserConfig({
    addViteSsrExternal(bundlerOptions, app, '@simonwep/pickr')
  },

+  define: {
+    __VUEPRESS_VERSION__: peerDependencies.vuepress,
+  },
+
  bundler: viteBundler(),

  theme,
--- a/docs/.vuepress/themes/components/ThemeColors.vue
+++ b/docs/.vuepress/themes/components/ThemeColors.vue
@ -16,8 +16,10 @@ const { lightColors, darkColors, css, reset } = useThemeColors()
      <h4>{{ name }}</h4>
      <section v-for="color in group" :key="color.key" class="theme-color">
        <ColorPick v-model="color.value" />
-        <h5>{{ color.name }}</h5>
-        <span class="desc">{{ color.desc }}</span>
+        <div>
+          <h5>{{ color.name }}</h5>
+          <span class="desc">{{ color.desc }}</span>
+        </div>
      </section>
    </div>
  </div>
@ -27,8 +29,10 @@ const { lightColors, darkColors, css, reset } = useThemeColors()
      <h4>{{ name }}</h4>
      <section v-for="color in group" :key="color.key" class="theme-color">
        <ColorPick v-model="color.value" />
-        <h5>{{ color.name }}</h5>
-        <span class="desc">{{ color.desc }}</span>
+        <div>
+          <h5>{{ color.name }}</h5>
+          <span class="desc">{{ color.desc }}</span>
+        </div>
      </section>
    </div>
  </div>
--- a/docs/1.示例/照片类作品示例.md
+++ b/docs/1.示例/照片类作品示例.md
@ -0,0 +1,70 @@
+---
+title: 照片类作品示例
+author: Plume Theme
+createTime: 2024/08/17 14:30:23
+permalink: /article/30995vcd/
+---
+
+<script setup>
+import { ref, onMounted } from 'vue'
+
+const list = ref([])
+
+onMounted(async () => {
+  const res = await fetch('https://api.pengzhanbo.cn/wallpaper/bing/list/zh/').then((res) => res.json())
+  list.value = res.map(item => ({
+    title: item.title,
+    image: item.url,
+    author: item.copyright.replace('© ', '').split('/')?.[0].trim(),
+    description: item.description,
+    date: item.ssd.replace(/(\d{4})(\d{2})(\d{2})_(\d{2})(\d{2})/, (_, y, m, d, h, mm) => `${y}/${m}/${d} ${h}:${mm}`),
+    href: item.url
+  }))
+})
+</script>
+
+## 单列照片
+
+```md :no-line-numbers
+<ImageCard v-for="item in list" :key="item.image" v-bind="item" />
+```
+
+<ImageCard v-for="item in list" :key="item.image" v-bind="item" />
+
+## 双列照片
+
+```md :no-line-numbers
+<CardGrid cols="2">
+  <ImageCard v-for="item in list" :key="item.image" v-bind="item" />
+</CardGrid>
+```
+
+<CardGrid cols="2">
+  <ImageCard v-for="item in list" :key="item.image" v-bind="item" />
+</CardGrid>
+
+## 三列照片
+
+```md :no-line-numbers
+<CardGrid cols="3">
+  <ImageCard v-for="item in list" :key="item.image" v-bind="item" />
+</CardGrid>
+```
+
+<CardGrid cols="3">
+  <ImageCard v-for="item in list" :key="item.image" v-bind="item" />
+</CardGrid>
+
+## 不同尺寸设备适配
+
+调整窗口大小以观察效果
+
+```md :no-line-numbers
+<CardGrid :cols="{ sm: 2, md: 3, lg: 3 }">
+  <ImageCard v-for="item in list" :key="item.image" v-bind="item" />
+</CardGrid>
+```
+
+<CardGrid :cols="{ sm: 2, md: 3, lg: 3 }">
+  <ImageCard v-for="item in list" :key="item.image" v-bind="item" />
+</CardGrid>
--- a/docs/notes/theme/guide/功能/组件.md
+++ b/docs/notes/theme/guide/功能/组件.md
@ -28,7 +28,7 @@ VuePress 支持在 Markdown 文件中使用 组件。

 **输入：**

-```md
+```md :no-line-numbers
 - VuePress - <Badge type="info" text="v2" />
 - VuePress - <Badge type="tip" text="v2" />
 - VuePress - <Badge type="warning" text="v2" />
@ -58,7 +58,7 @@ VuePress 支持在 Markdown 文件中使用 组件。

 **输入：**

-```md
+```md :no-line-numbers
 - home - <Icon name="material-symbols:home" color="currentColor" size="1em" />
 - vscode - <Icon name="skill-icons:vscode-dark" size="2em" />
 - twitter - <Icon name="skill-icons:twitter" size="2em" />
@ -79,7 +79,7 @@ VuePress 支持在 Markdown 文件中使用 组件。
 ::: code-tabs
@tab .vuepress/config.ts

-```ts
+```ts :no-line-numbers
 export default defineUserConfig({
  theme: plumeTheme({
    plugins: {
@ -103,7 +103,7 @@ export default defineUserConfig({

 **输入：**

-```md
+```md :no-line-numbers
 - 鼠标悬停 - <Plot>悬停时可见</Plot>
 - 点击 - <Plot trigger="click">点击时可见</Plot>
 ```
@ -135,7 +135,7 @@ export default defineUserConfig({

 **输入：**

-```md
+```md :no-line-numbers
 <Card title="卡片标题" icon="twemoji:astonished-face">
  这里是卡片内容。
 </Card>
@ -183,7 +183,7 @@ export default defineUserConfig({

 **输入：**

-```md
+```md :no-line-numbers
 <LinkCard title="卡片标题" href="/" description="这里是卡片内容" />
 <LinkCard icon="twemoji:astonished-face" title="卡片标题" href="/" />
 ```
@ -193,13 +193,109 @@ export default defineUserConfig({
 <LinkCard title="卡片标题" href="/" description="这里是卡片内容" />
 <LinkCard icon="twemoji:astonished-face" title="卡片标题" href="/" />

+## 图片卡片
+
+使用 `<ImageCard>` 组件在页面中显示图片卡片。
+
+图片卡片 有别于 markdown 的 普通插入图片方式，它展示与图片相关的更多信息，包括标题、描述、作者、链接等。
+适用于如 摄影作品、设计作品、宣传海报 等场景。
+
+### Props
+
+| 名称        | 类型                       | 默认值 | 说明                                    |
+| ----------- | -------------------------- | ------ | --------------------------------------- |
+| image       | `string`                   | `''`   | 必填，图片链接                          |
+| title       | `string`                   | `''`   | 可选，标题 (展示其它信息需要依赖此属性) |
+| description | `string`                   | `''`   | 可选，描述                              |
+| author      | `string`                   | `''`   | 可选，作者                              |
+| href        | `string`                   | `''`   | 可选，链接                              |
+| date        | `string \| Date \| number` | `''`   | 可选，日期                              |
+
+**输入：**
+
+```md :no-line-numbers
+<ImageCard
+  image="https://cn.bing.com/th?id=OHR.AlfanzinaLighthouse_ZH-CN9704515669_1920x1080.webp"
+  title="阿尔凡齐纳灯塔，阿尔加维，葡萄牙"
+  description="今天照片中的灯塔位于葡萄牙南部海岸阿尔加维的卡沃埃罗。阿尔凡齐纳灯塔建于1919年，照耀着大海，帮助船只在该地区周围危险的水域航行。这座灯塔是著名的旅游胜地，同时也是该地区与海洋紧密联系的象征。如果你有幸住在灯塔附近，那么本周末就是拜访灯塔的最佳时机。"
+  href="/"
+  author="Andreas Kunz"
+  date="2024/08/16"
+/>
+```
+
+**输出：**
+
+<ImageCard
+  image="https://cn.bing.com/th?id=OHR.AlfanzinaLighthouse_ZH-CN9704515669_1920x1080.webp"
+  title="阿尔凡齐纳灯塔，阿尔加维，葡萄牙"
+  description="今天照片中的灯塔位于葡萄牙南部海岸阿尔加维的卡沃埃罗。阿尔凡齐纳灯塔建于1919年，照耀着大海，帮助船只在该地区周围危险的水域航行。这座灯塔是著名的旅游胜地，同时也是该地区与海洋紧密联系的象征。如果你有幸住在灯塔附近，那么本周末就是拜访灯塔的最佳时机。"
+  href="/"
+  author="Andreas Kunz"
+  date="2024/08/16"
+/>
+
+还可以放到 `<CardGrid>` 组件中。
+
+**输入：**
+
+```md :no-line-numbers
+<CardGrid>
+  <ImageCard
+    image="https://cn.bing.com/th?id=OHR.AlfanzinaLighthouse_ZH-CN9704515669_1920x1080.webp"
+    title="阿尔凡齐纳灯塔，阿尔加维，葡萄牙"
+    description="..."
+    href="/"
+    author="Andreas Kunz"
+    date="2024/08/16"
+  />
+  <ImageCard
+    image="https://cn.bing.com/th?id=OHR.AlfanzinaLighthouse_ZH-CN9704515669_1920x1080.webp"
+    title="阿尔凡齐纳灯塔，阿尔加维，葡萄牙"
+    description="..."
+    href="/"
+    author="Andreas Kunz"
+    date="2024/08/16"
+  />
+</CardGrid>
+```
+
+**输出：**
+
+<CardGrid>
+  <ImageCard
+    image="https://cn.bing.com/th?id=OHR.AlfanzinaLighthouse_ZH-CN9704515669_1920x1080.webp"
+    title="阿尔凡齐纳灯塔，阿尔加维，葡萄牙"
+    description="今天照片中的灯塔位于葡萄牙南部海岸阿尔加维的卡沃埃罗。阿尔凡齐纳灯塔建于1919年，照耀着大海，帮助船只在该地区周围危险的水域航行。这座灯塔是著名的旅游胜地，同时也是该地区与海洋紧密联系的象征。如果你有幸住在灯塔附近，那么本周末就是拜访灯塔的最佳时机。"
+    href="/"
+    author="Andreas Kunz"
+    date="2024/08/16"
+  />
+  <ImageCard
+    image="https://cn.bing.com/th?id=OHR.AlfanzinaLighthouse_ZH-CN9704515669_1920x1080.webp"
+    title="阿尔凡齐纳灯塔，阿尔加维，葡萄牙"
+    description="今天照片中的灯塔位于葡萄牙南部海岸阿尔加维的卡沃埃罗。阿尔凡齐纳灯塔建于1919年，照耀着大海，帮助船只在该地区周围危险的水域航行。这座灯塔是著名的旅游胜地，同时也是该地区与海洋紧密联系的象征。如果你有幸住在灯塔附近，那么本周末就是拜访灯塔的最佳时机。"
+    href="/"
+    author="Andreas Kunz"
+    date="2024/08/16"
+  />
+</CardGrid>
+
+[查看 照片类作品示例](../../../../1.示例/照片类作品示例.md)
+
 ## 卡片排列容器

 当你需要将多个卡片排列，可以使用 `<CardGrid>` 组件。在空间足够时，多个卡片会自动排列。

+### Props
+
+| 名称 | 类型                                             | 默认值 | 说明           |
+| :--- | :----------------------------------------------- | :----- | :------------- |
+| cols | `number \| Record<'sm' \| 'md' \| 'lg', number>` | `2`    | 卡片排列列数。 |
+
 **输入：**

-```md
+```md :no-line-numbers
 <CardGrid>
  <Card title="卡片标题" icon="twemoji:astonished-face">
    这里是卡片内容。
--- a/docs/notes/theme/guide/安装与使用.md
+++ b/docs/notes/theme/guide/安装与使用.md
@ -9,6 +9,10 @@ tags:
  - 快速开始
 ---

+<script setup>
+const vuepressVersion = __VUEPRESS_VERSION__
+</script>
+
 ## 依赖环境

 - [Node.js v18.20.0+](https://nodejs.org/)
@ -94,7 +98,7 @@ tags:
  :::

  :::warning
-  主题当前版本 已适配至 `vuepress@2.0.0-rc.14`，你应该安装这个版本的 VuePress。
+  主题当前版本 已适配至 <code>vuepress@{{ vuepressVersion }}</code>，你应该安装这个版本的 VuePress。
  高于或低于这个版本，可能会存在潜在的兼容性问题。
  :::

@ -160,7 +164,7 @@ tags:
  :::

  :::warning
-  无论是否需要使用 **多语言** ，你都应该为 VuePress 配置 正确 `lang` 选项值。
+  无论是否需要使用 __多语言__ ，你都应该为 VuePress 配置 正确 `lang` 选项值。
  主题需要根据 `lang` 选项来确定语言环境文本。
  :::

--- a/docs/notes/theme/guide/知识笔记.md
+++ b/docs/notes/theme/guide/知识笔记.md
@ -22,13 +22,13 @@ tags:

 示例：

-```
+``` :no-line-numbers
 {sourceDir}/
 ├─ notes/
-    ├─ typescript/
-    │  ├─ foo.md
-    ├─ rust/
-    │  ├─ foo.md
+│   ├─ typescript/
+│   │  └─  foo.md
+│   └─  rust/
+│      └─  foo.md
 ```

 其中，`typescript` 和 `rust` 为目录名，各自独立保存与之相关的 markdown 文件。