Read headings in 1.0.0

[danilopolani]

What version of astro are you using?

1.0.0

Are you using an SSR adapter? If so, which one?

None

What package manager are you using?

npm

What operating system are you using?

Windows

Describe the Bug

Prior to 1.0.0 we had a astro.headings object to get all the current headings from a MD file.
Now, that property has been removed (although still appears in the docs) and it seems that from a MD file we don't have anymore a way to get the headings.

I decided then to convert my md files to mdx, but also with MDX you can access getHeadings() only when using import/Astro.glob, but I'm using the layout property in the frontmatter, so no luck even with this.
In fact, it has even "broken" the docs starter theme, not showing anymore the headings in the right sidebar.

So... What should be the current solution to achieve it?

Link to Minimal Reproducible Example

https://github.com/withastro/astro/tree/main/examples/docs

Participation

• [X] I am willing to submit a pull request for this issue.

[bholmesdev]

Thanks for reporting @danilopolani! Yes, this is definitely a problem in our documentation. We suggest accessing headings as a top-level prop from your layout like so:

---
// src/layouts/BaseLayout.astro
const { headings } = Astro.props;
---

This should be corrected in the present docs example as well (see the RightSidebar.astro).

This behavior sadly has not made its way to the MDX integration though, so we'll need a separate PR for that. We will update the documentation to reflect this change ASAP though!

[duncanwerner]

This should be corrected in the present docs example as well

Actually your linked file is correct but the docs template is broken because it doesn't handle headers properly. I was going to post a bug but I guess this is related. In the documentation template, MainLayout.astro does not handle headings; it needs to get them from props and then set them as prop on RightSidebar. It's a two line fix but I can put up a PR if you want.

(edit: Astro 1.0.0, wsl, npm)

[bholmesdev]

@duncanwerner Ah, good to know! Yes, feel free to open a PR. We are updating the docs to reflect this new headings object as well (https://github.com/withastro/docs/pull/1246). Let me know if you hit any roadblocks and tag me on the review!

[danilopolani]

Thank you guys! So for MDX we still have to wait a little bit to access the headings like MD would do with content.headings, right?

[bholmesdev]

@danilopolani Working on a PR to align MDX with MD! To confirm, this is the 100% finalized API we are mirroring. There are some subtle changes:

content - all frontmatter from the Markdown or MDX document. content.file - The absolute path of this file (e.g. /home/user/projects/.../file.md). content.url - If it’s a page, the URL of the page (e.g. /en/guides/markdown-content). headings - A list of headings (h1 -> h6) in the Markdown document with associated metadata. This list follows the type: { depth: number; slug: string; text: string }[]. rawContent() - A function that returns the raw Markdown document as a string. compiledContent() - A function that returns the Markdown document compiled to an HTML string.

[bholmesdev]

@duncanwerner Checking if you're still interested in an examples/docs PR! I plan to tackle this change by tomorrow if not, no worries :)

[duncanwerner]

No, go ahead and make changes.

[bholmesdev]

So to confirm everything here:

• Today, you can access headings from MD and MDX using Astro.props.headings. Update to astro@latest and @astrojs/mdx@latest if that isn't the case!
• We should update @examples/docs to use headings properly

@danilopolani Let me know if that's correct!

[danilopolani]

So to confirm everything here:

* Today, you can access headings from MD and MDX using `Astro.props.headings`. Update to `astro@latest` and `@astrojs/mdx@latest` if that isn't the case!

* We should update `@examples/docs` to use `headings` properly

@danilopolani Let me know if that's correct!

Hey, sorry for my delay in answering, I just updated the dependencies and I can retrieve headings from Astro.props following the (updated) docs example, thank you!