PHPNomad Documentation System

This is the documentation system for PHPNomad. It converts Markdown documentation files into a static website, providing both a development environment for writing documentation and a static site generator for production deployment.

Setup

1. Install dependencies:

composer install

2. Create your configuration file at configs/app.json:

{
"templateRoot": "./templates",
"docsRoot": "./docs"
}

3. Ensure your documentation directory structure is in place:

.
├── configs/
│ └── app.json
├── docs/ # Your PHPNomad documentation in Markdown
├── templates/ # Documentation site templates
│ └── assets/ # CSS, JS, and other assets
└── dist/ # Generated static documentation (created automatically)

Writing Documentation

Place your Markdown documentation files in the docs directory. The file structure determines the URL structure of your documentation:

docs/
├── index.md # Landing page at /
├── getting-started.md # /getting-started
└── core/
├── index.md # /core
├── container.md # /core/container
└── events.md # /core/events

Development Server

While writing documentation, you can run a local development server that provides live updates:

php -S localhost:8080 index.php

This will serve your documentation at http://localhost:8080. Changes to your Markdown files will be reflected immediately upon page refresh.

Generating Static Documentation

To generate a static version of the documentation for deployment:

php generate.php

This process will:

1. Create or clean the dist directory
2. Convert all Markdown documentation to HTML
3. Copy the template assets to dist/public/assets
4. Generate the documentation navigation structure

Testing Static Generation

After generating the static documentation, you can verify it:

cd dist
php -S localhost:8081

Visit http://localhost:8081 to review the generated static documentation.

Template Structure

The documentation system requires two main templates in your templates directory:

• doc.twig - Template for documentation pages
• 404.twig - Documentation not found page

Assets

Place your documentation site's assets (CSS, JavaScript, images) in templates/assets. These will be automatically copied to dist/public/assets during static site generation.

Features

• Markdown to HTML conversion with GitHub Flavored Markdown support
• Automatic documentation navigation generation based on file structure
• Development server with live updates
• Static site generation for production deployment
• Asset management