Skip to content

Commit 0c5ccea

Browse files
larbishlarbish
committed
chore(playground): match content docs
1 parent 79ed12b commit 0c5ccea

File tree

4 files changed

+244
-138
lines changed

4 files changed

+244
-138
lines changed

‎playground/docus/content/9.studio/2.setup.md‎

Lines changed: 47 additions & 119 deletions
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ npx nuxi module add nuxt-studio@alpha
4343

4444
## Configure
4545

46-
Add the module to your `nuxt.config.ts` and configure your GitHub repository:
46+
Add the module to your `nuxt.config.ts` and configure your repository based on your Git provider:
4747

4848
```ts [nuxt.config.ts]
4949
export default defineNuxtConfig({
@@ -56,59 +56,74 @@ export default defineNuxtConfig({
5656
// Studio admin route (default: '/_studio')
5757
route: '/_studio',
5858

59-
// GitHub repository configuration (owner and repo are required)
59+
// Git repository configuration (owner and repo are required)
6060
repository: {
61-
provider: 'github', // only GitHub is currently supported
62-
owner: 'your-username', // your GitHub username or organization
61+
provider: 'github', // 'github' or 'gitlab'
62+
owner: 'your-username', // your GitHub/GitLab username or organization
6363
repo: 'your-repo', // your repository name
6464
branch: 'main', // the branch to commit to (default: main)
65-
rootDir: '' // optional: if your Nuxt app is in a subdirectory (default: '')
6665
}
6766
}
6867
})
6968
```
7069

71-
::callout
70+
### Options
71+
72+
#### Root directory `default: ''`
73+
7274
If your Nuxt Content application is in a monorepo or subdirectory, specify the `rootDir` option to point to the correct location.
73-
::
7475

75-
## GitHub OAuth App
76+
```ts [nuxt.config.ts]
77+
export default defineNuxtConfig({
78+
studio: {
79+
repository: {
80+
...
81+
rootDir: 'docs'
82+
}
83+
}
84+
})
85+
```
7686

77-
Nuxt Studio uses GitHub OAuth for authentication.
87+
#### Private Repository Access `default: true`
7888

79-
::prose-steps
89+
By default, Studio requests access to both public and private repositories.
8090

81-
### Navigate to GitHub Developer Settings
91+
Setting `private: false` limits the OAuth scope to public repositories only, which may be preferable for security or compliance reasons when working with public repositories.
8292

83-
Go to [GitHub Developer Settings](https://github.com/settings/developers) and click **New OAuth App**
93+
```ts [nuxt.config.ts]
94+
export default defineNuxtConfig({
95+
studio: {
96+
repository: {
97+
...
98+
private: false
99+
}
100+
}
101+
})
102+
```
84103

85-
### Configure the OAuth Application
104+
## Dev mode
86105

87-
Fill in the required fields:
88-
- **Application name**: Your app name
89-
- **Homepage URL**: `https://yourdomain.com`
90-
- **Authorization callback URL**: `https://yourdomain.com`
106+
🚀 That’s all you need to enable Studio in local.
91107

92-
:note[If you want to try studio locally, set the callback url to your local url `http://localhost:3000`]
108+
Once your project is running locally, any file changes will be synchronized in real time with the file system.
93109

94-
### Copy Your Credentials
110+
::warning
111+
The publish system is only available in production mode. You can use your classical workflow (IDE, CLI, GitHub Desktop...) to publish your changes in local.
112+
::
95113

96-
After creating the OAuth app, you'll receive:
114+
## Production mode
97115

98-
- A **Client ID** (visible immediately)
99-
- A **Client Secret** (click **Generate a new client secret**)
116+
While Nuxt Studio can be useful during development (especially with the upcoming Studio editor) its main advantage is the ability to publish changes directly from your production website.
100117

101-
### Set your environment Variables
118+
### OAuth Configuration
102119

103-
Add the GitHub OAuth credentials to your deployment platform's environment variables or in your `.env` file in local
120+
To enable this Nuxt Studio supports authentication through both GitHub and GitLab OAuth providers allowing you to log in and publish updates from production.
104121

105-
```bash [.env]
106-
STUDIO_GITHUB_CLIENT_ID=<your_github_client_id>
107-
STUDIO_GITHUB_CLIENT_SECRET=<your_github_client_secret>
108-
```
122+
::tip{icon="i-lucide-info" to="/docs/studio/github#oauth-providers"}
123+
Choose your provider and follow the dedicated setup instructions for your Git provider in this section.
109124
::
110125

111-
## Deployment
126+
### Deployment
112127

113128
Nuxt Studio requires a server-side route for authentication.
114129

@@ -129,105 +144,18 @@ export default defineNuxtConfig({
129144
})
130145
```
131146

132-
## Working with Staging/Preview Branches
133-
134-
By default, Studio commits changes to the branch specified in your configuration (typically `main`). However, you can configure Studio to work with a staging or preview branch instead.
135-
136-
This is useful when you want to review changes on a preview environment before merging to production. You can currently handle pull requests manually from GitHub, but automatic PR creation is included in our roadmap and will be implemented in a future release.
137-
138-
::prose-steps
139-
### Configure
140-
141-
Update your `nuxt.config.ts` to target your staging branch.
142-
143-
:::tip
144-
You can use environment variables to manage multiple branches for different environments.
145-
:::
146-
147-
```ts [nuxt.config.ts]
148-
export default defineNuxtConfig({
149-
studio: {
150-
repository: {
151-
owner: 'your-username',
152-
repo: 'your-repo',
153-
branch: PROCESS.ENV.STUDIO_GITHUB_BRANCH_NAME, // Target your staging branch instead of main
154-
}
155-
}
156-
})
157-
```
158-
159-
### Deploy
160-
161-
Configure your hosting platform to deploy the staging branch to a preview URL (e.g., `staging.yourdomain.com`).
162-
163-
### Create a Separate GitHub OAuth App
164-
165-
Create a new OAuth App specifically for your staging environment:
166-
167-
- **Application name**: Your App Name (Staging)
168-
- **Homepage URL**: `https://staging.yourdomain.com`
169-
- **Authorization callback URL**: `https://staging.yourdomain.com`
170-
171-
### Set Environment Variables
172-
173-
Configure your staging deployment with the staging OAuth credentials and your br
174-
175-
```bash [.env.staging]
176-
STUDIO_GITHUB_CLIENT_ID=<your_staging_github_client_id>
177-
STUDIO_GITHUB_CLIENT_SECRET=<your_staging_github_client_secret>
178-
STUDIO_GITHUB_BRANCH_NAME=<your_staging_branch_name>
179-
```
180-
181-
### Access Studio on Staging
182-
183-
Navigate to `https://staging.yourdomain.com/_studio` to edit content. All commits will be pushed to your configured staging branch.
184-
185-
### Merging to Production
186-
187-
Once you're satisfied with changes on your staging branch, create a pull request from your staging branch to your main branch on GitHub to deploy to production.
188-
189-
:::note
190-
**Pull Request Automation Coming Soon**
191-
192-
:br
193-
194-
Automatic pull request creation from Studio is planned for a future release. For now, you'll need to manually create PRs on GitHub to merge staging changes into your main branch.
195-
:::
196-
::
197-
198147
### Accessing Studio
199148

200149
After deployment, access the Studio interface by navigating to your configured route (default: `/_studio`):
201150

202-
1. Click **Login with GitHub** if it does not directly redirect to the OAuth app authorization page
151+
1. Click the login button if it does not directly redirect to the OAuth app authorization page
203152
2. Authorize the OAuth application
204-
3. You'll be redirected back to Studio, ready to edit your content
153+
3. You'll be redirected back to Studio ready to edit your content
205154

206155
::note
207156
Secure OAuth-based login with **Google** should be available quickly in the Beta release.
208157
::
209158

210159
::tip
211-
You can also use the shortcut :kbd{value="meta"} + :kbd{value="."} to redirect to the Studio route.
160+
You can also use the shortcut `CMD` + `K` to redirect to the Studio route.
212161
::
213-
214-
## Development mode
215-
216-
Nuxt Studio includes an **experimental** development mode that enables real-time file system synchronization:
217-
218-
```ts [nuxt.config.ts]
219-
export default defineNuxtConfig({
220-
studio: {
221-
development: {
222-
sync: true // Enable development mode
223-
}
224-
}
225-
})
226-
```
227-
228-
When enabled, Nuxt Studio will:
229-
230-
- ✅ Write changes directly to your local `content/` directory
231-
- ✅ Write media changes to your local `public/` directory
232-
- ❌ Listen for file system changes and update the editor
233-
- ❌ Commit changes to your repository (use your classical workflow instead)

‎playground/docus/content/9.studio/3.providers.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
---
2+
title: Oauth Providers
3+
description: Configure OAuth providers and synchronizes content between your production website and your Git repository.
4+
navigation:
5+
title: Providers
6+
seo:
7+
title: Git Integration with Studio
8+
description: Configure GitHub or GitLab OAuth and synchronizes content between your production website and your Git repository.
9+
---
10+
11+
::prose-note
12+
After initial OAuth setup, synchronization happens automatically and requires no manual action.
13+
::
14+
15+
## OAuth Providers
16+
17+
Nuxt Studio supports authentication with both GitHub and GitLab OAuth providers.
18+
19+
### GitHub OAuth App
20+
21+
To use GitHub as your Git provider, you need to create a GitHub OAuth application.
22+
23+
::prose-steps{level="4"}
24+
#### Navigate to GitHub Developer Settings
25+
26+
Go to [GitHub Developer Settings](https://github.com/settings/developers) and click **New OAuth App**
27+
28+
#### Configure the OAuth Application
29+
30+
Fill in the required fields:
31+
32+
- **Application name**: Your app name
33+
- **Homepage URL**: `https://yourdomain.com`
34+
- **Authorization callback URL**: `https://yourdomain.com`:note [If you want to try studio locally, set the callback url to your local url `http://localhost:3000`]
35+
36+
#### Copy Your Credentials
37+
38+
After creating the OAuth app, you'll receive:
39+
40+
- A **Client ID** (visible immediately)
41+
- A **Client Secret** (click **Generate a new client secret**)
42+
43+
#### Set your environment Variables
44+
45+
Add the GitHub OAuth credentials to your deployment platform's environment variables or in your `.env` file in local
46+
47+
```bash [.env]
48+
STUDIO_GITHUB_CLIENT_ID=<your_github_client_id>
49+
STUDIO_GITHUB_CLIENT_SECRET=<your_github_client_secret>
50+
```
51+
::
52+
53+
### GitLab OAuth App
54+
55+
To use GitLab as your Git provider, you need to create a GitLab OAuth application.
56+
57+
::prose-steps{level="4"}
58+
#### Navigate to GitLab Applications
59+
60+
Go to your GitLab [User Settings → Applications](https://gitlab.com/-/user_settings/applications) (or your group/organization settings) and create a **New Application**.
61+
62+
#### Configure the OAuth Application
63+
64+
Fill in the required fields:
65+
66+
- **Application name**: Your app name
67+
- **Redirect URI**: `https://yourdomain.com/__nuxt_studio/auth/gitlab`
68+
- **Scopes**: Select `api` (required for publication) :note[If you want to try studio locally, add your local url as redirect URI: `http://localhost:3000/__nuxt_studio/auth/gitlab`]
69+
70+
#### Copy Your Credentials
71+
72+
After creating the OAuth application, you'll receive:
73+
74+
- An **Application ID** (visible immediately)
75+
- A **Secret** (visible immediately)
76+
77+
#### Set your environment Variables
78+
79+
Add the GitLab OAuth credentials to your deployment platform's environment variables or in your `.env` file in local
80+
81+
```bash [.env]
82+
STUDIO_GITLAB_CLIENT_ID=<your_gitlab_application_id>
83+
STUDIO_GITLAB_CLIENT_SECRET=<your_gitlab_secret>
84+
```
85+
::
86+
87+
::tip
88+
That's it! Once deployed with the appropriate credentials set as environment variables. Studio will be accessible from your production instance. Just login on the `/_studio` (or on the route you've configured) to start editing.
89+
::
90+
91+
## Advanced options
92+
93+
### Custom Redirect URL
94+
95+
By default, Studio uses your deployment URL as the OAuth redirect URL. If you need to customize it you can specify a custom redirect URL:
96+
97+
```bash [.env]
98+
# Using GitHub provider
99+
STUDIO_GITHUB_REDIRECT_URL=https://custom-domain.com
100+
101+
# Using GitLab provider
102+
STUDIO_GITLAB_REDIRECT_URL=https://custom-domain.com
103+
```
104+
105+
::callout
106+
This is useful when you need to handle OAuth callbacks through a specific endpoint.
107+
::
108+
109+
## Working with Staging/Preview Branches
110+
111+
By default, Studio commits changes to the branch specified in your configuration (typically `main`). However, you can configure Studio to work with a staging or preview branch instead.
112+
113+
This is useful when you want to review changes on a preview environment before merging to production. You can currently handle pull requests manually from GitHub, but automatic PR creation is included in our roadmap and will be implemented in a future release.
114+
115+
::prose-steps
116+
### Configure
117+
118+
Update your `nuxt.config.ts` to target your staging branch.
119+
120+
:::tip
121+
You can use environment variables to manage multiple branches for different environments.
122+
:::
123+
124+
```ts [nuxt.config.ts]
125+
export default defineNuxtConfig({
126+
studio: {
127+
repository: {
128+
owner: 'your-username',
129+
repo: 'your-repo',
130+
branch: PROCESS.ENV.STUDIO_BRANCH_NAME, // Target your staging branch instead of main
131+
}
132+
}
133+
})
134+
```
135+
136+
### Deploy
137+
138+
Configure your hosting platform to deploy the staging branch to a preview URL (e.g., `staging.yourdomain.com`).
139+
140+
### Create a Separate OAuth App (based on your Git provider)
141+
142+
Create a new OAuth App specifically for your staging environment and use your staging URL as callback URL.
143+
144+
### Set Environment Variables
145+
146+
Configure your staging deployment env varibales with the staging OAuth credentials.
147+
148+
```bash [.env.staging]
149+
STUDIO_GITHUB_CLIENT_ID=<your_staging_github_client_id>
150+
STUDIO_GITHUB_CLIENT_SECRET=<your_staging_github_client_secret>
151+
STUDIO_GITHUB_BRANCH_NAME=<your_staging_branch_name>
152+
```
153+
154+
### Access Studio on Staging
155+
156+
Navigate to `https://staging.yourdomain.com/_studio` to edit content. All commits will be pushed to your configured staging branch.
157+
158+
### Merging to Production
159+
160+
Once you're satisfied with changes on your staging branch, create a pull request from your staging branch to your main branch on GitHub to deploy to production.
161+
162+
:::note
163+
**Pull Request Automation Coming Soon**
164+
165+
:br
166+
167+
Automatic pull request creation from Studio is planned for a future release. For now, you'll need to manually create PRs on GitHub to merge staging changes into your main branch.
168+
:::
169+
::

0 commit comments

Comments
 (0)