nochso/writeme
, (*1)
nochso/writeme is a PHP CLI utility for maintaining README and related files., (*2)
For example the following table of contents was generated from the @toc@ placeholder in WRITEME.md., (*3)
Introduction
writeme can be considered a template engine with a focus on typical Markdown documents like readme, change logs,
project documentation etc. Even though it's geared towards Markdown, other Markup languages and plain text will work., (*4)
A writeme document can contain YAML frontmatter and text content:, (*5)
---
answer: 42
---
@answer@
The frontmatter placeholder @answer@ will be converted to 42 by running writeme <file>. This is pretty basic,
however there are other types of placeholders you can use., (*6)
You could even write your own by implementing the Placeholder interface. For example the documentation of each
placeholder is automatically generated from the PHPDocs of the placeholder classes. That way this README is easily
updated., (*7)
Installation
For end-users the PHAR version is preferred. To install it globally:, (*8)
- Download the PHAR file from the
latest release.
- Make it executable:
chmod +x writeme.phar
- Move it somewhere within your
PATH: sudo cp writeme.phar /usr/local/bin/writeme
As local Composer development dependency per project:, (*9)
composer require --dev nochso/writeme
As global Composer dependency:, (*10)
composer global require nochso/writeme
Requirements
This project is written for and tested with PHP 5.6, 7.0 and HHVM., (*11)
Usage
Running writeme
If you've required nochso/writeme in your project using Composer, you can run the writeme executable PHP file located in
vendor/bin:, (*12)
vendor/bin/writeme
Run it without any arguments to get an overview of available arguments., (*13)
Initializing a new template
writeme comes with a template for a typical Composer based project available on Packagist. You can initialize
your own WRITEME.md based on this template:, (*14)
writeme --init
Simply answer the questions. Some are optional and pressing enter will either skip them or use defaults., (*15)
Some placeholders have default settings: you will be asked if you want to override these. Your custom settings will
then be added to the YAML frontmatter., (*16)
Once you're done, you should have two new files. The template and the resulting output, usually WRITEME.md and
README.md., (*17)
Escaping placeholders
To avoid replacing a placeholder, escape the @ characters with backslashes: \@example.escape\@., (*18)
Specifying a target file name
By default files named WRITEME* will be saved to README*. Names that are all upper/lower-case are preserved.
This default behaviour can be overriden using the CLI option --target <filename> or frontmatter key target:, (*19)
target: DOCS.md
Available placeholders
Frontmatter @*@
Frontmatter placeholders return values defined in the frontmatter., (*20)
You can define any kind of structure as long as it doesn't collide with the name of any other available placeholder:, (*21)
---
greet: Hello
user:
name: [Annyong, Tobias]
key.has.dots: yes
---
@greet@ @user.name.0@!
key has dots: @key\.has\.dots@
Frontmatter values are accessed using dot-notation, resulting in this output:, (*22)
Hello Annyong!
key has dots: yes
Using dots in the keys themselves is possible by escaping them with backslashes. See the Dot class provided by
nochso/omni., (*23)
@*@
TOC @toc@
TOC placeholder creates a table of contents from Markdown headers., (*24)
@toc@
Collects all Markdown headers contained in the document with a
configurable maximum depth., (*25)
@toc.sub($maxDepth)@
@toc.sub@ collects Markdown headers that are below the placeholder and on the same or deeper level., (*26)
If there's a header above the placeholder, its depth will be used as a minimum depth.
If there's no header above the placeholder, the first header after the placeholder will be used for the minimum depth.
There is currently no maximum depth for @toc.sub@., (*27)
e.g., (*28)
# ignore me
@toc.sub@
## sub 1
# ignore me again
is converted into, (*29)
# ignore me
- [sub 1](#sub-1)
## sub 1
# ignore me again
-
$maxDepth = 0 int
- How many levels of headers you'd like to keep.
Defaults to zero, meaning all sub-headers are kept.
Default options
toc:
max-depth: 3
-
toc.max-depth
- Maximum depth of header level to extract.
API @api@
API creates documentation from your PHP code., (*30)
By default it will search for all *.php files in your project excluding the Composer vendor and test* folders., (*31)
Available template names:, (*32)
-
summary - Indented list of namespaces, classes and methods including the first line of PHPDocs.
-
short - Indented list of namespaces and classes including the first line of PHPDocs.
-
full - Verbose documentation for each class and methods.
@api($templateName)@
-
$templateName string
- 'summary', 'short' or 'full'
Default options
api:
file: ['*.php']
from: [.]
folder-exclude: [vendor, test, tests]
-
api.file
- List of file patterns to parse.
-
api.from
- List of folders to search files in.
-
api.folder-exclude
- List of folders to exclude from the search.
Changelog @changelog@
Changelog fetches the most recent release notes from a CHANGELOG written in Markdown., (*33)
This placeholder is intended for changelogs following the keep-a-changelog conventions.
However it should work for any Markdown formatted list of releases: each release is identified by a Markdown header.
What kind of header marks a release can be specified by the changelog.release-level option., (*34)
@changelog@
Default options
changelog:
max-changes: 2
release-level: 2
shift-level: 0
file: CHANGELOG.md
search-depth: 2
-
changelog.max-changes
- Maximum amount of releases to include.
-
changelog.release-level
- The header level that represents a release header.
-
changelog.shift-level
- Amount of levels to add when displaying headers.
-
changelog.file
- Filename of the CHANGELOG to extract releases from.
-
changelog.search-depth
- How deep the folders should be searched.
Badge @badge@
@image($imageUrl, $altText, $url)@
-
$imageUrl string
-
$altText string
- Alternative text for image.
-
$url = NULL string|null
- Optional URL the image will link to. If null, no link will
be created.
@badge($subject, $status, $color, $altText, $url)@
Badge creation via shields.io.
* $subject string
* Subject to the left of the badge.
* $status string
* Status to the right of the badge.
* $color = 'lightgrey' string
* Optional status color. Defaults to lightgrey. Can be any hex
color, e.g. 0000FF or one of the following: brightgreen,
green, yellowgreen, yellow, orange, red, lightgrey or blue.
* $altText = NULL string|null
* Optional alternative text for image. Defaults to
subject - status.
* $url = NULL string|null
* Optional URL the badge will link to. If null, no link will be
created., (*35)
@badge.writeme@
Bonus badge for mentioning writeme., (*36)
@badge.travis($userRepository, $branch)@
Travis CI build status.
* $userRepository = NULL string|null
* User/repository, e.g. nochso/writeme. Defaults to composer.name
* $branch = NULL string|null
* Optional branch name., (*37)
@badge.license($userRepository)@
@badge.scrutinizer($userRepository, $branch)@
scrutinizer.
* $userRepository = NULL null
* Github user/repository.
* $branch = NULL null, (*38)
@badge.coveralls($userRepository, $branch)@
@badge.tag($userRepository)@
License
nochso/writeme is released under the MIT license. See the LICENSE for the full license text., (*41)
Wallogit.com
