sounisi5011/readme-generator

---
buildStatus:
  gitHubActions:
    workflowName: GitHub Actions
codeClimate:
  maintainabilityBadgeURL: https://api.codeclimate.com/v1/badges/1aabcc39ecde1caeb45d/maintainability
---
# {{ pkg.name }}

{% if not pkg.private -%}
[![Go to the latest release page on npm](https://img.shields.io/npm/v/{{ pkg.name }}.svg)]({{ pkg.name | npmURL }})
{% endif -%}
[![License: {{ pkg.license }}](https://img.shields.io/static/v1?label=license&message={{ pkg.license | urlencode }}&color=green)]({{ '/LICENSE' | repoBrowseURL(branch='master') }})
{%- if pkg.engines and pkg.engines.node %}
![Supported Node.js version: {{ pkg.engines.node }}](https://img.shields.io/static/v1?label=node&message={{ pkg.engines.node | urlencode }}&color=brightgreen)
{%- endif %}
{%- if (pkg.types or pkg.typings) and deps.typescript %}
![Type Definitions: TypeScript](https://img.shields.io/static/v1?label=types&message=TypeScript&color=blue)
{%- endif %}
{%- if deps.jest %}
[![Tested with Jest](https://img.shields.io/badge/tested_with-jest-99424f.svg)](https://github.com/facebook/jest)
{%- endif %}
{%- if deps.commitizen %}
[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)
{%- endif %}
{%- if deps.shipjs %}
[![Deploy with Ship.js](https://img.shields.io/badge/deploy-🛳%20Ship.js-blue?style=flat)](https://github.com/algolia/shipjs)
{%- endif %}
{%- if not pkg.private %}
[![Minified Bundle Size Details](https://img.shields.io/bundlephobia/min/{{ pkg.name }}/{{ pkg.version }})](https://bundlephobia.com/result?p={{ pkg.name }}@{{ pkg.version }})
[![Install Size Details](https://packagephobia.now.sh/badge?p={{ pkg.name }}@{{ pkg.version }})](https://packagephobia.now.sh/result?p={{ pkg.name }}@{{ pkg.version }})
{%- endif %}
[![Dependencies Status](https://david-dm.org/{{ repo.user }}/{{ repo.project }}/status.svg)](https://david-dm.org/{{ repo.user }}/{{ repo.project }})
{%- if buildStatus %}
{% if buildStatus.gitHubActions.workflowName -%}
    {%- if not buildStatus.gitHubActions.branch -%}
        {%- setProp buildStatus.gitHubActions.branch = 'master' -%}
    {%- endif -%}
    {%- setProp buildStatus.badgeURL -%}
        https://github.com/{{ repo.user }}/{{ repo.project }}/workflows/{{ buildStatus.gitHubActions.workflowName | urlencode }}/badge.svg?branch={{ buildStatus.gitHubActions.branch | urlencode }}
    {%- endset -%}
    {%- setProp buildStatus.pageURL -%}
        https://github.com/{{ repo.user }}/{{ repo.project }}/actions?query={% filter urlencode %}workflow:"{{ buildStatus.gitHubActions.workflowName }}" branch:{{ buildStatus.gitHubActions.branch }}{% endfilter %}
    {%- endset -%}
{%- endif -%}
{%- if buildStatus.pageURL -%}
[![Build Status]({{ buildStatus.badgeURL }})]({{ buildStatus.pageURL }})
{%- else -%}
![Build Status]({{ buildStatus.badgeURL }})
{%- endif -%}
{%- endif %}
{%- if codeClimate %}
{%- if codeClimate.maintainabilityBadgeURL %}
[![Maintainability Status]({{ codeClimate.maintainabilityBadgeURL }})](https://codeclimate.com/github/{{ repo.user }}/{{ repo.project }}/maintainability)
{%- endif %}
{%- if codeClimate.testCoverageBadgeURL %}
[![Test Coverage Status]({{ codeClimate.testCoverageBadgeURL }})](https://codeclimate.com/github/{{ repo.user }}/{{ repo.project }}/test_coverage)
{%- endif %}
{%- endif %}

{{ pkg.description | replace(r/\S+\.[a-z]+/g, '`$&`') }}.

## Install

```sh
npm install --save-dev {{ repo.shortcut(semver=(pkg.version if pkg.version | isOlderReleasedVersion == false)) }}
```

## Usage

```console
$ {{ pkg.name | omitPackageScope }} --help
{{ 'ts-node --transpile-only ./src/index.ts --help' | execCommand }}
```

### Setting API token when using `{{ pkg.name }}` with private repository

`{{ pkg.name }}` reads the repository information (for example, a list of pushed tags). If you want to use it in a private repository, you need to set the API token according to the repository type.

#### GitHub

[Get a GitHub personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token#creating-a-token) and specify it in the environment variable `GITHUB_TOKEN`.

```console
$ GITHUB_TOKEN="..." {{ pkg.name | omitPackageScope }}
```

If you use the `{{ pkg.name }}` with GitHub Actions, you don't need to get a personal access token; you can use [`GITHUB_TOKEN` secret](https://docs.github.com/en/actions/reference/authentication-in-a-workflow#about-the-github_token-secret) in GitHub Actions.

```yaml
steps:
  - run: npx {{ pkg.name | omitPackageScope }}
    env:
      {% raw %}GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}{% endraw %}
```

#### GitLab

Currently not supported.

#### Bitbucket

Currently not supported.

### Default Defined Variables

* `pkg` - [Source]({{ '/src/main.ts' | repoBrowseURL | linesSelectedURL( start=r/= *readPkgJson\(/,  end=r/Object\.assign\([a-zA-Z0-9]+, *\{ *pkg *\}\)|\.pkg *= *pkg *[;\n]/ ) }}) and [Source]({{ '/src/utils/package-json.ts' | repoBrowseURL | linesSelectedURL( r/^export function readPkgJson\((?:(?!\})[^\n]*\n)+/m ) }})

    Object value of `package.json`

* `repo` - [Source]({{ '/src/main.ts' | repoBrowseURL | linesSelectedURL( r/^( +)repo: *\{\n+(?:\1 [^\n]+\n+)+\1/m ) }})

    Object value indicating repository data.
    It is generate by reading [the `repository` field] of [`package.json`].

[`package.json`]: https://docs.npmjs.com/files/package.json
[the `repository` field]: https://docs.npmjs.com/files/package.json#repository

* `deps` - [Source]({{ '/src/main.ts' | repoBrowseURL | linesSelectedURL( start=r/^ +const deps =/m, end=r/\btemplateContext\b[^\n]*\bdeps\b/ ) }}) and [Source]({{ '/src/utils/installed-dependencies.ts' | repoBrowseURL }})

    Object value indicating dependencies data.
    It is generate by reading `package-lock.json`.

### Additional Tags

#### `setProp`

[Source]({{ '/src/template-tags/setProp.ts' | repoBrowseURL }})

`setProp` lets you create/modify variable properties.

template:

```nunjucks{% raw %}
{% set data = {} %}
{{ data | dump }}
{% setProp data.username = 'joe' %}
{{ data | dump }}
```{% endraw %}

output:

```
{% set data = {} %}
{{ data | dump }}
{% setProp data.username = 'joe' %}
{{ data | dump }}
```

`setProp` can also create/modify variables.
So you can replace [the `set` tag] with `setProp`.

[the `set` tag]: https://mozilla.github.io/nunjucks/templating.html#set

{% set username = '' -%}
template:

```nunjucks{% raw %}
username: {{ username }}
{% setProp username = "joe" %}
username: {{ username }}
```{% endraw %}

output:

```
username: {{ username }}
{% setProp username = "joe" %}
username: {{ username }}
```

Like the `set` tag, `setProp` can also capture the contents of a block.

template:

``````nunjucks{% raw %}
{% setProp data.gitignore = {} %}
{% setProp data.gitignore.contents -%}
    {% include '.gitignore' %}
{%- endset %}

**`.gitignore`**
```
{{ data.gitignore.contents }}
```
``````{% endraw %}

output:

``````
{% setProp data.gitignore = {} %}
{% setProp data.gitignore.contents -%}
    {% include '.gitignore' %}
{%- endset %}

**`.gitignore`**
```
{{ data.gitignore.contents }}
```
``````

### Additional Filters

#### `omitPackageScope`

[Source]({{ '/src/template-filters/omitPackageScope.ts' | repoBrowseURL | linesSelectedURL( r/^export function omitPackageScope\([^\n]*\n+(?: [^\n]+\n+)+\}/m ) }})

template:

```nunjucks{% raw %}
{{ '@foo/bar' | omitPackageScope }}
```{% endraw %}

output:

```
{{ '@foo/bar' | omitPackageScope }}
```

#### `npmURL`

[Source]({{ '/src/template-filters/npmURL.ts' | repoBrowseURL | linesSelectedURL( r/^export function npmURL\([^\n]*\n+(?: [^\n]+\n+)+\}/m ) }})

template:

```nunjucks{% raw %}
- {{ 'foo' | npmURL }}
- {{ 'foo@1.2.3' | npmURL }}
- {{ 'foo@legacy' | npmURL }}
- {{ '@hoge/bar' | npmURL }}
- {{ '@hoge/bar@0.1.1-alpha' | npmURL }}
- {{ '@hoge/bar@dev' | npmURL }}
- {{ pkg.name | npmURL }}
- {{ deps.nunjucks | npmURL }}
- {{ deps['@types/node'] | npmURL }}
```{% endraw %}

output:

```
- {{ 'foo' | npmURL }}
- {{ 'foo@1.2.3' | npmURL }}
- {{ 'foo@legacy' | npmURL }}
- {{ '@hoge/bar' | npmURL }}
- {{ '@hoge/bar@0.1.1-alpha' | npmURL }}
- {{ '@hoge/bar@dev' | npmURL }}
- {{ pkg.name | npmURL }}
- {{ deps.nunjucks | npmURL }}
- {{ deps['@types/node'] | npmURL }}
```

#### `execCommand`

[Source]({{ '/src/template-filters/execCommand.ts' | repoBrowseURL | linesSelectedURL( r/^export async function execCommand\([^\n]*\n+(?: [^\n]+\n+)+\}/m ) }})

template:

```nunjucks{% raw %}
{{ 'tsc --version' | execCommand }}
---
{{ ['eslint', '--version'] | execCommand }}
```{% endraw %}

output:

```
{{ 'tsc --version' | execCommand }}
---
{{ ['eslint', '--version'] | execCommand }}
```

#### `linesSelectedURL`

[Source]({{ '/src/template-filters/linesSelectedURL.ts' | repoBrowseURL | linesSelectedURL( r/^export async function linesSelectedURL\([^\n]*\n+(?: [^\n]+\n+)+\}/m ) }})

template:

```nunjucks{% raw %}
11. {{ '/types.node_modules/npm-path.d.ts' | repoBrowseURL | linesSelectedURL(       r/^export =/ ) }}
21. {{ '/types.node_modules/npm-path.d.ts' | repoBrowseURL | linesSelectedURL( start=r/^export =/ ) }}

12. {{ '/types.node_modules/npm-path.d.ts' | repoBrowseURL | linesSelectedURL(       r/^(declare [^\n]*\n)+/m ) }}
22. {{ '/types.node_modules/npm-path.d.ts' | repoBrowseURL | linesSelectedURL( start=r/^(declare [^\n]*\n)+/m ) }}

13. {{ '/types.node_modules/npm-path.d.ts' | repoBrowseURL | linesSelectedURL(       r/^(declare [^\n]*)(\ndeclare [^\n]*)*/m ) }}
23. {{ '/types.node_modules/npm-path.d.ts' | repoBrowseURL | linesSelectedURL( start=r/^(declare [^\n]*)(\ndeclare [^\n]*)*/m ) }}

34. {{ '/.eslintrc.yaml' | repoBrowseURL | linesSelectedURL( start=r/^parserOptions:$/m, end=r/.\n\S/ ) }}
35. {{ '/.eslintrc.yaml' | repoBrowseURL | linesSelectedURL( start=r/^parserOptions:$/m, end=r/.\n(?=\S)/ ) }}
36. {{ '/.eslintrc.yaml' | repoBrowseURL | linesSelectedURL( start=r/^parserOptions:$/m, end=r/.(?=\n\S)/ ) }}

41. {{ '/.prettierrc.yaml' | repoBrowseURL | linesSelectedURL( start=r/^ /, end=r/^[^\n]*$/ ) }}

{% set repoData = { repoType: 'github',
                    fileFullpath: '.eslintrc.yaml',
                    browseURL: 'http://example.com/path/to' }
-%}
51. {{ repoData | linesSelectedURL(r/(?<!\w)sourceType:/) }}
```{% endraw %}

output:

```
11. {{ '/types.node_modules/npm-path.d.ts' | repoBrowseURL | linesSelectedURL(       r/^export =/ ) }}
21. {{ '/types.node_modules/npm-path.d.ts' | repoBrowseURL | linesSelectedURL( start=r/^export =/ ) }}

12. {{ '/types.node_modules/npm-path.d.ts' | repoBrowseURL | linesSelectedURL(       r/^(declare [^\n]*\n)+/m ) }}
22. {{ '/types.node_modules/npm-path.d.ts' | repoBrowseURL | linesSelectedURL( start=r/^(declare [^\n]*\n)+/m ) }}

13. {{ '/types.node_modules/npm-path.d.ts' | repoBrowseURL | linesSelectedURL(       r/^(declare [^\n]*)(\ndeclare [^\n]*)*/m ) }}
23. {{ '/types.node_modules/npm-path.d.ts' | repoBrowseURL | linesSelectedURL( start=r/^(declare [^\n]*)(\ndeclare [^\n]*)*/m ) }}

34. {{ '/.eslintrc.yaml' | repoBrowseURL | linesSelectedURL( start=r/^parserOptions:$/m, end=r/.\n\S/ ) }}
35. {{ '/.eslintrc.yaml' | repoBrowseURL | linesSelectedURL( start=r/^parserOptions:$/m, end=r/.\n(?=\S)/ ) }}
36. {{ '/.eslintrc.yaml' | repoBrowseURL | linesSelectedURL( start=r/^parserOptions:$/m, end=r/.(?=\n\S)/ ) }}

41. {{ '/.prettierrc.yaml' | repoBrowseURL | linesSelectedURL( start=r/^ /, end=r/^[^\n]*$/ ) }}

{% set repoData = { repoType: 'github',
                    fileFullpath: '.eslintrc.yaml',
                    browseURL: 'http://example.com/path/to' }
-%}
51. {{ repoData | linesSelectedURL(r/(?<!\w)sourceType:/) }}
```

#### `repoBrowseURL`

*This filter is only defined if the generator was able to read the remote repository from [the `repository` field] of [`package.json`]*.

[Source]({{ '/src/template-filters/repoBrowseURL.ts' | repoBrowseURL | linesSelectedURL( r/^( +)return async function repoBrowseURL\([^\n]*\n+(?:\1 [^\n]+\n+)+\1\}/m ) }})

template:

```nunjucks{% raw %}
11. {{ '/.template/README.njk' | repoBrowseURL }}
12. {{ '/.template/README.njk' | repoBrowseURL(tag='foo') }}
13. {{ '/.template/README.njk' | repoBrowseURL(branch='gh-pages') }}
14. {{ '/.template/README.njk' | repoBrowseURL(commit='4626dfa') }}
15. {{ '/.template/README.njk' | repoBrowseURL(committish='COMMIT-ISH') }}

21. {{ '.template/README.njk' | repoBrowseURL }}

31. {{ './README.njk' | repoBrowseURL }}

41. {{ '../src/index.ts' | repoBrowseURL }}
```{% endraw %}

output:

```
11. {{ '/.template/README.njk' | repoBrowseURL }}
12. {{ '/.template/README.njk' | repoBrowseURL(tag='foo') }}
13. {{ '/.template/README.njk' | repoBrowseURL(branch='gh-pages') }}
14. {{ '/.template/README.njk' | repoBrowseURL(commit='4626dfa') }}
15. {{ '/.template/README.njk' | repoBrowseURL(committish='COMMIT-ISH') }}

21. {{ '.template/README.njk' | repoBrowseURL }}

31. {{ './README.njk' | repoBrowseURL }}

41. {{ '../src/index.ts' | repoBrowseURL }}
```

#### `isOlderReleasedVersion`

*This filter is only defined if the generator was able to read the remote repository from [the `repository` field] of [`package.json`]*.

Determines if a version has been released in a remote repository, and if the current commit is more recent than the version's corresponding tag.
The version detection is done using the same algorithm as the `#semver:<semver>` format of [the `npm install` command][npm-install].
There are three types of return values:

[npm-install]: https://docs.npmjs.com/cli/install

* `true` - If the specified version of a git tag exists in a remote repository and the current commit and git tag are different.
* `false`
    * If the specified version of a git tag exists in a remote repository and the current commit and git tag are same.
    * If the specified version of a git tag does not exist in the remote repository.
* `null`
    * If a remote repository does not exist.
    * If can't access a remote repository.
    * If the current directory is not a git repository.
    * Run the `git init` command, then haven't first committed yet.

[Source]({{ '/src/template-filters/isOlderReleasedVersion.ts' | repoBrowseURL | linesSelectedURL( r/^( +)return async function isOlderReleasedVersion\([^\n]*\n+(?:\1 [^\n]+\n+)+\1\}/m ) }})

template:

```nunjucks{% raw %}
0.0.2: {{ '0.0.2' | isOlderReleasedVersion | dump }}
{{pkg.version}}: {{ pkg.version | isOlderReleasedVersion | dump }}
999.90.1: {{ '999.90.1' | isOlderReleasedVersion | dump }}
```{% endraw %}

output:

```
0.0.2: {{ '0.0.2' | isOlderReleasedVersion | dump }}
{{pkg.version}}: {{ pkg.version | isOlderReleasedVersion | dump }}
999.90.1: {{ '999.90.1' | isOlderReleasedVersion | dump }}
```

## Tests

To run the test suite, first install the dependencies, then run `npm test`:

```sh
npm install
npm test
```

## Contributing

see [CONTRIBUTING.md]({{ '/CONTRIBUTING.md' | repoBrowseURL(branch='master') }})