Problem

Small documentation sites often start with a flat docs/ folder. As projects grow to include multiple modules, APIs, and conceptual deep-dives, a disorganised folder structure becomes a significant maintenance burden. Files become difficult to locate, and the navigation sidebar becomes an overwhelming “wall of links.”

Why it matters

A disorganised folder structure creates a confusing user experience, since docmd’s routing and default navigation are derived from your file system. For authors, a lack of clear structure leads to content duplication and inconsistent naming. This makes documentation harder to manage as more contributors join.

Approach

We recommend adopting an information architecture framework like Diátaxis. It separates content into four distinct categories: Tutorials, How-To Guides, Reference, and Explanation. Mapping these categories strictly to your physical file system provides a clear roadmap for both readers and authors.

Implementation

1. The Diátaxis Hierarchy

Organise your source directory into semantic subfolders. This physical isolation makes it easier to manage large sets of files and ensures a clean URL structure.

my-project/
├── docs/
│   ├── tutorials/           (Learning-oriented: step-by-step lessons)
│   │   └── getting-started.md
│   ├── guides/              (Task-oriented: solving specific problems)
│   │   └── deployment.md
│   ├── reference/           (Information-oriented: technical descriptions)
│   │   └── api-spec.md
│   ├── explanation/         (Understanding-oriented: theoretical background)
│   │   └── architecture.md
│   └── navigation.json      (Main navigation definition)
└── docmd.config.json

2. Strategic Use of navigation.json

Instead of defining a massive navigation tree in your global configuration, use navigation.json files within your source directories. docmd follows a Resolution Priority system. This allows you to define distinct sidebar hierarchies for different sections of your site.

// docs/navigation.json
[
  {
    "title": "Tutorials",
    "icon": "book-open",
    "children": [
      { "title": "Get Started", "path": "/tutorials/getting-started" }
    ]
  },
  {
    "title": "Reference",
    "icon": "braces",
    "children": [
      { "title": "API Specification", "path": "/reference/api-spec" }
    ]
  }
]

3. File-Based Routing

Every Markdown file’s location in the folder structure determines its final URL. For example, docs/guides/auth.md becomes your-site.com/guides/auth. Use this to your advantage to create intuitive, memorable URLs.

Trade-offs

Strict organisational frameworks like Diátaxis require a clear understanding of content types. Technical writers may occasionally find it difficult to categorise a specific document. Establishing clear internal contribution guidelines is essential to maintain consistency as your team grows.