Sections

A section is the range of a Markdown document that begins with a heading and continues until the next heading of the same or higher rank, or the end of the document.

The section includes its starting heading, all body content beneath it, and any lower-ranked child headings and their content. Here, “higher rank” means a smaller heading-level number: H1 ranks above H2, H2 above H3, and so on.

An md-utils concept

Neither Markdown nor HTML inherently defines this heading-delimited unit as a section. HTML has a <section> element, but a sequence of HTML headings does not automatically create the same ranges. md-utils defines the term operationally so its commands, rules, and structural types can refer to document regions consistently.

This definition is based on Markdown headings and their hierarchy. It does not depend on an HTML <section> element being present in rendered output.

Section boundaries

Consider this Markdown:

# Guide

An overview.

## Setup

Prepare the project.

### Install

Run the installer.

#### Verify

Check the installed version.

### Configure

Choose the project settings.

## Usage

Run the project.

It contains nested section ranges:

• The H1 Guide section contains the complete document from # Guide onward.
• The H2 Setup section includes its own paragraph, both H3 sections, and the H4 Verify section. It ends immediately before the H2 Usage heading.
• The H3 Install section includes the H4 Verify section. It ends immediately before the H3 Configure heading.
• The H4 Verify section contains its heading and paragraph. It ends at the H3 Configure heading because H3 has a higher rank than H4.
• The H2 Usage section continues to the end of the document.

In short, an H3 section ends at the next H1, H2, or H3. An H4, H5, or H6 does not end it because those headings are descendants inside the H3 section.

Heading, body, and descendants

md-utils distinguishes between a complete section and its body:

• The heading is the line that starts the section.
• The body is everything after that heading up to the section boundary.
• A descendant section starts at a lower-ranked heading inside the body.
• A direct child section is an immediate child in the parsed heading hierarchy, with no intervening heading ancestor.

The complete section includes the heading and body. As a result, operating on a complete section also carries or removes its descendants. Replacing only a section body preserves the starting heading but replaces the content and descendant sections beneath it.

Content before the first heading is document preamble, not a section. A heading-like line inside a fenced code block is code, not a section boundary. A heading with no content still defines a section; its body is empty.

Where md-utils uses sections

The section model appears in several parts of md-utils:

• md-utils section lists, extracts, inserts, replaces, removes, and reorders complete sections or section bodies.
• mdtype definitions can declare a section constraint for a named heading and require its content to be any or nonEmpty.
• mdtype heading relationships can require one heading to be a directChild or descendant of another.
• Structural rule predicates use the same Markdown hierarchy rather than treating source text as a flat sequence of lines.

This structural model applies to Markdown records. md-utils does not infer Markdown sections from non-Markdown source files such as Swift, JavaScript, or HTML; section and heading predicates report that the capability is unsupported for those records.

See Working with Sections for command examples and the complete md-utils section workflow.