Working with Sections

Use heading-aware commands to work with complete Markdown sections.

What md-utils means by a section

Markdown and HTML do not inherently define the heading-delimited unit that md-utils calls a section. HTML has a <section> element, but a sequence of 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:

A section starts at a Markdown 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.

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.

Find sections

md-utils section list lists headings in document order and shows the structure that the section commands operate on:

md-utils section list guide.md

Filter the displayed levels or choose another output format when inspecting a large document:

md-utils section list guide.md --min-level 2 --max-level 4 --format tree

section list is equivalent to md-utils toc. The available formats are md-bullet-links, md-only-headings, tree, json, json-pretty, plain, and html.

Most section commands identify a heading in one of two ways:

• --name "Install" matches heading text, case-insensitively by default. Add --case-sensitive when capitalization must match.
• --index 3 selects the third heading in document order. Indexes are one-based and are useful when heading names repeat.

Read a section

Get a section by heading name:

md-utils section get --name "Install" guide.md

The output contains the ### Install heading, its body, and its nested #### Verify section. It stops before ### Configure.

Get a section by its heading index:

md-utils section get --index 3 guide.md

Write the extracted section to another file with --output:

md-utils section get --name "Install" --output install.md guide.md

section get operates on one Markdown file at a time.

Replace a section body

section set preserves the selected heading and replaces everything in its body, including any existing descendant sections. Read the replacement from a file:

md-utils section set --name "Install" --input new-install-body.md guide.md

Or provide the replacement on standard input:

echo "Run the installer, then verify its version." \
  | md-utils section set --name "Install" guide.md

By default, the transformed document is written to standard output. Add --in-place to update the source file:

md-utils section set --name "Install" --input new-install-body.md \
  --in-place guide.md

section set operates on one Markdown file at a time.

Insert a section

section insert adds a new section before or after an existing section. Name the new heading with --name, select the document with --into, and choose an anchor by heading name or one-based index:

md-utils section insert --name "Troubleshooting" --into guide.md \
  --after "Configure" --contents "Resolve common setup problems."

Use --before, --after-index, or --before-index for other placements. The inserted content can come from --contents, --from-file, or standard input. If the content already starts with a heading matching --name, md-utils uses that heading instead of adding a duplicate.

md-utils normalizes heading levels so the inserted content remains contained in one section. Use --level to request an explicit H1–H6 level when needed. The command writes the transformed document to standard output unless --in-place is supplied; --dry-run previews without writing.

Remove a section

Removing a section removes its heading, body, and every descendant section:

md-utils section remove --into guide.md --name "Install" --in-place

Select by heading index with --index. Omit --in-place or use --dry-run to inspect the transformed document without changing the source.

Reorder sibling sections

Move commands operate among sibling headings: sections with the same parent and heading level. The entire section moves as one unit, including all nested content.

Move a section one sibling position upward:

md-utils section move-up --name "Configure" --in-place guide.md

Move it multiple sibling positions with --count:

md-utils section move-down --name "Install" --count 2 --in-place guide.md

Move it to a specific one-based sibling position:

md-utils section move-to --name "Configure" --position 1 \
  --in-place guide.md

Without --in-place, the move commands write the transformed document to standard output. They operate on one Markdown file at a time.

Sections in mdtype definitions

The same concept appears in mdtype structural contracts. A type definition can declare a section constraint that identifies a heading and requires its section content to be either any or nonEmpty. Heading relationship constraints can separately require one heading to be a directChild or a descendant of another.

This lets a type describe structure such as “the document has a non-empty Installation section” without requiring that section to be exclusive to one type. Section commands manipulate that heading-delimited range; type commands check whether the range satisfies the declared contract.

Structural rule predicates use the same Markdown hierarchy rather than treating source text as a flat sequence of lines. This 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.

Command summary

Run md-utils section --help or md-utils section COMMAND --help for the full option reference.