Configure table-of-contents heading levels (h2, h3, h4...)

[hhk7734]

💥 Proposal

(A clear and concise description of what the proposal is.)

Have you read the Contributing Guidelines on issues?

I read the issue side.

Docs: ToC is created using only <h2> and <h3>.

After changing node_modules/@docusaurus/mdx-loader/src/remark/rightToc/search.js
with the code below and setting minDepth and maxDepth, Users can display the ToC in the desired range.

This code has only been tested on my page. I am not familiar with javascript and I always write docs from <h1>(#). So I'm not sure if the code below is ok.

function search(node) {
  const headings = [];
  const minDepth = 1;
  const maxDepth = 4;
  const current = Array(maxDepth - minDepth + 1).fill(-1);
  let previousDepth = 0;

  const onHeading = (child, index, parent) => {
    const value = toString(child);

    if (parent !== node || !value || child.depth > maxDepth || child.depth < minDepth) {
      return;
    }

    const entry = {
      value: toValue(child),
      id: child.data.id,
      children: [],
    };

    if (!headings.length || previousDepth >= child.depth) {
      previousDepth = child.depth;
      current.fill(-1, child.depth - minDepth + 1)
    }

    index = child.depth - minDepth;
    let table = headings;
    for(let i = 0; i < index; i++) {
      table = table[current[i]].children;
    }
    table.push(entry);
    current[index] += 1;
  };

  visit(node, 'heading', onHeading);

  return headings;
}

[fanny]

Hey @hhk7734 I appreciate your suggestion, but I don't know if make sense allows the TOC in every level of Heading. The goal of the TOC is set highlights for sections, if you put a Head like h5, h6 sounds like less important, so for me is ok not include in TOC.

[hhk7734]

Hi @fanny
The range that user want to display may be different. I want to be able to set the range. So I used minDepth and maxDepth in the code.

[lex111]

I think this will be a useful feature, definitely we need it. However, the algorithm presented in the issue does not seem reliable, we need to work on a better solution. PR as always welcome.

Similar issue on Canny - https://docusaurus.canny.io/admin/board/feature-requests/p/configuration-option-for-table-of-content

[vjpr]

A workaround to make it configurable per doc is to use the suggest plugin above and configure via first comment in document.

<!-- {tocMinDepth: 1, tocMaxDepth: 4} -->

# h1

const plugin = (options = {}) => {
  const name = options.name || 'toc';

  const transformer = (node) => {

    // Because frontmatter is not passed along we must use comments instead for config.
    const firstComment = node.children.find(node => node.type === 'comment')
    let config = {}
    if (firstComment) {
      config = require('json5').parse(firstComment.value)
    }
    // --

Have to use hacky comments because frontmatter is inaccessible. See: #3935

[felipecrs]

This feature would be very much appreciated for documentation regarding nested objects, such as a complex JSON schema.

[schontz]

This feature would help new electron docs.