Skip to content

Commit 03df7e8

Browse files
jankapunktjankapunkt
authored
Merge pull request #388 from node-oauth/docs/vitepress
Docs: vitepress
2 parents d4dc7c7 + f6379f9 commit 03df7e8

File tree

145 files changed

+10787
-5403
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

145 files changed

+10787
-5403
lines changed

‎.eslintignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
.github
2+
.nyc_output
3+
coverage
4+
docs/*
5+
node_modules

‎.github/workflows/deploy_docs.yml‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Sample workflow for building and deploying a VitePress site to GitHub Pages
2+
#
3+
name: Deploy VitePress site to Pages
4+
5+
on:
6+
push:
7+
branches: [master]
8+
9+
# Allows you to run this workflow manually from the Actions tab
10+
workflow_dispatch:
11+
12+
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
13+
permissions:
14+
contents: read
15+
pages: write
16+
id-token: write
17+
18+
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
19+
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
20+
concurrency:
21+
group: pages
22+
cancel-in-progress: false
23+
24+
jobs:
25+
# Build job
26+
build:
27+
runs-on: ubuntu-latest
28+
steps:
29+
- name: Checkout
30+
uses: actions/checkout@v4
31+
with:
32+
fetch-depth: 0 # Not needed if lastUpdated is not enabled
33+
# - uses: pnpm/action-setup@v3 # Uncomment this block if you're using pnpm
34+
# with:
35+
# version: 9 # Not needed if you've set "packageManager" in package.json
36+
# - uses: oven-sh/setup-bun@v1 # Uncomment this if you're using Bun
37+
- name: Setup Node
38+
uses: actions/setup-node@v4
39+
with:
40+
node-version: 20
41+
cache: npm # or pnpm / yarn
42+
- name: Setup Pages
43+
uses: actions/configure-pages@v4
44+
- name: Install dependencies
45+
run: npm ci # or pnpm install / yarn install / bun install
46+
- name: Build with VitePress
47+
run: npm run docs:build # or pnpm docs:build / yarn docs:build / bun run docs:build
48+
- name: Upload artifact
49+
uses: actions/upload-pages-artifact@v3
50+
with:
51+
path: docs/.vitepress/dist
52+
53+
# Deployment job
54+
deploy:
55+
environment:
56+
name: github-pages
57+
url: ${{ steps.deployment.outputs.page_url }}
58+
needs: build
59+
runs-on: ubuntu-latest
60+
name: Deploy
61+
steps:
62+
- name: Deploy to GitHub Pages
63+
id: deployment
64+
uses: actions/deploy-pages@v4

‎CONTRIBUTING.md‎

Lines changed: 47 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -7,18 +7,18 @@ in order to get your pull requests accepted.
77
## Disclose security vulnerabilities
88

99
First things first:
10-
This project has strong security implications and we appreciate every help to
10+
This project has strong security implications, and we appreciate every help to
1111
improve security.
1212

13-
**However, please read our [security policy](./SECURITY.md), before taking
14-
actions.**
13+
**However, please read our [security policy](https://github.com/node-oauth/node-oauth2-server/security/policy),
14+
before taking actions.**
1515

1616

1717

1818
## Guiding principles
1919

2020
Before contributing to this project it is important to understand how this
21-
project and it's collaborators views itself regarding it's scope and purpose.
21+
project and it's collaborators views itself regarding its scope and purpose.
2222

2323
### OAuth2 standard compliance
2424

@@ -38,7 +38,7 @@ Extended readings:
3838
- [RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients](https://datatracker.ietf.org/doc/html/rfc7636)
3939
- [RFC 7591 - OAuth 2.0 Dynamic Client Registration Protocol](https://datatracker.ietf.org/doc/html/rfc7591)
4040

41-
### Framework agnostic
41+
### Framework-agnostic
4242

4343
Design decisions and implementations are always done with keeping in mind, that
4444
there are multiple frameworks out there that use this project.
@@ -47,8 +47,7 @@ there are multiple frameworks out there that use this project.
4747

4848
## Development
4949

50-
If you want to fix bugs or add new features, **please read this chapter and it's
51-
sections carefully!**
50+
If you want to fix bugs or add new features, **please read this chapter and it's sections carefully!**
5251

5352
### No PR without issue
5453

@@ -60,24 +59,24 @@ and discuss, whether this is a useful addition to the project.
6059
First, clone and install this project from source via
6160

6261
```bash
63-
$ git clone [email protected]:node-oauth/node-oauth2-server.git
64-
$ cd node-oauth2-server
65-
$ git checkout development # important! do not work on master!
66-
$ npm install
62+
git clone [email protected]:node-oauth/node-oauth2-server.git
63+
cd node-oauth2-server
64+
git checkout development # important! do not work on master!
65+
npm install
6766
```
6867

6968
From here you can run several scripts for development purposes:
7069

7170
```bash
72-
$ npm run test # runs the tests once
73-
$ npm run test:coverage # runs the tests including coverage
74-
$ npm run docs # generates the API docs
71+
npm run test # runs the tests once
72+
npm run test:coverage # runs the tests including coverage
73+
npm run docs # generates the API docs
7574
```
7675

7776
To work on a new feature or a fix please create a new branch:
7877

7978
```bash
80-
$ git checkout -b feature-xyz # or fix-xyz
79+
git checkout -b feature-xyz # or fix-xyz
8180
```
8281

8382
### Coding rules
@@ -93,8 +92,9 @@ with ticket number at the end of summary:
9392
```
9493
<type>(<scope>): <short summary> #<issue number>
9594
```
95+
9696
Summary in present tense. Not capitalized. No period at the end.
97-
The <type> and <summary> fields are mandatory, the (<scope>) and #<number> field is optional.
97+
The `<type>` and `<summary>` fields are mandatory, the `(<scope>)` and `#<number>` fields are optional.
9898

9999
### Run the tests before committing
100100

@@ -105,13 +105,13 @@ the history with commits, that are solely targeting lint fixes.
105105
You can run the tests via
106106

107107
```bash
108-
$ npm run test
108+
npm run test
109109
```
110110

111111
or
112112

113113
```bash
114-
$ npm run test:coverage
114+
npm run test:coverage
115115
```
116116

117117
to see your coverage.
@@ -152,7 +152,7 @@ Also make sure, to comply with the following list:
152152

153153
#### Review process
154154

155-
Finally your PR needs to pass the review process:
155+
Finally, your PR needs to pass the review process:
156156

157157
- A certain amount of maintainers needs to review and accept your PR
158158
- Please **expect change requests**! They will occur and are intended to improve
@@ -165,3 +165,31 @@ Finally your PR needs to pass the review process:
165165
#### After merge
166166

167167
Please delete your branch after merge.
168+
169+
## Documentation
170+
171+
We use Vitepress+Markdown for our documentation.
172+
If you want to contribute to the docs, please get familiar with Vitepress: https://vitepress.dev
173+
174+
### Setting up docs
175+
176+
You need NPM to set up the docs using the following:
177+
178+
```shell
179+
npm install
180+
npm run docs:setup
181+
```
182+
183+
You can then edit the `guide` section manually.
184+
185+
### API Docs
186+
187+
**DO NOT** edit the `api` section, as API docs are automatically
188+
generated from our internal JSDoc comments.
189+
190+
Instead, update the comments directly within the code and run `npm run docs:api`
191+
to generate the api docs.
192+
193+
### Building the docs
194+
195+
Run `npm run docs:build` to build the docs.

‎docs/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
.vitepress/cache
2+
.vitepress/dist

‎docs/.vitepress/config.mts‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
import {defineConfig} from 'vitepress'
2+
3+
// https://vitepress.dev/reference/site-config
4+
export default defineConfig({
5+
title: "@node-oauth/oauth2-server",
6+
description: "OAuth2 server for Node.js",
7+
head: [['link', { rel: 'icon', href: '/images/favicon.ico' }]],
8+
themeConfig: {
9+
// https://vitepress.dev/reference/default-theme-config
10+
nav: [
11+
{text: 'Home', link: '/'},
12+
{text: 'Guide', link: '/guide/getting-started'},
13+
{text: 'API', link: '/api/server'}
14+
],
15+
16+
sidebar: [
17+
{
18+
text: 'Guide',
19+
items: [
20+
{text: 'Getting started', link: '/guide/getting-started'},
21+
{text: 'Grant types', link: '/guide/grant-types'},
22+
{text: 'Model', link: '/guide/model'},
23+
{text: 'Token types', link: '/guide/token-types'},
24+
{text: 'PKCE', link: '/guide/pkce'},
25+
{text: 'Adapters', link: '/guide/adapters'},
26+
{text: 'Migrating to v5', link: '/guide/migrating-to-v5'},
27+
{text: 'Contributing', link: '/guide/contributing'},
28+
]
29+
},
30+
{
31+
text: 'API',
32+
items: [
33+
{text: 'OAuth2Server', link: '/api/server'},
34+
{text: 'Model', link: '/api/model'},
35+
{text: 'Request', link: '/api/request'},
36+
{text: 'Response', link: '/api/response'},
37+
{
38+
text: 'Errors', items: [
39+
{text: 'Access Denied', link: '/api/errors/access-denied-error'},
40+
{text: 'Insufficient Scope', link: '/api/errors/insufficient-scope-error'},
41+
{text: 'Invalid Argument', link: '/api/errors/invalid-argument-error'},
42+
{text: 'Invalid Client', link: '/api/errors/invalid-client-error'},
43+
{text: 'Invalid Grant', link: '/api/errors/invalid-grant-error'},
44+
{text: 'Invalid Request', link: '/api/errors/invalid-request-error'},
45+
{text: 'Invalid Scope', link: '/api/errors/invalid-scope-error'},
46+
{text: 'Invalid Token', link: '/api/errors/invalid-token-error'},
47+
{text: 'OAuth Error', link: '/api/errors/oauth-error'},
48+
{text: 'Server Error', link: '/api/errors/server-error'},
49+
{text: 'Unauthorized Client', link: '/api/errors/unauthorized-client-error'},
50+
{text: 'Unauthorized Request', link: '/api/errors/unauthorized-request-error'},
51+
{text: 'Unsupported Grant Type', link: '/api/errors/unsupported-grant-type-error'},
52+
{text: 'Unsupported Response Type', link: '/api/errors/unsupported-response-type-error'},
53+
]
54+
},
55+
{
56+
text: 'Grant Types', items: [
57+
{ text: 'Abstract Grant Type', link: '/api/grant-types/abstract-grant-type' },
58+
{ text: 'Authorization Code', link: '/api/grant-types/authorization-code-grant-type' },
59+
{ text: 'Client Credentials', link: '/api/grant-types/client-credentials-grant-type' },
60+
{ text: 'Password', link: '/api/grant-types/password-grant-type' },
61+
{ text: 'Refresh Token', link: '/api/grant-types/refresh-token-grant-type' },
62+
]
63+
},
64+
{
65+
text: 'Handlers', items: [
66+
{ text: 'Authenticate Handler', link: '/api/handlers/authenticate-handler' },
67+
{ text: 'Authorize Handler', link: '/api/handlers/authorize-handler' },
68+
{ text: 'Token Handler', link: '/api/handlers/token-handler' },
69+
]
70+
},
71+
{
72+
text: 'Models', items: [
73+
{ text: 'Token Model', link: '/api/models/token-model' },
74+
]
75+
},
76+
{
77+
text: 'PKCE', items: [
78+
{ text: 'PKCE', link: '/api/pkce/pkce' },
79+
]
80+
},
81+
{
82+
text: 'Response Types', items: [
83+
{ text: 'Code', link: '/api/response-types/code-response-type' },
84+
{ text: 'Token', link: '/api/response-types/token-response-type' },
85+
]
86+
},
87+
{
88+
text: 'Token Types', items: [
89+
{ text: 'Bearer', link: '/api/token-types/bearer-token-type' },
90+
{ text: 'Mac', link: '/api/token-types/mac-token-type' },
91+
]
92+
},
93+
{
94+
text: 'Utils', items: [
95+
{ text: 'Crypto', link: '/api/utils/crypto-util' },
96+
{ text: 'Date', link: '/api/utils/date-util' },
97+
{ text: 'Scope', link: '/api/utils/scope-util' },
98+
{ text: 'String', link: '/api/utils/string-util' },
99+
{ text: 'Token', link: '/api/utils/token-util' },
100+
]
101+
},
102+
]
103+
}
104+
],
105+
106+
socialLinks: [
107+
{icon: 'github', link: 'https://github.com/node-oauth/node-oauth2-server'}
108+
]
109+
}
110+
})

0 commit comments

Comments
 (0)