Headings

Use markdown heading syntax to structure your documentation with six levels of hierarchical headings.

4 min read

Headings

Headings create the structure and hierarchy of your documentation. Mordoc supports six levels of headings using standard markdown syntax.

Basic Syntax

Use hash symbols (#) to create headings. The number of hashes determines the heading level:

Markdown

# Heading Level 1
## Heading Level 2
### Heading Level 3
#### Heading Level 4
##### Heading Level 5
###### Heading Level 6

Heading Hierarchy

Level 1: Page Title

Use a single # for the main page title. Typically, each page should have only one level 1 heading.

Markdown

# Getting Started with Mordoc

Getting Started with Mordoc

Level 2: Major Sections

Use ## for major sections within your page.

Markdown

## Installation
## Configuration
## Usage

Installation

Configuration

Usage

Level 3: Subsections

Use ### for subsections under major sections.

Markdown

### System Requirements
### Download Instructions

System Requirements

Download Instructions

Level 4-6: Detailed Hierarchy

Use ####, #####, and ###### for more detailed hierarchical structures.

Markdown

#### Step-by-Step Guide
##### Prerequisites Check
###### Verify Node Version

Step-by-Step Guide

Prerequisites Check

Verify Node Version

Best Practices

Heading Structure

Start with Level 1: Every page should begin with a single # heading
Don't Skip Levels: Go from ## to ###, not ## to ####
Be Consistent: Use parallel structure for headings at the same level
Keep It Short: Headings should be concise and descriptive

Good Heading Structure

Markdown

# User Guide

## Getting Started
### Installation
### First Steps

## Advanced Features
### Custom Themes
### API Integration

Poor Heading Structure

Markdown

# User Guide

#### Installation (skips levels)

## First Steps (inconsistent order)

##### Custom Themes (skips levels)

Heading IDs and Anchors

Mordoc automatically generates IDs for all headings, enabling deep linking.

Automatic ID Generation

A heading like this:

Markdown

## Installation Guide

Gets an ID of installation-guide, allowing you to link to it:

Markdown

[Jump to Installation](/page#installation-guide)

ID Generation Rules

Converts to lowercase
Replaces spaces with hyphens
Removes special characters
Handles unicode characters

Heading	Generated ID
`## Quick Start`	`quick-start`
`## API Reference`	`api-reference`
`## FAQ & Troubleshooting`	`faq-troubleshooting`

Table of Contents Integration

Headings automatically appear in the table of contents (TOC) sidebar. The TOC displays the hierarchical structure of your page based on heading levels.

By default:

Level 2 (##) and Level 3 (###) headings appear in the TOC
Level 1 is the page title
Level 4-6 may be included based on configuration

See Table of Contents Configuration for customization options.

Styling Headings

Headings can be styled through the typography configuration file.

Edit config/styles/typography.json:

Json

{
  "headings": {
    "h1": {
      "fontSize": "2.5rem",
      "fontWeight": "700",
      "lineHeight": "1.2",
      "marginTop": "0",
      "marginBottom": "1rem",
      "color": "inherit"
    },
    "h2": {
      "fontSize": "2rem",
      "fontWeight": "600",
      "lineHeight": "1.3",
      "marginTop": "2rem",
      "marginBottom": "1rem",
      "color": "inherit"
    },
    "h3": {
      "fontSize": "1.5rem",
      "fontWeight": "600",
      "lineHeight": "1.4",
      "marginTop": "1.5rem",
      "marginBottom": "0.75rem"
    }
  }
}

Available Style Properties

Property	Description	Example Values
`fontSize`	Size of the heading text	`2rem`, `24px`
`fontWeight`	Weight/thickness of font	`400`, `600`, `700`
`lineHeight`	Spacing between lines	`1.2`, `1.5`
`marginTop`	Space above heading	`1rem`, `24px`
`marginBottom`	Space below heading	`0.5rem`, `12px`
`color`	Text color	`#333333`, `inherit`
`fontFamily`	Font family override	`Georgia, serif`

Style Inheritance

Headings inherit base styles from the typography.json configuration. You can override specific properties for each heading level.

Accessibility

Proper heading structure is crucial for accessibility:

Screen Readers: Use heading hierarchy to navigate content
SEO: Search engines use headings to understand page structure
Readability: Clear headings make content scannable

Accessibility Checklist

✓ Use semantic heading levels (don't skip levels)
✓ Ensure headings describe the content that follows
✓ Maintain consistent heading hierarchy across pages
✓ Don't use headings for styling (use CSS instead)

Avoid using headings solely for visual styling. If you need larger text, use CSS styling instead of heading tags.

Examples

Documentation Page Structure

Markdown

# API Reference

## Authentication
### API Keys
### OAuth Flow

## Endpoints
### Users
#### GET /users
#### POST /users
### Projects
#### GET /projects
#### POST /projects

## Rate Limiting
### Default Limits
### Enterprise Plans

Tutorial Structure

Markdown

# Build Your First App

## Before You Begin
### What You'll Learn
### What You'll Need

## Step 1: Setup
### Install Dependencies
### Configure Environment

## Step 2: Create Components
### Header Component
### Footer Component

## Step 3: Deploy
### Build for Production
### Deploy to Hosting

Next Steps

Learn about other content elements:

Links - Create hyperlinks and cross-references
Images - Embed images in your documentation
Lists - Use ordered and unordered lists