first commit
This commit is contained in:
2
docs/content/1.getting-started/.navigation.yml
Normal file
2
docs/content/1.getting-started/.navigation.yml
Normal file
@ -0,0 +1,2 @@
|
||||
title: Getting Started
|
||||
icon: false
|
||||
54
docs/content/1.getting-started/2.introduction.md
Normal file
54
docs/content/1.getting-started/2.introduction.md
Normal file
@ -0,0 +1,54 @@
|
||||
---
|
||||
title: Introduction
|
||||
description: Welcome to Docus theme documentation.
|
||||
navigation:
|
||||
icon: i-lucide-house
|
||||
seo:
|
||||
title: Introduction
|
||||
description: Discover how to create, manage, and publish documentation
|
||||
effortlessly with Docus.
|
||||
---
|
||||
|
||||
Welcome to **Docus**, a fully integrated documentation solution built with [Nuxt UI Pro](https://ui.nuxt.com/pro).
|
||||
|
||||
## What is Docus?
|
||||
|
||||
Docus is a theme based on the [UI Pro documentation template](https://docs-template.nuxt.dev/). While the visual style comes ready out of the box, your focus should be on writing content using the Markdown and [MDC syntax](https://content.nuxt.com/docs/files/markdown#mdc-syntax) provided by [Nuxt Content](https://content.nuxt.com).
|
||||
|
||||
We use this theme across all our Nuxt module documentations, including:
|
||||
|
||||
::card-group
|
||||
:::card
|
||||
---
|
||||
icon: i-simple-icons-nuxtdotjs
|
||||
target: _blank
|
||||
title: Nuxt Image
|
||||
to: https://image.nuxt.com
|
||||
---
|
||||
The documentation of `@nuxt/image`
|
||||
:::
|
||||
|
||||
:::card
|
||||
---
|
||||
icon: i-simple-icons-nuxtdotjs
|
||||
target: _blank
|
||||
title: Nuxt Supabase
|
||||
to: https://supabase.nuxtjs.org
|
||||
---
|
||||
The documentation of `@nuxt/supabase`
|
||||
:::
|
||||
::
|
||||
|
||||
## Key Features
|
||||
|
||||
This theme includes a range of features designed to improve documentation management:
|
||||
|
||||
- **Powered by** [**Nuxt 3**](https://nuxt.com): Utilizes the latest Nuxt framework for optimal performance.
|
||||
- **Built with** [**Nuxt UI**](https://ui.nuxt.com) **and** [**Nuxt UI Pro**](https://ui.nuxt.com/pro): Integrates a comprehensive suite of UI components.
|
||||
- [**MDC Syntax**](https://content.nuxt.com/usage/markdown) **via** [**Nuxt Content**](https://content.nuxt.com): Supports Markdown with component integration for dynamic content.
|
||||
- [**Nuxt Studio**](https://content.nuxt.com/docs/studio) **Compatible**: Write and edit your content visually. No Markdown knowledge is required!
|
||||
- **Auto-generated Sidebar Navigation**: Automatically generates navigation from content structure.
|
||||
- **Full-Text Search**: Includes built-in search functionality for content discovery.
|
||||
- **Optimized Typography**: Features refined typography for enhanced readability.
|
||||
- **Dark Mode**: Offers dark mode support for user preference.
|
||||
- **Extensive Functionality**: Explore the theme to fully appreciate its capabilities.
|
||||
65
docs/content/1.getting-started/3.installation.md
Normal file
65
docs/content/1.getting-started/3.installation.md
Normal file
@ -0,0 +1,65 @@
|
||||
---
|
||||
title: Installation
|
||||
description: Get started with Docus.
|
||||
navigation:
|
||||
icon: i-lucide-download
|
||||
seo:
|
||||
description: Get started with Docus documentation theme.
|
||||
---
|
||||
|
||||
## Local development
|
||||
|
||||
::steps
|
||||
### Create your docs directory
|
||||
|
||||
Use the `docus` CLI to create a new Docus project in the `docs/` directory:
|
||||
|
||||
```bash [Terminal]
|
||||
npx docus init docs
|
||||
```
|
||||
|
||||
We recommend using the `npm` package manager.
|
||||
|
||||
### Start your docs server in development
|
||||
|
||||
Move to the `docs/` directory and start your docs server in development mode:
|
||||
|
||||
```bash [Terminal]
|
||||
npm run dev
|
||||
```
|
||||
|
||||
A local preview of your documentation will be available at <http://localhost:4000>
|
||||
|
||||
### Write your documentation
|
||||
|
||||
Head over the [Edition](/concepts/edition) section to learn how to write your documentation.
|
||||
::
|
||||
|
||||
## Online Edition with [Nuxt Studio](https://content.nuxt.com/studio)
|
||||
|
||||
::prose-steps
|
||||
### Create a new project on [Nuxt Studio](https://nuxt.studio)
|
||||
|
||||
From your user or team dashboard, click the `New project` button then choose `Start from a template` and select **Docus.** Clone it on your GitHub personal account or any organisation of your choice.
|
||||
|
||||
### Deploy in one click
|
||||
|
||||
Once your project has been created and you're in the project dashboard, navigate to the `Deploy` section, choose the `GitHub Pages` tab and set your [Nuxt UI Pro license](https://ui.nuxt.com/pro/pricing) (`NUXT_UI_PRO_LICENSE` ) in the environment variables then click on the **Deploy** button.
|
||||
|
||||
:::prose-note
|
||||
---
|
||||
to: https://content.nuxt.com/docs/studio/setup#enable-the-full-editing-experience
|
||||
---
|
||||
This is a one click static deployment available with [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site) but you can also handle deployment yourself and use the `Selfhosted` tab.
|
||||
:::
|
||||
|
||||
### Write your documentation in the editor
|
||||
|
||||
Once the deployment is achieved, you'll be able to display the preview of your documentation. You can browse your content pages to edit them or create new ones.
|
||||
|
||||
:video{controls loop poster="https://res.cloudinary.com/nuxt/video/upload/v1747230893/studio/wzt9zfmdvk7hgmdx3cnt.jpg" src="https://res.cloudinary.com/nuxt/video/upload/v1747230893/studio/wzt9zfmdvk7hgmdx3cnt.mp4"}
|
||||
::
|
||||
|
||||
::prose-tip{to="https://content.nuxt.com/docs/studio/debug"}
|
||||
If you want to try Docus and Nuxt Studio in develoment mode without an UI Pro license, you can check the Nuxt Content documentation for local setup with Nuxt Studio.
|
||||
::
|
||||
52
docs/content/1.getting-started/4.project-structure.md
Normal file
52
docs/content/1.getting-started/4.project-structure.md
Normal file
@ -0,0 +1,52 @@
|
||||
---
|
||||
navigation:
|
||||
icon: i-lucide-folder-tree
|
||||
title: Project Structure
|
||||
---
|
||||
|
||||
Docus provides a ready-to-use [documentation website starter](https://github.com/nuxtlabs/docus/tree/main/.starter).
|
||||
|
||||
This is the minimal directory structure to get an up and running Docus website.
|
||||
|
||||
```bash
|
||||
content/
|
||||
index.md
|
||||
public/
|
||||
favicon.ico
|
||||
package.json
|
||||
```
|
||||
|
||||
### `content/` directory
|
||||
|
||||
This is where you [write pages](/concepts/edition) in Markdown.
|
||||
|
||||
### `public/` directory
|
||||
|
||||
Files contained within the `public/` directory are served at the root and are not modified by the build process of your documentation. This is where you can locate your medias.
|
||||
|
||||
### `package.json`
|
||||
|
||||
This file contains all the dependencies and scripts for your application. The `package.json` of a Docus application si really minimal and looks like:
|
||||
|
||||
```json [package.json]
|
||||
{
|
||||
"name": "docus-starter",
|
||||
"scripts": {
|
||||
"dev": "docus dev",
|
||||
"build": "docus build"
|
||||
},
|
||||
"devDependencies": {
|
||||
"docus": "latest"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `app.config.ts`
|
||||
|
||||
*This file is not mandatory to start a Docus application.*
|
||||
|
||||
This is where you can [configure Docus](/concepts/configuration) to fit your branding, handle SEO and adapt links and socials.
|
||||
|
||||
::prose-tip{to="/concepts/nuxt"}
|
||||
Docus uses a layer system, you can go further and use any feature or file of a classical Nuxt project from `nuxt.config.ts` to `app/components` or `server/` directory.
|
||||
::
|
||||
129
docs/content/1.getting-started/5.studio.md
Normal file
129
docs/content/1.getting-started/5.studio.md
Normal file
@ -0,0 +1,129 @@
|
||||
---
|
||||
title: Web Editor
|
||||
description: Build your documentation using Nuxt Studio web editor
|
||||
navigation:
|
||||
icon: i-lucide-mouse-pointer-2
|
||||
---
|
||||
|
||||
## **Introduction**
|
||||
|
||||
The [Nuxt Studio](https://nuxt.studio) **web editor** is a browser-based visual interface for creating, editing, and reviewing your documentation. It provides a preview experience while keeping your work in sync with your Git repository.
|
||||
|
||||
:video{controls loop src="https://res.cloudinary.com/nuxt/video/upload/v1747230893/studio/wzt9zfmdvk7hgmdx3cnt.mp4"}
|
||||
|
||||
::prose-tip{to="https://content.nuxt.com/studio"}
|
||||
Learn more about Nuxt Studio in the Nuxt Content documentation.
|
||||
::
|
||||
|
||||
## **Web Editor vs. CLI**
|
||||
|
||||
The **web editor** of [Nuxt Studio](https://nuxt.studio) allows you to manage your documentation entirely from your browser. There is no need for local development tools or terminal commands. It’s ideal for maintaining your docs in one centralised place, with an easy tool without any Markdown skills required.
|
||||
|
||||
The **CLI (Command Line Interface)**, on the other hand, is a local tool designed for developers who prefer working in their own IDE.
|
||||
|
||||
::prose-note
|
||||
Both tools are fully integrated with Git, so you can switch between them as needed. Team members can choose whichever method suits their workflow best.
|
||||
::
|
||||
|
||||
## **Two distinct editors**
|
||||
|
||||
Nuxt Studio offers a versatile workspace for both developers and content writers, giving them the freedom to choose between two distinct editors for content creation and management: the **Markdown editor** and the **Visual editor**.
|
||||
|
||||
You can select your favorite editor from the settings page of your project.
|
||||
|
||||
::prose-note
|
||||
Each editor serves its own purpose, some users are used to Markdown edition, while others prefer a non-technical, visual approach. At the end, **Markdown syntax is the final output** for both editors.
|
||||
::
|
||||
|
||||
## **Markdown editor**
|
||||
|
||||
|
||||
|
||||
The Markdown editor in Nuxt Studio provides full control over your content, allowing you to write directly you documentation in **Markdown** and integrate Vue components with the [MDC syntax](https://content.nuxt.com/docs/files/markdown#mdc-syntax).
|
||||
|
||||
When your file is saved with the Markdown 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 Markdown who want precise control over the layout and structure of their content.
|
||||
|
||||
## **Visual editor**
|
||||
|
||||
|
||||
|
||||
The Nuxt Studio editor is heavily inspired by Notion, well known for its intuitive design and flexibility. Much like a standard text editor, the Studio editor is designed to be familiar and easy to use.
|
||||
|
||||
However, it stands out with its additional features that improve the writing experience:
|
||||
|
||||
### **Toolbar**
|
||||
|
||||
Highlight your text to reveal the toolbar, giving you access to all the standard text editing features provided by the [Markdown syntax](/essentials/markdown-syntax):
|
||||
|
||||
- Title formatting
|
||||
- Bold
|
||||
- Italic
|
||||
- Strike-through
|
||||
- Code
|
||||
- Link
|
||||
- Class
|
||||
- Bullet list
|
||||
- Numerated list
|
||||
|
||||
### **The** `/` **shortcut**
|
||||
|
||||
Simply type `/` anywhere in the editor to access all Studio features.
|
||||
|
||||
#### **Formatting features**
|
||||
|
||||
- Title formatting
|
||||
- Line break
|
||||
- Horizontal rule
|
||||
- Code-block
|
||||
- Paragraph
|
||||
- Bold & italic
|
||||
|
||||
#### **Components**
|
||||
|
||||
One of Studio's standout features is its ability to integrate and customize any complex component directly within the editor.
|
||||
|
||||
In other terms, all [Nuxt UI components](/essentials/components) are usable and can be integrated directly from the editor. An editor can also tweak the component properties, slots and styles.
|
||||
|
||||
::prose-note
|
||||
You can also create custom components and let the user integrate them from the visual editor.
|
||||
::
|
||||
|
||||
Just type `/` to access the list of all the components available.
|
||||
|
||||
#### **Images**
|
||||
|
||||
Using the `/`shortcut, you can quickly insert an image by selecting the `Image` option. A modal will open to let you choose the media you want to insert.
|
||||
|
||||
From the media modal, you can set the **alt attribute** for SEO and accessibility purpose.
|
||||
|
||||
#### **Videos**
|
||||
|
||||
Using the `/` shortcut, you can quickly insert a video by selecting the `Video` choice and filling up the Video URL.
|
||||
|
||||
As soon as a video is added, a tab will automatically open with all the props field **available by default**, for you to fill out the URL and customize your media.
|
||||
|
||||
## **Live Preview**
|
||||
|
||||
|
||||
|
||||
Once your documentation is deployed, it provides a live preview feature that lets you instantly see updates to your project.
|
||||
|
||||
We're using your production website to override contents and display the new visual. This is why we need the URL to be set in the **deploy** section.
|
||||
|
||||
When you are editing your website with Studio, the live preview can be displayed on the right part of your screen. You get an instant feedback when typing. It syncs the preview based on your draft updates.
|
||||
|
||||
## **Making Changes**
|
||||
|
||||
To edit your documentation:
|
||||
|
||||
1. **Browse files** using the file explorer.
|
||||
2. **Open a file** by clicking on it.
|
||||
3. **Edit content** in either visual or Markdown mode. All edits are automatically saved as drafts.
|
||||
4. **Preview your changes** to see how they’ll appear when published.
|
||||
|
||||
## **Publishing Changes**
|
||||
|
||||
When you’re ready to publish:
|
||||
|
||||
- Click the **Publish** button in the top-right corner of the editor.
|
||||
- Your changes will be pushed directly to your deployment branch and go live immediately.
|
||||
24
docs/content/1.getting-started/6.migration.md
Normal file
24
docs/content/1.getting-started/6.migration.md
Normal file
@ -0,0 +1,24 @@
|
||||
---
|
||||
title: Migration
|
||||
description: " How to migrate your documentation from an existing Markdown
|
||||
solution to Docus"
|
||||
navigation:
|
||||
icon: i-lucide-replace
|
||||
---
|
||||
|
||||
## **Migrating to Docus**
|
||||
|
||||
Already using a Markdown-based solution for your documentation? Whether it’s **Docus v1**, the **Nuxt UI Pro docs template**, or another static site setup, migrating to Docus is simple and straightforward.
|
||||
|
||||
Docus offers a clean and maintainable solution with a single dependency: the Docus library itself. There’s no need to manage multiple .dependencies With everything built-in and maintained together, keeping your documentation up to date is easier than ever.
|
||||
|
||||
To migrate, just move your existing Markdown files into the `content/` directory of the Docus starter.
|
||||
|
||||
From there, you have two scenarios:
|
||||
|
||||
- **If your current docs already use Nuxt Content and the MDC syntax**, make sure the components used in your content exist in Nuxt UI. If any components are missing, you can easily create your own custom ones.
|
||||
- **If you’re using standard Markdown**, you can copy your files as is. Then, enhance your documentation progressively using the [built-in components](/essentials/components) provided by Nuxt UI.
|
||||
|
||||
Once your content has been moved to the `content/` folder, you can go through the [configuration section](/concepts/configuration) to easily customize your app.
|
||||
|
||||
Docus is designed to focus on writing content, so if you're already using Markdown, you can easily switch to it.
|
||||
Reference in New Issue
Block a user