Add anchor links to headings

[olayway]

In Obsidian you can create internal links that point to a specific heading in a given file, by adding # and the name of the heading to the link. E.g. [[docs/roadmap#Callouts]], would point to Callouts heading in /docs/roadmap.md.
Such links to headings are correctly converted to URL's (in this case it would be [root_URL]/docs/roadmap#callouts) but since headings at the moment don't have ids, #callouts has no effect.

See https://github.com/rehypejs/rehype-autolink-headings

Acceptance

• Headings get id/anchors (olayway:) this is easily done with rehype-slug and rehype-auto-link-headings
• they are compatible with what obsidian generate (olayway:) yes, tested with these two packages
• they are compatible with remark-toc e.g. with Table of content support in markdown #27 (olayway:) yes, tested with these two packages and remark-toc
• they are compatible with what we do in RHS ToC (sidebar current page table of contents) #95 (olayway:) I'd say it's not a matter of compatibility; it's the matter of populating the RHS ToC with headings (that we have added ids and anchors to) from each page (see notes below)
• working links to a specific heading within a given page, e.g. [[roadmap#Planned features]] (olayway:) yes, tested with these two packages
• working links to a specific heading within a given page with a custom name, e.g. [[roadmap#Planned features|Work in progress...]] (olayway:) yes, tested with these two packages

Notes

rehype-slug, rehype-autolink-headings, and remark-toc have been tested on this branch: https://github.com/flowershow/flowershow/tree/47-headings-links

• see headings on any page - they have [ # ] icon above them that links to themselves as well as ids (this is just a test, not styled yet)
• see table of contents on /docs/mdx page
• see testing obsidian links to headings on /test/links-to-headings page

Pros of using the above 3 packages

It is very simple (almost done on the above test branch, only headings require some styling) and works just like that.

Cons

These packages allow for minimal customization. Even styling headings to achieve the hover-over effect with [ # ] icon like tailwind has is not that simple and will require some workaround (or even a slightly different result).

Additionally, we still would need a way to populate the RHS ToC (#95) with headings from the current page, which would require parsing the page once again in search for headings (sth that is already done twice by rehype-slug and rehype-autolink-headings), extracting their slugs and somehow making them available to the RHS ToC. Tailwind is doing it the custom way - using custom Heading components that (apart from adding ids and links) register/unregister themselves to/from the ToC.

My analysis of Tailwind's solution: https://github.com/datopian/product/blob/main/notes/tailwindcss-website-toc.md

Proposed solution

Since adding links and in-markdown ToC is extremely simple using the 3 packages mentioned above, I'd use them for now and start working on custom solutions while working on RHS ToC.

[rufuspollock]

@olayway at least research e.g. look at best practice in tailwindui, look at simple approach e.g. as we did in life-itself/web3#116

[olayway]

@rufuspollock see my comments above

[rufuspollock]

@olayway excellent analysis 👏 - really thorough and clear with pros and cons that summarize the issue and a clear recommendation. Agree on proceeding as suggested.