DokuWiki Sidebar and Navigation — Custom Sidebars, Breadcrumbs, and Menus

In this tutorial, you'll learn how to customize the DokuWiki sidebar, configure breadcrumb navigation, build custom navigation menus, and use DokuWiki's built-in navigation features to help users find content.

What You'll Learn

• What the sidebar is and how it works
• Creating and editing sidebar content
• Adding navigation links to the sidebar
• Configuring breadcrumb trails
• Understanding DokuWiki's navigation hierarchy
• Custom navigation menus for specific namespaces
• Hiding or modifying the sidebar

Why It Matters

The sidebar is the primary navigation tool in DokuWiki. It appears on every page and gives users constant access to important links. A well-designed sidebar reduces the need for users to search or remember URLs. Poor sidebar design — or no sidebar at all — makes a wiki hard to navigate, especially for new users.

Real-World Use

A company wiki has a sidebar with links to: the start page, recent changes, a manual table of contents (TOC), quick links to the most-used sections (HR policies, IT support, project management), and a search box. New employees learn to look at the sidebar first when they need to find anything. The sidebar is part of the company onboarding documentation.

Learning Path

flowchart LR
  A[Media Management] --> B[Sidebar]
  B --> C[Namespaces]
  C --> D[Namespace Management]
  D --> E[Page Revisions]
  E --> F[Search]

What is the Sidebar?

The sidebar is a vertical panel on the left side of every DokuWiki page. It contains dynamic elements (navigation tree, search box) and static content defined by the wiki administrator.

The sidebar content is stored in the page sidebar at namespace root. Its file is data/pages/sidebar.txt.

Creating the Sidebar

To create or edit the sidebar:

1. Navigate to http://yourserver/wiki/sidebar
2. If it does not exist, click "Create this page"
3. Write your sidebar content using normal DokuWiki syntax
4. Save

The sidebar appears on all pages immediately after creation.

Basic Sidebar Template

====== Navigation ======

  * [[start|Home]]
  * [[wiki:syntax|Syntax Reference]]
  * [[recent|Recent Changes]]
  * [[index|Site Map]]

----

====== Quick Links ======

  * [[projects:start|Projects]]
  * [[team:start|Team]]
  * [[guides:start|User Guides]]

----

**Search**

{{search>}}

The `{{search>}}` tag embeds the search form in the sidebar.

## Sidebar Content Best Practices

- **Keep it short**: The sidebar should fit on screen without scrolling. Use links to sub-pages rather than listing every page.
- **Use headings sparingly**: One or two section headings break up the sidebar visually.
- **Prioritize by usage**: Put the most-used links at the top.
- **Group related links**: Use bullet lists to group similar items (e.g., all project links, all reference links).
- **Include the start page**: Always link back to the start page from the sidebar.

## The Navigation Tree

DokuWiki can automatically generate a navigation tree showing the page hierarchy. To enable it, add to `conf/local.php`:

```php
<?php
$conf['sidebar'] = 'sidebar';

The default template includes a tree view of the namespace hierarchy. The tree is dynamically generated from the page structure.

Breadcrumbs

Breadcrumbs show the path from the start page to the current page. They appear at the top of the content area.

Enabling Breadcrumbs

Breadcrumbs are enabled by default. To configure them:

<?php
// conf/local.php
$conf['breadcrumbs'] = 5;     // Number of breadcrumb trail items (0 to disable)
$conf['youarehere'] = 1;      // Show "You are here" navigation

Breadcrumb Trail

The breadcrumb trail shows the last N pages you visited. It is session-based — each user sees their own trail.

Home > Projects > Roadmap > Current Page

You Are Here Navigation

The "You are here" navigation shows the current page's position in the namespace hierarchy:

You are here: Start > Projects > Roadmap

This is based on the namespace structure, not browsing history.

Custom Navigation Menus

For wikis with complex structures, you may want different navigation for different sections.

Namespace-Specific Sidebars

You can create a sidebar for a specific namespace by creating a page called sidebar in that namespace:

data/pages/
└── projects/
    └── sidebar.txt    # Sidebar for pages in the projects namespace

When a user views any page in the projects namespace, DokuWiki looks for projects:sidebar first. If it exists, it is shown instead of the root sidebar.

Navigation Page

Create a dedicated navigation page and include it in the sidebar using the INCLUDE syntax:

====== Navigation ======

~~INCLUDE:nav:main-menu~~

Links to sub-menus:
  * [[nav:projects-menu|Projects]]
  * [[nav:team-menu|Team]]

Then create each sub-menu as a separate page for easier maintenance.

Hiding the Sidebar

You can hide the sidebar on specific pages by adding this line anywhere in the page content:

~~NOSIDEBAR~~

This is useful for pages that need full-width content, such as embedded dashboards or wide tables.

To hide the sidebar globally, set in conf/local.php:

<?php
$conf['sidebar'] = '';

Sidebar Layout Tips

Using Horizontal Rules

Separate sections with horizontal rules (----) to create visual breathing room.

Using Icons

Some templates support small icons next to links. The default template does not include icons, but you can add them using the image syntax:

{{:home-icon.png?12}} [[start|Home]]

Combining Static and Dynamic Content

Mix manually written links with dynamic elements:

====== Quick Links ======

  * [[start|Home]]
  * [[recent|Recent Changes]]

----

====== Navigation Tree ======

{{tree>}}

----

{{search>}}

The {{tree>}} tag displays the automatic page tree, and {{search>}} shows the search box.

Common Mistakes

1. Making the sidebar too long: A sidebar with 30 links forces users to scroll past navigation to reach page content. Limit to 10-15 links and use nesting for sub-pages.
2. Not updating the sidebar when pages change: If you rename or delete a page, update the sidebar links immediately. Broken sidebar links create a poor user experience.
3. Confusing page IDs with display text: [[start|Home]] links to the start page but shows "Home" as the display text. Using [[start]] shows the page ID as the text, which may not be user-friendly.
4. Removing the search box: Even with excellent navigation, users need search. Always include {{search>}} in the sidebar.
5. Using stale breadcrumb configuration: If breadcrumbs show "0 items" or behave unexpectedly, check the $conf['breadcrumbs'] setting in local.php.

Practice Questions

1. What file stores the sidebar content, and what happens if it does not exist?
2. How do you create a namespace-specific sidebar that appears only when browsing pages in that namespace?
3. What is the difference between the breadcrumb trail and the "You are here" navigation?
4. Challenge: Design a complete navigation system for a wiki with 5 namespaces (Projects, Team, Guides, Policies, Reference). Create a root sidebar with general links. Create namespace-specific sidebars for each namespace. Configure breadcrumbs to show 5 items. Add the search box to the sidebar. Create a custom navigation menu page that is included in the sidebar. Test that the correct sidebar appears for pages in each namespace.

FAQ

Mini Project

Goal: Build a complete navigation system for your wiki.

1. Create a root sidebar with: a "Home" link, a "Quick Links" section with 4 links, a "Documentation" section with 3 links, a horizontal rule, and the search box
2. Create a namespace-specific sidebar for one namespace (e.g., projects:sidebar) with project-specific links
3. Configure breadcrumbs to show 5 items: open conf/local.php and set $conf['breadcrumbs'] = 5
4. Test that navigating between namespaces shows the correct sidebar
5. Add the ~~NOSIDEBAR~~ tag to one page and verify the sidebar disappears on that page
6. Document your navigation design decisions

What's Next

Now users can navigate your wiki. Learn about namespaces to understand how DokuWiki organizes content into hierarchical groups.