Fills template blocks within your markdown readme files. With monorepo packages support build-in.
Use
<!-- {blockname} --><!-- {blockname} end -->within your markdown file.
After processing, contents between those comment blocks will be filled.
Look at this README.md source for comparison.
- Fields extracted from
package.json:
<!-- title -->
# @hitorisensei/markdown-readme-generator
<!-- title end -->
<!-- description -->
Fills template blocks within your markdown readme files. With monorepo packages support build-in.<!-- description end -->
- Deep package.json fields and inline rendering
`yargs` dependency version: **<!-- dependencies.yargs -->^17.0.1<!-- dependencies.yargs end -->** !
gives:
yargs dependency version: ^17.0.1 !
...etc
- List of monorepo packages (check --packages CLI option)
<!-- packages -->
## example
`example-monorepo-package`
A monorepo package example
<!-- packages end -->
- Links to packages
<!-- link example -->
[example](#example)
<!-- link example end -->
- [Custom block definitions](#Custom block definitions)
Options:
--version Show version number [boolean]
-o, --outFile output file path. Can be relative to project root
or absolute [required] [default: "README.md"]
-i, --inFile input/template file path. Can be relative to
project root or absolute. If inFile is used,
outFile will not contain template comment tags,
unless keepTags option is set.
[default: "README.md"]
--packages packages directory location [default: "packages/"]
--keepTags keep template tags even if inFile is used.
[boolean] [default: false]
--project root project location
--dry do not write output file, print results to stdout
instead [boolean]
--skipGeneratedHeader Do not add "DO NOT EDIT THIS FILE" header to output
files when template file is used
[boolean] [default: false]
-r, --recursive should also update readme files in packages
[default: true]
--create create readme file if one does not exist yet
[default: true]
-v, --verbose display verbose output [boolean] [default: false]
--custom load custom block definitions from file (js or
json)
--help Show help [boolean]
You can describe your own replacement blocksCustom with either .json file or .js module
const { execSync } = require('child_process');
const usageContent = execSync('node . --help').toString();
module.exports = {
// you can use https://www.npmjs.com/package/json2md notation
asJsonMD: [
{
code: {
language: 'bash',
content: [usageContent],
},
},
],
// or literal markdown
asLiteralMd: `
\`\`\`bash
${usageContent}
\`\`\`
`,
};
{
"asJsonMD": [
{
"code": {
"language": "bash",
"content": [
"Options:\n --version Show version number [boolean]\n -o, --outFile output file path. Can be relative to project root\n or absolute [required] [default: \"README.md\"]\n -i, --inFile input/template file path. Can be relative to\n project root or absolute. If inFile is used,\n outFile will not contain template comment tags,\n unless keepTags option is set.\n [default: \"README.md\"]\n --packages packages directory location [default: \"packages/\"]\n --keepTags keep template tags even if inFile is used.\n [boolean] [default: false]\n --project root project location\n --dry do not write output file, print results to stdout\n instead [boolean]\n --skipGeneratedHeader Do not add \"DO NOT EDIT THIS FILE\" header to output\n files when template file is used\n [boolean] [default: false]\n -r, --recursive should also update readme files in packages\n [default: true]\n --create create readme file if one does not exist yet\n [default: true]\n -v, --verbose display verbose output [boolean] [default: false]\n --custom load custom block definitions from file (js or\n json)\n --help Show help [boolean]\n"
]
}
}
],
"asLiteralMd": "\n ```bash\n Options:\n --version Show version number [boolean]\n -o, --outFile output file path. Can be relative to project root\n or absolute [required] [default: \"README.md\"]\n -i, --inFile input/template file path. Can be relative to\n project root or absolute. If inFile is used,\n outFile will not contain template comment tags,\n unless keepTags option is set.\n [default: \"README.md\"]\n --packages packages directory location [default: \"packages/\"]\n --keepTags keep template tags even if inFile is used.\n [boolean] [default: false]\n --project root project location\n --dry do not write output file, print results to stdout\n instead [boolean]\n --skipGeneratedHeader Do not add \"DO NOT EDIT THIS FILE\" header to output\n files when template file is used\n [boolean] [default: false]\n -r, --recursive should also update readme files in packages\n [default: true]\n --create create readme file if one does not exist yet\n [default: true]\n -v, --verbose display verbose output [boolean] [default: false]\n --custom load custom block definitions from file (js or\n json)\n --help Show help [boolean]\n\n ```\n "
}