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.

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/

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

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

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!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

syam-bukkuru commented May 19, 2026 •

edited

Loading