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.
- Install dependencies:
composer install
- Create your configuration file at
configs/app.json
:
{
"templateRoot": "./templates",
"docsRoot": "./docs"
}
- 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)
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
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.
To generate a static version of the documentation for deployment:
php generate.php
This process will:
- Create or clean the
dist
directory - Convert all Markdown documentation to HTML
- Copy the template assets to
dist/public/assets
- Generate the documentation navigation structure
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.
The documentation system requires two main templates in your templates
directory:
doc.twig
- Template for documentation pages404.twig
- Documentation not found page
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.
- 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