Skip to content

Latest commit

 

History

History
412 lines (325 loc) · 10.4 KB

README.md

File metadata and controls

412 lines (325 loc) · 10.4 KB

Documentation

Expanded documentation for the readme-md-cli project.

Project Package Interpretation

When the readme-md CLI command is executed in a project directory's root it attempts to extract and interpret as much information from the package.json file as possible if one exists.

The documents generated by this utility consist of various sections consisting of both a title and a body. The following sections are generated based upon the gathered package data:

Title Section

This section consists of a level one header which acts as the document title and a brief project description in the body. The title is populated with the value of the package's name property while the body is populated with the value of the package's description property.

Given the following package:

{
  "name": "package-name",
  "description": "A brief description."
}

The following section markup will be output:

package-name
============
A brief description.

Install Section

This section consists of a level two header titled "Install" and a body containing a fenced code block with the package install command derived from the package's name property.

Given the following package:

{
  "name": "package-name"
}

The following section markup will be output:

Install
-------
```sh
npm install package-name
```

However, if a yarn.lock file is present in the root of the project directory the following variant markup will be output:

Install
-------
```sh
yarn add package-name # Or alternatively: `npm install package-name`
```

Global install instructions will be output in the event of preferGlobal being defined as true in the project's package.json.

Given the following package:

{
  "name": "package-name",
  "preferGlobal": true
}

The following section markup will be output:

Install
-------
```sh
npm install --global package-name
```

However, if a yarn.lock file is present in the root of the project directory the following variant markup will be output:

Install
-------
```sh
yarn global add package-name # Or alternatively: `npm install --global package-name`
```

Alternatively, if a pnpm-lock.yaml file is present in the root of the project directory the following variant markup will be output:

Install
-------
```sh
pnpm add --global package-name # Or alternatively: `npm install --global package-name`
```

If either pnpm or Yarn is specified in the engines property in the project's package.json that will take precedence over any lockfile detection.

Given the following package:

{
  "name": "package-name",
  "engines": {
    "pnpm": "*"
  },
  "preferGlobal": true
}

The following section markup will be output:

Install
-------
```sh
pnpm add --global package-name # Or alternatively: `npm install --global package-name`
```

Usage Section

A usage section can be drafted and stored in a .config/readme-md/sections/usage.md file relative to your project root. Given that $PROJECT represents the path to a project then an absolute path representation would be $PROJECT/.config/readme-md/sections/usage.md.

The contents of this Markdown document will be trimmed and posted directly below a "Usage" header following the "Install" section.

Testing Section

This section consists of a level two header titled "Testing" and a body containing a fenced code block with the package testing command if the package's scripts.test property is defined and a non-empty string.

Given the following package:

{
  "scripts": {
    "test": "cli-test-bin"
  }
}

The following section markup will be output:

Testing
-------
```sh
npm test
```

License Section

This section consists of a level two header titled "License" and a body containing a declaration of the package's license status.

Given the following package:

{
  "license": "EXAMPLE"
}

The following section markup will be output:

License
-------
The EXAMPLE License. See the license file for details.

In addition, if a LICENSE, LICENSE.md, LICENSE.rst, or LICENSE.txt file or any lowercased variant is present in the root of the project directory the license will be hyperlinked.

Given that a LICENSE file is present in our project root the following variant markup will be output:

License
-------
The EXAMPLE License. See the [license](LICENSE) file for details.

Project Level Configuration

Project specific configuration is stored in .config/readme-md/config.yaml file relative to your project root. Given that $PROJECT represents the path to a project then an absolute path representation would be $PROJECT/.config/readme-md/config.yaml.

Parameters are defined via the following properties:

badges

Enables and defines the rendering of assorted badges related to the project as provided by shields.io.

To utilize badge generation readme-md requires that your package.json's repository property is not only defined but also using a GitHub hyperlink.

The repository property must be defined in your package.json using the following declaration style:

{
  "repository": {
    "type": "git",
    "url": "git+https://github.com/example-user/example-project.git"
  }
}

Also, the following "shortcut syntax" is supported:

{
  "repository": "example-user/example-project"
}

In addition, the prefixed "shortcut syntax" is supported as well:

{
  "repository": "github:example-user/example-project"
}

Note: If you do not have a repository defined no badges will render. The badge rendering process will silently fail but will not interrupt the rendering of the project readme otherwise.

When readme-md init is invoked for a project the following default settings are defined:

badges:
  style: flat-square
  render:
    - github-actions
    - license
    - node.js
    - npm

Note: If your have no project level config as defined by readme-md init these are still the defaults applied when invoking readme-md.

To change the graphical style of the badges simply define badges.style as your desired choice out of "plastic", "flat", "flat-square", "for-the-badge", or "social" as described here.

The badges rendered can be changed by simply adding or removing them from the badges.render array. For instance, to only display a license badge you would define your configuration like so:

badges:
  style: flat-square
  render:
    - license

To disable badge rendering altogether the badges.render property needs to be set to an empty array like so:

badges:
  render: []

GitHub Actions Badge

If you choose to render a GitHub Actions badge it will try to obtain the required information automatically. So when specifying the following:

badges:
  render:
    - github-actions

The app will attempt to query your default Git branch, and it will look in the $PROJECT/.github/workflows directory for any files in the form of *.{yaml,yml}. If only one workflow file is found it will select that as the workflow to generate a badge for.

However, if you have multiple workflows you will need to specify which one to create a badge. Otherwise, the first detected workflow will be selected. So if we wanted to generate a badge for our $PROJECT/.github/workflows/workflow.yaml workflow we'd do like so:

badges:
  render:
    - github-actions
  config:
    github-actions:
      workflow: workflow.yaml

In a similar manner if we needed to specify the workflow branch as "develop" for example you would do it like this:

badges:
  render:
    - github-actions
  config:
    github-actions:
      branch: develop

License Badge

To render a license badge repository must be set to a GitHub repo and license must be set in your package.json In addition a license file must be present in your project. See License Section for a list of supported license files.

badges:
  render:
      - license

description

Setting this allows you to override the description in your project's package.json file.

description: My example description.

hero-image

Setting this will display a hero image in your readme immediately below the description. It accepts an object with two properties, alt and src.

hero-image:
  alt: A hero image
  src: path/to/image.png

prefer-npm

Setting this to true overrides any detection of pnpm or Yarn and utilizes npm based examples for the "Install" and "Testing" sections. Defaults to false.

prefer-npm: false

prefer-semicolons

This parameter decides whether statements in the autogenerated "Usage" section should be terminated by a semicolon. Defaults to true.

prefer-semicolons: true

quote-type

Can have a value of either "double" or "single". This parameter decides what quote type to use in the autogenerated "Usage" section. Defaults to "single".

quote-type: single

see-also

Enables and defines the contents of a "See Also" section positioned at the -1 section index. An object consisting of <link text>: <target uri> key/value pairs (e.g., Example: http://www.example.org/).

Given the following config:

see-also:
  Example: https://www.example.org/
  IETF: https://www.ietf.org/

The following section markup will be output:

See Also
--------
- [Example](https://www.example.org/)
- [IETF](https://www.ietf.org/)

See Also