Skip to content

Commit 2aa3e5e

Browse files
larbishlarbish
authored
docs(studio): dedicated section
1 parent 3db7fdf commit 2aa3e5e

21 files changed

+529
-2
lines changed

‎README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ Nuxt Content reads the `content/` directory in your project, parses `.md`, `.yml
1212

1313
- [📖  Read the documentation](https://content3.nuxt.dev)
1414
- [✨  Intro video](https://www.youtube.com/watch?v=o9e12WbKrd8)
15-
- [✍️  Nuxt Studio](https://nuxt.studio)
15+
- [✍️  Nuxt Studio](https://content3.nuxt.dev/docs/studio)
1616

1717
## Features
1818

‎docs/content/docs/1.getting-started/1.index.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ The new collections system provides automatic TypeScript types for all your data
3737

3838
### Nuxt Studio Integration :badge[Soon]{color=neutral}
3939

40-
[Nuxt Studio](https://nuxt.studio) and v3 are designed to complement each other perfectly. The [studio module](https://github.com/nuxtlabs/studio-module) is now integrated directly into Nuxt Content, creating an ideal environment where developers can focus on code while team members manage content through an intuitive interface.
40+
[Nuxt Studio](/studio/setup) and v3 are designed to complement each other perfectly.. The [studio module](https://github.com/nuxtlabs/studio-module) is now integrated directly into Nuxt Content, creating an ideal environment where developers can focus on code while team members manage content through an intuitive interface.
4141

4242
:hr
4343

‎docs/content/docs/7.studio/.navigation.yml

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
icon: i-lucide-monitor
2+
title: Studio

‎docs/content/docs/7.studio/1.setup.md

+96
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
---
2+
title: Setup Nuxt Studio
3+
seo:
4+
title: Introduction and setup of Nuxt Studio - the visual CMS platform of Nuxt Content
5+
description: Studio is a the Git-based CMS platform for Nuxt Content websites, providing an intuitive interface to edit your Markdown, YAML and JSON files and publish your changes to GitHub.
6+
navigation:
7+
title: Setup
8+
description: Studio is the intuitive interface to edit Nuxt Content websites. Edit your Markdown, YAML and JSON files and publish your changes to GitHub.
9+
---
10+
11+
Studio is a Nuxt Content plugin you can activate to use the visual CMS platform.
12+
13+
Content editors can benefit from a user-friendly interface including, among other things, editors to edit their `Markdown`, `YAML` or `JSON` files.
14+
15+
Developers can customize the edition experience and provide tools to the editor who can focus on content without requiring any technical expertise.
16+
17+
:video{autoplay controls loop poster="/assets/home/videos/HomeNotionLikePoster.webp" src="https://res.cloudinary.com/nuxt/video/upload/v1729157955/frontmatterform2_rmh58v.mp4"}
18+
19+
## Authentication
20+
21+
The Studio admin is located on [studio.content.nuxt.com](https//nuxt.studio). From there you can either login with GitHub or with Google. Both methods give you the same edition rights but since Studio is [synchronized with GitHub](/docs/studio/github), the repository import must be handled by a GitHub user.
22+
23+
::warning
24+
Google authentication is adapted for non technical users. Google users have to join a team with existing projects to edit them.
25+
::
26+
27+
## Connect your Nuxt Content repository
28+
29+
Once you are logged in the admin, you have the possibility to import your Nuxt Content repository from the interface.
30+
31+
::tip
32+
Two options are available, you can either import an existing repository or use one of our [templates](/studio/templates).
33+
::
34+
35+
The only requirement is to host your repository on GitHub. From the interface, connect to our [GitHub app](/docs/studio/github), you'll be then able to link a GitHub repository to your Studio project.
36+
37+
Once the project is created, you can start editing your files with the Studio editors and publish your changes.
38+
39+
## Enable the live preview
40+
41+
Once created, your project URL must be set to enjoy all Studio features, especially the live preview of your website.
42+
43+
::tip
44+
We are proposing a GitHub Pages deployment. By using it, we will handle all the requirements for you. However, if you want to use the deployment platform of your choice, please follow the simple guideline below.
45+
::
46+
47+
To enable the live preview, you just need to activate studio in the content configuration of your fv`nuxt.config.ts` file.
48+
49+
```ts [nuxt.config.ts]
50+
export default defineNuxtConfig({
51+
content: {
52+
studio: {
53+
enabled: true
54+
}
55+
}
56+
})
57+
```
58+
59+
Once deployed, you can ensure Studio has been activated by navigating to the `/__studio.json` page on your site. This metadata page is automatically generated by the Content module and must be accessible to connect your URL in the self-hosted section of Studio.
60+
61+
### Troubleshooting
62+
63+
The `__studio.json` file is generated but you encounter a `Forbidden error: invalid property check` when setting your URL in the self-hosted section, follow these steps:
64+
65+
1. Ensure the `gitInfo` field is set and accurate in the `__studio.json` file:
66+
67+
```json [https://your-website.com/__studio.json]
68+
"gitInfo": {
69+
"name": "studio-front",
70+
"owner": "nuxtlabs",
71+
"url": "https://github.com/nuxtlabs/studio-front"
72+
},
73+
```
74+
75+
::warning
76+
This information should be populated automatically in most cases. We support most popular providers (Vercel, Netlify, etc.), but if you're using a non supported provider or a custom one, it may not be fetched correctly.
77+
::
78+
79+
2. You can manually override this data by setting those configs in your `nuxt.config.ts`:
80+
81+
```ts [nuxt.config.ts]
82+
export default defineNuxtConfig({
83+
content: {
84+
studio: {
85+
enabled: true,
86+
gitInfo: {
87+
name: 'Your repository name',
88+
owner: 'Your repository owner/organization',
89+
url: 'Your GitHub repository URL'
90+
}
91+
}
92+
}
93+
})
94+
```
95+
96+
3. By ensuring these fields are correctly set, you can resolve the `Forbidden error` and successfully enable your site preview on Nuxt Studio. If not, please contact us on the [Discord server](https://discord.gg/sBXDm6e8SP).

‎docs/content/docs/7.studio/2.syncronization.md

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: Allow real time synchronization between Studio and GitHub
3+
description: Nuxt Studio is natively synced with GitHub. Install the Nuxt Studio GitHub app and enable content publication on GitHub directly from Studio.
4+
navigation:
5+
title: Synchronization
6+
---
7+
8+
::tip
9+
This section explains the syncronization behaviour between Studio and GitHub. However this process is handled directly from the platform and do not require any external action. This page purpose is purely informational.
10+
::
11+
12+
## Overview
13+
14+
Nuxt Studio integrates with the [GitHub](https://github.com) API, enabling smooth synchronization between Studio and your GitHub repositories. This first-class integration is made possible through the utilization of [GitHub Apps](https://docs.github.com/en/developers/apps/getting-started-with-apps/about-apps#about-github-apps).
15+
16+
## Installation
17+
18+
To begin, you need to install the [Nuxt Studio GitHub App](https://github.com/apps/nuxt-studio) in your personal account or in the organizations you manage. Installing a GitHub App requires either organization ownership or admin permissions in a repository. If you lack the necessary permissions, the repository owner will need to approve the request.
19+
20+
You can access the installation page from anywhere on the app by clicking on [Install with GitHub](https://github.com/apps/nuxt-studio/installations/new).
21+
22+
### Permissions
23+
24+
During the installation of our GitHub app, you will be prompted to grant certain permissions:
25+
26+
- Read access to `actions`, `metadata`, `members`, and `plan`
27+
- Read and write access to `secrets`, `administration`, `contents`, `pages`, `pull requests` and `workflows`
28+
29+
We need read access to `actions` to send a notification when a workflow run fails on a pull request or on the repository default branch. `metadata` is mandatory to fetch repository data, `members` to import your organization members and repository collaborators and `plan` is used to propose features based on your GitHub account plan.
30+
31+
Nuxt Studio acts on your behalf to create repositories, branches, pull requests, and perform commits and merges. We also offer one-click deployment to GitHub Pages with instant preview of workflows and environment variables secrets management. To accomplish this, we need read and write access to `administration`, `contents`, `pages`, `pull requests`, `workflows` and `secrets`.
32+
33+
### Repositories Installations
34+
35+
When installing our GitHub app, you will be prompted to select all repositories or a subset of them. This selection can be changed at any time by going to the [GitHub app settings](https://github.com/apps/nuxt-studio/installations/new).
36+
37+
By clicking on `Install`, Nuxt Studio will install each repository you have selected, enabling you to perform all the actions listed above.
38+
39+
## Uninstall
40+
41+
All the data imported from GitHub is directly associated with your GitHub app installation. If you uninstall the GitHub app, all the associated data will be deleted.

‎docs/content/docs/7.studio/3.content.md

+143
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
---
2+
title: Edit your content
3+
navigation:
4+
title: Content editors
5+
description: Discover and select your favorite way to manage your content between the visual or the code editor.
6+
seo:
7+
title: Edit your Nuxt Content website with our editors
8+
description: Overview of our different Studio CMS editors to manage your content and your medias. Choose between our visual editors and our code editor.
9+
---
10+
11+
Nuxt Studio offers a versatile workspace for both developers and content writers, giving them the freedom to choose between our differents editors:
12+
- [Notion-like editor](#markdown-editor-markdown-files) for `Markdown` files
13+
- [Form editor](#form-editor-yaml-and-json-files) for `YAML` and `JSON` files
14+
- [Code editor](#code-editor) for any kind of files (for technical users only)
15+
16+
::tip
17+
You can choose your favorite editor from the settings page of your project.
18+
::
19+
20+
Each editor serves its own purpose. Some users are used to code edition, while others prefer a non-technical, visual approach. At the end, **code syntax is the final output** for both editors.
21+
22+
## Notion-like editor (`Markdown` files)
23+
24+
![edit your website with a visual interface](/docs/studio/visual-markdown-editor.webp)
25+
26+
This editor is heavily inspired by Notion, well known for its intuitive design and flexibility. Much like a standard text editor, this editor is designed to be familiar and easy to use. However, it stands out with its additional features that improve the writing experience:
27+
28+
29+
### Front-matter
30+
31+
[Front-matter](/docs/files/markdown#front-matter) is a convention of Markdown-based CMS to provide meta-data to pages, like description or title or any other data you would like to store as `key: value` pair.
32+
33+
Based on the user [collection and schema](/docs/collection/define) provided, a form is generated to edit this metadata from the editor.
34+
35+
:video{autoplay controls loop poster="/assets/home/videos/HomeNotionLikePoster.webp" src="https://res.cloudinary.com/nuxt/video/upload/v1729157955/frontmatterform2_rmh58v.mp4"}
36+
37+
### Toolbar
38+
39+
Highlight your text to reveal the toolbar, giving you access to all the standard text editing features (title formatting, Bold, Italic, Strike-through, code, link, class, bullet list, numerated list...).
40+
41+
### Medias
42+
43+
Users can simply drag and drop images directly into the editor. An upload modal will open to let you choose the destination folder.
44+
45+
By typing `/` and searching for `Image` or `Video`, they can quickly insert a media. A modal will open to let them choose the media they want to insert from the media gallery (aka the`public` folder of the Nuxt application).
46+
47+
From the media modal, you can set the [alt attribute](https://www.w3schools.com/tags/att_img_alt.asp) for SEO and accessibility purpose.
48+
49+
### Vue Components
50+
51+
One of this editor standout features is its ability to integrate and customize any complex `Vue` component directly within the editor.
52+
53+
In other terms, a developer can create any kind of visually complex components and editors will be able to use them and focus on the content. An editor can also tweak the component properties, styles, and behavior to fit its specific requirements as long as the developer made it customizable.
54+
55+
::steps{level="4"}
56+
57+
#### Create your component
58+
59+
You can create Vue components and integrate them into Markdown. They just need to be located in the `/components/content` folder to be available.
60+
61+
```vue [components/content/HomeFeature.vue]
62+
<template>
63+
<div class="flex items-start gap-3">
64+
<div class="flex items-center justify-center border rounded-lg p-1.5">
65+
<UIcon :name="icon" />
66+
</div>
67+
<div class="flex flex-col">
68+
<h3 class="font-semibold">
69+
<ContentSlot name="title" />
70+
</h3>
71+
<span>
72+
<ContentSlot name="description" />
73+
</span>
74+
</div>
75+
</div>
76+
</template>
77+
78+
<script setup lang="ts">
79+
defineProps({
80+
icon: {
81+
type: String,
82+
default: 'i-ph-cursor-click',
83+
},
84+
})
85+
</script>
86+
```
87+
88+
#### Integrate these components easily within any Markdown file using [MDC syntax](/docs/files/markdown#mdc-syntax)
89+
90+
```mdc [content/index.md]
91+
::home-feature
92+
---
93+
icon: i-ph-cube
94+
---
95+
#title
96+
Embedded Vue components
97+
#description
98+
Edit slots and props inside the Notion-like editor.
99+
::
100+
```
101+
102+
103+
#### Edit them with our Studio editors
104+
105+
The visual editor simplifies the component edition, allowing you to integrate and edit them directly in the visual editor. Non technical users can play with **slots** and **props** without any technical knowledge.
106+
107+
![vue component edition on Studio](/docs/studio/home-content-studio-dark.webp)
108+
109+
All components in the `/components/content` folder are available in the editor. Studio users can type `/` anywhere while editing to access the list of available components.
110+
111+
::tip{to="/docs/studio/debug"}
112+
Take a look at this section to validate your `Vue` component integration in the editor in local development.
113+
::
114+
115+
::
116+
117+
::tip{to="https://nuxt.studio/blog/visual-editor"}
118+
You want to know how we've built this editor and how it works under the hood? Check this blog post.
119+
::
120+
121+
## Form editor (`YAML` and `JSON` files)
122+
123+
![YAML and JSON edition with auto generated form](/docs/studio/json-yml-forms.png)
124+
125+
This editor removes the need for users to interact directly with complex file syntax such as `YAML` or `JSON`.
126+
127+
Based on the user [collection and schema](/docs/collection/define) provided, a form is generated for both `YAML` and `JSON` files.
128+
129+
::warning
130+
Arrays are not yet handled but should be generated soon thanks to collections and user-defined schemas.
131+
::
132+
133+
## Code editor
134+
135+
![Edit directly your raw content with our code editor](/docs/studio/code-editor.webp)
136+
137+
Even though the two previous editors are dedicated to a specific file extension (`md` or `yaml`/`json`). The code editor can be used with any kind of file.
138+
139+
It provides full control over your content, allowing you to write raw content directly:
140+
- [MDC](/docs/files/markdown) syntax for `Markdown` files
141+
- [JSON](/docs/files/json) or [YAML](/docs/files/yaml) syntax
142+
143+
When your file is saved with the code editor, the content is stored exactly as you've written it, preserving all specific syntax and formatting. This editor is ideal for users comfortable with code syntax (`Markdown`, `YAML` or `JSON`) who want precise control over structure of their content.

‎docs/content/docs/7.studio/4.medias.md

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
title: Manage and integrate Medias in Nuxt Content Studio CMS
3+
navigation:
4+
title: Medias
5+
description: Explore how to browse and manage media files, and integrate them into your projects using Nuxt Content Studio CMS features.
6+
---
7+
8+
9+
## Browse your medias
10+
11+
All medias located in the `/public` directory are available in the **Media** tab of the Studio platform.
12+
13+
![Media gallery on Studio](/docs/studio/editors-medias.webp)
14+
15+
It's an intuitive interface for non technical users to manage their `/public` directory.
16+
17+
Users can easily browse folders, upload new media at any level, and drag and drop media into other folders, making medias organization straightforward.
18+
19+
The interface is designed to be intuitive for non-technical users. It can be viewed as a user friendly IDE.
20+
21+
## Use it in the Notion-like editor
22+
23+
Users can simply drag and drop images directly into the editor. An upload modal will open to let you choose the destination folder.
24+
25+
By typing `/` and searching for `Image`, they can quickly insert a media. A modal will open to let them choose the media they want to insert.
26+
27+
From the media modal, you can set the [alt attribute](https://www.w3schools.com/tags/att_img_alt.asp) for SEO and accessibility purpose.

0 commit comments

Comments
 (0)