Skip to content

Commit fe8db09

Browse files
WRXinYueWRXinYue
committed
docs: update readme
1 parent 91fbf3d commit fe8db09

File tree

1 file changed

+139
-28
lines changed

1 file changed

+139
-28
lines changed

‎README.md‎

Lines changed: 139 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,6 @@ import { addonGitLog } from 'valaxy-addon-git-log'
2323
export default defineValaxyConfig({
2424
addons: [
2525
addonGitLog({
26-
// contributor: {
27-
// mode: 'log',
28-
// },
2926
repositoryUrl: 'https://github.com/your-username/your-repository.git',
3027
}),
3128
],
@@ -44,36 +41,27 @@ To add Git contributors to a page, use the `GitLogContributor` component:
4441
</template>
4542
```
4643

47-
### Customization
44+
### Customization examples
4845

4946
If you are a theme developer or want to customize pages with git information, you can refer to the following example:
5047

5148
```vue
5249
<script setup lang="ts">
53-
import { useAddonGitLog } from 'valaxy-addon-git-log'
50+
import { useGitLog } from 'valaxy-addon-git-log'
5451
55-
const { contributors } = useAddonGitLog()
52+
const gitLog = useGitLog()
5653
</script>
5754
5855
<template>
5956
<ul>
60-
<li v-for="contributor in contributors" :key="contributor.email">
57+
<li v-for="contributor in gitLog.contributors" :key="contributor.email">
6158
<img :src="contributor.avatar" alt="Avatar" width="30" height="30">
6259
{{ contributor.name }}
6360
</li>
6461
</ul>
6562
</template>
6663
```
6764

68-
Regarding the full `contributors` parameter:
69-
70-
| Name | Type | Description |
71-
| ------ | -------- | ------------------------------------------------------------------ |
72-
| name | `string` | Contributor's name |
73-
| email | `string` | Contributor's email |
74-
| avatar | `string` | Contributor's avatar URL, obtained through gravatar based on email |
75-
| count | `number` | Number of contributions |
76-
7765
## Configuration / Options
7866

7967
In your project (wether theme or addon), you can write this in `valaxy.config.ts`.
@@ -83,27 +71,150 @@ export default defineValaxyConfig<ThemeConfig>({
8371
addons: [
8472
addonGitLog({
8573
contributor: {
86-
mode: 'log',
74+
mode: 'api',
8775
// logArgs: '--first-parent --follow',
8876
},
8977
}),
9078
],
9179
})
9280
```
9381

94-
| Name | Type | Default | Description |
95-
| ------------------- | ---------------------------------- | ----------- | ------------------------------------------- |
96-
| repositoryUrl | `string` | `undefined` | The URL of the repository. |
97-
| contributor.mode | `'api'` \| `'log'` \| `'shortLog'` | `'api'` | The method to generate Git information. |
98-
| contributor.logArgs | `string` | `''` | Additional arguments for `git log` command. |
99-
100-
Besides the `api` method, the `mode` option also includes `log` and `shortLog` methods. These methods allow you to generate Git information during build time, with the `git log` command by default adding the `--no-merges` parameter.
82+
| Name | Type | Default | Description |
83+
| ------------------- | ------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
84+
| repositoryUrl | `string` | `undefined` | The URL of the GitHub repository. This is used to specify the repository from which to fetch information. |
85+
| contributor.mode | `'api'` \| `'git'` | `'api'` | Defines the method to retrieve Git contributor information. If set to `'api'`, the GitHub API is used. If set to `'log'`, the `git log` command is used during build time, with the `--no-merges` parameter added by default. |
86+
| contributor.logArgs | `string` | `''` | Additional arguments passed to the `git log` command when `contributor.mode` is set to `'git'`. These arguments can customize the `git log` query (e.g., limiting the number of commits, filtering by date, etc.). |
10187

10288
> [!WARNING]
103-
> If you use the `log` or `shortLog` method to deploy projects on static servers (such as `Netlify`, `Vercel`), there may be restrictions. To ensure proper deployment on these platforms, please use the `api` method.
89+
> If you use the `git` method to deploy projects on static servers (such as `Netlify`, `Vercel`), there may be restrictions. To ensure proper deployment on these platforms, please use the `api` method.
90+
91+
## Components
92+
93+
### GitLogContributor
94+
95+
```vue
96+
<template>
97+
<GitLogContributor />
98+
</template>
99+
```
100+
101+
### GitLogChangelog
102+
103+
```vue
104+
<template>
105+
<GitLogChangelog />
106+
</template>
107+
```
108+
109+
## Composables
110+
111+
### useGitLog
112+
113+
This composable provides a simple way to fetch Git log data based on the current page's context.
114+
115+
```ts
116+
import { useGitLog } from 'valaxy-addon-git-log'
117+
import { computed } from 'vue'
118+
119+
const gitLog = useGitLog()
120+
const contributors = computed(() => gitLog.value.contributors)
121+
const changeLog = computed(() => gitLog.value.changeLog)
122+
```
123+
124+
**Return Type:**
125+
126+
```ts
127+
export interface GitLog {
128+
contributors: Contributor[]
129+
changeLog: Changelog[]
130+
path: string
131+
}
132+
```
104133

105-
## FAQ
134+
| Name | Type | Description |
135+
| ------------ | --------------- | -------------------------------- |
136+
| contributors | `Contributor[]` | see `useContributor` return type |
137+
| changeLog | `Changelog[]` | see `useChangelog` return type |
138+
| path | `string` | |
106139

107-
### Why does `shortLog` have no git information?
140+
### useContributor
141+
142+
```ts
143+
import { useContributor } from 'valaxy-addon-git-log'
144+
145+
const contributor = useContributor()
146+
```
147+
148+
**Return Type:**
149+
150+
```ts
151+
export interface Contributor {
152+
name: string
153+
email: string
154+
avatar: string
155+
count: number
156+
github: string | null
157+
hash: string
158+
}[]
159+
```
160+
161+
| Name | Type | Description |
162+
| ------ | ---------------- | ------------------------------------------------------------------ |
163+
| name | `string` | Contributor's name |
164+
| email | `string` | Contributor's email |
165+
| avatar | `string` | Contributor's avatar URL, obtained through gravatar based on email |
166+
| count | `number` | Number of contributions |
167+
| github | `string \| null` | Only supported `api` mode |
168+
| hash | `string` | A unique hash generated based on the contributor's email |
169+
170+
### useChangelog
171+
172+
```ts
173+
import { useChangelog } from 'valaxy-addon-git-log'
174+
175+
const changelog = useChangelog()
176+
```
177+
178+
**Return Type:**
179+
180+
```ts
181+
export interface Changelog {
182+
functions: string[]
183+
version?: string
184+
hash: string
185+
date: string
186+
message: string
187+
refs?: string
188+
body?: string
189+
author_name: string
190+
author_email: string
191+
}[]
192+
```
193+
194+
| Name | Type | Description |
195+
| -------------- | ----------------------- | ----------------------------------------------------------------------- |
196+
| `functions` | `string[]` | List of functions affected or related to the changelog entry. |
197+
| `version` | `string` \| `undefined` | Optional version number for the release or update. |
198+
| `hash` | `string` | Unique identifier or commit hash for the change. |
199+
| `date` | `string` | The date when the change was made or the changelog entry was created. |
200+
| `message` | `string` | A brief summary or description of the change. |
201+
| `refs` | `string` \| `undefined` | Optional reference information, such as ticket IDs or PR links. |
202+
| `body` | `string` \| `undefined` | Optional detailed body content or additional explanation of the change. |
203+
| `author_name` | `string` | Name of the person who made the change. |
204+
| `author_email` | `string` | Email address of the person who made the change. |
205+
206+
## Other
207+
208+
### Virtual modules
209+
210+
```ts
211+
import changelog from 'virtual:git-log/changelog'
212+
```
213+
214+
The `changelog` variable contains all the commit logs.
215+
216+
```ts
217+
import contributors from 'virtual:git-log/contributors'
218+
```
108219

109-
The 'git shortlog' command requires reading some content from standard input. This plugin uses '/dev/tty' by default to obtain the controlling terminal device of the current process, serving as the input or output device. However, on static servers such as Vercel, these '/dev/tty' or Node.js's 'options.stdio' are restricted, leading to issues.
220+
The `contributors` variable contains information about all contributors.

0 commit comments

Comments
 (0)