Documentation
Concepts
Inclusion Links

Inclusion Links

Why Hierarchy Matters

Hierarchy is one of the most natural ways humans organize knowledge. We instinctively break complex information into nested structures:

  • Books have chapters, sections, and paragraphs
  • Organizations have departments, teams, and roles
  • Biology classifies life into kingdoms, phyla, species
  • Outlines structure ideas from general to specific

This isn’t arbitrary—hierarchical thinking is how we manage complexity. It lets us zoom out for overview or zoom in for detail. It provides context: knowing something is “under” a topic tells you what it relates to.

Good knowledge systems should support this natural way of thinking.

The Problem

Traditional ways of organizing information don’t match how knowledge actually works.

Directories: One Place Only

File systems force everything into a single hierarchy. A document about “React Performance Optimization” must live in either /frontend/react/ or /performance/—it can’t naturally exist in both.

This leads to:

  • Arbitrary placement decisions
  • Broken references when folders change
  • Duplicates or “misc” folders when nothing fits

But knowledge isn’t a single tree—it’s interconnected.

Tags: Flexible but Shallow

Tags allow multiple categories, but they lack structure:

  • No order or priority
  • No explanation of relationships
  • No hierarchy
  • No grouping within a category

A document tagged #react #performance #frontend doesn’t explain how these topics relate or which one is primary.

The Solution: Inclusion Links

An inclusion link is a markdown link placed on its own line:

# Frontend Development

[React Fundamentals](react-fundamentals.md)

[Vue.js Guide](vue-guide.md)

[Performance Optimization](performance.md)

When a link appears on its own line, it defines structure:
“Frontend Development” becomes the parent of the linked documents.

This simple rule turns plain markdown into a structured, navigable system.

What This Enables

Multiple Contexts (Polyhierarchy)

A document can belong to multiple parents:

# React Topics                    # Performance Topics

[Performance Optimization]        [Performance Optimization]

The same document appears in both contexts without duplication.

Structure with Meaning

Unlike tags, inclusion links allow ordering, grouping, and explanation:

# Projects

## Active

[Website Redesign](website-redesign.md)
Building the new company site

[Analytics Dashboard](analytics.md)
Real-time metrics visualization

## On Hold

[Mobile App](mobile-app.md)
Waiting for API completion

You’re not just grouping items—you’re adding context.

Navigable Hierarchies

By linking documents together, you naturally create paths through your knowledge:

Knowledge Base > Work Projects > Website Redesign
Knowledge Base > Learning Notes > JavaScript Frameworks

This makes navigation and search more meaningful—you see not just what matches, but where it fits.

Flexible Level of Detail

You can control how much information is visible:

  • Extract sections into separate documents to hide details
  • Inline documents to expand and show full content

Your knowledge base can expand or collapse depending on your needs.

Inclusion Links vs Inline Links

Inclusion Links (Structure)

Standalone links define parent-child relationships and are used for:

  • Navigation
  • Hierarchical traversal (--depth)
  • Structured views

Inline Links (References)

Links inside text create conceptual connections:

# Habit Formation

The [Habit Loop](habit-loop.md) consists of cue, routine, and reward.
This process is driven by [Dopamine Pathways](dopamine.md) in the brain.

These links:

  • Create backlinks
  • Show relationships between ideas
  • Do not affect structure

Why This Distinction Matters

When retrieving content with depth:

iwe retrieve psychology --depth 2
  • Inclusion links expand into full content
  • Inline links remain references only

This keeps structure clean while preserving connections between ideas.

Summary

Inclusion links turn markdown into a structured system without losing flexibility:

  • No forced single hierarchy
  • No flat, contextless tagging
  • Documents can exist in multiple contexts
  • Structure, ordering, and meaning are explicit
  • Navigation and search become contextual

Instead of choosing where something belongs, you define how it connects.

The Context Bridge