Skip to content

Commit e989693

Browse files
chrisbbreuerchrisbbreuer
committed
docs: add initial documentation
1 parent 6aabea6 commit e989693

File tree

8 files changed

+659
-71
lines changed

8 files changed

+659
-71
lines changed

‎docs/.vitepress/config.ts

Lines changed: 23 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -53,16 +53,33 @@ const sidebar = [
5353
{
5454
text: 'Get Started',
5555
items: [
56-
{ text: 'Intro', link: '/intro' },
57-
{ text: 'Install', link: '/install' },
56+
{ text: 'Introduction', link: '/intro' },
57+
{ text: 'Installation', link: '/install' },
5858
{ text: 'Usage', link: '/usage' },
59-
{ text: 'Config', link: '/config' },
59+
{ text: 'Configuration', link: '/config' },
6060
],
6161
},
62-
{ text: 'Showcase', link: '/Showcase' },
62+
{
63+
text: 'Features',
64+
items: [
65+
{ text: 'Conventional Commits', link: '/features/conventional-commits' },
66+
{ text: 'Message Format Rules', link: '/features/message-format' },
67+
{ text: 'Issue References', link: '/features/issue-references' },
68+
{ text: 'Custom Rules', link: '/features/custom-rules' },
69+
],
70+
},
71+
{
72+
text: 'Advanced',
73+
items: [
74+
{ text: 'Git Hooks', link: '/advanced/git-hooks' },
75+
{ text: 'CI Integration', link: '/advanced/ci-integration' },
76+
{ text: 'Performance', link: '/advanced/performance' },
77+
],
78+
},
79+
{ text: 'API Reference', link: '/api-reference' },
6380
]
64-
const description = 'A TypeScript Starter Kit. For a better Development Experience.'
65-
const title = 'ts-starter | A TypeScript Starter Kit. For a better Development Experience.'
81+
const description = 'A lightweight, customizable commit message linter to enforce commit message conventions.'
82+
const title = 'GitLint | Enforce consistent git commit messages.'
6683

6784
export default withPwa(
6885
defineConfig({

‎docs/api-reference.md

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# API Reference
2+
3+
GitLint provides a programmatic API that you can use in your JavaScript or TypeScript applications. This page documents the main functions and types available in the GitLint API.
4+
5+
## Core Functions
6+
7+
### `lintCommitMessage`
8+
9+
Validates a commit message against configured rules.
10+
11+
```ts
12+
function lintCommitMessage(message: string, verbose?: boolean): LintResult
13+
```
14+
15+
#### Parameters
16+
17+
- `message`: The commit message to validate
18+
- `verbose`: Whether to enable verbose output (defaults to configuration value)
19+
20+
#### Returns
21+
22+
- `LintResult`: The validation result object
23+
24+
Example:
25+
26+
```ts
27+
import { lintCommitMessage } from 'gitlint'
28+
29+
const result = lintCommitMessage('feat: add new feature')
30+
console.log(result.valid) // true or false
31+
```
32+
33+
### `installGitHooks`
34+
35+
Installs GitLint Git hooks in the current repository.
36+
37+
```ts
38+
function installGitHooks(force?: boolean): boolean
39+
```
40+
41+
#### Parameters
42+
43+
- `force`: Whether to overwrite existing hooks
44+
45+
#### Returns
46+
47+
- `boolean`: True if hooks were installed successfully
48+
49+
Example:
50+
51+
```ts
52+
import { installGitHooks } from 'gitlint'
53+
54+
const success = installGitHooks(true)
55+
```
56+
57+
### `uninstallGitHooks`
58+
59+
Removes GitLint Git hooks from the current repository.
60+
61+
```ts
62+
function uninstallGitHooks(): boolean
63+
```
64+
65+
#### Returns
66+
67+
- `boolean`: True if hooks were uninstalled successfully
68+
69+
Example:
70+
71+
```ts
72+
import { uninstallGitHooks } from 'gitlint'
73+
74+
const success = uninstallGitHooks()
75+
```
76+
77+
## Types
78+
79+
### `LintResult`
80+
81+
Represents the result of validating a commit message.
82+
83+
```ts
84+
interface LintResult {
85+
valid: boolean
86+
errors: string[]
87+
warnings: string[]
88+
}
89+
```
90+
91+
### `GitLintConfig`
92+
93+
Represents the GitLint configuration options.
94+
95+
```ts
96+
interface GitLintConfig {
97+
verbose: boolean
98+
rules?: Record<string, RuleLevel | [RuleLevel, RuleConfig?]>
99+
defaultIgnores?: string[]
100+
ignores?: string[]
101+
parserPreset?: string
102+
formatter?: string
103+
}
104+
```
105+
106+
### `RuleLevel`
107+
108+
Represents the severity level of a rule.
109+
110+
```ts
111+
type RuleLevel = 0 | 1 | 2 | 'off' | 'warning' | 'error'
112+
```
113+
114+
### `RuleConfig`
115+
116+
Represents the configuration options for a rule.
117+
118+
```ts
119+
interface RuleConfig {
120+
[key: string]: any
121+
}
122+
```
123+
124+
### `LintRule`
125+
126+
Represents a validation rule.
127+
128+
```ts
129+
interface LintRule {
130+
name: string
131+
description: string
132+
validate: (commitMsg: string, config?: RuleConfig) => LintRuleOutcome
133+
}
134+
```
135+
136+
### `LintRuleOutcome`
137+
138+
Represents the outcome of applying a rule to a commit message.
139+
140+
```ts
141+
interface LintRuleOutcome {
142+
valid: boolean
143+
message?: string
144+
}
145+
```
146+
147+
### `CommitParsedResult`
148+
149+
Represents a parsed commit message.
150+
151+
```ts
152+
interface CommitParsedResult {
153+
header: string
154+
type: string | null
155+
scope: string | null
156+
subject: string | null
157+
body: string | null
158+
footer: string | null
159+
mentions: string[]
160+
references: CommitReference[]
161+
raw: string
162+
}
163+
```
164+
165+
### `CommitReference`
166+
167+
Represents a reference to an issue or pull request in a commit message.
168+
169+
```ts
170+
interface CommitReference {
171+
action: string | null
172+
owner: string | null
173+
repository: string | null
174+
issue: string
175+
raw: string
176+
prefix: string
177+
}
178+
```

‎docs/config.md

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,146 @@ _This is just an example of the ts-starter docs._
44

55
The Reverse Proxy can be configured using a `reverse-proxy.config.ts` _(or `reverse-proxy.config.js`)_ file and it will be automatically loaded when running the `reverse-proxy` command.
66

7+
GitLint is highly configurable to match your team's commit message standards. You can customize the validation rules, severity levels, and ignored patterns.
8+
9+
## Configuration File
10+
11+
GitLint can be configured using a `gitlint.config.js` or `gitlint.config.ts` file in your project root. The configuration file should export a default object with your desired options:
12+
13+
```ts
14+
// gitlint.config.ts
15+
import type { GitLintConfig } from 'gitlint'
16+
17+
const config: GitLintConfig = {
18+
verbose: true,
19+
rules: {
20+
'conventional-commits': 2,
21+
'header-max-length': [2, { maxLength: 72 }],
22+
'body-max-line-length': [2, { maxLength: 100 }],
23+
'body-leading-blank': 2,
24+
'no-trailing-whitespace': 1,
25+
},
26+
defaultIgnores: [
27+
'^Merge branch',
28+
'^Merge pull request',
29+
'^Merged PR',
30+
'^Revert ',
31+
'^Release ',
32+
],
33+
ignores: [],
34+
}
35+
36+
export default config
37+
```
38+
39+
## Configuration Options
40+
41+
### `verbose`
42+
43+
Type: `boolean`
44+
Default: `true`
45+
46+
Enables verbose output when validating commit messages.
47+
48+
### `rules`
49+
50+
Type: `Record<string, RuleLevel | [RuleLevel, RuleConfig?]>`
51+
Default: See below
52+
53+
Define the rules to apply during validation. Each rule can be:
54+
55+
- A number (0, 1, 2) or string ('off', 'warning', 'error') indicating the rule's severity
56+
- An array with the first element as the severity and the second as rule-specific configuration
57+
58+
Default rules:
59+
60+
```ts
61+
{
62+
'conventional-commits': 2,
63+
'header-max-length': [2, { maxLength: 72 }],
64+
'body-max-line-length': [2, { maxLength: 100 }],
65+
'body-leading-blank': 2,
66+
'no-trailing-whitespace': 1,
67+
}
68+
```
69+
70+
### `defaultIgnores`
71+
72+
Type: `string[]`
73+
Default: `['Merge branch', 'Merge pull request', 'Merged PR', 'Revert ', 'Release ']`
74+
75+
Regular expression patterns for commit messages that should be automatically ignored by GitLint. These patterns are checked against the start of the commit message.
76+
77+
### `ignores`
78+
79+
Type: `string[]`
80+
Default: `[]`
81+
82+
Custom regular expression patterns for commit messages to ignore. These are in addition to the `defaultIgnores`.
83+
84+
## Rule Severity Levels
85+
86+
GitLint supports the following severity levels for rules:
87+
88+
- `0` or `'off'`: Disable the rule
89+
- `1` or `'warning'`: Trigger a warning (validation passes, but warning is displayed)
90+
- `2` or `'error'`: Trigger an error (validation fails)
91+
92+
## Available Rules
93+
94+
### `conventional-commits`
95+
96+
Enforces the [Conventional Commits](https://www.conventionalcommits.org/) standard format:
97+
98+
```
99+
type(optional scope): description
100+
```
101+
102+
### `header-max-length`
103+
104+
Enforces a maximum length for the commit header (first line).
105+
106+
Options:
107+
108+
- `maxLength`: Maximum number of characters allowed (default: 72)
109+
110+
### `body-max-line-length`
111+
112+
Enforces a maximum length for each line in the commit body.
113+
114+
Options:
115+
116+
- `maxLength`: Maximum number of characters allowed per line (default: 100)
117+
118+
### `body-leading-blank`
119+
120+
Enforces a blank line between the header and body of the commit message.
121+
122+
### `no-trailing-whitespace`
123+
124+
Prevents trailing whitespace in the commit message.
125+
126+
## Using Environment Variables
127+
128+
You can also configure GitLint using environment variables with the `GITLINT_` prefix:
129+
130+
```bash
131+
# Set verbose mode
132+
export GITLINT_VERBOSE=true
133+
134+
# Disable a rule
135+
export GITLINT_RULES_BODY_LEADING_BLANK=0
136+
```
137+
138+
## Configuration Precedence
139+
140+
GitLint uses the following precedence order for configuration (highest to lowest):
141+
142+
1. Command-line arguments
143+
2. Environment variables
144+
3. Configuration file
145+
4. Default values
146+
7147
```ts
8148
// reverse-proxy.config.{ts,js}
9149
import type { ReverseProxyOptions } from '@stacksjs/rpx'

0 commit comments

Comments
 (0)