Option to offset heading levels

[jakearchibald]

Describe the feature
An option, like baseHeadingLevel: 2, which would turn # into <h2>, and ## into <h3>.

Why is this feature necessary?
Sometimes a single piece of markdown output will be used in a larger HTML page, so the top level heading an a markdown file won't equal an <h1> in the target page.

Describe alternatives you've considered
You could just alter the markdown file itself, but that's tricky if you're outputting the same markdown in multiple places where the heading levels should be different.

You could write a heading renderer, but that can get tricky if you already have a heading renderer that's doing something other than just changing the heading level.

[styfle]

Hi Jake,

That’s an interesting idea!

I think you should be able to achieve this result with marked.use().

Will this solve your problem?

[UziTech]

We are trying to prevent feature creep and slim marked down to be an extensible module that just handles the core functionality of converting markdown to html according the specs. We will be deprecating any option that can be moved into an extension soon.

You can create an extension that would handle this:

// marked-base-heading
const marked = require('marked');
module.exports = function (base = 1) {
  return {
    renderer: {
      heading(text, level, raw, slugger) {
        const renderer = new marked.Renderer(this.options);
        return renderer.heading(text, level + base - 1, raw, slugger);
      }
    }
  };
}

// index.js
const marked = require('marked');
marked.use(require('marked-base-heading')(2));

const html = marked('# heading 2');
// <h2 id="heading-2">heading 2</h2>
...

[jakearchibald]

Interesting! I didn't realise this.options could be used in this way. Does this work even if there are other heading renderers?

The docs mention that a renderer function can return false to defer to the next handler, maybe there needs to be an example of this arg-transforming behaviour.

[UziTech]

There can only be one renderer for each token, if you return false it will call the previous renderer but there is no way to change the arguments for the previous renderer.

You could also change the level in the tokens before they get to the renderer either by adding tokenizers for heading and lheading that call the original tokenizers and change the depth, or by getting the tokens with marked.lexer and iterating over each token to change the depth property before sending the tokens to marked.parser

function iterateTokens(tokens, pred) {
  for (const token of tokens) {
    pred(token);
    if (token.tokens) {
      iterateTokens(token.tokens, pred);
    }
  }
}

const tokens = marked.lexer(markdown, options);

iterateTokens(tokens, (token) => {
  if (token.type === 'heading') {
    token.depth += 1;
  }
});

const html = marked.parser(tokens, options);

[UziTech]

I just realized that iterateTokens function will not find tokens in a table and list. Maybe it would be worth it to create an easier way to iterate over the tokens.

[UziTech]

PR #1664 adds a marked.iterateTokens function that will allow you to run a function for every token.

[jakearchibald]

Yeah, that works, as long as it's clear that the tokens are mutable.

[UziTech]

walkTokens should be available in v1.1.0. I used this as the walkTokens example
https://marked.js.org/#/USING_PRO.md#walk-tokens