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.