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](https://docs.npmjs.com/files/package.json#name) property
while the body is populated with the value of the package's
[description](https://docs.npmjs.com/files/package.json#description-1) property.

Given the following package:

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

The following section markup will be output:

```md
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](https://docs.npmjs.com/files/package.json#name) property.

Given the following package:

```json
{
  "name": "package-name"
}
```

The following section markup will be output:

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

However, if a [yarn.lock](https://yarnpkg.com/en/docs/yarn-lock) file is present
in the root of the project directory the following variant markup will be
output:

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

Alternatively, if a [pnpm-lock.yaml](https://pnpm.io/git#lockfiles) file is present in the root of the project directory the following variant markup will be output:

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

Global install instructions will be output in the event of
[preferGlobal](https://docs.npmjs.com/files/package.json#preferglobal) being
defined as `true` in the project's `package.json`.

Given the following package:

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

The following section markup will be output:

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

However, if a [yarn.lock](https://yarnpkg.com/en/docs/yarn-lock) file is present
in the root of the project directory the following variant markup will be
output:

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

Alternatively, if a [pnpm-lock.yaml](https://pnpm.io/git#lockfiles) file is present in the root of the project directory the following variant markup will be output:

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

If either [pnpm](https://pnpm.io/) or [Yarn](https://yarnpkg.com/) is specified in the [engines](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#engines) property in the project's `package.json` that will take precedence over any lockfile detection.

Given the following package:

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

The following section markup will be output:

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

Lastly, if [npm](https://docs.npmjs.com/cli/v10/commands/npm), [pnpm](https://pnpm.io/), or [Yarn](https://yarnpkg.com/) is specified in the `package.json` in the `packageManager` field this will take precedence over anything defined in `engines` or any lockfiles present.

Given the following package:

```json
{
  "name": "package-name",
  "engines": {
    "yarn": "*"
  },
  "packageManager": "pnpm@^9.12.1",
  "preferGlobal": true
}
```

The following section markup will be output:

````md
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:

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

The following section markup will be output:

````md
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:

```json
{
  "license": "EXAMPLE"
}
```

The following section markup will be output:

```md
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:

```md
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](http://shields.io/).

To utilize badge generation `readme-md` requires that your `package.json`'s
[repository](https://docs.npmjs.com/files/package.json#repository) property is
not only defined but also using a [GitHub](https://github.com/) hyperlink.

The [repository](https://docs.npmjs.com/files/package.json#repository) property
must be defined in your `package.json` using the following declaration style:

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

Also, the following "shortcut syntax" is supported:

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

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

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

_**Note:** If you do not have a
[repository](https://docs.npmjs.com/files/package.json#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:

```yml
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](https://shields.io/badges#:~:text=Possible%20values%3A%20%5Bflat%2C%20flat%2Dsquare%2C%20plastic%2C%20for%2Dthe%2Dbadge%2C%20social%5D).

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:

```yml
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:

```yml
badges:
  render: []
```

#### GitHub Actions Badge
If you choose to render a [GitHub Actions](https://github.com/features/actions)
badge it will try to obtain the required information automatically. So when
specifying the following:

```yml
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:

```yml
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:

```yml
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](#license-section) for a list of supported
license files.

```yml
badges:
  render:
      - license
```

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

```yml
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`.

```yml
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`.

```yml
prefer-npm: false
```

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

```yml
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".

```yml
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:

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

The following section markup will be output:

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

See Also
--------
- [package.json Spec](https://docs.npmjs.com/files/package.json)
- [YAML Spec](http://www.yaml.org/spec/1.2/spec.html)