When you place a markdown link on its own line, IWE treats it as a structural relationship—the current document becomes the "parent" of the linked document. This lets you organize knowledge into hierarchies without folders, and a single document can have multiple parents.
Hierarchy is one of the most natural ways humans organize knowledge. We instinctively break complex information into nested structures:
- Living things are classified into kingdoms, classes, orders, and species
- Places nest from continents to countries to cities to neighborhoods
- Organizations have companies, departments, teams, and roles
- Projects break down into epics, features, and tasks
This isn't arbitrary—hierarchical thinking is how we manage complexity. It lets us zoom out to see the big picture or zoom in to focus on specifics—and switch between these views effortlessly. It provides context: knowing something is "under" a topic tells you what it relates to.
What makes knowledge truly interesting is where hierarchies intersect. "Color Theory" belongs under both Art and Physics. "Game Theory" connects Mathematics and Economics. "Nutrition" bridges Chemistry and Health. These intersections are where insight lives.
Good knowledge systems should support this natural way of thinking.
Traditional ways of organizing information don't match how knowledge actually works.
File systems force everything into a single hierarchy. A note about "Meditation" must live in either /health/ or /productivity/—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 allow multiple categories, but they lack structure:
- No order or priority
- No explanation of relationships
- No hierarchy
- No grouping within a category
A note tagged #health #productivity #mindfulness doesn't explain how these topics relate or which one is primary.
An inclusion link is a markdown link placed on its own line:
# Photography
[Composition](composition.md)
[Lighting](lighting.md)
[Post-Processing](post-processing.md)When a link appears on its own line, it defines structure: "Photography" becomes the parent of the linked documents.
This simple rule turns plain markdown into a structured, navigable system.
A document can belong to multiple parents.
In health-practices.md:
# Health Practices
[Meditation](meditation.md)In productivity-tools.md:
# Productivity Tools
[Meditation](meditation.md)The same document appears in both contexts without duplication.
Unlike tags, inclusion links allow ordering, grouping, and explanation:
# Psychology
## Cognitive
How we encode, store, and retrieve information
[Memory](memory.md)
Biases, heuristics, and rational choice
[Decision Making](decision-making.md)
## Behavioral
Cue, routine, reward loops
[Habit Formation](habit-formation.md)
You're not just grouping items—you're adding context.
By linking documents together, you naturally create paths through your knowledge:
Knowledge Base > Psychology > Cognitive > Memory
Knowledge Base > Photography > Composition
This makes navigation and search more meaningful—you see not just what matches, but where it fits.
When a document appears under a parent, it inherits meaning from that relationship. A "Memory" note under "Psychology" is understood differently than "Memory" under "Computer Architecture."
The parent page can also add explicit context:
# Cognitive Psychology
Foundation of learning and recall
[Memory](memory.md)
Selective focus and its limits
[Attention](attention.md)These descriptions aren't part of the child documents—they live in the parent, explaining why each child belongs here.
You can control how much information is visible. With --depth 1, you see only immediate children:
# Psychology
- Memory
- Decision Making
- Habit Formation
With --depth 3, the full subtree expands:
# Psychology
- Memory
- Working Memory
- Capacity Limits
- Chunking Strategies
- Long-term Memory
- Decision Making
- Habit Formation
Use Extract Actions to move details into separate documents, or Inline Notes to expand linked content in place.
Inclusion links define parent-child relationships and are used for:
- Navigation
- Hierarchical traversal (
--depth) - Structured views
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
When retrieving content with depth:
iwe retrieve psychology --depth 2The --depth flag controls how many levels of inclusion links to expand. See IWE Retrieve for details.
- Inclusion links expand into full content
- Inline links remain references only
This keeps structure clean while preserving connections between ideas.
Inclusion links give you structure without rigidity:
- Documents can exist in multiple contexts
- Ordering, grouping, and meaning are explicit
- Navigation becomes contextual
For a deeper understanding of how IWE represents these relationships internally, see Data Model.