{"id":15525248,"url":"https://github.com/donatj/mddoc","last_synced_at":"2026-03-06T19:34:51.821Z","repository":{"id":45111016,"uuid":"14760847","full_name":"donatj/mddoc","owner":"donatj","description":"A simple, directed, markdown documentation generator for PHP","archived":false,"fork":false,"pushed_at":"2025-11-14T23:05:23.000Z","size":449,"stargazers_count":1,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-11-15T01:17:35.753Z","etag":null,"topics":["documentation","documentation-tool","markdown"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/donatj.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"custom":"https://www.paypal.me/donatj/15","ko_fi":"donatj","github":"donatj"}},"created_at":"2013-11-27T22:34:04.000Z","updated_at":"2025-11-14T23:05:27.000Z","dependencies_parsed_at":"2024-05-16T06:03:55.525Z","dependency_job_id":"5e4cfc2e-24c0-43ab-b9df-d01610953561","html_url":"https://github.com/donatj/mddoc","commit_stats":{"total_commits":243,"total_committers":5,"mean_commits":48.6,"dds":0.522633744855967,"last_synced_commit":"d6e888ee9a3f3818419cf18f60eb7950238eb1a6"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/donatj/mddoc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donatj%2Fmddoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donatj%2Fmddoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donatj%2Fmddoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donatj%2Fmddoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/donatj","download_url":"https://codeload.github.com/donatj/mddoc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/donatj%2Fmddoc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30193649,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-06T19:07:06.838Z","status":"ssl_error","status_checked_at":"2026-03-06T18:57:34.882Z","response_time":250,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","documentation-tool","markdown"],"created_at":"2024-10-02T10:56:00.060Z","updated_at":"2026-03-06T19:34:51.779Z","avatar_url":"https://github.com/donatj.png","language":"PHP","funding_links":["https://www.paypal.me/donatj/15","https://ko-fi.com/donatj","https://github.com/sponsors/donatj"],"categories":[],"sub_categories":[],"readme":"# MDDoc\n\n[![Latest Stable Version](https://poser.pugx.org/donatj/mddoc/version)](https://packagist.org/packages/donatj/mddoc)\n[![Total Downloads](https://poser.pugx.org/donatj/mddoc/downloads)](https://packagist.org/packages/donatj/mddoc)\n[![License](https://poser.pugx.org/donatj/mddoc/license)](https://packagist.org/packages/donatj/mddoc)\n[![ci.yml](https://github.com/donatj/mddoc/actions/workflows/ci.yml/badge.svg)](https://github.com/donatj/mddoc/actions/workflows/ci.yml)\n\n\nA simple, directed markdown documentation generator for PHP projects.\n\nA simple use-case is to generate a README.md based on the project's source code as well as other options as defined in the config file.\n\nThis projects allows you to define a set of directives for *how* to document a project, and output to markdown.\n\nThis allows everything from README's to entire websites to be generated using this tool.\n\nThis is done using a simple, expressive XML syntax. This includes:\n\n- Automatic documentation of code\n- Automatic composer requirements / installation instructions\n- Raw and code-tag wrapped file inclusion\n- Script output\n- Automatic Badge Creation\n- Creating sub-documents\n- Much more\n\n\n\n## Requirements\n\n- **php**: \u003e=7.2\n- **ext-dom**: *\n- **ext-json**: *\n- **ext-libxml**: *\n- **donatj/cli-toolkit**: ^0.3.1\n- **donatj/flags**: ^1.5\n- **donatj/mddom**: ^0.2.0\n- **phpdocumentor/reflection**: ~5.2.0\n- **psr/log**: ^1|^2|^3\n- **symfony/polyfill-php80**: ^1.28\n\n## Examples\n\n- PhpUserAgent's [README](https://github.com/donatj/PhpUserAgent)\n- [boomerang.work](https://boomerang.work/) - The documentation site for Boomerang*!* is fully generated using this tool.\n\nThis very README you are reading (also including [DOCS.md](DOCS.md)) is generated by the file [.mddoc.xml.dist](.mddoc.xml.dist)\n\n\n```xml\n\u003cmddoc\u003e\n  \u003cautoloader type=\"psr4\" root=\"src\" namespace=\"donatj\\MDDoc\"/\u003e\n  \u003cdocpage target=\"README.md\"\u003e\n\n    \u003csection title=\"MDDoc\"\u003e\n      \u003cbadge-poser type=\"version\"/\u003e\n      \u003cbadge-poser type=\"downloads\"/\u003e\n      \u003cbadge-poser type=\"license\"/\u003e\n      \u003cbadge-github-action name=\"donatj/mddoc\" workflow-file=\"ci.yml\"/\u003e\n\n      \u003ctext\u003e\u003c![CDATA[\nA simple, directed markdown documentation generator for PHP projects.\n\nA simple use-case is to generate a README.md based on the project's source code as well as other options as defined in the config file.\n\nThis projects allows you to define a set of directives for *how* to document a project, and output to markdown.\n\nThis allows everything from README's to entire websites to be generated using this tool.\n\nThis is done using a simple, expressive XML syntax. This includes:\n\n- Automatic documentation of code\n- Automatic composer requirements / installation instructions\n- Raw and code-tag wrapped file inclusion\n- Script output\n- Automatic Badge Creation\n- Creating sub-documents\n- Much more\n\n]]\u003e\u003c/text\u003e\n      \u003csection title=\"Requirements\"\u003e\n        \u003ccomposer-requires/\u003e\n      \u003c/section\u003e\n\n      \u003csection title=\"Examples\"\u003e\n        \u003ctext\u003e\u003c![CDATA[\n- PhpUserAgent's [README](https://github.com/donatj/PhpUserAgent)\n- [boomerang.work](https://boomerang.work/) - The documentation site for Boomerang*!* is fully generated using this tool.\n\nThis very README you are reading (also including [DOCS.md](DOCS.md)) is generated by the file [.mddoc.xml.dist](.mddoc.xml.dist)\n]]\u003e\u003c/text\u003e\n        \u003creplace search=\"\u0026#x9;\" replace=\"  \"\u003e\n          \u003csource name=\".mddoc.xml.dist\" lang=\"xml\"/\u003e\n        \u003c/replace\u003e\n      \u003c/section\u003e\n\n      \u003csection title=\"Full API Docs (WIP)\"\u003e\n        \u003cdocpage target=\"DOCS.md\"\u003e\n          \u003csection title=\"Full API Docs (WIP)\"\u003e\n            \u003crecursive-directory warn-undocumented=\"false\" name=\"src\"/\u003e\n          \u003c/section\u003e\n        \u003c/docpage\u003e\n      \u003c/section\u003e\n\n      \u003csection title=\"Configuration Syntax\"\u003e\n        \u003cexec cmd=\"./bin/document-tags.php\"/\u003e\n      \u003c/section\u003e\n    \u003c/section\u003e\n  \u003c/docpage\u003e\n\u003c/mddoc\u003e\n\n```\n\n## Full API Docs (WIP)\n\n[See: DOCS.md](DOCS.md)\n\n## Configuration Syntax\n\n### `\u003cautoloader /\u003e`  \n  \nSpecifies an PHP autoloader to use for the documentation generation  \n  \nThis autoloader is used at the current documentation level and inherited by  \nall children  \n  \nMultiple autoloaders can be specified, and they will be checked in the order  \nthey are specified  \n  \nThese are necessary to specify by hand because the composer autoloaders  \ndo not provide a method to locate a class by name without loading it,  \nwhich is necessary for documentation generation without code execution.  \n  \n#### Attributes:  \n  \n- `type` **(required)** - The type of autoloader to use, either \"psr0\" or \"psr4\"  \n- `root` **(required)** - The root directory of the autoloader  \n- `namespace` - The namespace of the autoloader, only used for psr4  \n  \n### `\u003csection\u003e…\u003c/section\u003e`  \n  \nDefine a logical section of the generated documentation  \n  \nNesting sections results in the header level being increased (h1, h2, h3, etc)  \n  \nExample:  \n  \n```xml  \n\u003csection title=\"This is an H1\"\u003e  \n   \u003csection title=\"This is an H2\"\u003e  \n        \u003csection title=\"This is an H3\"\u003e  \n          \u003ctext\u003eSome Text\u003c/text\u003e  \n        \u003c/section\u003e  \n   \u003c/section\u003e  \n\u003c/section\u003e  \n```  \n  \nResults in:  \n  \n```markdown  \n# This is an H1  \n  \n## This is an H2  \n  \n### This is an H3  \n  \nSome Text  \n```  \n  \n#### Attributes:  \n  \n- `title` **(required)** - The heading of the section  \n  \n### `\u003creplace\u003e…\u003c/replace\u003e`  \n  \nReplace text in the wrapped content. Optionally use a preg_replace() regex.  \n  \n#### Attributes:  \n  \n- `search` **(required)** - The text to search for  \n- `replace` **(required)** - The text to replace with  \n- `regex` - Whether to use a regex or not - expects \"true\" or \"false\" - defaults to \"false\"  \n  \n### `\u003cdocpage\u003e…\u003c/docpage\u003e`  \n  \nDocumentation page - stores the contents of child elements to a file  \n  \nNesting docpages results in a link being added in the parent page to the child page  \n  \nInherits all attributes from `\u003cfile\u003e`  \n  \n#### Attributes:  \n  \n- `target` **(required)** - Filename to output  \n- `link` - Optional custom link for parent documents  \n- `link-text` - Optional custom text for the link in parent documents  \n- `link-pre-text` - Optional custom text to precede the link in parent documents  \n- `link-post-text` - Optional custom text to follow the link in parent documents  \n  \n### `\u003ctext /\u003e`  \n  \nInclude either raw or cdata text content  \n  \nExample:  \n  \n```xml  \n\u003ctext\u003eSome Text\u003c/text\u003e  \n\u003ctext\u003e\u003c![CDATA[Some Text]]\u003e\u003c/text\u003e  \n```  \n  \n### `\u003cfile /\u003e`  \n  \nGenerate documentation for a single PHP file  \n  \n#### Attributes:  \n  \n- `name` **(required)** - The file to document  \n- `skip-class-header` _[recursive]_ - Skip the class header line  \n- `skip-class-constants` _[recursive]_ - Skip the class constants section  \n- `method-filter` - Regex to filter methods by - specify methods to be matched  \n- `skip-method-returns` - Skip the method return section  \n- `warn-undocumented` _[recursive]_ - Generate warning for undocumented methods. Defaults to \"true\".  \n  \n### `\u003crecursive-directory\u003e…\u003c/recursive-directory\u003e`  \n  \nRecursively search a directory for php files to generate documentation for  \n  \n#### Attributes:  \n  \n- `name` **(required)** - The directory to recursively search for files to document  \n- `file-filter` - A regex to filter files by - specify files to be matched  \n  \n### `\u003cinclude /\u003e`  \n  \nInclude the contents of a file  \n  \n#### Attributes:  \n  \n- `name` **(required)** - The poth of the file to include  \n  \n### `\u003csource /\u003e`  \n  \nInclude a source code block either as a file or inline  \n  \nExample:  \n  \n```xml  \n\u003csource name=\"path/to/file.php\" lang=\"php\" /\u003e  \n\u003csource lang=\"js\"\u003e  \nconsole.log('Hello World');  \n\u003c/source\u003e  \n```  \n  \n#### Attributes:  \n  \n- `name` - filename of optional source file  \n- `lang` - Optional language name for the opening  \n  \n### `\u003ccomposer-install /\u003e`  \n  \nReads the current projects' composer.json file and outputs the install command  \n  \n#### Attributes:  \n  \n- `text` - Text to display before the install command  \n- `global` - Whether to include global subcommand  \n- `dev` - Whether to include --dev flag  \n- `package-names` - Package name override. Comma delimited. Defaults to `name` key of composer.json  \n  \n### `\u003ccomposer-requires /\u003e`  \n  \nReads the current projects' composer.json file and outputs the required packages, versions and extensions  \n  \n### `\u003cbadge /\u003e`  \n  \nInclude a badge \"shield\" image from a given url  \n  \n#### Attributes:  \n  \n- `src` - The image url **(required)**  \n- `alt` - The image alt text **(required)**  \n- `href` - The optional url to link to wrap the badge in  \n- `title` - The optional link title  \n  \n### `\u003cbadge-coveralls /\u003e`  \n  \nInclude a coverage badge from BadgeCoveralls.io  \n  \n#### Attributes:  \n  \n- `name` - The BadgeCoveralls name of the Project. Required.  \n  \nThis includes the service name, e.g. \"github/donatj/php-dnf-solver\"  \n- `branch` - The branch to show. Defaults to empty which shows the default branch  \n  \n### `\u003cbadge-poser /\u003e`  \n  \nInclude a badge \"shield\" image from Pugx Poser https://poser.pugx.org/  \n  \n#### Attributes:  \n  \n- `type` **(required)** - The type of badge to display. One of: \"version\" \"downloads\" \"unstable\" \"license\" \"monthly\" \"daily\" \"phpversion\"  \n\"composerlock\"  \n- `name` - The packagist name of the package. Defaults to the name key of the composer.json file in the root of the project. Required if the composer.json file is not present.  \n- `suffix` - The poser endpoint to use. Defaults based on the type  \n  \n### `\u003cbadge-travis /\u003e`  \n  \nInclude a badge \"shield\" image from Travis CI  \n  \n#### Attributes:  \n  \n- `name` **(required)** - The packagist name of the Travis Project. Defaults to the name key of the composer.json file in the root of the  \nproject. Required if the composer.json file is not present.  \n- `branch` - The branch to show. Defaults to \"master\"  \n  \n### `\u003cbadge-scrutinizer /\u003e`  \n  \nInclude a badge \"shield\" image from Scrutinizer CI  \n  \n#### Attributes:  \n  \n- `name` **(required)** - The packagist name of the Scrutinizer Project. Defaults to the name key of the composer.json file in the root of  \nthe project. Required if the composer.json file is not present.  \n- `type` **(required)** - The type of badge to display. One of: \"quality\" \"coverage\" \"build-status\"  \n- `suffix` - The Scrutinizer endpoint to use. Defaults based on the type  \n- `branch` - The branch to show. Defaults to \"master\"  \n  \n### `\u003cbadge-shielded /\u003e`  \n  \nInclude a badge \"shield\" image from Shielded.dev  \n  \nEither the id or the color, title, and text options must be provided.  \n  \n#### Attributes:  \n  \n- `id` - The ID of the badge to display when displaying a dynamic badge.  \n- `color` - The color of the badge when displaying a static badge.  \n- `title` - The title of the badge when displaying a static badge.  \n- `text` - The text of the badge when displaying a static badge.  \n  \n### `\u003cbadge-github-action /\u003e`  \n  \nInclude a badge \"shield\" image for a GitHub Actions workflow  \n  \n#### Attributes:  \n  \n- `name` **(required)** - The name of the `.yml` file in the `.github/workflows/` directory including the `.yml` extension  \n- `branch` - The name of the branch to show the badge for. Defaults to the default branch.  \n- `event`  \n- `workflow-file` **(required)** - The filename of the workflow file to use as the badge source  \n  \n### `\u003cexec /\u003e`  \n  \nExecute a command and include the standard output in the documentation  \n  \n#### Attributes:  \n  \n- `cmd` **(required)** - The command to execute  \n- `format` - The format to output the result in - options include \"raw\" \"code\" and \"code-block\" defaults to \"raw\"  \n- `allow-error` - Set to 'true' to allow non-zero exit codes to continue","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdonatj%2Fmddoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdonatj%2Fmddoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdonatj%2Fmddoc/lists"}