Heading anchors in Hexo

11 Feb, 2018HTML, Hexo


  • Heading: ie heading, from # to ###### in Markdown , Corresponding to <h1> to <h6> in HTML. The following uses #[n] and <hn> (n: 1-6) to represent;

  • Anchor: ie anchor, the anchor will be used as the id of the element to be located at the anchor and the part after the # at the end of the link URL.

  • Links: Many web pages support clicking on the title to automatically add #anchor to the URL, which makes it easy for the viewer to share the current document part through the URL, especially when the web content is very large, this function is particularly useful. This article has also been implemented.


Hexo’s Markdown rendering is used by default hexo-renderer-marked (hereinafter referred to as hrm), the actual Markdown to HTML conversion is marked As a plug-in, hrm has adjusted the rendering of some of these elements.

hrm has done special processing for the heading (ie heading, from # to ###### in Markdown, corresponding to <h1> to <h6> in HTML), and will give output <hn> (n means 1-6) element plus id attribute, and an internal <a> element. The value of id here is based on the content of heading, removing extra spaces at the beginning and end, if there is a space in between, it is obtained by connecting it with a hyphen. If the id has a repeated value, -1 will be added to the second id, and if it continues to repeat, it will become -2, -3...


hrm is not very thoughtful about repeated id, consider this situation:

## example
## example
## example-1

The id of the first heading is example, then the second one should be example-1, and the third conflicts with the second. The current version (0.3.2) of hrm does not deal with this problem. Any treatment.

The second problem is that when the text of my heading is Chinese (or other non-English characters), the hash id in the URL may be transcoded and become very long, or it is the text I want to heading and the id of the anchor Different. The current hrm cannot meet this requirement.


So I fork hrm, and solved both of these problems: https://github.com/mdluo/hexo-renderer-marked, wrote a complete test case (I modified part of the test to cover 100%) and corresponding Documents. The modified content can refer to the following PR link.

I will submit a PR to the original hrm PR has been submitted, but you can pass it before merging

yarn add https://github.com/mdluo/hexo-renderer-marked

To use.


Add a configuration in _config.yml

  anchorAlias: true

Then use a format similar to the following in markdown. The problem of id duplication (including links as id) has been solved, and it will take effect regardless of whether this item is turned on or not.

## [plugin](#the-plugin)
## [Problem](#problem)
## [How to use](#usage)

If the generated webpage has not changed, you can try hexo clean to clear the cache and recompile.

In addition, in order to leave a little space at the top when the webpage is positioned to a certain anchor, you can set padding and margin. And to make heading have an interactive effect, you can add a ::before pseudo-element. The specific effect can refer to this article.

h1, h2, h3, h4, h5, h6 {
  padding-top: 1em;
  margin-top: -1em;
  &:hover {
    &::before {
      margin-left: -0.8em;
      position: absolute;

Any other questions are welcome to discuss in PR or leave a comment under this article.

Powered by Gatsby. Theme inspired by end2end.

© 2014-2021. Made withby mdluo.