{"id":30450000,"url":"https://github.com/nochso/writeme","last_synced_at":"2026-04-21T03:31:08.454Z","repository":{"id":62530045,"uuid":"53227302","full_name":"nochso/writeme","owner":"nochso","description":"WRITEME to README. Help create and maintain READMEs using placeholders.","archived":false,"fork":false,"pushed_at":"2016-04-16T21:02:06.000Z","size":225,"stargazers_count":0,"open_issues_count":14,"forks_count":0,"subscribers_count":1,"default_branch":"develop","last_synced_at":"2025-08-23T15:10:25.232Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nochso.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-03-05T22:57:13.000Z","updated_at":"2016-03-05T22:57:34.000Z","dependencies_parsed_at":"2022-11-02T14:31:01.452Z","dependency_job_id":null,"html_url":"https://github.com/nochso/writeme","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/nochso/writeme","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nochso%2Fwriteme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nochso%2Fwriteme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nochso%2Fwriteme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nochso%2Fwriteme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nochso","download_url":"https://codeload.github.com/nochso/writeme/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nochso%2Fwriteme/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32075213,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-21T02:38:07.213Z","status":"ssl_error","status_checked_at":"2026-04-21T02:38:06.559Z","response_time":128,"last_error":"SSL_read: 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":[],"created_at":"2025-08-23T13:20:16.754Z","updated_at":"2026-04-21T03:31:08.435Z","avatar_url":"https://github.com/nochso.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# nochso/writeme\n\n[![GitHub tag](https://img.shields.io/github/tag/nochso/writeme.svg)](https://github.com/nochso/writeme/releases)\n[![write me to read me](https://img.shields.io/badge/writeme-readme-blue.svg)](https://github.com/nochso/writeme)\n\nnochso/writeme is a PHP CLI utility for maintaining README and related files.\n\nFor example the following table of contents was generated from the `@toc@` placeholder in [WRITEME.md](WRITEME.md).\n\n- [nochso/writeme](#nochsowriteme)\n- [Introduction](#introduction)\n- [Installation](#installation)\n- [Requirements](#requirements)\n- [Usage](#usage)\n    - [Running writeme](#running-writeme)\n    - [Initializing a new template](#initializing-a-new-template)\n    - [Escaping placeholders](#escaping-placeholders)\n    - [Specifying a target file name](#specifying-a-target-file-name)\n- [Available placeholders](#available-placeholders)\n    - [Frontmatter `@*@`](#frontmatter-)\n    - [TOC `@toc@`](#toc-toc)\n    - [API `@api@`](#api-api)\n    - [Changelog `@changelog@`](#changelog-changelog)\n    - [Badge `@badge@`](#badge-badge)\n- [License](#license)\n\n# Introduction\nwriteme can be considered a template engine with a focus on typical Markdown documents like readme, change logs,\nproject documentation etc. Even though it's geared towards Markdown, other Markup languages and plain text will work.\n\nA writeme document can contain [YAML](https://learnxinyminutes.com/docs/yaml/) frontmatter and text content:\n\n```markdown\n---\nanswer: 42\n---\n@answer@\n```\nThe frontmatter placeholder `@answer@` will be converted to `42` by running `writeme \u003cfile\u003e`. This is pretty basic,\nhowever there are other [types of placeholders](#available-placeholders) you can use.\n\nYou could even write your own by implementing the `Placeholder` interface. For example the documentation of each\nplaceholder is automatically generated from the PHPDocs of the placeholder classes. That way this README is easily\nupdated.\n# Installation\nFor end-users the PHAR version is preferred. To install it **globally**:\n\n1. Download the PHAR file from the\n   [latest release](https://github.com/nochso/writeme/releases).\n2. Make it executable: `chmod +x writeme.phar`\n3. Move it somewhere within your `PATH`: `sudo cp writeme.phar /usr/local/bin/writeme`\n\nAs **local Composer development** dependency per project:\n```\ncomposer require --dev nochso/writeme\n```\n\nAs **global** Composer dependency:\n```\ncomposer global require nochso/writeme\n```\n\n# Requirements\nThis project is written for and tested with PHP 5.6, 7.0 and HHVM.\n\n# Usage\n\n## Running writeme\n\nIf you've required `nochso/writeme` in your project using Composer, you can run the `writeme` executable PHP file located in\n`vendor/bin`:\n\n    vendor/bin/writeme\n\nRun it without any arguments to get an overview of available arguments.\n\n## Initializing a new template\nwriteme comes with a template for a typical Composer based project available on Packagist. You can initialize\nyour own WRITEME.md based on this template:\n\n    writeme --init\n\nSimply answer the questions. Some are optional and pressing enter will either skip them or use defaults.\n\nSome placeholders have default settings: you will be asked if you want to override these. Your custom settings will\nthen be added to the YAML frontmatter.\n\nOnce you're done, you should have two new files. The template and the resulting output, usually `WRITEME.md` and\n`README.md`.\n\n## Escaping placeholders\nTo avoid replacing a placeholder, escape the `@` characters with backslashes: `\\@example.escape\\@`.\n\n## Specifying a target file name\n\nBy default files named `WRITEME*` will be saved to `README*`. Names that are all upper/lower-case are preserved.\nThis default behaviour can be overriden using the CLI option `--target \u003cfilename\u003e` or frontmatter key `target`:\n\n```yaml\ntarget: DOCS.md\n```\n\n# Available placeholders\n\n## Frontmatter `@*@`\n\nFrontmatter placeholders return values defined in the frontmatter.\n\nYou can define any kind of structure as long as it doesn't collide with the name of any other available placeholder:\n\n```yaml\n---\ngreet: Hello\nuser:\n    name: [Annyong, Tobias]\nkey.has.dots: yes\n---\n@greet@ @user.name.0@!\nkey has dots: @key\\.has\\.dots@\n```\n\nFrontmatter values are accessed using dot-notation, resulting in this output:\n\n```markdown\nHello Annyong!\nkey has dots: yes\n```\n\nUsing dots in the keys themselves is possible by escaping them with backslashes. See the `Dot` class provided by\n[nochso/omni](https://github.com/nochso/omni).\n\n### `@*@`\n\n\n\n\n\n\n## TOC `@toc@`\n\nTOC placeholder creates a table of contents from Markdown headers.\n\n### `@toc@`\n\nCollects **all** Markdown headers contained in the document with a\nconfigurable maximum depth.\n\n\n### `@toc.sub($maxDepth)@`\n\n`@toc.sub@` collects Markdown headers that are **below** the placeholder and on the same or deeper level.\n\nIf there's a header above the placeholder, its depth will be used as a minimum depth.\nIf there's no header above the placeholder, the first header after the placeholder will be used for the minimum depth.\nThere is currently no maximum depth for `@toc.sub@`.\n\ne.g.\n```markdown\n# ignore me\n\n@toc.sub@\n## sub 1\n# ignore me again\n```\nis converted into\n\n```markdown\n# ignore me\n- [sub 1](#sub-1)\n## sub 1\n# ignore me again\n```\n* `$maxDepth = 0`  `int`\n    * How many levels of headers you'd like to keep.\nDefaults to zero, meaning all sub-headers are kept.\n\n\n### Default options\n```yaml\ntoc:\n    max-depth: 3\n```\n\n* `toc.max-depth`\n    * Maximum depth of header level to extract.\n\n## API `@api@`\n\nAPI creates documentation from your PHP code.\n\nBy default it will search for all `*.php` files in your project excluding the Composer `vendor` and `test*` folders.\n\nAvailable template names:\n\n- `summary` - Indented list of namespaces, classes and methods including the first line of PHPDocs.\n- `short` - Indented list of namespaces and classes including the first line of PHPDocs.\n- `full` - Verbose documentation for each class and methods.\n\n### `@api($templateName)@`\n\n\n* `$templateName`  `string`\n    * 'summary', 'short' or 'full'\n\n\n### Default options\n```yaml\napi:\n    file: ['*.php']\n    from: [.]\n    folder-exclude: [vendor, test, tests]\n```\n\n* `api.file`\n    * List of file patterns to parse.\n* `api.from`\n    * List of folders to search files in.\n* `api.folder-exclude`\n    * List of folders to exclude from the search.\n\n## Changelog `@changelog@`\n\nChangelog fetches the most recent release notes from a CHANGELOG written in Markdown.\n\nThis placeholder is intended for changelogs following the [keep-a-changelog](http://keepachangelog.com/) conventions.\nHowever it should work for any Markdown formatted list of releases: each release is identified by a Markdown header.\nWhat kind of header marks a release can be specified by the `changelog.release-level` option.\n\n### `@changelog@`\n\n\n\n\n### Default options\n```yaml\nchangelog:\n    max-changes: 2\n    release-level: 2\n    shift-level: 0\n    file: CHANGELOG.md\n    search-depth: 2\n```\n\n* `changelog.max-changes`\n    * Maximum amount of releases to include.\n* `changelog.release-level`\n    * The header level that represents a release header.\n* `changelog.shift-level`\n    * Amount of levels to add when displaying headers.\n* `changelog.file`\n    * Filename of the CHANGELOG to extract releases from.\n* `changelog.search-depth`\n    * How deep the folders should be searched.\n\n## Badge `@badge@`\n\n\n\n### `@image($imageUrl, $altText, $url)@`\n\n\n* `$imageUrl`  `string`\n    * URL to a badge image.\n* `$altText`  `string`\n    * Alternative text for image.\n* `$url = NULL`  `string|null`\n    * Optional URL the image will link to. If null, no link will\nbe created.\n\n\n### `@badge($subject, $status, $color, $altText, $url)@`\n\nBadge creation via shields.io.\n* `$subject`  `string`\n    * Subject to the left of the badge.\n* `$status`  `string`\n    * Status to the right of the badge.\n* `$color = 'lightgrey'`  `string`\n    * Optional status color. Defaults to lightgrey. Can be any hex\ncolor, e.g. `0000FF` or one of the following: brightgreen,\ngreen, yellowgreen, yellow, orange, red, lightgrey or blue.\n* `$altText = NULL`  `string|null`\n    * Optional alternative text for image. Defaults to\n`subject - status`.\n* `$url = NULL`  `string|null`\n    * Optional URL the badge will link to. If null, no link will be\ncreated.\n\n\n### `@badge.writeme@`\n\nBonus badge for mentioning writeme.\n\n\n### `@badge.travis($userRepository, $branch)@`\n\nTravis CI build status.\n* `$userRepository = NULL`  `string|null`\n    * User/repository, e.g. `nochso/writeme`. Defaults to `composer.name`\n* `$branch = NULL`  `string|null`\n    * Optional branch name.\n\n\n### `@badge.license($userRepository)@`\n\n\n* `$userRepository = NULL` \n\n\n\n### `@badge.scrutinizer($userRepository, $branch)@`\n\nscrutinizer.\n* `$userRepository = NULL`  `null`\n    * Github user/repository.\n* `$branch = NULL`  `null`\n\n\n\n### `@badge.coveralls($userRepository, $branch)@`\n\n\n* `$userRepository = NULL` \n\n* `$branch = NULL` \n\n\n\n### `@badge.tag($userRepository)@`\n\n\n* `$userRepository = NULL` \n\n\n\n\n\n\n# License\nnochso/writeme is released under the MIT license. See the [LICENSE](LICENSE.md) for the full license text.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnochso%2Fwriteme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnochso%2Fwriteme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnochso%2Fwriteme/lists"}