feat(gatsby-transform-remark): populate id to headings from markdownAST

[bongnv]

Description

Currently, in order to generate table of contents, we can use tableOfContents in gatsby-transform-remark together gatsby-remark-autolink-headers. However, tableOfContents is kind of static and it's hard to add more effects.

Using headings instead doesn't return enough information (id or anchor) in order to link to heading.

The MR will populate id from data.id or id in data.HTMLAttributes in markdownAST in.
With schema

id
depth
value

headings should be able to provide enough information to render a custom TOC.

Documentation

id needs to be populated in order to use. It works best with gatsby-remark-autolink-headers.

If id is available, it is an empty string by default.

Use

    markdownRemark(fields: { slug: { eq: $slug } }) {
      id
      html
      headings {
        id
        value
        depth
      }
    }
  }

To query headings.

Related Issues

[pieh]

few small comments to address

additionally - but this might not be straight forward to do - would it be possible to add test case - following

gatsby/packages/gatsby-transformer-remark/src/__tests__/extend-node.js

Lines 1243 to 1267 in e1ef491

	bootstrapTest(
	`returns value`,
	`
	# first title
	## second title
	`,
	`headings {
	value
	depth
	}`,
	node => {
	expect(node).toMatchSnapshot()
	expect(node.headings).toEqual([
	{
	value: `first title`,
	depth: 1,
	},
	{
	value: `second title`,
	depth: 2,
	},
	])
	}
	)

"template"? I'm not sure if that will work because remark itself probably doesn't add any ids?

[bongnv]

@pieh , how do you run test locally?
I used yarn jest gatsby-transformer-remark, it gave me a couple of errors like:

    Cannot find module 'gatsby-cli/lib/reporter' from 'extend-node.js'

       5 | const { typeDefs } = require(`../create-schema-customization`)
       6 |
    >  7 | jest.mock(`gatsby-cli/lib/reporter`, () => {

and

    Cannot find module 'gatsby-core-utils' from 'on-node-create.js'

      4 | const { graphql } = require(`gatsby/graphql`)
      5 |
    > 6 | const { createContentDigest } = require(`gatsby-core-utils`)
        |                                 ^

[pieh]

You would need to run yarn bootstrap in root of repo first to build all the packages locally (those test fail, because this package is not built, so it can't import it)

[bongnv]

Hi @pieh ,
build is green now. please let me know if there is any concern.

[pieh]

Figured out how to setup test to use autolink-headers - I added one so there is actual test that verify it returns id if they are set

[pieh]

Looks awesome - thanks!

[gatsbot]

Holy buckets, @bongnv — we just merged your PR to Gatsby! 💪💜

Gatsby is built by awesome people like you. Let us say “thanks” in two ways:

1. We’d like to send you some Gatsby swag. As a token of our appreciation, you can go to the Gatsby Swag Store and log in with your GitHub account to get a coupon code good for one free piece of swag. We’ve got Gatsby t-shirts, stickers, hats, scrunchies, and much more. (You can also unlock even more free swag with 5 contributions — wink wink nudge nudge.) See gatsby.dev/swag for details.
2. We just invited you to join the Gatsby organization on GitHub. This will add you to our team of maintainers. Accept the invite by visiting https://github.com/orgs/gatsbyjs/invitation. By joining the team, you’ll be able to label issues, review pull requests, and merge approved pull requests.

If there’s anything we can do to help, please don’t hesitate to reach out to us: tweet at @gatsbyjs and we’ll come a-runnin’.

Thanks again!

[muescha]

should the id field also go into some docs (or the transform-remark README)?