Markdown Section Anchors: Heading Links Guide

[Jump to Summary](#executive-summary)
[[Document Name#Target Heading]]
[[Note#^block-id]]

In extensive technical documentation, lengthy research papers, detailed meeting minutes, and architectural runbooks, navigating directly to a specific section or clause is essential.

Markdown provides multiple mechanisms for deep document linking: standard internal heading anchors (for same-document jumps), WikiLink heading references (for cross-note navigation), and atomic block identifiers (for linking to specific paragraphs).

In Oyma and Obsidian, section anchors transform long documents into fluid, navigable reference materials.

Same-document heading links: [Text](#anchor)

To link to a heading within the same document, create a standard Markdown hyperlink where the destination URL begins with a hash symbol (#) followed by the heading’s anchor slug:

# Comprehensive Architecture Review

## Table of Contents
- [Executive Summary](#executive-summary)
- [Local Storage Engine](#local-storage-engine)
- [Security Invariants](#security-invariants)

---

## Executive Summary
This document provides an overview of our local-first implementation...

## Local Storage Engine
All notes are stored as CommonMark files on local disk...

## Security Invariants
Zero network telemetry egress occurs during normal operations...

When readers click Executive Summary, the editor or browser scrolls smoothly to that heading.

How Markdown generators construct heading anchor slugs

Most CommonMark and GFM parsers generate anchor slugs using a standardized algorithm:

1. Convert to lowercase: Architecture Overview → architecture overview
2. Remove punctuation: Remove characters like ?, !, :, ,, ., and quotes.
3. Replace spaces with hyphens: Replace consecutive spaces with a single hyphen (-): architecture-overview
4. Duplicate disambiguation: If two headings have identical titles, subsequent headings append a numeric counter (architecture-overview-1, architecture-overview-2).

Examples of slug generation

Cross-note heading links: [[Note#Heading]]

In Oyma and Obsidian, you can link directly to a heading located inside a different note:

We established our privacy principles in [[Privacy Architecture#Security Invariants]].
See the performance benchmarks in [[Local Whisper Pipeline#Latency Tests]].

Autocompletion in Oyma

When writing in Oyma:

1. Type [[Note Title
2. Type #
3. A menu of every heading inside that note appears instantly.
4. Select the target heading and press Enter.

Block-level references: [[Note#^block-id]]

When a concept is stated within an individual bullet point or paragraph rather than under a dedicated heading, you can link to that exact block:

In Note A:
The maximum audio buffer allocation is 512MB per session. ^buffer-limit

In Note B:
As defined in [[Note A#^buffer-limit]], buffer size is strictly capped.

Internal anchors in Oyma on macOS

In Oyma:

• Clicking any heading anchor or block link navigates smoothly to the target position with subtle visual highlighting.
• When headings are renamed, Oyma intelligently updates incoming cross-note links to preserve connectivity.
• All links remain standard plain text on your Mac disk.

Frequently asked questions

How do I create an internal link to a heading within the same Markdown document?

Use standard Markdown link syntax with a hash symbol (`#`) followed by the lowercase, hyphenated heading text (kebab-case slug): `[Jump to Section](#target-section-title)`.

How are heading anchors generated from heading titles?

Standard Markdown parsers convert heading text to lowercase, strip punctuation marks, and replace spaces with single hyphens (`# Architecture Overview` becomes `#architecture-overview`).

How do I link to a specific heading in another note in Obsidian or Oyma?

Use a WikiLink with a hash symbol: `[[Note Title#Heading Name]]`. In Oyma, typing `#` after the note title automatically autocompletes all available headings within that document.

Can I link to a specific paragraph or bullet item rather than a heading?

Yes. In Oyma and Obsidian, block references use the caret symbol (`^`): `[[Note Title#^block-id]]`. You can create a block ID by typing `^custom-id` at the end of any paragraph.