readmix

Readmix is a command-line README generator.

You can find the source code at iaseth/readmix.

Table of contents

• readmix
  • Table of contents
  • Installation
  • Getting started
  • Filename conventions
  • Usage
  • Features
  • Flags
  • Props
  • Filters
    • Example usage
  • Mixins
    • Example usage
  • Package details
  • Dependencies
  • Dev dependencies
  • License

Installation

You can install readmix 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/ 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 Readmix.

• 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:

| Short | Long | Description | | --------- | ---------------- | ---------------------------------------------------------------------------- | | -A | --api | Run the Readmix JSON API. | | -C | --compile | Compile to Markdown. | | -D | --debug | Turns debug mode ON. | | -F | --force | Force update files. | | -H | --html | Compile to HTML. | | -I | --init | Initialize readmix in directory, creates rxconfig.json with default options. | | -L | --list | List all input files. | | -M | --markdown | Compile to Markdown. | | -O | --open | Open live preview in default web browser. | | -P | --preview | Run a live preview server. | | -Q | --quiet | Turns quiet mode ON. | | -R | --recursive | Select subdirectories recursively. | | -S | --status | Print status. | | -V | --version | Print version. | | -W | --watch | Watch input files for changes. | | -X | --experimental | Turns experimental mode ON. | | -Z | --zen | Turns zen mode ON. |

Props

Every rx file has access to the global Rx object with the following properties: | Prop | Value | | --- | --- | | appName | Readmix | | commands | Object [8] | | filters | Object [17] | | flags | Object [17] | | helpers | Object [22] | | mixins | Object [24] | | sugars | Object [3] | | utils | Object [1] | | descriptions | Object [4] | | packageJson | Object [14] | | packageLockJson | Object [5] | | tsconfigJson | Object [2] | | rxconfigJson | Object [4] | | gitconfig | Object [3] |

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: | Filter | Args | | --- | --- | | Table | 0 | | Print | 0 | | PrintPropsTable | 0 | | PrintFunctionsTable | 0 | | PrintFiltersTable | 0 | | File | 0 | | CodeFile | 0 | | CodeBlock | 0 | | Indent | 0 | | GithubLink | 0 | | NpmLink | 0 |

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: | Function | Args | | --- | --- | | arrayTable() | 2 | | objectTable() | 1 | | table() | 0 | | giveCredit() | 0 | | apache2License() | 1 | | bsd2License() | 1 | | bsd3License() | 1 | | cclLicense() | 0 | | epl1License() | 0 | | epl2License() | 0 | | gnuGplLicense() | 1 | | gnuLgplLicense() | 1 | | iscLicense() | 1 | | mitLicense() | 1 | | mplLicense() | 0 | | msplLicense() | 0 | | zlibLicense() | 1 | | tableOfContents() | 1 |

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 Readmix:

{{ giveCredit() }}

Package details

| Name | Value | | -------------- | ----------------------------------------------- | | Name | readmix | | Description | Readmix is a command-line markdown generator. | | Version | 0.9.0 | | Author | iaseth | | Homepage | https://readmix.js.org | | Repository | iaseth/readmix | | License | MIT | | Dependencies | 8 |

Dependencies

| | Package | Version | | --- | ----------- | ----------- | | 1 | cors | ^2.8.5 | | 2 | express | ^4.18.2 | | 3 | ini | ^4.1.0 | | 4 | js-yaml | ^4.1.0 | | 5 | json5 | ^2.2.3 | | 6 | marked | ^4.3.0 | | 7 | nunjucks | ^3.2.4 | | 8 | toml | ^3.0.0 |

Dev dependencies

| | Package | Version | | --- | ------------------ | ----------- | | 1 | @types/cors | ^2.8.13 | | 2 | @types/express | ^4.17.17 | | 3 | @types/marked | ^4.0.8 | | 4 | @types/node | ^18.16.0 | | 5 | @types/nunjucks | ^3.2.2 | | 6 | autoprefixer | ^10.4.14 | | 7 | html-color-names | ^0.3.2 | | 8 | jest | ^29.5.0 | | 9 | postcss | ^8.4.23 | | 10 | tailwindcss | ^3.3.2 |

License

MIT License

Copyright (c) Ankur Seth.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Credit

This file was generated using readmix.