feat(helper/toc): specify maximum number of items to output

KentarouTakeda commented 1 month ago

What does it do?

Added the ability to set an upper limit on the number of items in the table of contents output by the toc() helper.

If no value is specified, the default is Infinity. This is no different from previous behavior. If we specify a number greater than or equal to 1, the elements will be truncated in the following order.

Delete items from descendants to ancestors (from <h6> to <h1>) to fit within the specified number.
Subheadings, which are lower-level headings on the page, will be removed in groups by level.
The behavior differs only for the highest heading that appears on the page, which is deleted sequentially from the back.

For example, if we have a heading like this:

## 1 ### 1-1 ### 1-2 ## 2 ### 2-1

If 5 is specified for max_items, all items will be output. On the other hand, if we specify 4 or 3,

## 1 ~~### 1-1~~ truncated ~~### 1-2~~ truncated ## 2 ~~### 2-1~~ truncated

All <h3> are removed, resulting in two items being output. This is the same result as specifying 2 for max_items. This is because this outline requires five elements to display up to <h3>.

Only the highest heading that appears on the page behaves differently. For example, if we specify 1 for max_items,

## 1 ~~### 1-1~~ truncated ~~### 1-2~~ truncated ~~## 2~~ truncated ~~### 2-1~~ truncated

Instead of all <h2> being deleted at once as before, they will be deleted sequentially from the bottom. This is to avoid unintentionally not outputting anything.

In addition to the code, I welcome any feedback regarding the specifications described here. I believe this specification is the best, but if you have any other good ideas, I would definitely consider them.

Screenshots

Pull request tasks

[x] Add test cases for the changes.
[x] Passed the CI test.

github-actions[bot] commented 1 month ago

How to test

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

github-actions[bot] commented 1 month ago

Flamegraph

https://e7b7a6947479c16b482f9c9fdd727a22240c07f7-14-hexo.surge.sh/flamegraph.html https://e7b7a6947479c16b482f9c9fdd727a22240c07f7-16-hexo.surge.sh/flamegraph.html https://e7b7a6947479c16b482f9c9fdd727a22240c07f7-18-hexo.surge.sh/flamegraph.html

coveralls commented 1 month ago

Pull Request Test Coverage Report for Build 9240404180

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

For more information on this, see Tracking coverage changes with pull request builds.
To avoid this issue with future PRs, see these Recommended CI Configurations.
For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

26 of 26 (100.0%) changed or added relevant lines in 1 file are covered.
11 unchanged lines in 2 files lost coverage.
Overall coverage increased (+0.002%) to 99.48%

Files with Coverage Reduction	New Missed Lines	%
lib/box/index.ts	4	96.07%
lib/plugins/processor/post.ts	7	97.78%
<!--	Total:	11	-->

Totals
Change from base Build 8875175928:	0.002%
Covered Lines:	9368
Relevant Lines:	9417

💛 - Coveralls

KentarouTakeda commented 1 month ago

It seems that the test is failing at some points unrelated to this pull request. Other pull requests have also failed, so I'll leave it as is.

hexojs / hexo