refactor(toc): support skipping heading level

[stevenjoezhang]

What does it do?

Issue resolved: #2137

Screenshots

Pull request tasks

• Add test cases for the changes.
• Passed the CI test.

[github-actions]

How to test

git clone -b toc https://github.com/hexojs/hexo.git
cd hexo
npm install
npm test

[coveralls]

Pull Request Test Coverage Report for Build 16493028975

Details

• 87 of 87 (100.0%) changed or added relevant lines in 1 file are covered.
• No unchanged relevant lines lost coverage.
• Overall first build on toc at 99.526%

---

Totals
Change from base Build 15609358336:	99.5%
Covered Lines:	9870
Relevant Lines:	9917

---

💛 - Coveralls

[Copilot]

Pull Request Overview

This PR refactors the Table of Contents (TOC) helper to support skipping heading levels by replacing the previous linear processing approach with a tree-based structure. The refactor addresses issue #2137 by properly handling cases where heading levels are not sequential (e.g., h1 followed directly by h3).

Key changes:

• Replaced linear TOC generation with tree-based approach using buildTree() function
• Separated numbering logic into dedicated assignNumbers() function
• Added comprehensive test case for skipped heading levels scenario

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
lib/plugins/helper/toc.ts	Complete refactor from linear to tree-based TOC generation with new helper functions
test/scripts/helpers/toc.ts	Added test case verifying correct handling of skipped heading levels

[Copilot]

The str parameter should have explicit type annotation string to maintain consistency with TypeScript best practices and the original function signature.

Suggested change

	function tocHelper(str, options: Options = {}) {
	function tocHelper(str: string, options: Options = {}) {

[Copilot]

Function parameters lack type annotations. Should be str: string, { min_depth, max_depth }: {min_depth: number, max_depth: number}, and max_items: number to maintain TypeScript type safety.

Suggested change

	function getAndTruncateTocObj(str, { min_depth, max_depth }, max_items) {
	function getAndTruncateTocObj(str: string, { min_depth, max_depth }: { min_depth: number, max_depth: number }, max_items: number) {

[Copilot]

The headings parameter should have explicit type annotation to maintain TypeScript consistency. Consider adding appropriate interface or type definition.

Suggested change

	function buildTree(headings) {
	function buildTree(headings: Heading[]) {

[Copilot]

The nodes parameter should have explicit type annotation to maintain TypeScript consistency. Consider adding appropriate interface or type definition.

Suggested change

	function assignNumbers(nodes) {
	const counters = [];
	function dfs(list, depth) {
	function assignNumbers(nodes: Node[]) {
	const counters: number[] = [];
	function dfs(list: Node[], depth: number) {

[Copilot]

This extremely long assertion string (over 500 characters) is difficult to read and maintain. Consider breaking it into a multi-line template literal or extracting it to a variable for better readability.

Suggested change

	toc(input).should.eql('<ol class="toc"><li class="toc-item toc-level-1"><a class="toc-link"><span class="toc-number">1.</span> <span class="toc-text">Title 1</span></a><ol class="toc-child"><li class="toc-item toc-level-3"><a class="toc-link"><span class="toc-number">1.1.</span> <span class="toc-text">Title 3</span></a><ol class="toc-child"><li class="toc-item toc-level-4"><a class="toc-link"><span class="toc-number">1.1.1.</span> <span class="toc-text">Title 4</span></a></li></ol></li><li class="toc-item toc-level-2"><a class="toc-link"><span class="toc-number">1.2.</span> <span class="toc-text">Title 2</span></a><ol class="toc-child"><li class="toc-item toc-level-5"><a class="toc-link"><span class="toc-number">1.2.1.</span> <span class="toc-text">Title 5</span></a></li></ol></li></ol></li><li class="toc-item toc-level-1"><a class="toc-link"><span class="toc-number">2.</span> <span class="toc-text">Title 1</span></a></li></ol>');
	toc(input).should.eql(`
	<ol class="toc">
	<li class="toc-item toc-level-1">
	<a class="toc-link">
	<span class="toc-number">1.</span> <span class="toc-text">Title 1</span>
	</a>
	<ol class="toc-child">
	<li class="toc-item toc-level-3">
	<a class="toc-link">
	<span class="toc-number">1.1.</span> <span class="toc-text">Title 3</span>
	</a>
	<ol class="toc-child">
	<li class="toc-item toc-level-4">
	<a class="toc-link">
	<span class="toc-number">1.1.1.</span> <span class="toc-text">Title 4</span>
	</a>
	</li>
	</ol>
	</li>
	<li class="toc-item toc-level-2">
	<a class="toc-link">
	<span class="toc-number">1.2.</span> <span class="toc-text">Title 2</span>
	</a>
	<ol class="toc-child">
	<li class="toc-item toc-level-5">
	<a class="toc-link">
	<span class="toc-number">1.2.1.</span> <span class="toc-text">Title 5</span>
	</a>
	</li>
	</ol>
	</li>
	</ol>
	</li>
	<li class="toc-item toc-level-1">
	<a class="toc-link">
	<span class="toc-number">2.</span> <span class="toc-text">Title 1</span>
	</a>
	</li>
	</ol>
	`);