Skip to content

Commit

Permalink
docs: use vitepress (#3921)
Browse files Browse the repository at this point in the history
* docs: use vitepress

* docs: update src docs references
  • Loading branch information
marcalexiei authored and escapedcat committed Feb 27, 2024
1 parent 02bf398 commit 868983c
Show file tree
Hide file tree
Showing 59 changed files with 1,844 additions and 2,127 deletions.
36 changes: 31 additions & 5 deletions .github/CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ Please consider these guidelines when filing a pull request:
_ What you added
_ What you removed

## Coding Rules
### Coding Rules

To keep the code base of commitlint neat and tidy the following rules apply to every change

Expand All @@ -48,7 +48,7 @@ To keep the code base of commitlint neat and tidy the following rules apply to e
- Favor micro library over swiss army knives (rimraf, ncp vs. fs-extra)
- Be awesome

## Commit Rules
### Commit Rules

To help everyone with understanding the commit history of commitlint the following commit rules are enforced.
To make your life easier commitlint is commitizen-friendly and provides the npm run-script `commit`.
Expand All @@ -61,17 +61,43 @@ To make your life easier commitlint is commitizen-friendly and provides the npm
- maximum of 100 characters
- message format of `$type($scope): $message`

## Testing
### Environment setup

From the project root directory, use the following commands to run the test suite
This project uses `yarn`, so be sure that it is available in your shell environment.

After cloning the repo run

```sh
yarn clean
yarn install
```

### Testing

From the project root directory, use the following commands to run the test suite

```sh
yarn build
yarn test
```

### Documentation updates

Documentation uses `vitepress`.
To run and edit the documentation locally run:

```sh
yarn docs-dev
```

To have a preview of the deployed doc run:

```sh
yarn docs-build
yarn docs-serve
```

For more information refer to [vitepress documentation](https://vitepress.dev).

## Package dependency overview

![commitlint-dependencies](https://user-images.githubusercontent.com/4248851/58385093-34b79780-7feb-11e9-8f27-bffc4aca3eba.png)
Expand Down
61 changes: 61 additions & 0 deletions .github/workflows/docs-deploy.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
name: Deploy docs site to Pages

on:
push:
branches: [main]

workflow_dispatch:

permissions:
contents: read
pages: write
id-token: write

concurrency:
group: pages
cancel-in-progress: false

jobs:
# Build job
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0

- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 18
cache: yarn

- name: Setup Pages
uses: actions/configure-pages@v4

- name: Install dependencies
run: yarn install

- name: Build with VitePress
run: |
yarn docs-build
touch ./docs/.vitepress/dist/.nojekyll
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: ./docs/.vitepress/dist

# Deployment job
deploy:
environment:
name: docs
url: ${{ steps.deployment.outputs.page_url }}
needs: build
runs-on: ubuntu-latest
name: Deploy
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -13,5 +13,8 @@ package.json.lerna_backup
tsconfig.tsbuildinfo
coverage

docs/.vitepress/dist
docs/.vitepress/cache

# For testing nested workspaces does not have the package's dependencies name in the scope
!**/config-lerna-scopes/fixtures/nested-workspaces/**/node_modules
15 changes: 5 additions & 10 deletions @commitlint/cli/README.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,11 @@
> Lint commit messages
# @commitlint/cli

<p align="center">
<img width="750" src="https://conventional-changelog.github.io/commitlint/assets/commitlint.svg">
<img width="750" src="https://commitlint.js.org/assets/commitlint.svg">
</p>

# @commitlint/cli

## Getting started
Lint commit messages

```
npm install --save-dev @commitlint/cli @commitlint/config-angular
echo "module.exports = {extends: ['@commitlint/config-angular']};" > commitlint.config.js
```
## Documentation

Consult [docs/cli](https://conventional-changelog.github.io/commitlint/#/reference-cli) for comprehensive documentation.
Consult [CLI reference](https://commitlint.js.org/reference/cli) for comprehensive documentation.
2 changes: 1 addition & 1 deletion @commitlint/cli/src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -306,7 +306,7 @@ async function main(args: MainArgs): Promise<void> {
name: 'empty-rules',
message: [
'Please add rules to your `commitlint.config.js`',
' - Getting started guide: https://commitlint.js.org/#/?id=getting-started',
' - Getting started guide: https://commitlint.js.org/guides/getting-started',
' - Example config: https://github.com/conventional-changelog/commitlint/blob/master/%40commitlint/config-conventional/src/index.ts',
].join('\n'),
},
Expand Down
8 changes: 4 additions & 4 deletions @commitlint/config-angular/README.md
Original file line number Diff line number Diff line change
@@ -1,23 +1,23 @@
> Lint your commits, angular-style
# @commitlint/config-angular

Lint your commits, angular-style

Shareable `commitlint` config enforcing the [Angular commit convention](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#commit).
Use with [@commitlint/cli](../cli) and [@commitlint/prompt-cli](../prompt-cli).

## Getting started

```sh
npm install --save-dev @commitlint/config-angular @commitlint/cli
echo "module.exports = {extends: ['@commitlint/config-angular']};" > commitlint.config.js
echo "export default {extends: ['@commitlint/config-angular']};" > commitlint.config.js
```

## Rules

### Problems

The following rules are considered problems for `@commitlint/config-angular` and will yield a non-zero exit code when not met.
Consult [docs/rules](https://conventional-changelog.github.io/commitlint/#/reference-rules) for a list of available rules.
Consult [Rules reference](https://commitlint.js.org/reference/rules) for a list of available rules.

#### type-enum

Expand Down
8 changes: 4 additions & 4 deletions @commitlint/config-conventional/README.md
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
> Lint your conventional commits
# @commitlint/config-conventional

Lint your conventional commits

Shareable `commitlint` config enforcing [conventional commits](https://conventionalcommits.org/).
Use with [@commitlint/cli](https://npm.im/@commitlint/cli) and [@commitlint/prompt-cli](https://npm.im/@commitlint/prompt-cli).

## Getting started

```sh
npm install --save-dev @commitlint/config-conventional @commitlint/cli
echo "module.exports = {extends: ['@commitlint/config-conventional']};" > commitlint.config.js
echo "export default {extends: ['@commitlint/config-conventional']};" > commitlint.config.js
```

## Rules
Expand All @@ -18,7 +18,7 @@ echo "module.exports = {extends: ['@commitlint/config-conventional']};" > commit

The following rules are considered problems for `@commitlint/config-conventional` and will yield a non-zero exit code when not met.

Consult [docs/rules](https://conventional-changelog.github.io/commitlint/#/reference-rules) for a list of available rules.
Consult [Rules reference](https://commitlint.js.org/reference/rules) for a list of available rules.

#### type-enum

Expand Down
12 changes: 6 additions & 6 deletions @commitlint/config-lerna-scopes/readme.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
> Lint your lerna project commits
# @commitlint/config-lerna-scopes

Lint your lerna project commits

Shareable `commitlint` config enforcing lerna package and workspace names as scopes.
Use with [@commitlint/cli](../cli) and [@commitlint/prompt-cli](../prompt-cli).

## Getting started

```
```sh
npm install --save-dev @commitlint/config-lerna-scopes @commitlint/cli
echo "module.exports = {extends: ['@commitlint/config-lerna-scopes']};" > commitlint.config.js
echo "export default {extends: ['@commitlint/config-lerna-scopes']};" > commitlint.config.js
```

## Examples

```
```text
❯ cat commitlint.config.js
{
extends: ['@commitlint/config-lerna-scopes']
Expand All @@ -41,4 +41,4 @@ packages
✔ found 0 problems, 0 warnings
```

Consult [docs/rules](https://conventional-changelog.github.io/commitlint/#/reference-rules) for a list of available rules.
Consult [Rules reference](https://commitlint.js.org/reference/rules) for a list of available rules.
6 changes: 3 additions & 3 deletions @commitlint/config-nx-scopes/readme.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
> Lint your nx project commits
# @commitlint/config-nx-scopes

Lint your nx project commits

Shareable `commitlint` config enforcing nx project and workspace names as scopes.
Use with [@commitlint/cli](../cli) and [@commitlint/prompt-cli](../prompt-cli).

Expand Down Expand Up @@ -98,4 +98,4 @@ packages
✔ found 0 problems, 0 warnings
```

Consult [docs/rules](https://conventional-changelog.github.io/commitlint/#/reference-rules) for a list of available rules.
Consult [Rules reference](https://commitlint.js.org/reference/rules) for a list of available rules.
6 changes: 3 additions & 3 deletions @commitlint/config-patternplate/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
> Lint your commits, patternplate-style
# @commitlint/config-patternplate

Lint your commits, patternplate-style

Shareable `commitlint` config enforcing the patternplate commit convention.
Use with [@commitlint/cli](../cli) and [@commitlint/prompt-cli](../prompt-cli).

Expand All @@ -27,4 +27,4 @@ The following rules are considered problems for `@commitlint/config-patternplate
- **rule**: `always`
- **value**: determined based on pattern tree. `system` and all pattern ids present in `patterns` are allowed

Consult [docs/rules](https://conventional-changelog.github.io/commitlint/#/reference-rules) for a list of available rules.
Consult [Rules reference](https://commitlint.js.org/reference/rules) for a list of available rules.
6 changes: 3 additions & 3 deletions @commitlint/config-pnpm-scopes/readme.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
> Lint your pnpm workspaces project commits
# @commitlint/config-pnpm-scopes

Lint your pnpm workspaces project commits

Shareable `commitlint` config enforcing pnpm workspaces names as scopes.
Use with [@commitlint/cli](../cli) and [@commitlint/prompt-cli](../prompt-cli).

Expand Down Expand Up @@ -41,4 +41,4 @@ packages
✔ found 0 problems, 0 warnings
```

Consult [docs/rules](https://conventional-changelog.github.io/commitlint/#/reference-rules) for a list of available rules.
Consult [Rules reference](https://commitlint.js.org/reference/rules) for a list of available rules.
12 changes: 6 additions & 6 deletions @commitlint/config-rush-scopes/readme.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
> Lint your rush project commits
# @commitlint/config-rush-scopes

Lint your rush project commits

Shareable `commitlint` config enforcing rush package and workspace names as scopes.
Use with [@commitlint/cli](../cli) and [@commitlint/prompt-cli](../prompt-cli).

## Getting started

```
```sh
npm install --save-dev @commitlint/config-rush-scopes @commitlint/cli
echo "module.exports = {extends: ['@commitlint/config-rush-scopes']};" > commitlint.config.js
echo "export default {extends: ['@commitlint/config-rush-scopes']};" > commitlint.config.js
```

## Examples

```
```text
❯ cat commitlint.config.js
{
extends: ['@commitlint/config-rush-scopes']
Expand All @@ -41,4 +41,4 @@ packages
✔ found 0 problems, 0 warnings
```

Consult [docs/rules](https://conventional-changelog.github.io/commitlint/#/reference-rules) for a list of available rules.
Consult [Rules reference](https://commitlint.js.org/reference/rules) for a list of available rules.
2 changes: 1 addition & 1 deletion @commitlint/cz-commitlint/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,4 +58,4 @@ yarn commit

## Related

- [Commitlint Reference Prompt](https://commitlint.js.org/#/reference-prompt) - How to customize prompt information by setting commitlint.config.js
- [Commitlint Reference Prompt](https://commitlint.js.org/reference/prompt) - How to customize prompt information by setting commitlint.config.js
Loading

0 comments on commit 868983c

Please sign in to comment.