feat(theme): add blog type presets, close #4166

vuepress-theme-hope · May 21, 2024 · 0f32699 · 0f32699
1 parent 6d853e6
commit 0f32699
Show file tree

Hide file tree

Showing 12 changed files with 436 additions and 21 deletions.
diff --git a/docs/theme/src/.vuepress/theme.ts b/docs/theme/src/.vuepress/theme.ts
@@ -1,6 +1,8 @@
 import { theme } from "docs-shared";
 import { getDirname, path } from "vuepress/utils";
 import { AVAILABLE_SERVICES } from "vuepress-plugin-components";
+import { getRecentUpdatedArticles } from "vuepress-theme-hope/presets/getRecentUpdatedArticles.js";
+import { getSlides } from "vuepress-theme-hope/presets/getSlides.js";
 
 import { enNavbarConfig, zhNavbarConfig } from "./navbar/index.js";
 import { enSidebarConfig, zhSidebarConfig } from "./sidebar/index.js";
@@ -80,6 +82,14 @@ export default theme(
     plugins: {
       blog: {
         excerptLength: 0,
+        type: [
+          getRecentUpdatedArticles({
+            locales: { "/": "Recent Updated", "/zh/": "最近更新" },
+          }),
+          getSlides({
+            locales: { "/": "Slides", "/zh/": "幻灯片" },
+          }),
+        ],
       },
 
       components: {

diff --git a/docs/theme/src/guide/blog/article.md b/docs/theme/src/guide/blog/article.md
@@ -91,7 +91,10 @@ By default, the type list path will be `/key/` (with `key` replaced by your actu
 
 :::
 
-Also, you need to set `blogLocales[key]` in theme locales with the actual type name, so that the theme can display the type name correctly.
+To let theme display the type name correctly, you need to:
+
+- Either set `blogLocales[key]` in theme locales with the actual type name,
+- Or set `title` in the frontmatter of the layout page.
 
 To get start with, we would like to show you some examples.
 

diff --git a/docs/theme/src/guide/customize/presets.md b/docs/theme/src/guide/customize/presets.md
@@ -275,6 +275,114 @@ export default defineClientConfig({
 
 :::
 
+## Config Related
+
+### Custom Blog Types
+
+- Recent Updated:
+
+  ```ts
+  // vuepress-theme-hope/presets/getRecentUpdatedArticles.js
+  export interface RecentUpdateArticlesOptions {
+    /**
+     * Path of this blog type
+     *
+     * @default "/recent-updated/"
+     */
+    path?: string;
+
+    /**
+     * Locale text for the blog type
+     *
+     * @example {
+     *  '/': 'Recent Updated',
+     *  '/zh/': '最近更新',
+     * }
+     */
+    locales?: Record<string, string>;
+  }
+
+  export const getRecentUpdatedArticles: (
+    options: RecentUpdateArticlesOptions,
+  ) => BlogTypeOptions;
+  ```
+
+  ::: details Code Example
+
+  ```ts
+  import { getRecentUpdatedArticles } from "vuepress-theme-hope/presets/getSlides.js";
+
+  export default {
+    theme: hopeTheme({
+      plugins: {
+        blog: {
+          type: [
+            getRecentUpdatedArticles({
+              locales: {
+                "/": "Recent Updated",
+                "/zh/": "最近更新",
+              },
+            }),
+          ],
+        },
+      },
+    }),
+  };
+  ```
+
+  :::
+
+- Slides:
+
+  ```ts
+  // vuepress-theme-hope/presets/getSlides.js
+  export interface SlidesOptions {
+    /**
+     * Path of this blog type
+     *
+     * @default "/slides/"
+     */
+    path?: string;
+
+    /**
+     * Locales for the blog type
+     *
+     * @example {
+     *  '/': 'Slides',
+     *  '/zh/': '幻灯片',
+     * }
+     */
+    locales?: Record<string, string>;
+  }
+
+  export const getSlides = (options: SlidesOptions) => BlogTypeOptions;
+  ```
+
+  ::: details Code Example
+
+  ```ts
+  import { getSlides } from "vuepress-theme-hope/presets/getSlides.js";
+
+  export default {
+    theme: hopeTheme({
+      plugins: {
+        blog: {
+          type: [
+            getSlides({
+              locales: {
+                "/": "Slides",
+                "/zh/": "幻灯片",
+              },
+            }),
+          ],
+        },
+      },
+    }),
+  };
+  ```
+
+  :::
+
 ## Style Related
 
 You can create a [client config file](../../cookbook/vuepress/config.md#client-config-file) and import the following files through the `import` statement.

diff --git a/docs/theme/src/zh/guide/blog/article.md b/docs/theme/src/zh/guide/blog/article.md
@@ -100,7 +100,10 @@ tag:
 
 :::
 
-你还需要在主题语言环境中使用实际类型名称设置 `blogLocales[key]`，以便主题可以正确显示类型名称。
+为了让主题正确显示类型名称，你需要：
+
+- 或者在主题多语言选项中设置 `blogLocales[key]` 为实际类型名称，
+- 或者在布局页面的 frontmatter 中设置 `title`。
 
 为了方便上手，我们在这里展示一些示例。
 

diff --git a/docs/theme/src/zh/guide/customize/presets.md b/docs/theme/src/zh/guide/customize/presets.md
@@ -274,6 +274,115 @@ export default defineClientConfig({
 
 :::
 
+## 配置相关
+
+### 自定义博客类型
+
+- 最近更新:
+
+  ```ts
+  // vuepress-theme-hope/presets/getRecentUpdatedArticles.js
+  export interface RecentUpdateArticlesOptions {
+    /**
+     * 此博客类型的路径
+     *
+     * @default "/recent-updated/"
+     */
+    path?: string;
+
+    /**
+     * 博客类型的本地化文字
+     *
+     * @example {
+     *  '/': 'Recent Updated',
+     *  '/zh/': '最近更新',
+     * }
+     */
+    locales?: Record<string, string>;
+  }
+
+  export const getRecentUpdatedArticles: (
+    options: RecentUpdateArticlesOptions,
+  ) => BlogTypeOptions;
+  ```
+
+  ::: details 代码示例
+
+  ```ts
+  import { getRecentUpdatedArticles } from "vuepress-theme-hope/presets/getSlides.js";
+
+  export default {
+    theme: hopeTheme({
+      plugins: {
+        blog: {
+          type: [
+            getRecentUpdatedArticles({
+              locales: {
+                "/": "Recent Updated",
+                "/zh/": "最近更新",
+              },
+            }),
+          ],
+        },
+      },
+    }),
+  };
+  ```
+
+  :::
+
+- Slides:
+
+  ```ts
+  // vuepress-theme-hope/presets/getSlides.js
+  export interface SlidesOptions {
+    /**
+     * 此博客类型的路径
+     *
+     *
+     * @default "/slides/"
+     */
+    path?: string;
+
+    /**
+     * 博客类型的本地化文文字
+     *
+     * @example {
+     *  '/': 'Slides',
+     *  '/zh/': '幻灯片',
+     * }
+     */
+    locales?: Record<string, string>;
+  }
+
+  export const getSlides = (options: SlidesOptions) => BlogTypeOptions;
+  ```
+
+  ::: details 代码示例
+
+  ```ts
+  import { getSlides } from "vuepress-theme-hope/presets/getSlides.js";
+
+  export default {
+    theme: hopeTheme({
+      plugins: {
+        blog: {
+          type: [
+            getSlides({
+              locales: {
+                "/": "Slides",
+                "/zh/": "幻灯片",
+              },
+            }),
+          ],
+        },
+      },
+    }),
+  };
+  ```
+
+  :::
+
 ## 样式相关
 
 你可以创建 [客户端配置文件](../../cookbook/vuepress/config.md#客户端配置文件) `.vuepress/client.{ts,js}`，并通过 `import` 语句导入下方文件。

diff --git a/packages/theme/src/client/modules/blog/components/ArticleType.ts b/packages/theme/src/client/modules/blog/components/ArticleType.ts
@@ -1,12 +1,18 @@
 import type { VNode } from "vue";
 import { computed, defineComponent, h } from "vue";
-import { RouteLink, usePageData, useRouteLocale } from "vuepress/client";
+import {
+  RouteLink,
+  resolveRoute,
+  usePageData,
+  useRouteLocale,
+} from "vuepress/client";
 
 import { useThemeLocaleData } from "@theme-hope/composables/index";
 import {
   useArticles,
   useStars,
 } from "@theme-hope/modules/blog/composables/index";
+import { PageInfo } from "../../../../shared/index.js";
 
 import "../styles/article-type.scss";
 
@@ -31,10 +37,17 @@ export default defineComponent({
           path: articles.value.path,
         },
         { text: locale.star, path: stars.value.path },
-        ...__VP_BLOG_TYPES__.map(({ key, path }) => ({
-          text: locale[key],
-          path: path.replace(/^\//, localePath.value),
-        })),
+        ...__VP_BLOG_TYPES__.map(({ key, path }) => {
+          const routePath = path.replace(/^\//, localePath.value);
+
+          return {
+            text:
+              locale[key] ??
+              resolveRoute(routePath).meta[PageInfo.title] ??
+              key,
+            path: routePath,
+          };
+        }),
       ];
     });
 

diff --git a/packages/theme/src/client/modules/blog/components/BlogHomePage.ts b/packages/theme/src/client/modules/blog/components/BlogHomePage.ts
@@ -24,7 +24,7 @@ export default defineComponent({
     const projects = computed(() => frontmatter.value.projects ?? []);
 
     return (): VNode =>
-      h("div", { class: "vp-page vp-blog" }, [
+      h("div", { class: "vp-page vp-blog-home" }, [
         h(BlogHero),
         h("div", { class: "blog-page-wrapper" }, [
           h("main", { id: "main-content", class: "vp-blog-main" }, [

diff --git a/packages/theme/src/client/modules/blog/styles/layout.scss b/packages/theme/src/client/modules/blog/styles/layout.scss
@@ -1,18 +1,21 @@
-.vp-page.vp-blog {
-  display: flex;
-  flex-direction: column;
-  justify-content: space-between;
+.vp-page {
+  &.vp-blog,
+  &.vp-blog-home {
+    display: flex;
+    flex-direction: column;
+    justify-content: space-between;
 
-  box-sizing: border-box;
+    box-sizing: border-box;
 
-  padding-bottom: 2rem;
+    padding-bottom: 2rem;
 
-  background: var(--bg-color-back);
+    background: var(--bg-color-back);
 
-  .theme-container.has-toc & {
-    @media (min-width: hope-config.$pc) {
-      // fix toc padding
-      padding-inline-end: 0;
+    .theme-container.has-toc & {
+      @media (min-width: hope-config.$pc) {
+        // fix toc padding
+        padding-inline-end: 0;
+      }
     }
   }
 }