Merge pull request #162 from liudonghua123/feature_frontmatterTitleFi…

…eldName add frontmatterTitleFieldName option
jooy2 · Jul 6, 2024 · de23c71 · de23c71
2 parents 4eaab59 + b0786b8
commit de23c71
Show file tree

Hide file tree

Showing 6 changed files with 65 additions and 2 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,9 @@
 # Changelog
 
+## 1.23.3 (2024-07-05)
+
+- Add `frontmatterTitleFieldName` option. When used with `useTitleFromFrontmatter`, the `text` field of sidebar will extract from the value of `frontmatterTitleFieldName` instead of default `title` field if it exists.
+
 ## 1.23.2 (2024-05-16)
 
 - Revert `5ed188e`. do not warn 'use option together'

diff --git a/docs/guide/api.md b/docs/guide/api.md
@@ -21,6 +21,7 @@ This page describes all the options in the VitePress Sidebar.
 | [useTitleFromFileHeading](#usetitlefromfileheading) | [convertSameNameSubFileToGroupIndexPage](#convertsamenamesubfiletogroupindexpage) |
 | [useTitleFromFrontmatter](#usetitlefromfrontmatter) | [folderLinkNotIncludesFileName](#folderlinknotincludesfilename) |
 | [useFolderTitleFromIndexFile](#usefoldertitlefromindexfile) | [useFolderLinkFromIndexFile](#usefolderlinkfromindexfile) |
+| [frontmatterTitleFieldName](#frontmatterTitleFieldName) |  |
 
 | Include/Exclude | Styling Menu Title |
 | --- | --- |
@@ -108,6 +109,13 @@ If the value is `true`, display the title based on the value of `title` in `Fron
 
 The `Frontmatter` should be located at the top of the document, and should look like this (Space is required between the `title:` value and the title.)
 
+## `frontmatterTitleFieldName`
+
+- Type: `string`
+- Default: `title`
+
+Display the title based on the value of this option in `Frontmatter` in the file. If the specified value is not exists in `Frontmatter`, then the default `title` will used as fallback.
+
 ```markdown
 ---
 title: This is frontmatter title value.

diff --git a/lib/index.ts b/lib/index.ts
@@ -41,6 +41,7 @@ declare interface Options {
   rootGroupLink?: string;
   rootGroupCollapsed?: boolean | null | undefined;
   frontmatterOrderDefaultValue?: number;
+  frontmatterTitleFieldName?: string;
   /**
    * @deprecated
    */
@@ -703,11 +704,19 @@ export default class VitePressSidebar {
 
     if (options.useTitleFromFrontmatter) {
       // Use content frontmatter title value instead of file name
-      const value = VitePressSidebar.getValueFromFrontmatter<string | undefined>(
+      let value = VitePressSidebar.getValueFromFrontmatter<string | undefined>(
         filePath,
-        'title',
+        options.frontmatterTitleFieldName || 'title',
         undefined
       );
+      // Try to use title front-matter as fallback
+      if (!value) {
+        value = VitePressSidebar.getValueFromFrontmatter<string | undefined>(
+          filePath,
+          'title',
+          undefined
+        );
+      }
       if (value) {
         return VitePressSidebar.formatTitle(options, value);
       }

diff --git a/test/res/frontmatter-custom-title-field/a.md b/test/res/frontmatter-custom-title-field/a.md
@@ -0,0 +1,10 @@
+---
+title: A Frontmatter
+sidebar_title: A Frontmatter Customized
+order: 1
+date: 2024-07-05
+author: liudonghua
+exclude: true
+---
+
+# A File
diff --git a/test/res/frontmatter-custom-title-field/b.md b/test/res/frontmatter-custom-title-field/b.md
@@ -0,0 +1,9 @@
+---
+title: B Frontmatter
+order: 1
+date: 2024-07-05
+author: liudonghua
+exclude: true
+---
+
+# A File
diff --git a/test/test.spec.ts b/test/test.spec.ts
@@ -1232,6 +1232,29 @@ describe('VitePress Sidebar Test', () => {
     done();
   });
 
+  it('Option: frontmatterTitleFieldName', (done) => {
+    assert.deepEqual(
+      generateSidebar({
+        documentRootPath: `${TEST_DIR_BASE}/frontmatter-basic`,
+        useTitleFromFileHeading: true,
+        useTitleFromFrontmatter: true,
+        frontmatterTitleFieldName: 'sidebar_title'
+      }),
+      [
+        {
+          text: 'A Frontmatter Customized',
+          link: '/a'
+        },
+        {
+          text: 'B Frontmatter',
+          link: '/b'
+        }
+      ]
+    );
+
+    done();
+  });
+
   it('Option: convertSameNameSubFileToGroupIndexPage (A)', (done) => {
     assert.deepEqual(
       generateSidebar({