@hitorisensei/markdown-readme-generator

@hitorisensei/markdown-readme-generator

Fills template blocks within your markdown readme files. With monorepo packages support build-in.

Usage

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.

Block supplied by default:

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

CLI Options

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]

Custom block definitions

You can describe your own replacement blocksCustom with either .json file or .js module

JS

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}
    \`\`\`
  `,
};

JSON

{
  "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  "
}