feat: display title in frontmatter as heading fallback (#1556)

e2e/fixtures/heading-title/doc/guide.md

@@ -0,0 +1,3 @@
+---
+title: Heading Title
+---

e2e/fixtures/heading-title/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@rspress-fixture/rspress-heading-title",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "dev": "rspress dev",
+    "build": "rspress build",
+    "preview": "rspress preview"
+  },
+  "dependencies": {
+    "rspress": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^18.11.17"
+  }
+}

e2e/fixtures/heading-title/rspress.config.ts

@@ -0,0 +1,6 @@
+import * as path from 'node:path';
+import { defineConfig } from 'rspress/config';
+
+export default defineConfig({
+  root: path.join(__dirname, 'doc'),
+});

e2e/fixtures/heading-title/tsconfig.json

@@ -0,0 +1 @@
+{}

e2e/tests/heading-title.test.ts

@@ -0,0 +1,36 @@
+import { expect, test } from '@playwright/test';
+import path from 'node:path';
+import { getPort, killProcess, runDevCommand } from '../utils/runCommands';
+
+const fixtureDir = path.resolve(__dirname, '../fixtures');
+
+test.describe('heading-title test', async () => {
+  let appPort;
+  let app;
+  test.beforeAll(async () => {
+    const appDir = path.join(fixtureDir, 'heading-title');
+    appPort = await getPort();
+    app = await runDevCommand(appDir, appPort);
+  });
+
+  test.afterAll(async () => {
+    if (app) {
+      await killProcess(app);
+    }
+  });
+
+  test('Guide page', async ({ page }) => {
+    await page.goto(`http://localhost:${appPort}/guide`, {
+      waitUntil: 'networkidle',
+    });
+    const h1 = await page.$('h1');
+    const className = await page.evaluate(h1 => h1?.className, h1);
+    expect(className).toContain('title_3b154'); // hash in css module should stable
+    const text = await page.evaluate(h1 => h1?.textContent, h1);
+    expect(text).toContain('Heading Title');
+    expect(await page.evaluate(h1 => h1?.id, h1)).toBe('heading-title');
+    expect(await page.evaluate(link => link?.hash, await h1?.$('a'))).toBe(
+      '#heading-title',
+    );
+  });
+});

packages/core/src/node/mdx/loader.ts

@@ -33,6 +33,7 @@ interface LoaderOptions {
 export interface PageMeta {
   toc: TocItem[];
   title: string;
+  headingTitle: string;
   frontmatter?: Record<string, any>;
 }
 
@@ -167,6 +168,7 @@ export default async function mdxLoader(
       pageMeta = {
         ...compilationMeta,
         title: frontmatter.title || compilationMeta.title || '',
+        headingTitle: compilationMeta.title,
         frontmatter,
       } as PageMeta;
     } else {
@@ -183,6 +185,7 @@ export default async function mdxLoader(
       pageMeta = {
         toc,
         title: frontmatter.title || title || '',
+        headingTitle: title,
         frontmatter,
       };
       // We should check dead links in mdx-rs mode

packages/core/src/runtime/App.tsx

@@ -25,6 +25,7 @@ export enum QueryStatus {
 
 type PageMeta = {
   title: string;
+  headingTitle: string;
   toc: Header[];
   frontmatter: Record<string, any>;
 };

packages/document/docs/en/api/config/config-theme.mdx

@@ -687,3 +687,20 @@ export default defineConfig({
   },
 });
 ```
+
+## fallbackHeadingTitle
+
+- Type: `boolean`
+- Default: `true`
+
+Whether to display [`frontmatter.title`](./config-frontmatter#title) as fallback when the heading title is not presented. For example:
+
+```ts title="rspress.config.ts"
+import { defineConfig } from 'rspress/config';
+
+export default defineConfig({
+  themeConfig: {
+    fallbackHeadingTitle: false,
+  },
+});
+```

packages/document/docs/zh/api/config/config-theme.mdx

@@ -673,3 +673,21 @@ export default defineConfig({
   },
 });
 ```
+
+## fallbackHeadingTitle
+
+- Type: `boolean`
+- Default: `true`
+
+是否在文档标题未提供时将 [`frontmatter.title`](./config-frontmatter#title) 作为后备内容。比如:
+
+
+```ts title="rspress.config.ts"
+import { defineConfig } from 'rspress/config';
+
+export default defineConfig({
+  themeConfig: {
+    fallbackHeadingTitle: false,
+  },
+});
+```

packages/shared/src/types/defaultTheme.ts

@@ -115,6 +115,11 @@ export interface Config {
    * @default 'auto'
    */
   localeRedirect?: 'auto' | 'never';
+  /**
+   * Whether to show the fallback heading title when the heading title is not presented but `frontmatter.title` exists
+   * @default true
+   */
+  fallbackHeadingTitle?: boolean;
 }
 
 /**

packages/shared/src/types/index.ts

@@ -306,6 +306,7 @@ export interface FrontMatterMeta {
 export interface PageData {
   siteData: SiteData<DefaultThemeConfig>;
   page: BaseRuntimePageInfo & {
+    headingTitle?: string;
     pagePath: string;
     lastUpdatedTime?: string;
     description?: string;

packages/theme-default/package.json

@@ -44,6 +44,7 @@
     "htmr": "^1.0.2",
     "lodash-es": "^4.17.21",
     "nprogress": "^0.2.0",
+    "github-slugger": "^2.0.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-helmet-async": "^1.3.0",

packages/theme-default/src/layout/DocLayout/index.tsx

@@ -1,5 +1,6 @@
-import { useState } from 'react';
+import { useMemo, useState } from 'react';
 import { MDXProvider } from '@mdx-js/react';
+import { slug } from 'github-slugger';
 import { getCustomMDXComponent, ScrollToTop, Overview } from '@theme';
 import { Content, usePageData, NoSSR } from '@rspress/runtime';
 import { Aside } from '../../components/Aside';
@@ -9,6 +10,8 @@ import { SideMenu } from '../../components/LocalSideBar';
 import { TabDataContext } from '../../logic/TabDataContext';
 import styles from './index.module.scss';
 import type { UISwitchResult } from '../../logic/useUISwitch';
+import { H1 } from './docComponents/title';
+import { A } from './docComponents/link';
 
 export interface DocLayoutProps {
   beforeSidebar?: React.ReactNode;
@@ -43,7 +46,7 @@ export function DocLayout(props: DocLayoutProps) {
     components,
   } = props;
   const { siteData, page } = usePageData();
-  const { toc = [], frontmatter } = page;
+  const { headingTitle, title, toc = [], frontmatter } = page;
   const [tabData, setTabData] = useState({});
   const headers = toc;
   const { themeConfig } = siteData;
@@ -64,6 +67,22 @@ export function DocLayout(props: DocLayoutProps) {
     </TabDataContext.Provider>
   );
 
+  const fallbackTitle = useMemo(() => {
+    const titleSlug = title && slug(title);
+    return (
+      siteData.themeConfig.fallbackHeadingTitle !== false &&
+      !headingTitle &&
+      titleSlug && (
+        <H1 id={titleSlug}>
+          {title}
+          <A className="header-anchor" href={`#${titleSlug}`} aria-hidden>
+            #
+          </A>
+        </H1>
+      )
+    );
+  }, [headingTitle, title]);
+
   return (
     <div
       className={`${styles.docLayout} pt-0`}
@@ -93,6 +112,7 @@ export function DocLayout(props: DocLayoutProps) {
             <div>
               <div className="rspress-doc">
                 {beforeDocContent}
+                {fallbackTitle}
                 {docContent}
                 {afterDocContent}
               </div>