Code (backticks) as a part of h1 heading?

[JoshuaKGoldberg]

I see from #5065 -> https://docusaurus.io/docs/api/docusaurus-config that ` in headings is meant to work. But in JoshuaKGoldberg/learning-typescript-site#3 I see that when using the backticks inside specifically the top-level heading, it's still plain text:

The `satisfies` operator

Note that h2 and h3 headings do correctly format backticks into code.

Am I doing something wrong here?

[johnnyreilly]

This behaviour does not satisfies me 😉

[Josh-Cena]

Hmm, I'm surprised @slorber said it "would be fixed" in beta.2—AFAICT it had never worked. The H1 heading is different from the other headings because it's extracted before the Markdown is even properly parsed with MDX—we use a simple regex. This feature was originally implemented by @armano2. The idea is that H1 headings are actually sugar for:

---
title: The `satisfies` Operator
---

Your content

Where Markdown obviously doesn't work, since the front matter is plain text.

Another reason why it doesn't is because the H1 heading is used in many more places than the title itself. It's used in the browser tab title, in breadcrumb title, pagination, sidebar, etc., where none of them permit any kind of typography. A reasonable behavior is to assume everything within the heading is plain text, else we need to actually do the parsing and strip all the Markdown away, since we have to render plain text for most places anyway.

[Josh-Cena]

OK, maybe I'm dreaming of it 😄 I would double check later. Pretty sure H1 headings have limitations, but maybe not here.

PS. .mdx and .md have absolutely no difference in how they are processed. Maybe we should write this in the largest font and bold and italic and underline on the front page.

[JoshuaKGoldberg]

FWIW I swizzled around this with LearningTypeScript/site@9446595. In theory I could have done actual Markdown parsing but figured I'd keep it simple for now.

I'd be happy to send a PR with actual markdown parsing in the titles if you think it'd be a good idea!

[slorber]

Yes, h1 titles are a special case and converted as text-only for multiple other use-cases (notably sidebar and SEO metadata).

The alternative to this special case would have been to use a runtime markdown parser (has a cost, may change with Server Components) or parse the syntax in node and use dangerouslySetInnerHTML (not great either)

---

It looks like we only ever implemented unwrapping titles that are full inline code blocks 😄

function toTextContentTitle(contentTitle: string): string {
  if (contentTitle.startsWith('`') && contentTitle.endsWith('`')) {
    return contentTitle.substring(1, contentTitle.length - 1);
  }
  return contentTitle;
}

Probably not very hard to fix and unwrap the title with text + inline code, if someone want to send a PR

[JoshuaKGoldberg]

send a PR

Ooh! Me! Pick me! 😁

[Josh-Cena]

@JoshuaKGoldberg Go for it! 😄