DokuWiki Namespaces — Colon Syntax, Folder Mapping, and Structure Design

In this tutorial, you'll learn how DokuWiki namespaces work, how colons in page IDs map to folders on disk, how to design a namespace hierarchy, and how namespaces affect permissions and navigation.

What You'll Learn

• What namespaces are and why they matter
• How colons in page IDs map to directory paths
• Starting pages for namespaces
• Designing a namespace hierarchy
• How namespaces affect ACL permissions
• Cross-namespace linking and navigation

Why It Matters

Namespaces are the organizational backbone of DokuWiki. Unlike MediaWiki which uses category tags for organization, DokuWiki uses a hierarchical folder structure. Every page must live in exactly one namespace (or the root). A good namespace design makes your wiki easy to navigate, simplifies permissions, and keeps the file system organized. A bad design leads to orphaned pages, confusing navigation, and permission nightmares.

Real-World Use

A software company organizes its wiki into namespaces by department and project: engineering:product-a:api, engineering:product-a:deployment, engineering:product-b:api, marketing:campaigns, hr:policies. Each namespace has a start page that serves as a section index. ACL permissions grant the engineering team edit access to engineering:* and the marketing team edit access to marketing:*. New employees can immediately find all content related to their department.

Learning Path

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

What is a Namespace?

A namespace is a container for related pages. In DokuWiki, namespaces are represented as directories on the filesystem.

The root namespace (the top-level directory) is the default. All pages belong to the root namespace unless you specify otherwise.

Page IDs use colons to separate namespaces:

start                    # Root namespace
projects:roadmap         # "projects" namespace, "roadmap" page
projects:api:auth        # "projects:api" namespace, "auth" page

The colon in the page ID corresponds to the directory separator in the file path.

Colon to Folder Mapping

DokuWiki converts colons in page IDs to directory separators:

projects:api:authentication
        ↓
data/pages/projects/api/authentication.txt

Here is how different page IDs map to file paths:

This mapping is automatic — you do not need to create directories manually. When you create a page in a new namespace, DokuWiki creates the directories if they do not exist.

Namespace Start Pages

Each namespace can have a start page, which is the page displayed when someone navigates to the namespace without specifying a page:

http://yourserver/wiki/projects:

The trailing colon tells DokuWiki to load the start page of the projects namespace. The start page is start.txt within that namespace's directory.

The namespace start page is useful as a section index:

====== Projects ======

This section contains all project-related documentation.

----

=== Active Projects ===

  * [[projects:project-a|Project A]] — Q3 2026 release
  * [[projects:project-b|Project B]] — Q4 2026 release

=== Archived Projects ===

  * [[projects:project-z|Project Z]] — Completed

----

**Contributing**: See [[guides:project-setup|Project Setup Guide]] for guidelines on creating new project pages.

Links from the namespace start page to pages within the same namespace can use relative page IDs (just the page name without the namespace prefix).

Designing a Namespace Hierarchy

Good namespace design follows these principles:

Flat vs Deep Hierarchy

# Flat (good for small wikis)
projects:
team:
policies:
guides:

# Deep (use for large wikis with strict organization)
engineering:product-a:api:v2:
engineering:product-b:api:v2:
marketing:campaigns:2026:
marketing:campaigns:2026:q3:

For wikis with fewer than 500 pages, a flat or 2-level hierarchy works well. For larger wikis, 3-4 levels help organize content.

Naming Conventions

• Use lowercase names
• Use hyphens for multi-word namespaces (project-roadmap not project_roadmap)
• Keep names short but descriptive
• Use singular names for concept namespaces (guide not guides)
• Use plural for containers (projects not project)

Common Namespace Structures

By Department:

engineering:
  backend:
  frontend:
  devops:
marketing:
  campaigns:
  brand:
hr:
  policies:
  onboarding:

By Project:

project-alpha:
  requirements:
  development:
  testing:
  deployment:
project-beta:
  requirements:
  development:
  testing:

By Content Type:

guides:
  installation:
  configuration:
  troubleshooting:
reference:
  api:
  commands:
  configuration-options:

Namespaces and Links

When linking between pages in the same namespace, you can use relative links:

[[pagename]]           # Links to pagename in current namespace
[[:pagename]]           # Links to pagename in root namespace
[[../sibling]]          # Links to sibling in parent namespace (not standard DokuWiki)

Relative linking keeps your wiki portable — if you move an entire namespace, internal links still work.

To link from one namespace to a page in another namespace, use the full page ID:

[[projects:roadmap|View the project roadmap]]
[[team:start|Team page]]

Namespaces and ACL

One of the most powerful features of namespaces is that ACL permissions can be set per namespace. This allows you to create private areas within a public wiki:

# conf/acl.auth.php
*                       @ALL          @1     # Everyone can read
*                       @user         @8     # Users can edit
@projects               @admin        @16    # Only admins edit projects namespace
@hr:policies            @hr-team      @16    # Only HR team edits HR policies

You will learn more about ACL in Lesson 15. For now, understand that namespace is the primary unit of permission management.

Namespaces and Navigation

The sidebar and navigation tree reflect the namespace structure. When you create a new namespace, it appears in the navigation tree automatically (if the navigation tree is enabled).

Common Mistakes

1. Creating too many top-level namespaces: 30 top-level namespaces make the navigation tree unusable. Group related content into 5-8 top-level namespaces with sub-namespaces.
2. Mixing content types in one namespace: Having installation guides, API docs, and team meeting notes all in the root namespace defeats the purpose of organization.
3. Using deeply nested namespaces unnecessarily: Namespaces 5+ levels deep are hard to navigate and create long page IDs. Aim for 2-3 levels maximum.
4. Forgetting the start page: Each namespace should have a start page as an index. Without it, the namespace has no landing page.
5. Changing namespace structure after content is created: Moving pages between namespaces is possible but labor-intensive. Plan your namespace structure before creating content at scale.

Practice Questions

1. How does DokuWiki map the page ID engineering:backend:api:authentication to the file system?
2. What is the purpose of a namespace start page, and what page ID does it use?
3. How do namespaces affect ACL permissions, and why is this useful for team wikis?
4. Challenge: Design a namespace hierarchy for a medium-sized wiki (approximately 200 pages) for a software development company with: 3 product teams, a marketing department, an HR department, an internal IT team, and a company-wide knowledge base. Each product team needs space for API docs, deployment guides, and meeting notes. The HR namespace must be restricted to HR team members only. Draw the namespace tree and explain the rationale for each design decision.

FAQ

Mini Project

Goal: Design and implement a namespace hierarchy for a wiki.

1. Plan a namespace structure with at least 5 top-level namespaces and 2 levels of nesting
2. Create the structure by creating a start page for each namespace
3. Add a brief description to each namespace start page explaining what content belongs there
4. Create at least 2 actual content pages in two different namespaces
5. Add cross-namespace links between pages
6. Verify that the navigation tree shows all namespaces correctly
7. Write a brief document explaining your namespace design and the reasoning behind it

What's Next

Now you understand namespace structure. Learn how to manage namespaces including moving pages, renaming, and namespace-level permissions.