feat: add article toc title length limit

Author: evannotfound

_config.yml

@@ -318,6 +318,7 @@ articles:
     number: false # Whether to add number to TOC automatically
     expand: true # Whether to expand TOC
     init_open: true # Open toc by default
+    title_max_length: 40 # Hide the article title in the TOC when it exceeds this length
   # Whether to enable copyright notice
   copyright:
     enable: true # Whether to enable

docs/content/docs/en/posts/articles.mdx

@@ -277,6 +277,17 @@ Whether to default open the table of contents.
 | :-----: | :-------------: | :-----------: |
 | Boolean | `true \| false` |    `true`     |
 
+### Article Title Maximum Length
+
+**Configuration Item: `articles.toc.title_max_length`**
+
+The article title is omitted from the table of contents when it exceeds this
+number of characters. Set it to `0` to always omit the title.
+
+| Type | Possible Values | Default Value |
+| :---: | :---: | :---: |
+| Number | `0` or greater | `40` |
+
 ## Article Copyright
 
 ### Toggle

docs/content/docs/zh/posts/articles.mdx

@@ -270,6 +270,16 @@ npm install hexo-wordcount
 | :---: | :---: | :---: |
 | 布尔值 | `true \| false` | `true` |
 
+### 文章标题最大长度
+
+**配置项名称：`articles.toc.title_max_length`**
+
+当文章标题超过此字符数时，不在目录中显示文章标题。设置为 `0` 可始终隐藏标题。
+
+| 类型 | 可选值 | 默认值 |
+| :---: | :---: | :---: |
+| 数字 | `0` 或更大 | `40` |
+
 ## 文章版权
 
 ### 开关

layout/pages/post/toc.ejs

@@ -1,6 +1,15 @@
+<%
+    const configuredTitleMaxLength = theme.articles.toc.title_max_length;
+    const titleMaxLength = Number.isInteger(configuredTitleMaxLength) && configuredTitleMaxLength >= 0
+        ? configuredTitleMaxLength
+        : 40;
+    const showTitle = page.title && [...String(page.title)].length <= titleMaxLength;
+%>
 <div class="box-border w-full">
     <div class="mb-1 text-xs font-medium text-rd-gray-1000"><%- __('toc') %></div>
-    <div class="mb-2.5 text-lg leading-normal font-bold whitespace-normal text-rd-gray-1000"><%= page.title %></div>
+    <% if (showTitle) { %>
+        <div class="mb-2.5 text-lg leading-normal font-bold whitespace-normal text-rd-gray-1000"><%= page.title %></div>
+    <% } %>
     <%- toc(page.content, {
         class: 'nav',
         list_number: theme.articles.toc.number,

tests/fixtures/optional-theme-config.yml

@@ -14,6 +14,8 @@ theme_config:
     style:
       delete_mask: true
       image_caption: true
+    toc:
+      title_max_length: 0
     code_block:
       highlight_theme:
         light: atom-one-light

tests/theme-generation.test.mjs

@@ -17,6 +17,9 @@ const includes = (output, values) => {
 const borderedPageTitle =
   '<h1 class="text-4xl mt-4 mb-8 font-medium font-display tracking-tight border-b border-rd-gray-alpha-400 pb-2">';
 
+const getArticleToc = (output) =>
+  output.match(/<aside id="article-toc"[\s\S]*?<\/aside>/)?.[0] || "";
+
 const readTemplates = (directory) => fs.readdirSync(directory, { withFileTypes: true })
   .flatMap((entry) => {
     const entryPath = path.join(directory, entry.name);
@@ -88,6 +91,15 @@ test("theme build and generation configurations", async (t) => {
     assert.ok(outputExists("css/build/theme.css"));
   });
 
+  await t.test("article TOC omits titles above the configured length", () => {
+    const shortTitleToc = getArticleToc(readOutput("2022/10/02/theme-demo/index.html"));
+    const longTitleToc = getArticleToc(readOutput("2024/01/17/super-long-title-test/index.html"));
+
+    assert.ok(shortTitleToc.includes("主题样式 Demo"));
+    assert.ok(!longTitleToc.includes("This is an extremely long title"));
+    assert.ok(longTitleToc.includes("Super Long Title Test"));
+  });
+
   await t.test("archive renders an unframed semantic timeline", () => {
     const archive = readOutput("archives/index.html");
     includes(archive, [
@@ -199,6 +211,7 @@ test("theme build and generation configurations", async (t) => {
     const nested = readOutput("2026/08/06/tab-folding-nesting-test/index.html");
     includes(home, ['id="local-search"', 'id="reading-progress"', 'id="preloader"', 'id="aplayer"']);
     includes(writing, ["data-writing-button", 'data-lazy-state="pending"']);
+    assert.ok(!getArticleToc(writing).includes("主题样式 Demo"));
     includes(nested, ["data-tabs", 'role="tabpanel"', 'class="folding']);
   });