saggre / phpdocumentor-markdown
Markdown template for phpDocumentor3
Installs: 47 418
Dependents: 22
Suggesters: 0
Security: 0
Stars: 18
Watchers: 2
Forks: 8
Open Issues: 3
Language:Twig
Requires (Dev)
- php: >=8.1
- ext-json: *
- cweagans/composer-patches: ^1.7
- phpdocumentor/phpdocumentor: 3.8.0
- phpunit/phpunit: ^10
- symfony/filesystem: ^6.4
This package is auto-updated.
Last update: 2025-07-10 18:32:18 UTC
README
Use cases: In-repository documentation, GitHub/GitLab wikis, AI prompt context.
Markdown template for phpDocumentor3
Wish there was an easy way to generate PHP source code documentation?
Using phpDocumentor
with phpDocumentor-markdown
template, you can automatically generate GitHub/GitLab-ready Markdown documentation from PHP source code.
This template can be used to document:
Name | Descriptions | Inheritance | Implements | Constants | Properties | Methods | Inherited methods | |
---|---|---|---|---|---|---|---|---|
Classes | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
Interfaces | ✅ | ✅ | ✅ | ➖ | ✅ | ✅ | ✅ | ➖ |
Traits | ✅ | ✅ | ➖ | ➖ | ✅ | ✅ | ✅ | ➖ |
Name | Descriptions | Types (parameter, return, etc.) | Access modifiers | |
---|---|---|---|---|
Functions | ✅ | ✅ | ✅ | ✅ |
Methods | ✅ | ✅ | ✅ | ✅ |
Properties | ✅ | ✅ | ✅ | ✅ |
Example
Examples are available in the .wiki directory.
Installation & Usage
- Please refer to this guide for instructions on installing phpDocumentor.
- Usage instructions assume that
phpdoc
is the phpDocumentor binary.
Running manually
# Run phpDocumentor with --template argument pointed to this directory's markdown template phpdoc --directory=src --target=docs --template=<PATH TO THIS REPOSITORY/themes/markdown>
Using Composer
Installation via Composer
# Require this package. You probably want it as a dev dependency
composer require --dev saggre/phpdocumentor-markdown
Running manually after installing via Composer
# Run phpDocumentor with --template argument pointed to markdown template inside vendor directory phpdoc --directory=src --target=docs --template="vendor/saggre/phpdocumentor-markdown/themes/markdown"
Installation & Usage tips
Adding a Composer helper script
Add this script to your composer.json
and run composer create-docs
to generate the documentation.
"scripts": { "create-docs": "phpdoc --directory=src --target=docs --template='vendor/saggre/phpdocumentor-markdown/themes/markdown'" },
Using with PhpDocumentor XML config
Add a template element to your phpDocumentor XML config and run phpDocumentor
to generate the documentation.
<phpdocumentor> <!-- Specify template element inside phpdocumentor --> <template name="./vendor/saggre/phpdocumentor-markdown/themes/markdown"/> </phpdocumentor>
You can also check out the config file used for generating this repository's example documentation for a full example.
GitLab wiki
The output of this template can be used directly as a GitLab wiki.
GitHub wiki
⚠️ GitHub wiki uses a flat directory structure for linking, so the internal links in the resulting documentation will not work as expected.
CI pipelines
You can use the PhpDocumentor Docker image with this template in your CI pipelines to generate documentation automatically.
AI integration
The generated documentation can be used as prompt context for AI models that work with source code. For other use cases you'll likely want structured data, like JSON.
Running tests
# Clone the repository git clone git@github.com:Saggre/phpDocumentor-markdown.git # Go to the cloned repository cd phpDocumentor-markdown # Install dependencies composer install # Set up PHPUnit configuration cp phpunit.xml.dist phpunit.xml # Run PHPUnit in project root directory composer test
Contributing
- There are unit tests and functional tests available in the
tests
directory.- Unit tests are used to test individual Twig macros
- Functional tests are used to test the whole documentation generation process