Skip to content

Organizing Content

Best practices for structuring and organizing your wiki content.

Content Architecture

Information Hierarchy

Structure your content in a logical hierarchy:

Home
├── Getting Started (for beginners)
│   ├── Installation
│   ├── Quick Start
│   └── Basic Concepts
├── User Guides (how-to content)
│   ├── Creating Content
│   ├── Managing Pages
│   └── Advanced Features
├── Reference (technical details)
│   ├── Configuration
│   ├── API Documentation
│   └── Glossary
└── Resources (additional materials)
    ├── Examples
    ├── Templates
    └── FAQ

Directory Structure

Mirror your navigation in the file system:

docs/
├── index.md                    # Home page
├── getting-started/
│   ├── index.md               # Section overview
│   ├── installation.md
│   ├── quick-start.md
│   └── basic-concepts.md
├── guides/
│   ├── index.md
│   ├── creating-content.md
│   ├── managing-pages.md
│   └── advanced-features.md
├── reference/
│   ├── index.md
│   ├── configuration.md
│   ├── api/
│   │   ├── index.md
│   │   ├── endpoints.md
│   │   └── authentication.md
│   └── glossary.md
└── assets/
    ├── images/
    ├── videos/
    └── downloads/

Flat vs. Deep Navigation

nav:
  - Home: index.md
  - Installation: installation.md
  - Configuration: configuration.md
  - API Reference: api.md
  - FAQ: faq.md

Deep Navigation (Better for large wikis)

nav:
  - Home: index.md
  - Getting Started:
    - getting-started/index.md
    - Installation: getting-started/installation.md
    - First Steps: getting-started/first-steps.md
  - User Guide:
    - guides/index.md
    - Basics:
      - Creating Pages: guides/basics/pages.md
      - Navigation: guides/basics/navigation.md
    - Advanced:
      - Customization: guides/advanced/customization.md
      - Plugins: guides/advanced/plugins.md

Progressive Disclosure

Start simple, reveal complexity gradually:

nav:
  - Home: index.md
  - Quick Start: quick-start.md  # Simple entry point
  - Guides:                      # More detailed content
    - guides/index.md
    - Basic Usage: guides/basic.md
    - Advanced Usage: guides/advanced.md
  - Reference:                   # Complete documentation
    - reference/index.md
    - All Features: reference/features.md

Task-Based Navigation

Organize by what users want to do:

nav:
  - Home: index.md
  - How to:
    - Create a Page: how-to/create-page.md
    - Add Images: how-to/add-images.md
    - Deploy Wiki: how-to/deploy.md
  - Concepts:
    - Understanding Markdown: concepts/markdown.md
    - Site Structure: concepts/structure.md

Content Types

1. Landing Pages

Section overview pages (index.md in each directory):

# User Guides

Learn how to use all features of U.WIKI.

## Getting Started
- [Creating Your First Page](creating-pages.md)
- [Basic Markdown Syntax](markdown-basics.md)

## Advanced Topics
- [Custom Themes](themes.md)
- [Plugins and Extensions](plugins.md)

## Need Help?
Check our [FAQ](../faq.md) or [contact support](../support.md).

2. Tutorial Pages

Step-by-step instructions:

# How to Add a Search Function

## Prerequisites
- Basic understanding of configuration
- Admin access to mkdocs.yml

## Steps

### 1. Enable the search plugin
[Detailed steps...]

### 2. Configure search options
[More steps...]

## Next Steps
- [Customize search appearance](search-styling.md)
- [Add search analytics](search-analytics.md)

3. Reference Pages

Technical documentation:

# Configuration Reference

## Site Settings

### `site_name`
- **Type**: String
- **Required**: Yes
- **Default**: None
- **Description**: The name of your wiki

### `site_url`
- **Type**: String (URL)
- **Required**: For deployment
- **Default**: None
- **Description**: The canonical URL of your site

4. Concept Pages

Explanatory content:

# Understanding Static Site Generation

## What is a Static Site?

A static site consists of pre-built HTML files...

## Benefits

1. **Performance**: No server-side processing
2. **Security**: No database to hack
3. **Simplicity**: Just files on a server

## How MkDocs Works

[Explanation with diagrams...]

Cross-Referencing

Always use relative paths:

<!-- Good -->
See the [installation guide](../getting-started/installation.md)

<!-- Avoid -->
See the [installation guide](https://wiki.com/getting-started/installation)

Hub Pages

Create central pages that link to related content:

# Markdown Resources

Everything you need to know about Markdown:

- **Basics**: [Syntax Guide](markdown-syntax.md)
- **Advanced**: [Extended Syntax](markdown-extended.md)
- **Examples**: [Real-world Examples](markdown-examples.md)
- **Tools**: [Markdown Editors](markdown-editors.md)

Add "See Also" sections:

## See Also

- [Configuration Guide](../configuration.md)
- [Deployment Options](../deployment.md)
- [Troubleshooting](../troubleshooting.md)

Metadata and Tagging

Page Metadata

Use front matter for organization:

---
title: Advanced Configuration
category: reference
tags:
  - configuration
  - advanced
  - admin
difficulty: advanced
updated: 2024-12-16
---

Tag Pages

Create tag index pages:

# Pages Tagged "configuration"

- [Basic Configuration](../getting-started/configuration.md)
- [Advanced Configuration](../reference/advanced-config.md)
- [Plugin Configuration](../guides/plugin-config.md)

Search Optimization

Page Titles

Make titles descriptive and searchable:

<!-- Good -->
# How to Configure Email Notifications in U.WIKI

<!-- Less Good -->
# Email Setup

Headers Structure

Use headers to create searchable sections:

# Email Configuration

## SMTP Settings
Details about SMTP...

## Email Templates
How to customize templates...

## Troubleshooting Email Issues
Common problems and solutions...

Keywords

Include relevant keywords naturally:

This guide explains how to configure email notifications
in U.WIKI. Email alerts can be sent for various events...

Maintenance

Regular Reviews

  1. Monthly: Check for broken links
  2. Quarterly: Review and update outdated content
  3. Yearly: Restructure navigation based on usage

Version Control

Track changes effectively:

# Good commit messages
git commit -m "Add troubleshooting section to email config guide"
git commit -m "Reorganize navigation - group API docs together"

# Less helpful
git commit -m "Update docs"

Redirects

When moving pages, set up redirects:

plugins:
  - redirects:
      redirect_maps:
        'old-page.md': 'new-location/new-page.md'

Best Practices

1. Consistent Naming

  • Use lowercase
  • Replace spaces with hyphens
  • Be descriptive
✅ how-to-create-custom-themes.md
❌ theme_creation.md

2. Logical Grouping

Group related content together:

guides/
├── themes/
│   ├── choosing-themes.md
│   ├── customizing-themes.md
│   └── creating-themes.md

3. Avoid Deep Nesting

Limit to 3-4 levels maximum:

✅ docs/guides/advanced/plugins.md
❌ docs/guides/advanced/customization/themes/colors/palettes.md

4. User-Centric Organization

Organize by user needs, not technical structure:

✅ how-to/add-users.md
❌ admin/user-management/creation.md

Templates

Section Index Template

# [Section Name]

Brief description of this section.

## In This Section

### Getting Started
- [First Article](first-article.md) - Brief description
- [Second Article](second-article.md) - Brief description

### Advanced Topics
- [Advanced Article](advanced-article.md) - Brief description

## Related Sections
- [Related Section 1](../related1/index.md)
- [Related Section 2](../related2/index.md)

## Need Help?
Can't find what you're looking for? Try:
- Using the search bar above
- Checking our [FAQ](../faq.md)
- [Contacting support](../support.md)

Next Steps