Taking markdown to the next level
Documenting
Github has taken the humble README file and elevated it to star status by using Markdown. But after you've written a few of those, you start hoping that something will come along to take it to the next level.
BLUEPHRASE notation is a natural for documenting things, and with the --emit option set to "Github Flavored Markdown", you can write your next source code documentation as readme.blue and instantly convert it to readme.md on your next commit.
With Read Write Tools your once humble documentation can become a source of pride. Here's a portion of a real example (rwserve-custom-header):
h4 Customization
This plugin is open source and can be used as is, or repurposed into something less whimsical than just "Hello World!", such as:
ul {
Adding custom headers during development for debugging, version control, etc.
Conditionally adding custom headers that are intended for consumption by log monitoring utilities.
Providing custom headers in alternative languages to advertise non-obvious features of your website.
}
h3 Configuration is Everything
Make the software available by declaring it in the <<code plugins>> section of your configuration file. For detailed instructions on how to do this, refer to the <<a `https://rwserve.readwritetools.com/plugins.blue` plugins>> documentation on the <<code Read Write Tools HTTP/2 Server>> website.
h4 TL;DR
The <<code config>> settings are straightforward:
<<code header-name>> is the name of the response header you wish to add. The HTTP/2 protocol requires this name to comprise only lowercase letters, digits, and HYPHENs.
<<code header-value>> is the string value you wish to associate with the header. This value should consist of ISO-8859-1 characters only. UTF-8 characters can be used, but only when encoded according to the specification in IETF RFC 5987 "Character Set and Language Encoding for Hypertext Transfer Protocol (HTTP) Header Field Parameters"
The sample <<code router>> shown above will route all messages (<<code `*`>>) for <<i any>> HTTP method, to the plugin.
#### Customization
This plugin is open source and can be used as is, or repurposed into something
less whimsical than just "Hello World!", such as:
* Adding custom headers during development for debugging, version control, etc.
* Conditionally adding custom headers that are intended for consumption by log
monitoring utilities.
* Providing custom headers in alternative languages to advertise non-obvious
features of your website.
### Configuration is Everything
Make the software available by declaring it in the `plugins` section of your
configuration file. For detailed instructions on how to do this, refer to the <a href='https://rwserve.readwritetools.com/plugins.blue'>plugins</a>
documentation on the `Read Write Tools HTTP/2 Server` website.
#### TL;DR
The `config` settings are straightforward:
`header-name` is the name of the response header you wish to add. The HTTP/2
protocol requires this name to comprise only lowercase letters, digits, and
HYPHENs.
`header-value` is the string value you wish to associate with the header. This
value should consist of ISO-8859-1 characters only. UTF-8 characters can be
used, but only when encoded according to the specification in IETF RFC 5987
"Character Set and Language Encoding for Hypertext Transfer Protocol (HTTP)
Header Field Parameters"
The sample `router` shown above will route all messages (```*```) for *any* HTTP method,
to the plugin.
