Ascend Documentation

Appearance

Wiki Links & Backlinks ​

Connect your pages with powerful bidirectional linking.

Wiki links are a way to link between pages using double square brackets:

[[Page Name]]

Why they're called "wiki" links: Popularized by Wikipedia and wiki systems where [[Article Name]] creates links.

Benefits:

  • 🔗 Quick page linking
  • 📚 Build knowledge graphs
  • 🔍 Discover connections
  • 🔄 See what links to you (backlinks)

Basic Syntax ​

Type double brackets around a page title:

See [[Authentication Guide]] for details.
Related: [[User Management]] and [[API Reference]]

Result: Page names become clickable links

Step-by-Step ​

  1. Start typing in any text block
  2. Type [[
  3. Type page name: [[My Page Name
  4. Close brackets: ]]
  5. Link created! Text becomes a link

Full example:

Before: For setup instructions, see [[Installation Guide]]
After:  For setup instructions, see Installation Guide (linked)

Autocomplete (Future Feature) ​

Coming soon: While typing [[, you'll see:

  • Dropdown of existing pages
  • Filtered as you type
  • Click or Enter to select
  • Auto-completes page name

Current behavior: Type full page name manually

Backlinks show you which pages link TO the current page.

Example:

Page A mentions [[Page B]]
→ Page B shows "Linked from: Page A"

Think of it like:

  • Citations in academic papers
  • "What links here" on Wikipedia
  • Incoming references

Location: Right sidebar panel on every page

What you see:

  • Title: "Backlinks"
  • Count: Number of linking pages
  • List: Each page that links here
  • Context: Snippet showing where link appears
  • Link: Click to navigate to linking page

Example display:

Backlinks (3)

📄 Getting Started Guide
Context: "...see [[Authentication]] for details..."

📄 API Reference
Context: "...using [[Authentication]] tokens..."

📄 Troubleshooting
Context: "...[[Authentication]] not working..."

Automatic tracking:

  1. You type [[Page Name]] on Page A
  2. Save the page (autosave)
  3. System extracts all wiki links
  4. Creates backlink entry in database
  5. Page Name now shows backlink from Page A

No manual work needed!

✅ Use wiki links for:

  • Related documentation pages
  • Concept definitions
  • Cross-references
  • Building knowledge base
  • Creating topic clusters

Example:

Authentication uses [[JWT Tokens]] and requires 
a [[User Account]]. See [[Security Best Practices]] 
for implementation guidelines.

❌ Don't use for:

  • External URLs (use regular links)
  • Non-page references
  • Repeated mentions on same page
  • Navigation (use page tree/favorites)

Link to Exact Page Names ​

Wiki links require exact page title match:

✅ Works: [[Getting Started Guide]] (if page title is exactly "Getting Started Guide")

❌ Doesn't work: [[Getting Started]] (if page title is "Getting Started Guide")

❌ Doesn't work: [[getting started guide]] (if title uses different case)

Tip: Copy-paste page titles for accuracy!

Common Patterns ​

Documentation Cross-References ​

# API Authentication

Our API uses OAuth 2.0. See [[OAuth Setup Guide]] 
for initial configuration.

For token management, refer to [[Token Lifecycle]].

Troubleshooting: [[Common Auth Errors]]

Result: Tightly connected documentation

Concept Definitions ​

# Product Overview

Our product implements [[Event-Driven Architecture]] 
using [[Message Queues]] and [[Microservices]].

Each concept is explained in detail on its linked page.

Result: Easy to drill into concepts

Meeting Notes References ​

# Team Meeting - Dec 12

## Topics Discussed
- Progress on [[Project Apollo]]
- Blockers in [[API Development]]
- Next steps for [[Q4 OKRs]]

## Action Items
- Review [[Architecture Proposal]]
- Update [[Sprint Backlog]]

Result: Meeting connected to all relevant pages

Building Knowledge Graphs ​

Start with a hub page:

# Engineering Docs

## Backend
- [[API Design Guidelines]]
- [[Database Schema]]
- [[Deployment Process]]

## Frontend
- [[Component Library]]
- [[State Management]]
- [[Build System]]

Then link between related pages:

In [[API Design Guidelines]]:
"For database interactions, see [[Database Schema]]"

In [[Database Schema]]:
"Follow [[API Design Guidelines]] for endpoint structure"

Result: Interconnected knowledge base

Discovering Connections ​

Use backlinks to:

  • Find related content
  • See who references your work
  • Understand page importance
  • Discover gaps in documentation

Example: If [[Authentication]] has 20 backlinks, it's a central concept!

Content Maintenance ​

Check backlinks when:

  • Updating a page (will affect all linking pages)
  • Deprecating a concept (update all referencing pages)
  • Renaming a page (links may break)

Building Context ​

Backlinks show:

  • How page fits in knowledge base
  • Related topics
  • Who's using this information
  • Connection to projects

Tips & Tricks ​

Don't be shy about linking:

  • More links = better connections
  • Helps readers discover related content
  • Builds robust knowledge base
  • Easy to do with [[syntax]]

Build index pages with many links:

# Backend Engineering Resources

- [[API Documentation]]
- [[Database Guide]]
- [[Deployment Runbook]]
- [[Troubleshooting Guide]]
- [[Architecture Decisions]]

Use Backlinks for Content Ideas ​

When a page has many backlinks:

  • It's a key concept
  • Consider expanding it
  • Maybe split into sub-topics
  • Link to those new pages

If backlinks show missing pages:

  • Create the referenced page
  • Or update the link to existing page
  • Maintain clean connections

Markdown Integration ​

Wiki links work alongside regular markdown:

Mix and match:
- Wiki link: [[Page Name]]
- Regular link: [Google](https://google.com)
- Bold: **emphasis**
- Code: `code snippet`

Example: See [[API Guide]] or visit [our website](https://example.com)

Current Limitations ​

Not yet available:

  • ❌ Autocomplete while typing [[
  • ❌ Link validation (shows if page exists)
  • ❌ Broken link detection
  • ❌ Link preview on hover
  • ❌ Create linked page if it doesn't exist
  • ❌ Rename pages with auto-update links

But you can:

  • ✅ Create wiki links manually
  • ✅ View backlinks in sidebar
  • ✅ Navigate via backlinks
  • ✅ See link context
  • ✅ Build connected content

Keyboard Shortcuts ​

ActionKeys
Start wiki linkType [[
Complete wiki linkType ]]
Navigate to linked pageClick link
Navigate to backlinkClick in backlinks panel

No special shortcuts - just type the syntax!

Troubleshooting ​

Check:

  • Exact page title match?
  • Page exists in your workspace?
  • Closed with ]]?
  • Not a typo?

Solution:

  • Copy exact page title
  • Paste between [[]]

Check:

  • Page has been saved (autosave complete)?
  • Links created on OTHER pages, not this one?
  • Give it a moment to update

Solution:

  • Wait for autosave (2 seconds)
  • Refresh page if needed

This is good! It means your page is:

  • Well-connected
  • Important concept
  • Frequently referenced

Consider:

  • Splitting into sub-topics
  • Creating overview page
  • Linking to more specific pages

Best Practices ​

✅ Do: Link to authoritative sources

See [[API Authentication Guide]] (the main guide)

❌ Don't: Link to random pages

See [[Notes from meeting where we talked about auth]]

If you significantly change a page:

  1. Check backlinks
  2. Visit linking pages
  3. Update context if needed
  4. Ensure links still make sense

Use Descriptive Page Titles ​

Makes linking easier: ✅ Good: [[User Authentication Setup Guide]] ❌ Bad: [[Doc 123]] or [[Page 5]]

Future Enhancements ​

Coming soon:

  • 🔍 Autocomplete dropdown
  • ✅ Link validation
  • 🔨 Auto-fix broken links
  • 👀 Hover previews
  • 📊 Link graph visualization
  • 🔄 Bulk link updates
  • ➕ Create missing pages on click

Related Guides: