Filesystem Architecture

Your content organization defines your site structure. This guide outlines best practices for building scalable, maintainable Wordless sites.

Project Structure

wordless-site/
  ├── public/              (webroot)
  │   ├── index.php        (entry point)
  │   ├── .htaccess        (routing rules)
  │   └── assets/
  │       ├── css/
  │       ├── js/
  │       └── img/
  ├── content/             (all site content)
  │   ├── index.php        (homepage)
  │   ├── about.php
  │   ├── en/              (English section)
  │   │   ├── index.php
  │   │   ├── features/
  │   │   └── blog/
  │   ├── es/              (Spanish section)
  │   │   ├── index.php
  │   │   └── blog/
  │   └── docs/            (documentation)
  ├── templates/           (view files)
  │   ├── layouts/
  │   │   └── base.php
  │   ├── partials/
  │   └── page.php
  ├── app/                 (application code)
  ├── bootstrap/           (initialization)
  └── storage/             (cache, logs)

Naming Conventions

File Names

Use lowercase, hyphenated names for all files:

Folder Names

Use lowercase, plural names for folders containing multiple items:

Content Organization Patterns

Pattern 1: Section-Based Organization

content/
  en/
    blog/
      index.php          (listing page)
      post-one.php
      post-two.php
    docs/
      index.php
      getting-started.php
      deployment.php

Best for: Sites with clear sections (blog, documentation, resources).

Pattern 2: Date-Based Organization

content/
  blog/
    2026/
      index.php          (year archive)
      may/
        index.php        (month archive)
        05-hello-world.php
      june/
        12-new-features.php

Best for: High-volume blogs that need year/month/day organization.

Pattern 3: Flat Organization

content/
  index.php
  about.php
  contact.php
  privacy.php
  terms.php

Best for: Simple sites with a few pages.

Pattern 4: Hybrid Organization

Mix patterns as your site grows:

content/
  index.php
  about.php
  en/
    features/
    blog/
  es/
    features/
    blog/
  docs/
    guides/
    api/

Metadata Strategy

Always Define Title and Description

These are critical for SEO and user experience:

<?php $meta = [
    'title'       => 'Getting Started with Wordless',
    'description' => 'A complete guide to setting up your first Wordless site',
    'date'        => '2026-05-05',
]; ?>

Use Inheritance for Common Metadata

Define metadata once in folder index.php files:

// content/blog/index.php
<?php $meta = [
    'layout' => 'blog',
    'type'   => 'blog',
]; ?>

// All blog posts automatically inherit these

Scaling Strategies

For Growing Content

As your site grows, move into folders and index pages:

// Before (simple)
content/guides/getting-started.php

// After (scalable)
content/guides/
  index.php (listing)
  getting-started/
    index.php
    installation.php
    configuration.php

For Multiple Languages

Keep language folders at the root for clarity:

content/
  en/  (all English content)
  es/  (all Spanish content)
  fr/  (all French content)

For Multiple Sites

If deploying multiple Wordless sites, keep them in separate folders or repositories.

Best Practices

• Use descriptive names: Filenames should hint at content
• Avoid deep nesting: 4-5 levels maximum keeps URLs readable
• Use index.php for folders: Makes those URLs available
• Group related content: Semantic folder names improve maintainability
• Keep slugs consistent: Use the same slug across language variants
• Version control everything: Content is code in Wordless

Performance Considerations

• Filesystem is fast: PHP's file operations are optimized
• Use caching middleware: Cache rendered pages to avoid repeated parsing
• Minimize recursive scans: all('path') with a specific path is faster than all()

← Back to Features