Mastering Wiki-Links in Hugo

Introduction to Wiki-Links

Wiki-links are a simple, powerful syntax for linking between pages: Page Title. Popularized by wikis and note-taking apps like Obsidian and Roam Research, they make creating connections effortless.

Why Wiki-Links Matter

Compare traditional markdown links to wiki-links:

Traditional: [Link text](/posts/my-article/)
Wiki-link:   My Article

Benefits of wiki-links:

✅ Faster to write - No need to remember exact URLs
✅ Auto-complete friendly - Works with note-taking apps
✅ Refactor-safe - Title changes update automatically
✅ Encourage linking - Lower friction means more connections

How Vitis Handles Wiki-Links

The Vitis theme processes wiki-links intelligently:

1. Automatic Resolution

Knowledge Graphs
↓
<a href="/posts/knowledge-graphs/">Knowledge Graphs</a>

Vitis searches your content tree and finds the matching page, regardless of where it lives in your directory structure.

2. Broken Link Detection

When you link to a non-existent page:

Future Post Idea

Vitis renders it with a special style (dashed underline, different color) to indicate the target doesn’t exist yet. This encourages progressive content creation.

3. Automatic Backlinks

Every page automatically displays which other pages link to it:

📎 Backlinks (3)
→ Digital Garden Principles
→ Content Organization Tips  
→ Note-Taking Workflows

This creates bidirectional navigation without manual effort.

Wiki-Link Patterns and Best Practices

Basic Syntax

# Simple link
Page Title

# Link with different text (if supported)
Custom Link Text

# Link to a specific section
Page Title#Section Heading

Naming Conventions

Choose clear, descriptive titles:

❌ Post 1
❌ My Thoughts
✅ React Component Patterns
✅ CSS Grid Layout Guide

Good titles are:

Specific - Clear what the page is about
Searchable - Easy to find and autocomplete
Meaningful - Provide context when reading

Creating Link Networks

Build dense local networks around topics:

## Frontend Frameworks

Modern web development relies on robust Frontend Frameworks
like React, Vue, and Angular.

Each framework approaches State Management differently:
- React uses React Hooks and Context API
- Vue offers Vuex and Pinia  
- Angular provides RxJS and Services

Understanding Component Lifecycle is crucial for all three.

This creates a rich cluster of related content.

Hub and Spoke Pattern

Create “hub” pages that link to many related concepts:

---
title: "Web Development Hub"
---

## Core Technologies
- HTML Fundamentals
- CSS Architecture  
- JavaScript ES6+

## Frameworks
- React Ecosystem
- Vue.js Guide

## Tools
- Webpack Configuration
- Development Workflows

Spokes link back to the hub and to each other.

Progressive Disclosure

Start with broken links, fill them in over time:

Day 1:
Working with TypeScript improves Code Quality
through Static Type Checking.

Day 7:  
✅ Created: TypeScript page
⏳ To create: Code Quality, Static Type Checking

Day 30:
✅ All pages created!
✅ Added more connections between them

Technical Implementation

How Vitis Processes Links

Build Time Processing

Page Title → Search content tree → Generate URL

Backlink Generation

For each page → Find all wiki-links pointing to it → Display list

Graph Data Generation

Extract all links → Create nodes and edges → Output JSON

File Organization Freedom

Wiki-links work regardless of file location:

content/
  posts/
    web-dev.md     → React  ✓ Works
  notes/
    frameworks/
      react.md     ← Found!

You don’t need to know the exact path.

Advanced Techniques

Creating Index Pages

Use wiki-links to build dynamic indexes:

---
title: "Programming Languages Index"
---

## Compiled Languages
C++ | Rust | Go

## Interpreted Languages  
Python | Ruby | JavaScript

## Functional Languages
Haskell | Elixir | Clojure

Cross-Referencing Series

Link between parts of a series:

<!-- Part 1 -->
Next up, we'll explore Part 2: Advanced Patterns

<!-- Part 2 -->
Building on Part 1: Fundamentals, let's discuss...

Linking to Concepts

Create pages for abstract concepts:

Understanding Functional Composition helps when
working with Higher-Order Functions in JavaScript.

Even abstract ideas get their own pages!

Common Pitfalls

Case Sensitivity

Most implementations are case-sensitive:

React Hooks  ≠  react hooks  ≠  React hooks

Choose a convention and stick with it.

Duplicate Titles

Avoid having multiple pages with the same title:

❌ content/posts/intro.md (title: "Introduction")
❌ content/notes/intro.md (title: "Introduction")  
✅ Unique titles for each page

Over-Reliance on Broken Links

While broken links are useful, too many can be overwhelming:

❌ A B C D E F G
   (none exist yet)

✅ Start with 2-3 links, create those pages, then expand

Workflow Integration

Note-Taking Apps

Use Obsidian, Logseq, or Roam Research to:

Draft content with wiki-links
Export to markdown
Move files to Hugo content directory
Build site with Vitis

The wiki-link syntax transfers seamlessly!

Content Planning

Use broken links as a content roadmap:

# Content Pipeline

## Planned (via broken links)
- API Design Patterns (linked from 3 posts)
- Database Optimization (linked from 2 posts)
- Testing Strategies (linked from 1 post)

Priority: Most referenced first!

Measuring Link Health

Check your wiki-link health:

Link density: 3-8 outbound links per page is ideal
Broken link ratio: Aim for <20% broken links
Backlink distribution: Every page should have 1+ backlinks
Reciprocal links: 40%+ of links should be bidirectional

The Network Effect

Each wiki-link has multiplicative value:

1 page, 0 links   = 0 connections
2 pages, 1 link   = 1 connection  
3 pages, 3 links  = 3 connections
10 pages, 20 links = 20 connections

More links → More discovery → More learning

Getting Started

Take an existing post
Identify 3-5 key concepts
Convert them to wiki-links: Concept Name
Review the backlinks that now appear on other pages
Check the graph to see new connections

Start small, build momentum!

Building Your Digital Garden with Vitis
Knowledge Graphs: Connecting Ideas Visually
Content Organization Strategies
The Zettelkasten Method

Wiki-links are the connective tissue of your digital garden. Use them liberally to let your knowledge grow organically.