pkgtoc v0.5.1

pkgtoc

Markdown table of contents creator for packages

• Install
• Usage
• Options
• Shields and Versioning
  • Private repos
• Lerna
• Custom glob patterns
• Table placement
• Example (create-react-app)

Exploring a monorepo can be really tedious and confusing at first glance. Adding a table of packages to your markdown file will improve discoverablility and allow new users to jump directly to the packages they recognize.

Install

yarn add pkgtoc

Usage

yarn pkgtoc <filename>

Options

  <filename>             File to write table to [README.md]
  --columns <n>          Columns to use [2]
  --dry-run              Don't write file [false]
  --file                 File to write table to [README.md]
  --glob <s>             Glob pattern to search for packages [packages/*]
  --lerna                Use lerna.json packages glob [false]
  --shields              Show NPM versions w/ shields.io [false]
  --shields-auto         Create shields using dynamic URL to support private [false]
  --shields-color <s>    Shield hex color [cb3837]

Shields and Versioning

To support private repos, pkgtoc auto-constructs shields from shields.io. The --shields flag will enable this feature.

By default the shields are set to NPM's red color, you can pass a different hex color in with the --shields-color flag.

Private repos

If you have private repos, you can enable the --shields-auto flag to dynamically construct a shield based on reading your package.json file.

Note: Auto-constructing version shields will cause extra churn in your README file.

Lerna

Passing the --lerna flag will instruct pkgtoc to read from your lerna.json file to grab all of your packages. You can also automate this during releases by the below script to the version script in package.json.

yarn pkgtoc && git add README.md

Custom glob patterns

You can pass a custom glob pattern (e.g. foo/*) with --glob to point to where you keep your packages. Currently only supports a single glob.

Table placement

Tables will go to the top of the file if START/END comments are missing. You can move the comments around to move the placement of the table. These comments <!-- START pkgtoc, keep to allow update --> are for finding/replacing any table content.

Example (create-react-app)

yarn pkgtoc --shields

Version	Packages
	babel-plugin-named-asset-importBabel plugin for named asset imports in Create React App
	babel-preset-react-appBabel preset used by Create React App
	confusing-browser-globalsA list of browser globals that are often used by mistake instead of local variables
	create-react-appCreate React apps with no build configuration.
	eslint-config-react-appESLint configuration used by Create React App
	react-dev-utilsWebpack utilities used by Create React App
	react-error-overlayAn overlay for displaying stack frames.
	react-scriptsConfiguration and scripts for Create React App.