Readmix is a command-line README generator.
You can find the source code at iaseth/readmix.
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.
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.
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.
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.
-
Easily insert the contents of any file inside your
README:This will insert the contents of your
LICENSEfile:{{ "LICENSE" | File }}This will insert the contents of
tsconfig.jsonfile into a code-block:{{ "tsconfig.json" | CodeFile }}Here,
FileandCodeFileare filters provided byReadmix. -
Easy access to
package.jsonandpackage-lock.json:This will print the app version:
{{ packageJson.version }}This will print the app name:
{{ packageLockJson.name }}packageJsonandpackageLockJsonare available in everyrxfile assuming the correspondingJSONfiles are present. -
Allows you to write comments in your
markdownfiles:
:: This is a comment.
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. |
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.
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.
You can use the File filter to include the contents of your LICENSE file inside your README:
{{ "LICENSE" | File }}
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().
You can use the giveCredit() mixin to include a section giving credit to Readmix:
{{ giveCredit() }}
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 |
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 |
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 |
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.
This file was generated using readmix.