add MDX heading permalinks for tutorial pages by syam-bukkuru · Pull Request #1403 · processing/p5.js-website

syam-bukkuru · 2026-05-19T09:19:06Z

Summary

Adds MDX heading permalinks for tutorial pages using component overrides in TutorialLayout.astro.

Changes

Introduced reusable HeadingPermalink component (Preact)
Overrode h1–h6 in tutorial MDX rendering only
Preserved Astro-generated heading IDs
Made entire heading clickable (links to #fragment)
Added improved hover UX:
- # indicator appears on hover/focus (left side, subtle color)
- heading text underlines on hover
Scoped styles under .tutorials .rendered-markdown
Avoided nested anchor issues

Demo

Short demo showing heading hover, permalink visibility, and fragment navigation:
https://github.com/user-attachments/assets/ab1f6c54-a9a5-423d-860e-360aec349cd9

Testing

npm run check passes (no errors)
npm run build succeeds
Verified:
- hovering a heading shows # indicator
- clicking heading updates URL fragment
- direct #fragment navigation scrolls correctly
- headings without IDs do not break
- headings with inline links do not create nested anchors

Notes

Service worker 404 seen in dev console is unrelated to this change
No changes to routes, schemas, or global markdown behavior

davepagurek · 2026-05-20T22:45:56Z

@@ -1,4 +1,4 @@
-@import "/styles/variables.scss";
+@use "/styles/variables" as *;


Was this to fix anything in particular? Ideally this change should not need to affect how we import other files, or update the package lock.

Those changes were to address local Sass deprecation warnings about @import being phased out in favor of @use. I updated them while testing.

good to know, thanks!

davepagurek · 2026-05-20T22:48:13Z

+type HeadingProps = HTMLAttributes<HTMLHeadingElement> & {
+  as: HeadingTag;
+  children?: ComponentChildren;
+  id?: string;


For my understanding, what passes this in? Since it seems to be implicit, we may want to add a comment to explain it.

MDX passes these props automatically when rendering headings. Astro already injects things like id, children, etc. into the heading components, so this just forwards them into our custom component.

davepagurek · 2026-05-20T22:50:05Z

+          aria-label="Link to this section"
+        >
+          <span class="heading-permalink__text">{children}</span>
+          <span class="heading-permalink__icon">#</span>


Not huge, but possibly this could be done with just one <a> tag as before without <span> children if we add the # via CSS? something like

.heading-permalink::after: { content: '#'; display: inline; /* ...etc */ }

yeah I thought about that, but since we’re making the whole heading a link, if the heading text contains inline links it could create nested anchors. that’s why I split it out earlier.

but yeah using ::after for # still makes sense.

davepagurek · 2026-05-20T22:51:42Z

        img: FreeRatioImage,
        pre: PreProxy,
        a: LinkWrapper,
+        h1: HeadingPermalinkH1,


While the tutorial layout is the main thing I had in mind when raising the issue, are there other pages that would benefit from this too? e.g. probably pages with the contributor docs should also have it. Put another way, should this be the default, maybe with other pages opting out if need be? @ksen0 let me know if you have thoughts there!

I scoped it to tutorials first since that’s what the issue mentioned, but this could definitely be useful for other MDX pages like contributor docs too.

I wasn’t sure if it should be global by default or opt-in per layout, so I kept it limited for now. happy to extend it or move it to a shared layout if that’s preferred.

Makes sense, we can keep it limited at first, but I think at the very least let's do this in the contributor docs pages too to start with.

contribution_pages.mp4

I’ve extended the heading permalink behavior to contributor docs as well, while keeping it opt-in per layout rather than making it global for all markdown pages.

Tutorials and contributor docs now both use the shared heading permalink component, and the existing contributor docs jump-to links still use Astro’s generated heading slugs. I kept other MDX pages unchanged for now so we can expand deliberately if more pages need it later.

permalinks_for_all_pages.mp4

Applied permalink behavior for all pages, check once.

davepagurek · 2026-05-20T22:52:13Z

Thanks for working on this, your screen recording looks like what I was imagining for this feature! Left some comments, let me know what you think.

ksen0 · 2026-05-21T15:56:25Z

Thanks for working on this! Please link the issue in the PR description

syam-bukkuru · 2026-05-25T05:53:45Z

Thanks for working on this! Please link the issue in the PR description

Added the Issue Link in PR description. Please check once.

coseeian · 2026-05-28T01:40:51Z

+        <a
+          href={`#${id}`}
+          class="heading-permalink__link"
+          aria-label="Link to this section"


I suggest removing this aria-label so the browser can determine the accessible name from the actual link content.

Currently, generic text like "Link to this section" will repeat for every heading link, making them indistinguishable and confusing for screen reader users.

I am glad for your suggestion❤️. Made changes according to that, have a look into that.

Looks good to me. Thank you.

coseeian · 2026-05-28T14:59:12Z

+  }
+
+  .heading-permalink__link::after {
+    content: "#";


I suggest using alternative text syntax for the CSS-generated content to specify an empty string. This ensures screen readers do not read the character aloud:

.heading-permalink__link::after { content: "#" / ""; }

Browser support is strong across modern engines, excluding legacy IE (see Can I Use). You can verify this by inspecting the accessible name in the browser DevTools Accessibility tab to ensure the "#" symbol is excluded from the calculated link name.

For more details, see Sara Soueidan's article: https://www.sarasoueidan.com/blog/alt-text-for-css-generated-content/

Made the changes.

Looks good to me. Thank you.

syam-bukkuru · 2026-06-24T09:18:10Z

Hi @ksen0 , @davepagurek , @coseeian once check these changes. If there are any modifications, please mention. else, I like to clear the merge conflicts 😊.

ksen0 · 2026-06-26T21:32:52Z

HI @syam-bukkuru thanks for working on this, I really like how clear the indication is that the heading is linked! I also appreciate the sensible behavior of the links inside headings: both anchor link is visible and the additional link in the heading.

I did spot one side effect from generalizing this though:

Navigate to "Reference" > Typography section http://localhost:4321/reference/#Typography
Click on "Attributes"
Observe incorrectly being taken to an earlier sections' attributes subsection

Unless this is very straightforward to fix I'd suggest rather limiting the application of it on the Reference page to only h1/h2? cc @ritiupa, optionally, please feel free to weigh in on this.

Thanks to everyone for the careful reviews as well.

syam-bukkuru · 2026-06-28T18:15:27Z

perma_link.mp4

Thanks for spotting that @ksen0 . I’ve updated the Reference page anchors so repeated subheadings are now context-aware and unique, e.g. #typography-attributes instead of a shared #attributes. That keeps the linked heading UX intact while avoiding the jump-to-the-wrong-section issue.
I also updated the Reference jump-to links and the backlink from individual reference pages so they all use the same unique fragment format. So we shouldn’t need to limit this to just h1/h2 on Reference anymore.

syam-bukkuru mentioned this pull request May 19, 2026

Add permalinks for headings in tutorials #1398

Open

davepagurek reviewed May 20, 2026

View reviewed changes

syam-bukkuru requested a review from davepagurek May 25, 2026 05:54

coseeian reviewed May 28, 2026

View reviewed changes

add MDX heading permalinks for tutorial pages

d487cbe

syam-bukkuru force-pushed the feature/tutorial-heading-permalinks branch from ac1a777 to d487cbe Compare May 28, 2026 02:53

syam-bukkuru requested a review from coseeian May 28, 2026 03:01

coseeian reviewed May 28, 2026

View reviewed changes

syam-bukkuru requested a review from coseeian June 23, 2026 12:34

Added Permalinks behavior for every pages

ecd6b29

coseeian approved these changes Jun 24, 2026

View reviewed changes

syam-bukkuru requested a review from coseeian June 24, 2026 10:39

Fixed repeated subheadings

aebe836

		@@ -1,4 +1,4 @@
		@import "/styles/variables.scss";
		@use "/styles/variables" as *;

Uh oh!

Conversation

syam-bukkuru commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Demo

Testing

Notes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davepagurek commented May 20, 2026

Uh oh!

ksen0 commented May 21, 2026

Uh oh!

syam-bukkuru commented May 25, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

syam-bukkuru commented Jun 24, 2026

Uh oh!

ksen0 commented Jun 26, 2026

Uh oh!

syam-bukkuru commented Jun 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

syam-bukkuru commented May 19, 2026 •

edited

Loading