Skip to main content

​
Headings Plugin

The Headings plugin provides three heading levels (H1, H2, H3) for structuring your document hierarchy.

​
Installation

npm install @yoopta/headings

​
Usage

import { HeadingOne, HeadingTwo, HeadingThree } from '@yoopta/headings';
import { createYooptaEditor } from '@yoopta/editor';

const plugins = [
  HeadingOne,
  HeadingTwo,
  HeadingThree,
];

const editor = createYooptaEditor({ plugins });
You can also import all headings together: 
import Headings from '@yoopta/headings';

const plugins = [
  Headings.HeadingOne,
  Headings.HeadingTwo,
  Headings.HeadingThree,
];

​
Features

  • Three heading levels: H1, H2, H3
  • Keyboard shortcuts for each level
  • HTML, Markdown, and Email export
  • Supports text marks (bold, italic, etc.)
  • Supports alignment and depth

​
Heading One (H1)

​
Options

{
  type: 'HeadingOne',
  options: {
    display: {
      title: 'Heading 1',
      description: 'Big section heading',
    },
    shortcuts: ['h1', '#'],
  },
}

​
Element Type

import type { HeadingOneElement } from '@yoopta/headings';

type HeadingOneElement = SlateElement<'heading-one'>;

​
Commands

import { HeadingOneCommands } from '@yoopta/headings';

editor.commands.HeadingOne.insertHeadingOne();

​
Heading Two (H2)

​
Options

{
  type: 'HeadingTwo',
  options: {
    display: {
      title: 'Heading 2',
      description: 'Medium section heading',
    },
    shortcuts: ['h2', '##'],
  },
}

​
Element Type

import type { HeadingTwoElement } from '@yoopta/headings';

type HeadingTwoElement = SlateElement<'heading-two'>;

​
Commands

import { HeadingTwoCommands } from '@yoopta/headings';

editor.commands.HeadingTwo.insertHeadingTwo();

​
Heading Three (H3)

​
Options

{
  type: 'HeadingThree',
  options: {
    display: {
      title: 'Heading 3',
      description: 'Small section heading',
    },
    shortcuts: ['h3', '###'],
  },
}

​
Element Type

import type { HeadingThreeElement } from '@yoopta/headings';

type HeadingThreeElement = SlateElement<'heading-three'>;

​
Commands

import { HeadingThreeCommands } from '@yoopta/headings';

editor.commands.HeadingThree.insertHeadingThree();

​
Parsers

​
HTML

Deserialize: Converts <h1>, <h2>, <h3> tags to heading blocks Serialize: Each heading level outputs with appropriate styling 
<!-- H1 -->
<h1 data-meta-align="left" data-meta-depth="0" 
    style="margin-left: 0px; text-align: left">
  Heading One
</h1>

<!-- H2 -->
<h2 data-meta-align="left" data-meta-depth="0" 
    style="margin-left: 0px; text-align: left">
  Heading Two
</h2>

<!-- H3 -->
<h3 data-meta-align="left" data-meta-depth="0" 
    style="margin-left: 0px; text-align: left">
  Heading Three
</h3>

​
Markdown

# Heading One

## Heading Two

### Heading Three

​
Email

Wraps headings in table structure with appropriate font sizing: 
<table style="width:100%;">
  <tbody style="width:100%;">
    <tr>
      <td>
        <h1 style="
          margin-bottom: .5rem;
          scroll-margin: 5rem;
          font-size: 2.25rem;
          font-weight: 700;
          line-height: 2.5rem;
          margin-top: 1.5rem;">
          Heading One
        </h1>
      </td>
    </tr>
  </tbody>
</table>

​
Examples

​
Basic Document Structure

import YooptaEditor, { createYooptaEditor } from '@yoopta/editor';
import { HeadingOne, HeadingTwo, HeadingThree } from '@yoopta/headings';
import Paragraph from '@yoopta/paragraph';

function Editor() {
  const editor = useMemo(() => 
    createYooptaEditor({ 
      plugins: [
        HeadingOne,
        HeadingTwo, 
        HeadingThree,
        Paragraph,
      ] 
    }), 
    []
  );

  return <YooptaEditor editor={editor} />;
}

​
Programmatic Insertion

import { Blocks } from '@yoopta/editor';

// Insert H1
Blocks.insertBlock(editor, {
  type: 'HeadingOne',
  value: [
    {
      id: generateId(),
      type: 'heading-one',
      children: [{ text: 'Chapter Title' }],
    },
  ],
});

// Insert H2
Blocks.insertBlock(editor, {
  type: 'HeadingTwo',
  value: [
    {
      id: generateId(),
      type: 'heading-two',
      children: [{ text: 'Section Title' }],
    },
  ],
});

​
Using Keyboard Shortcuts

Type these shortcuts at the start of an empty paragraph:
  • h1 or # + Space → Converts to Heading 1
  • h2 or ## + Space → Converts to Heading 2
  • h3 or ### + Space → Converts to Heading 3

Build docs developers (and LLMs) love

Get started for freeTalk to us