Usage with CMS / embedded Markdown / HTML

[neet]

Thank you for maintaining this awesome library! This is a kind of essential tool that I can't make websites without this in the world that lost the Document Outline Algorithm 😭

I recently wrote an article in Japanese that introduces how to mark up headings properly in React and introduced react-headings.

• React で h1-h6 を正しく使い分ける
  https://zenn.dev/neet/articles/f25abb616ec105

I also tried to mention how to use react-headings with CMS or an embedded HTML / Markdown in that article, but I couldn't find a pretty way to achieve it.

This is basically what I've come up with (Using mdx-js):

import { useLevel } from "react-headings";
import { ElementType, ComponentProps, FC } from "react";

const makeRelativeH = (level: number) => {
  const RelativeH: FC<ComponentProps<"h2">> = (props) => {
    const baseLevel = useLevel();
    const absoluteLevel = Math.min(baseLevel + level - 1, 6);
    const Element = `h${absoluteLevel}` as ElementType;
    return <Element {...props} />;
  };

  return RelativeH;
};

// ===============

import { MDXProvider } from "@mdx-js/react";
import Article from "./article.mdx";

export const Cms: FC = () => {
  return (
    <div>
      <H>My blog</H>

      <Section component={<H>My article</H>}>
        <MDXProvider
          components={{
            h1: makeRelativeH(1),
            h2: makeRelativeH(2),
            h3: makeRelativeH(3),
            h4: makeRelativeH(4),
            h5: makeRelativeH(5),
            h6: makeRelativeH(6),
          }}
        >
          <Article />
        </MDXProvider>
      </Section>
    </div>
  );
};

But it directly accesses useLevel, does incrementation, calls Math.min, and concatenates with "h" which feels like I'm not getting the benefits of using a library.

My simple idea to avoid this is adding a new prop relativeLevel=X to H which makes the final heading level be (the current section's depth + X) so you can also use H in a flat structure.

<MDXProvider
  components={{
    h1: props => <H relativeLevel={1} {...props} />
    h2: props => <H relativeLevel={2} {...props} />
    h3: props => <H relativeLevel={3} {...props} />
    h4: props => <H relativeLevel={4} {...props} />
    h5: props => <H relativeLevel={5} {...props} />
    h6: props => <H relativeLevel={6} {...props} />
  }}
>,
  <Article />
</MDXProvider>

// Also...
<Section component={<H>Title</H>}           // → h1
  <H relativeLevel={1}>Heading level 1</H>  // → h2
  <H relativeLevel={2}>Heading level 2</H>  // → h3
</Section>

However, I then realised that this would also lead to users skipping the heading level. So I kept this idea to a Discussion post.

Do you have any idea?

[alexnault]

Hey @neet! Sorry for the late reply.

I really enjoyed your article! It does a great job explaining the heading and componentization problem.

The embedded HTML is an interesting case. To get more benefits from the library, one could use a solution similar to this:

import { H, Section } from 'react-headings';
import { MDXProvider } from '@mdx-js/react';
import Article from "./article.mdx";

const RelativeH = ({ level, ...props }) => {
  if (level === 1) {
    return <H {...props} />;
  }

  return (
    <Section component={<></>}>
      <RelativeH level={level - 1} {...props} />
    </Section>
  );
};

export const Cms = () => {
  return (
    <div>
      <H>My blog</H>
      <Section component={<H>My article</H>}>
        <MDXProvider
          components={{
            h1: (props) => <RelativeH level={1} {...props} />,
            h2: (props) => <RelativeH level={2} {...props} />,
            h3: (props) => <RelativeH level={3} {...props} />,
            h4: (props) => <RelativeH level={4} {...props} />,
            h5: (props) => <RelativeH level={5} {...props} />,
            h6: (props) => <RelativeH level={6} {...props} />,
          }}
        >
          <Article />
        </MDXProvider>
      </Section>
    </div>
  );
};

And like you said, introducing a relativeLevel prop might not be the best course of action since users could misuse the library by skipping levels and therefore break the hierarchy.

Cheers!