File Structure
Learn how to organize your documentation files for maximum clarity and maintainability.
Basic Structure
resources/docs/
├── index.md # Homepage (/docs)
├── getting-started.md # /docs/getting-started
├── features.md # /docs/features
└── includes/
└── common-info.md # Reusable snippet
Nested Directories
Create subdirectories to organize related content:
resources/docs/
├── index.md
├── getting-started.md
├── guides/
│ ├── installation.md # /docs/guides/installation
│ ├── configuration.md # /docs/guides/configuration
│ └── deployment.md # /docs/guides/deployment
├── api/
│ ├── authentication.md # /docs/api/authentication
│ ├── endpoints.md # /docs/api/endpoints
│ └── webhooks.md # /docs/api/webhooks
├── tutorials/
│ ├── beginner/
│ │ ├── first-steps.md # /docs/tutorials/beginner/first-steps
│ │ └── basic-concepts.md
│ └── advanced/
│ ├── optimization.md # /docs/tutorials/advanced/optimization
│ └── best-practices.md
└── includes/
├── requirements.md
├── installation-steps.md
└── common-warnings.md
The includes/ Directory
Store reusable content snippets here:
resources/docs/includes/
├── installation.md # ## Installation
To install this application:
```bash
git clone your-repository-url
cd your-project
composer install
npm install && npm run build
php artisan migrate
This content is reusable across multiple documentation pages using the include system.
├── common-info.md # This is a reusable snippet that can be included in multiple documentation pages. It demonstrates the single-sourcing capability - update once, reflect everywhere!
You can include any Markdown content here, such as:
- Lists
- Code blocks
- Links
- And more!
├── system-requirements.md # ## System Requirements
- PHP 8.2 or higher
- MySQL 8.0+ or PostgreSQL 13+
- Composer 2.x
- Node.js 18+ and NPM
- 2GB RAM minimum
- 10GB disk space
├── support-info.md # [Include not found: support-info] └── legal-disclaimer.md # [Include not found: legal-disclaimer]
<div class="note">Files in includes/ are not directly accessible as pages. They can only be used via the include shortcode.</div>
## File Naming Conventions
### Do's ✅
getting-started.md # Clear, descriptive api-authentication.md # Hyphenated user-management-guide.md # Multi-word with hyphens troubleshooting-common-errors.md # Descriptive name
### Don'ts ❌
GettingStarted.md # Don't use PascalCase getting_started.md # Avoid underscores gs.md # Too abbreviated getting started.md # No spaces api-auth.md # Avoid abbreviations
## URL Mapping
File paths map directly to URLs:
| File Path | URL |
|-----------|-----|
| `index.md` | `/docs` or `/docs/index` |
| `getting-started.md` | `/docs/getting-started` |
| `api/endpoints.md` | `/docs/api/endpoints` |
| `guides/installation.md` | `/docs/guides/installation` |
| `tutorials/advanced/optimization.md` | `/docs/tutorials/advanced/optimization` |
## Organizing by Type
### By Topic (Recommended)
resources/docs/ ├── authentication/ │ ├── overview.md │ ├── login.md │ ├── registration.md │ └── password-reset.md ├── user-management/ │ ├── creating-users.md │ ├── editing-users.md │ └── deleting-users.md └── reporting/ ├── generating-reports.md └── exporting-data.md
### By Audience
resources/docs/ ├── end-users/ │ ├── getting-started.md │ ├── basic-tasks.md │ └── troubleshooting.md ├── developers/ │ ├── api-reference.md │ ├── webhooks.md │ └── sdk-guide.md └── administrators/ ├── installation.md ├── configuration.md └── maintenance.md
### By Task
resources/docs/ ├── installation/ │ ├── requirements.md │ ├── step-by-step.md │ └── troubleshooting.md ├── configuration/ │ ├── basic-setup.md │ ├── advanced-options.md │ └── environment-variables.md └── usage/ ├── daily-tasks.md ├── reports.md └── integrations.md
## Large Documentation Sites
For very large sites, use deeper nesting:
resources/docs/ ├── index.md ├── getting-started/ │ ├── index.md # Overview page │ ├── installation.md │ ├── quick-start.md │ └── hello-world.md ├── fundamentals/ │ ├── index.md │ ├── concepts/ │ │ ├── architecture.md │ │ ├── components.md │ │ └── lifecycle.md │ ├── routing/ │ │ ├── basic-routing.md │ │ └── route-parameters.md │ └── views/ │ ├── creating-views.md │ └── passing-data.md ├── advanced/ │ ├── index.md │ ├── performance/ │ │ ├── optimization.md │ │ ├── caching.md │ │ └── profiling.md │ └── security/ │ ├── authentication.md │ └── authorization.md └── reference/ ├── api/ │ ├── classes.md │ └── methods.md └── config/ └── options.md
## Special Files
### index.md
- Homepage of documentation: `/docs`
- Can exist in subdirectories as section homepages
- Should provide overview and navigation to sub-pages
**Example:**
resources/docs/api/index.md # /docs/api (API section homepage)
## Version-Specific Documentation
You can organize by version:
resources/docs/ ├── index.md # Latest version ├── v2/ │ ├── getting-started.md │ ├── api.md │ └── changelog.md └── v1/ ├── getting-started.md ├── api.md └── changelog.md
Access: `/docs/v2/getting-started`, `/docs/v1/api`
## Images and Assets
Store images separately from markdown:
public/images/docs/ ├── getting-started/ │ ├── screenshot1.png │ └── screenshot2.png ├── features/ │ └── feature-overview.png └── diagrams/ ├── architecture.svg └── workflow.svg
Reference in markdown:
```markdown
Real-World Example
Complete structure for a SaaS application:
resources/docs/
├── index.md
├── getting-started.md
├── pricing.md
├── changelog.md
│
├── guides/
│ ├── account-setup.md
│ ├── inviting-users.md
│ ├── billing.md
│ └── integrations.md
│
├── features/
│ ├── dashboard.md
│ ├── reports.md
│ ├── analytics.md
│ └── notifications.md
│
├── api/
│ ├── overview.md
│ ├── authentication.md
│ ├── rate-limits.md
│ ├── endpoints/
│ │ ├── users.md
│ │ ├── projects.md
│ │ └── webhooks.md
│ └── examples/
│ ├── curl.md
│ ├── javascript.md
│ └── php.md
│
├── troubleshooting/
│ ├── common-issues.md
│ ├── error-codes.md
│ └── support.md
│
└── includes/
├── api-headers.md
├── authentication-note.md
├── rate-limit-info.md
└── support-contact.md
Tips for Organization
- Start Simple: Begin with flat structure, add nesting as needed
- Consistent Naming: Use consistent patterns throughout
- Index Pages: Add index.md to subdirectories for overviews
- Related Content: Keep related topics together
- Logical Flow: Order pages by user journey
- Search-Friendly: Use descriptive, keyword-rich filenames