From b87a5cfd7a4da0acbab9fb90c3b8a41291c3c0d4 Mon Sep 17 00:00:00 2001 From: pengzhanbo Date: Tue, 7 Oct 2025 23:40:16 +0800 Subject: [PATCH] docs: update docs --- docs/.vuepress/collections/en/theme-guide.ts | 4 +- docs/en/guide/quick-start/blog.md | 489 ------------------- docs/guide/quick-start/blog.md | 469 ------------------ docs/guide/quick-start/sidebar.md | 2 + 4 files changed, 4 insertions(+), 960 deletions(-) delete mode 100644 docs/en/guide/quick-start/blog.md delete mode 100644 docs/guide/quick-start/blog.md diff --git a/docs/.vuepress/collections/en/theme-guide.ts b/docs/.vuepress/collections/en/theme-guide.ts index aa12d876..7f9c2a19 100644 --- a/docs/.vuepress/collections/en/theme-guide.ts +++ b/docs/.vuepress/collections/en/theme-guide.ts @@ -17,8 +17,8 @@ export const themeGuide: ThemeCollectionItem = defineCollection({ 'usage', 'project-structure', 'write', - 'blog', - 'document', + // 'blog', + // 'document', 'international', 'deployment', 'optimize-build', diff --git a/docs/en/guide/quick-start/blog.md b/docs/en/guide/quick-start/blog.md deleted file mode 100644 index 96359778..00000000 --- a/docs/en/guide/quick-start/blog.md +++ /dev/null @@ -1,489 +0,0 @@ ---- -title: Blog -icon: material-symbols:article-outline -createTime: 2025/03/04 12:15:40 -permalink: /en/guide/blog/ -tags: - - Guide - - Quick Start ---- - - - -## Overview - -By default, the theme will treat all md files in the [documentation source directory](project-structure.md#documentation-source-directory) as blog posts, except for specific directories (e.g., the `notes` directory, which is used for notes). - -The theme will also categorize blog posts based on the directory structure of the md files, using the **directory name** as the **category** of the blog post. - -The theme will automatically generate a blog post list page with the link address `/blog/`, displaying all blog posts and relevant information about the blogger. - -## Configuration - -The blog feature is enabled by default in the theme, and you usually do not need to perform additional configurations. - -::: code-tabs -@tab .vuepress/config.ts - -```ts -export default defineUserConfig({ - theme: plumeTheme({ - // Disable the blog feature - // blog: false, - - blog: { - /** - * Configure included files via glob string, - * by default, it reads all `.md` files in the source directory, but excludes directories used for notes in the `notes` configuration. - */ - include: ['**/*.md'], - // If you want to only read articles from a specific directory in the source directory, such as the `blog` directory, you can configure it as: - // include: ['blog/**/*.md'], - - /** - * Configure excluded files via glob string, relative to the source directory - */ - exclude: ['.vuepress/', '**/README.md'], - - // Disable pagination - // pagination: false, - // Number of articles displayed per page - pagination: 15, - } - }) -}) -``` - -::: - -## Blogger Information - -The theme supports displaying basic information about the blogger. - -
- -
- -### Configuration - -You can set the blogger's avatar and other related information through the `profile` attribute. - -::: code-tabs -@tab .vuepress/config.ts - -```ts -export default defineUserConfig({ - theme: plumeTheme({ - profile: { - name: 'Your Name', - description: 'Description text, motto/signature', - avatar: '/blogger.png', - location: 'Your Location', - organization: 'Your Organization', - circle: true, // Whether the avatar is circular - layout: 'right', // Whether the personal information is on the left or right, 'left' | 'right' - }, - // Social links - social: [ - { icon: 'github', link: 'https://github.com/vuepress-theme-plume ' }, - // ... more - ] - }) -}) -``` - -::: - -## Article Metadata - -You can configure the display of blog post metadata, such as title, author, date, tags, etc. This data is configured through `frontmatter`. - -```md ---- -title: Article Title -createTime: 2024/01/01 00:00:00 -tags: - - tag1 - - tag2 ---- -``` - -Among them, `title` / `createTime` will be automatically filled in by the theme when creating a new md file, and you can modify them at will. - -The following are the available `frontmatter` properties in blog posts. - -| Property | Type | Default Value | Description | -| ----------- | --------------------------- | ------------------------- | --------------------------------------------------- | -| title | `string` | Automatically filled in with the filename | Article title | -| createTime | `string` | Current time | Article creation time | -| tags | `string[]` | `[]` | Article tags | -| sticky | `boolean \| number` | false | Whether to pin the article, if it's a number, the larger the number, the higher the pinning priority | -| draft | `boolean` | false | Whether it's a draft, draft articles will not be displayed | -| cover | `string` | `''` | Article cover image | -| coverStyle | `BlogPostCoverStyle` | `null` | Article cover image style | -| excerpt | `boolean \| string` | '' | Article excerpt, by default generated via `` comment, passing a string indicates custom content, and it will no longer be extracted from the main text | - -In addition to the above fields, you can also use the fields in the [general frontmatter configuration](../../config/frontmatter/basic.md) to flexibly control the behavior of the current page. - -## Article Excerpt - -If you want to add an excerpt to an article, you can use the `` comment to mark it. Any content before this comment will be considered as the excerpt. - -**Example:** - -```md ---- -title: Title ---- - -This content will be used as the excerpt - - - -This content will not be used as the excerpt -``` - -You can also use `frontmatter.excerpt` to control whether the article displays an excerpt and to customize the excerpt content. - -- `frontmatter.excerpt` defaults to `false`, indicating that the excerpt is not displayed, and the `` comment will be ignored. -- When `frontmatter.excerpt` is of type `string`, it indicates custom excerpt content, and the `` comment will be ignored. - -**Example:** - -```md ---- -title: Title -excerpt: Custom excerpt content ---- -``` - -You can use different methods to control the excerpt of the article as needed. - -::: tip The theme more strongly recommends using the `` comment to add excerpts -::: - -## Article Cover Image - -On the blog post list page, the theme supports adding cover images to articles and supports different layouts and flexible size configurations. - -To add a cover image to a blog post, you can configure `cover` in `frontmatter`: - -```md ---- -title: Title -cover: /images/cover.jpg # [!code ++] ---- -``` - -**Cover images** only support absolute paths or remote paths. When using an absolute path, the image is loaded from the `.vuepress/public` directory. - -::: file-tree - -- docs - - .vuepress - - public - - images - - cover.jpg - - config.ts - - article.md -- … - ::: - -The default effect is as follows: - -
- -
- -You can also adjust the layout position and aspect ratio of the cover image: - -```md ---- -title: Article Title -cover: /images/cover.jpg # [!code ++:5] -coverStyle: - layout: left - ratio: 16:9 - width: 300 ---- -``` - -The effect is as follows: - -
- -
- -When an article has no excerpt, it may look a bit empty. To address this, you can use `compact: true` to make the cover image fit the container edges, making the overall layout more compact: - -```md ---- -title: Article Title -cover: /images/cover.jpg # [!code ++:6] -coverStyle: - layout: left - ratio: 16:9 - width: 300 - compact: true ---- -``` - -The effect is as follows: - -
- -
- -::: warning compact: true only takes effect when the article has no excerpt -::: - -You can also set the cover image above the title, which becomes a large image style: - -```md ---- -title: Article Title -cover: /images/cover.jpg # [!code ++:5] -coverStyle: - layout: top - ratio: 16:9 - width: 300 ---- -``` - -The effect is as follows: - -
- -
- -### Preset Configuration - -Although the theme supports using different configurations for each article's cover image, for the sake of overall layout style and to simplify configuration, the theme also supports preset configurations for cover images: - -::: code-tabs -@tab .vuepress/config.ts - -```ts -export default defineUserConfig({ - theme: plumeTheme({ - - blog: { - // Configure the layout position of the cover image - // postCover: 'left', // 'left' | 'right' | 'odd-left' | 'odd-right' | 'top' - postCover: { - layout: 'left', - ratio: '16:9', - width: 300, - compact: true - } - } - }) -}) -``` - -::: - -```ts -type BlogPostCoverLayout = 'left' | 'right' | 'odd-left' | 'odd-right' | 'top' - -interface BlogPostCoverStyle { - /** - * The position of the blog post cover image - */ - layout?: BlogPostCoverLayout - /** - * The aspect ratio of the blog post cover image - * - * @default '4:3' - */ - ratio?: number | `${number}:${number}` - - /** - * The width of the cover image, only effective when layout is 'left' or 'right' - * - * @default 240 - */ - width?: number - /** - * Whether to use compact mode, in compact mode, the cover image fits the container edges - * @default false - */ - compact?: boolean -} -``` - -You may have noticed that in the preset configuration's `layout`, there are also two configurations supported: `odd-left` and `odd-right`. - -- `odd-left`: Indicates that odd items are on the left and even items are on the right -- `odd-right`: Indicates that odd items are on the right and even items are on the left - -For example, the effect of `odd-left` is as follows: - -
- - - -
- -::: warning Note -When on narrow screens of mobile devices, for visual effect considerations, the `layout` configuration is forcibly reset to `top`. -::: - -## Tag Page, Category Page, and Archive Page - -In addition to automatically generating the **blog post list page**, the theme will also automatically generate **tag pages**, **category pages**, and **archive pages**. - -The tag page can filter and display blog posts based on tags, with the default address being `/blog/tags/` - -The category page can display blog posts based on the original directory structure, with the default address being `/blog/categories/` - -The archive page archives articles based on their creation time, with the default address being `/blog/archives/` - -## Internationalization Support - -If internationalization is enabled, the blog list page will display the blog list of the corresponding language directory based on different languages. That is, the article list of each language is kept independent. - -Specifically, if one of your blog posts has different language versions, ensure that the same directory file structure and filename exist under different language directories. When switching languages, the theme can correctly switch to the corresponding language article. - -::: file-tree - -- docs - - en - - my-article.md - - fr - - my-article.md - - my-article.md -::: - -## Setting the Blog as the Homepage - -By default, the theme separates the **homepage** and the **blog page**. - -However, for users who want to build only a blog site, it might be a better choice to directly set the blog page as the **homepage**. - -The theme provides two ways to set the blog as the homepage to meet different scenario needs: - -- **Method One: Configure the `pageLayout` attribute of the homepage to `blog`** - -::: code-tabs -@tab docs/README.md - -```md ---- -pageLayout: blog ---- -``` - -::: - -This configuration will directly apply the blog layout to the page, displaying the blog post list. - -This is the simplest way to modify the homepage to a blog page, but the downside is the lack of flexibility. - -- **Method Two: Configure the `pageLayout` attribute of the homepage to `home`, and add a homepage area type of `type: blog`** - -::: code-tabs - -@tab docs/README.md - -```md ---- -pageLayout: home -config: - - type: blog ---- -``` - -::: - -With this method, you can not only add a blog post list to the homepage but also flexibly add different content to other areas of the page. - -For example, configure the first screen as `banner`, followed by the blog post list: - -::: code-tabs - -@tab docs/README.md - -```md ---- -pageLayout: home -config: - - type: banner - - type: blog ---- -``` - -::: - -For more customization configurations, please refer to [Customize the Homepage](../custom/custom-home.md). - -After using the above two methods to configure the homepage as the blog page, since the theme still generates the blog post list page with the address `/blog/` by default, this results in duplicate functional pages. Therefore, you need to [Theme Configuration > Blog Configuration](../../config/basic.md#blog) to **disable the automatic generation of the blog post list page**: - -(You can also modify the link addresses of the category page/tag page/archive page) - -::: code-tabs -@tab .vuepress/config.ts - -```ts -import { defineUserConfig } from 'vuepress' -import { plumeTheme } from 'vuepress-theme-plume' - -export default defineUserConfig({ - theme: plumeTheme({ - blog: { - postList: false, // Prevent the generation of the blog post list page - // tagsLink: '/blog/tags/', - // categoriesLink: '/blog/categories/', - // archiveLink: '/blog/archives/', - } - }) -}) -``` - -::: diff --git a/docs/guide/quick-start/blog.md b/docs/guide/quick-start/blog.md deleted file mode 100644 index d6035b7f..00000000 --- a/docs/guide/quick-start/blog.md +++ /dev/null @@ -1,469 +0,0 @@ ---- -title: 博客 -icon: material-symbols:article-outline -createTime: 2024/03/04 19:16:40 -permalink: /guide/blog/ -tags: - - 指南 - - 快速开始 ---- - -## 概述 - -主题默认会将 [文档源目录](./project-structure.md#文档源目录) 下的，除了特定的目录（如 `notes` 目录将作为笔记所在目录）， -所有 md 文件作为博客文章。 - -主题还会根据 md 文件 所在的 文件目录结构，以 **目录名** 作为 博客文章所属的 **分类**。 - -主题默认会生成一个 链接地址为 `/blog/` 的 博客文章列表页。 -展示所有的博客文章，以及 博主的相关信息。 - -## 配置 - -主题默认启用 博客功能，通常您无需进行额外的配置。 - -```ts title=".vuepress/config.ts" twoslash -import { defineUserConfig } from 'vuepress' -import { plumeTheme } from 'vuepress-theme-plume' - -export default defineUserConfig({ - theme: plumeTheme({ - // 禁用博客功能 - // blog: false, - - blog: { - /** - * 通过 glob string 配置包含文件， - * 默认读取 源目录中的所有 `.md` 文件，但会排除 `notes` 配置中用于笔记的目录。 - */ - include: ['**/*.md'], - // 如果希望只将源目录下某个目录下的文章读取为博客文章，比如 `blog` 目录，可以配置为： - // include: ['blog/**/*.md'], - - /** - * 通过 glob string 配置排除的文件，相对于 源目录 - */ - exclude: ['.vuepress/', '**/README.md'], - - // 禁用分页 - // pagination: false, - // 每页显示的文章数量 - pagination: 15, - } - }) -}) -``` - -## 博主信息 - -主题支持展示博主的基本信息。 - -
- -
- -### 配置 - -你可以通过 `profile` 属性来设置博主头像等相关信息。 - -```ts title=".vuepress/config.ts" twoslash -import { defineUserConfig } from 'vuepress' -import { plumeTheme } from 'vuepress-theme-plume' - -export default defineUserConfig({ - theme: plumeTheme({ - profile: { - name: '您的名字', - description: '描述文字，座右铭/签名', - avatar: '/blogger.png', - location: '您的位置', - organization: '您的组织', - circle: true, // 是否为圆形头像 - layout: 'right', // 个人信息在左侧还是右侧，'left' | 'right' - }, - // 社交链接 - social: [ - { icon: 'github', link: 'https://github.com/vuepress-theme-plume' }, - // ... more - ] - }) -}) -``` - -## 文章元数据 - -你可以配置展示博客文章的元数据，如标题、作者、日期、标签等。这些数据通过 `frontmatter` 配置。 - -```md ---- -title: 文章标题 -createTime: 2024/01/01 00:00:00 -tags: - - tag1 - - tag2 ---- -``` - -其中，`title` / `createTime` 会在新建 md 文件时由主题自动填充，你可以随意修改它们。 - -以下是在 博客文章中可用的 `frontmatter` 属性。 - -| 属性 | 类型 | 默认值 | 说明 | -| ---------- | --------------------------- | ------------------ | -------------------------------------------- | -| title | `string` | 默认自动填入文件名 | 文章标题 | -| createTime | `string` | 当前时间 | 文章创建时间 | -| tags | `string[]` | `[]` | 文章标签 | -| sticky | `boolean \| number` | false | 是否置顶, 如果为数字，则数字越大，置顶越靠前 | -| draft | `boolean` | false | 是否为草稿，草稿文章不会被展示 | -| cover | `string` | `''` | 文章封面 | -| coverStyle | `BlogPostCoverStyle` | `null` | 文章封面样式 | -| excerpt | `boolean \| string` | '' | 文章摘要，默认通过 `` 注释生成, 传入字符串表示自定义内容，不再从正文提取 | - -除了以上的字段，你还可以使用 [通用 frontmatter 配置](../../config/frontmatter/basic.md) 中的字段， -灵活的控制当前页面的行为。 - -## 文章摘要 - -如果你想要为文章添加摘要，你可以使用 `` 注释来标记它。任何在此注释之前的内容会被视为摘要。 - -**示例：** - -```md ---- -title: 标题 ---- - -这里的内容会被作为摘要 - - - -这里的内容不会被作为摘要 -``` - -还可以使用 `frontmatter.excerpt` 来控制文章是否显示摘要，以及 自定义摘要内容。 - -- `frontmatter.excerpt` 默认为 `false`，表示不显示摘要，此时 `` 注释会被忽略。 -- `frontmatter.excerpt` 为 `string` 类型时，表示自定义摘要内容，此时 `` 注释会被忽略。 - -**示例：** - -```md ---- -title: 标题 -excerpt: 自定义摘要内容 ---- -``` - -您可以根据需要使用不同的方式来控制文章的摘要。 - -::: tip 主题更建议使用 <!-- more --> 注释来添加摘要 -::: - -## 文章封面图 - -在博客文章列表页，主题支持为 文章添加封面图，并支持不同的 排版 和 灵活的尺寸配置。 - -为博客文章添加 封面图，可以在 `frontmatter` 中配置 `cover`: - -```md{3} ---- -title: 标题 -cover: /images/cover.jpg ---- -``` - -**封面图** 仅支持 绝对路径 或 远程路径。当使用 绝对路径时，从 `.vuepress/public` 目录中加载图片。 - -::: file-tree - -- docs - - .vuepress - - public - - images - - cover.jpg - - config.ts - - article.md -- … -::: - -默认效果如下： - -
- -
- -还可以为 封面图 调整 布局位置，以及 尺寸比例： - -```md{4-7} ---- -title: 文章标题 -cover: /images/cover.jpg -coverStyle: - layout: left - ratio: 16:9 - width: 300 ---- -``` - -效果如下: - -
- -
- -当文章没有摘要时，可能会显得比较空，为此你还可以通过 `compact: true` 使 封面图 贴合容器边缘，使整体变得更紧凑： - -```md{8} ---- -title: 文章标题 -cover: /images/cover.jpg -coverStyle: - layout: left - ratio: 16:9 - width: 300 - compact: true ---- -``` - -效果如下: - -
- -
- -::: warning `compact: true` 仅在文章没有摘要时生效 -::: - -还可以设置 封面图在 标题上方，此时变为 大图风格： - -```md{5} ---- -title: 文章标题 -cover: /images/cover.jpg -coverStyle: - layout: top - ratio: 16:9 - width: 300 ---- -``` - -效果如下: - -
- -
- -### 预设配置 - -虽然主题支持为每个文章的封面图使用不同的配置，出于整体布局风格的考虑，以及简化配置的目的， -主题还支持为封面图预设配置： - -```ts title=".vuepress/config.ts" twoslash -import { defineUserConfig } from 'vuepress' -import { plumeTheme } from 'vuepress-theme-plume' - -export default defineUserConfig({ - theme: plumeTheme({ - - blog: { - // 配置 封面图 布局位置 - // postCover: 'left', // 'left' | 'right' | 'odd-left' | 'odd-right' | 'top' - postCover: { - layout: 'left', - ratio: '16:9', - width: 300, - compact: true - } - } - }) -}) -``` - -```ts -type BlogPostCoverLayout = 'left' | 'right' | 'odd-left' | 'odd-right' | 'top' - -interface BlogPostCoverStyle { - /** - * 博客文章封面图的位置 - */ - layout?: BlogPostCoverLayout - /** - * 博客文章封面图的比例 - * - * @default '4:3' - */ - ratio?: number | `${number}:${number}` - - /** - * 封面图的宽度, 仅在 layout 为 'left' 或 'right' 时生效 - * - * @default 240 - */ - width?: number - /** - * 是否使用紧凑模式，紧凑模式下，封面图紧贴容器边缘 - * @default false - */ - compact?: boolean -} -``` - -你可能已经注意到，在预设配置的 `layout` 中，还支持 `odd-left` 和 `odd-right` 两种配置。 - -- `odd-left`: 表示 单数项在左侧，偶数项在右侧 -- `odd-right`: 表示 单数项在右侧，偶数项在左侧 - -比如 `odd-left` 效果如下： - -
- - - -
- -::: warning -当在 移动设备窄屏 上时，出于视觉效果考虑，`layout` 配置强制重置为 `top`。 -::: - -## 标签页，分类页和归档页 - -主题除了自动生成 **博客文章列表页** 以外，还会自动生成 **标签页**，**分类页** 和 **归档页**。 - -标签页 可以根据 标签 筛选并展示 博客文章， 默认地址为 `/blog/tags/` - -分类页 可以根据 原始目录结构 分类展示 博客文章, 默认地址为 `/blog/categories/` - -归档页根据文章的创建时间进行归, 默认地址为 `/blog/archives/` - -## 国际化支持 - -如果启用了 国际化，那么博客列表页将会 根据 不同的语言，展示对应语言目录下的博客列表。 -即 每个语言下的 文章列表 都是保持独立的。 - -特别的，如果您的 一篇博客文章 拥有不同的语言版本，请保持在 不同的语言目录下，都有相同的 -目录文件结构和文件名。当切换语言时，主题能够正确的切换到对应语言的文章。 - -::: file-tree - -- docs - - en - - my-article.md - - fr - - my-article.md - - my-article.md -::: - -## 设置博客为主页 - -默认情况下，主题 将 **首页** 与 **博客页** 分离。 - -但对于 希望只建立一个 博客站点 的用户而言，可能直接将 博客页 作为 **首页** 是个更好的选择。 - -主题提供了两种方式来设置博客为主页，满足不同的需求场景： - -- **方式一：配置 主页的 `pageLayout` 属性为 `blog`** - -```md title="docs/README.md" ---- -pageLayout: blog ---- -``` - -此配置会直接将页面应用 博客布局，显示博客文章列表。 - -这是将主页修改为 博客页的 最简单的方式，但缺点是 缺少灵活性。 - -- **方式二：配置 主页的 `pageLayout` 属性为 `home`, 添加 `type: blog` 的首页区域类型** - -```md title="docs/README.md" ---- -pageLayout: home -config: - - type: blog ---- -``` - -使用这种方式，你不仅可以在首页中添加 博客文章列表，还可以灵活的在页面的其他区域添加不同的内容。 - -比如，配置首屏为 `banner`，然后紧跟着 博客文章列表： - -```md title="docs/README.md" ---- -pageLayout: home -config: - - type: banner - - type: blog ---- -``` - -更多自定义配置，请参考 [自定义首页](../custom/home.md)。 - -当使用以上两种方式 将首页配置为 博客页后，由于主题默认依然会生成 地址为`/blog/` 的博客文章列表页， -这导致存在了重复功能的页面，为此，你需要 [主题配置 > 博客配置](../../config/theme.md#blog) 中， -**关闭自动生成博客文章列表页**： - -（还可以重新修改 分类页/标签页/归档页的链接地址） - -```ts title=".vuepress/config.ts" twoslash -import { defineUserConfig } from 'vuepress' -import { plumeTheme } from 'vuepress-theme-plume' - -export default defineUserConfig({ - theme: plumeTheme({ - blog: { - postList: false, // 禁止生成博客文章列表页 - // tagsLink: '/blog/tags/', - // categoriesLink: '/blog/categories/', - // archivesLink: '/blog/archives/', - } - }) -}) -``` - - diff --git a/docs/guide/quick-start/sidebar.md b/docs/guide/quick-start/sidebar.md index d5d13bce..b912b33c 100644 --- a/docs/guide/quick-start/sidebar.md +++ b/docs/guide/quick-start/sidebar.md @@ -165,7 +165,9 @@ import { defineCollection, defineCollections } from 'vuepress-theme-plume' // 单个集合配置 const typescript = defineCollection({ + type: 'doc', dir: 'typescript', + title: 'TypeScript 笔记', linkPrefix: '/typescript/', sidebar: [ 'guide/intro.md',