File Structure

OI Laravel Documentation uses a hierarchical file-based structure that automatically generates navigation. Understanding this structure is key to organizing your documentation effectively.

Directory Layout

Your documentation lives in resources/markdown/docs/ (configurable) and follows this pattern:

resources/markdown/docs/
├── meta.json                          # Root metadata
├── getting-started/
│   ├── meta.json                      # Section metadata
│   ├── _index.md                      # Section homepage
│   ├── installation.md
│   └── configuration.md
├── configuration/
│   ├── meta.json
│   ├── _index.md
│   ├── basic-setup.md
│   └── advanced-options.md
├── guides/
│   ├── meta.json
│   ├── _index.md
│   ├── common-tasks/
│   │   ├── meta.json                  # Subsection metadata
│   │   ├── _index.md
│   │   └── working-with-data.md
│   └── troubleshooting/
│       ├── meta.json
│       ├── _index.md
│       └── common-issues.md
└── api-reference/
    ├── meta.json
    ├── _index.md
    └── endpoints.md

Required Files

Root meta.json

The root docs/meta.json defines your documentation package:

{
    "type": "package",
    "name": "my-package-name",
    "title": "Documentation Title",
    "description": "Short description",
    "version": "1.0.0"
}

Fields:

• type - Always "package" (used for package imports)
• name - Package identifier (vendor/package format recommended)
• title - Display name
• description - Short summary
• version - Documentation version (optional)

This file is not shown in navigation but provides metadata for the entire documentation set.

Section meta.json

Each section folder requires a meta.json:

{
    "type": "section",
    "title": "Getting Started",
    "description": "Installation and setup guide",
    "order": 1
}

Fields:

• type - Always "section"
• title - Section display name
• description - Section description (shown in navigation)
• order - Sort order (lower numbers appear first)

Without meta.json, a section is skipped with a warning in console output.

The _index.md Pattern

The _index.md file in each section serves as the section's homepage:

getting-started/
├── meta.json
├── _index.md          # This is the section homepage
├── installation.md
└── configuration.md

When you navigate to /documentation/getting-started, you're viewing _index.md.

The URL structure follows folder nesting:

• getting-started/_index.md → /documentation/getting-started
• guides/common-tasks/_index.md → /documentation/guides/common-tasks
• getting-started/installation.md → /documentation/getting-started/installation

Nested Sections

You can nest sections to any depth. Each level requires its own meta.json:

guides/
├── meta.json                      # Section
├── _index.md
├── common-tasks/
│   ├── meta.json                  # Subsection
│   ├── _index.md
│   └── working-with-data.md
├── advanced/
│   ├── meta.json
│   ├── _index.md
│   ├── caching/
│   │   ├── meta.json              # Sub-subsection
│   │   ├── _index.md
│   │   └── strategies.md
│   └── optimization.md
└── troubleshooting/
    ├── meta.json
    ├── _index.md
    └── common-issues.md

This creates a navigation tree:

• Guides
  • Common Tasks
    • Working with Data
  • Advanced
    • Caching
      • Strategies
    • Optimization
  • Troubleshooting
    • Common Issues

Naming Conventions

File Naming

Use lowercase filenames with hyphens:

✓ getting-started.md
✓ installation-steps.md
✗ GettingStarted.md
✗ Installation_Steps.md

Section Naming

Section folder names match the URL path and should be descriptive:

✓ getting-started/
✓ configuration/
✓ api-reference/
✗ getting-started-guide/      (Too verbose)
✗ config/                       (Too ambiguous)

Ordering Files

Use numerical prefixes for strict ordering (optional):

01-installation.md
02-configuration.md
03-usage.md

Or specify order in frontmatter:

---
title: Installation
order: 1
---

Both methods work—use whichever you prefer.

Auto-Generation Files

The package automatically generates two JSON files. Never edit these manually—they're regenerated by commands:

navigation.json

Auto-generated by doc:gen-nav:

{
    "sections": [
        {
            "title": "Getting Started",
            "slug": "getting-started",
            "description": "Installation and setup",
            "order": 1,
            "pages": [
                {
                    "title": "Introduction",
                    "slug": "getting-started",
                    "url": "/documentation/getting-started"
                },
                {
                    "title": "Installation",
                    "slug": "installation",
                    "url": "/documentation/getting-started/installation"
                }
            ]
        }
    ]
}

search-index.json

Auto-generated by doc:gen-index:

{
    "documents": [
        {
            "id": "getting-started",
            "title": "Getting Started",
            "section": "Getting Started",
            "description": "Installation and setup",
            "url": "/documentation/getting-started",
            "content": "...",
            "headings": ["Installation", "Configuration"],
            "score": 0
        }
    ]
}

Organizing Large Documentation

By Feature

Organize documentation around features:

features/
├── authentication/
├── authorization/
├── payments/
└── notifications/

By Audience

Organize for different users:

docs/
├── user-guide/
├── developer-guide/
├── api-reference/
└── admin-manual/

By Topic

Group related topics:

docs/
├── getting-started/
├── core-concepts/
├── tutorials/
├── how-to-guides/
├── reference/
└── troubleshooting/

Regenerating Navigation

After adding, removing, or renaming files or folders, regenerate navigation:

php artisan doc:gen-nav

After content changes, regenerate search index:

php artisan doc:gen-index

Or both:

php artisan doc:gen-nav && php artisan doc:gen-index

Best Practices

1. Always include meta.json in sections - Prevents warnings and ensures proper ordering
2. Use _index.md for section homes - Makes section landing pages consistent
3. Keep folder depth reasonable - Maximum 3-4 levels is typical
4. Use descriptive names - File names should indicate content
5. Group related pages - Keep similar topics in the same section
6. Regenerate after changes - Always run generation commands after file changes
7. Test navigation - Visit your docs to ensure structure is correct

Common Mistakes

Missing meta.json in a section:

⚠ Section "guides" has no meta.json and will be skipped

Using capital letters in folder names:

❌ GettingStarted/  → URL becomes /documentation/GettingStarted
✓ getting-started/  → URL becomes /documentation/getting-started

Not regenerating navigation:

New files appear in filesystem but not in navigation menu.
Solution: Run `php artisan doc:gen-nav`

Forgetting _index.md:

Section exists but has no homepage. Create docs/section/_index.md.