README.md.rx

# readmix

{{ npm.link("Readmix") }} is a command-line `README` generator.

You can find the source code at {{ gh.link("iaseth/readmix") }}.


## Table of contents
{{ tableOfContents(doc) }}



## Installation
You can install {{ "readmix" | NpmLink }} with the following command:
=> npm i -g readmix

Now you should be able to run the `readmix` command in your terminal.



## Getting started
To get started with `Readmix`, create a file called `LICENSE.rx` in your current directory.
Put the following text in that file:
=> {{ mitLicense("Ankur Seth") }}
Here `mitLicense` is a mixin. A `mixin` is just a `JavaScript` function that returns a `string`.
This particular `mixin` is used to insert the `MIT License` in your name.
`Readmix` contains similar `mixins` like `apache2License` and `gnuGplLicense` to insert any popular license in your file.
Most of the license `mixins` accept 2 `args`, `Name` and `Year`.

Now, you can compile the file with the following command:
=> readmix --compile --markdown LICENSE.rx
This will output a file called `LICENSE` containing the `MIT License` with your name in it.



## Filename conventions
All readmix files end with the `.rx` entension. Readmix will only compile files that end with the `.rx` extension.
The output file will have the same filename but with the `.rx` removed.

| Input Filename | Output Filename |
| -------------- | --------------- |
| `README.md.rx` | `README.md`     |
| `LICENSE.rx`   | `LICENSE`       |

While the main purpose of `Readmix` is to generate `markdown`, you can use it to generate almost any filetype.
I often use `Readmix` to generate `.env`, `tex` and `css` files.



## Usage
To compile your `README.rx` to `README`:
=> readmix --compile --markdown README.rx

If you want the output file to be called `README.md`, you should name the input file as `README.md.rx`.

To compile all `rx` files in the current directory:
=> readmix --compile --markdown .

To compile all `rx` files in the current directory and all subdirectories:
=> readmix --compile --markdown --recursive .

To compile your `README.rx` to `HTML`:
=> readmix --compile --html README.rx

To run a preview server for all `rx` files in the current directory:
=> readmix --preview .
Not you can open [http://127.0.0.1:1996/](http://127.0.0.1:1996/) is your browser to see how your `rx` will look after compilation.



## Features
* Easily insert the contents of any file inside your `README`:

	This will insert the contents of your `LICENSE` file:
	=> {{ "LICENSE" | File }}

	This will insert the contents of `tsconfig.json` file into a code-block:
	=> {{ "tsconfig.json" | CodeFile }}

	Here, `File` and `CodeFile` are filters provided by `{{ appName }}`.

* Easy access to `package.json` and `package-lock.json`:

	This will print the app version:
	=> {{ packageJson.version }}

	This will print the app name:
	=> {{ packageLockJson.name }}

	`packageJson` and `packageLockJson` are available in every `rx` file assuming the corresponding `JSON` files are present.

* Allows you to write comments in your `markdown` files:
=> :: This is a comment.



## Flags

The  `readmix` command accepts the following command line options:

{{ arrayTable(Rx.flags, {singleFlag: "`Short`", doubleFlag: "`Long`", description: "Description"}) }}



## Props

Every `rx` file has access to the global `Rx` object with the following properties:
{{ Rx | PrintPropsTable }}

Every `property` on the `Rx` object is also available globally.
So, you can just write `appName` instead of `Rx.appName`.



## Filters

In addition to default filters in `nunjucks`, `Readmix` provides you with these additional `filters`:
{{ Rx.filters | PrintFiltersTable }}
Each `filter` is available globally.


### Example usage
You can use the `File` filter to include the contents of your `LICENSE` file inside your `README`:

=> {{ "LICENSE" | File }}



## Mixins

In addition to props, the `Rx` object also contains a `mixins` object with the following `mixins`:
{{ Rx.mixins | PrintFunctionsTable }}

Every `function` on the `Rx.mixins` object is also available globally.
So, you can just write `giveCredit()` instead of `Rx.mixins.giveCredit()` or `mixins.giveCredit()`.

### Example usage
You can use the `giveCredit()` mixin to include a section giving credit to `{{ appName }}`:

=> {{ giveCredit() }}


## Package details
{{ npm.packageDetails() }}


## Dependencies
{{ npm.dependencyTable() }}


## Dev dependencies
{{ npm.devDependencyTable() }}


## License
{{ "LICENSE.md" | File }}


{{ giveCredit() }}