feat($markdown): custom tag parsing for extractHeaders

[janvennemann]

Summary

Adds a new [tag, parseFunc] format for specifying the markdown.extractHeaders option to allow parsing of custom tags other than the default six section heading tags.

Usage example:

const { deeplyParseHeaders } = require('@vuepress/shared-utils')

module.exports = {
  markdown: {
    extractHeaders: [
      // Use default parsing for `h2` and `h3`
      'h2',
      'h3',
      // Use custom parsing for `app-heading` component
      ['app-heading', (token, content, md) => {
        const slug = token.attrs.find(([name]) => name === 'id')[1]
        const level = parseInt(token.attrs.find(([name]) => name === 'level')[1], 10)
        if (level > 2) {
          // Ignore all headings above h2
          return null
        }
        return {
          level,
          title: deeplyParseHeaders(content),
          slug: slug || md.slugify(content)
        }
      }]
    ]
  }
}

By default it uses the existing parsing of section heading tags if the array entry is specified as a string. If specified as [tag, parseFunc] it uses parseFunc to parse the tag. The signature of a custom parsing function is (token, content, md).

What kind of change does this PR introduce? (check at least one)

• Bugfix
• Feature
• Code style update
• Refactor
• Docs
• Build-related changes
• Other, please describe:

If changing the UI of default theme, please provide the before/after screenshot:

Does this PR introduce a breaking change? (check one)

• Yes
• No

If yes, please describe the impact and migration path for existing applications:

The PR fulfills these requirements:

• When resolving a specific issue, it's referenced in the PR's title (e.g. fix #xxx[,#xxx], where "xxx" is the issue number)

You have tested in the following browsers: (Providing a detailed version will be better.)

• Chrome 85.0.4183.121
• Firefox
• Safari
• Edge
• IE

If adding a new feature, the PR's description includes:

• A convincing reason for adding this feature
• Related documents have been updated
• Related tests have been updated

To avoid wasting your time, it's best to open a feature request issue first and wait for approval before working on it.

Other information:

I know that this is a niche use case, but unfortunately i couldn't find another way to hook into the header extraction to support custom tags. Let me explain a little more in detail what we are trying to achieve.

We want to use a markdown-it plugin which renders headings as a custom app-heading Vue component to have, amongst other things, better control over scrolling behavior for the anchor links. The current implementation for extractHeaders only supports the default h1, h2 etc section tags, since it determines the heading level from the tag. For our app-heading component we need a custom parsing so it determines the heading level from the component's level prop instead.

For reference, this is how our custom component looks like (simplified):

<template>
  <component
    :is="`h${level}`"
  >
    <a
      v-if="href"
      :href="href"
      class="header-anchor"
      @click="onClick"
    >
      #
    </a>

    <slot />
  </component>
</template>

<script>
export default {
  props: {
    href: String,
    level: String
  },

  methods: {
    onClick (e) {
      e.preventDefault()

      const hash = this.href

      if (this.hash === hash) return

      this.$router.push({ hash })
    }
  }
}
</script>