mirror of
https://github.com/zen-browser/docs.git
synced 2025-07-07 17:05:34 +02:00
Added setup guides for VS Code
This commit is contained in:
parent
f28a0b8520
commit
48a97362bd
3 changed files with 98 additions and 4 deletions
76
content/docs/contribute/docs/editing-with-vscode.mdx
Normal file
76
content/docs/contribute/docs/editing-with-vscode.mdx
Normal file
|
@ -0,0 +1,76 @@
|
||||||
|
---
|
||||||
|
title: Editing with VS Code
|
||||||
|
description: How to use Visual Studio Code to contribute to the Zen Browser documentation.
|
||||||
|
---
|
||||||
|
|
||||||
|
Visual Studio Code (VS Code) is a popular and powerful code editor that works well for editing Zen Browser documentation, especially with the right extensions.
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
- [**Visual Studio Code**](https://code.visualstudio.com/) installed on your machine.
|
||||||
|
- *Note: Popular forks of VS Code, such as [VSCodium](https://vscodium.com/), should also work well.*
|
||||||
|
|
||||||
|
## Recommended Extension: MDX
|
||||||
|
|
||||||
|
To get the best experience editing `.mdx` files in VS Code, we recommend installing the official MDX extension.
|
||||||
|
|
||||||
|
- **Extension Name:** MDX
|
||||||
|
- **Publisher:** unifiedjs
|
||||||
|
- **Marketplace Link:** [MDX - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx)
|
||||||
|
|
||||||
|
### Benefits
|
||||||
|
|
||||||
|
- **Syntax Highlighting:** Provides accurate syntax highlighting for both Markdown and JSX components within `.mdx` files.
|
||||||
|
- **IntelliSense:** Offers autocompletion and suggestions for MDX syntax and potentially imported components.
|
||||||
|
- **Error Checking:** Helps identify syntax errors in your MDX code.
|
||||||
|
|
||||||
|
### Installation
|
||||||
|
|
||||||
|
1. Open VS Code.
|
||||||
|
2. Go to the Extensions view by clicking the Extensions icon in the Activity Bar on the side of the window or by pressing `Ctrl+Shift+X` (Windows/Linux) or `Cmd+Shift+X` (macOS).
|
||||||
|
3. Search for `mdx`.
|
||||||
|
4. Click **Install** on the MDX extension by unifiedjs.
|
||||||
|
|
||||||
|
## Steps
|
||||||
|
|
||||||
|
1. **Open the Repository Folder**:
|
||||||
|
- In VS Code, go to `File > Open Folder...` (or `File > Open...` on macOS).
|
||||||
|
- Navigate to the cloned `docs` repository folder on your local machine and open it.
|
||||||
|
|
||||||
|
2. **Start Editing**:
|
||||||
|
- Open VS Code's File Explorer (left sidebar) and navigate to these key directories:
|
||||||
|
- **`content/docs/`** - Contains all documentation `.mdx` files you'll be editing
|
||||||
|
- **`public/assets/`** - Stores images and static assets referenced in documentation
|
||||||
|
- _**`src/`** - Contains site source code (no editing needed here)_
|
||||||
|
- Select any `.mdx` file to begin editing. With the MDX extension installed, you'll get:
|
||||||
|
- Syntax highlighting for Markdown and JSX
|
||||||
|
- IntelliSense suggestions
|
||||||
|
- Error checking
|
||||||
|
<Callout type="warn" title="Image Paths">
|
||||||
|
When adding images, reference them from `/assets` (not `/public/assets`). Example:
|
||||||
|
```
|
||||||
|

|
||||||
|
```
|
||||||
|
</Callout>
|
||||||
|
|
||||||
|
3. **Using Fumadocs Components**:
|
||||||
|
- Our documentation uses [Fumadocs UI](https://fumadocs.vercel.app/docs/ui) components like `<Callout />`, `<Tabs />`, `<Steps />`, etc.
|
||||||
|
- You can use these components directly within your `.mdx` files.
|
||||||
|
- **Global Components:** Components like `<Callout />` are globally available and don't require an explicit import.
|
||||||
|
- **Imported Components:** Components like `<Tabs />` or `<Steps />` need to be imported at the top of the `.mdx` file. Check existing files or the Fumadocs documentation for import examples.
|
||||||
|
```ts
|
||||||
|
import { Tabs, Tab } from 'fumadocs-ui/components/tabs';
|
||||||
|
import { Steps, Step } from 'fumadocs-ui/components/steps';
|
||||||
|
```
|
||||||
|
- Refer to the [Fumadocs UI Documentation](https://fumadocs.vercel.app/docs/ui) for details on available components and their usage.
|
||||||
|
|
||||||
|
4. **Run the Development Server** (Recommended):
|
||||||
|
- Open a terminal within VS Code (`Terminal > New Terminal`).
|
||||||
|
- Run the command `npm run dev`.
|
||||||
|
- This will start the development server, usually accessible at `http://localhost:3000`.
|
||||||
|
- The site will automatically update in your browser as you save changes to the `.mdx` files.
|
||||||
|
|
||||||
|
4. **Follow Contribution Steps**:
|
||||||
|
- Once you've made your changes, follow the standard contribution steps outlined in the main [Docs Contribution Guide](/contribute/docs#writing-guidelines): commit your changes, push them to your fork, and create a pull request.
|
||||||
|
|
||||||
|
Using VS Code with the MDX extension provides a robust environment for contributing to the Zen Browser documentation.
|
|
@ -12,7 +12,7 @@ Before you begin, ensure you have the following tools installed:
|
||||||
- [**Git**](https://git-scm.com/): Version control system to clone the repository and manage your code.
|
- [**Git**](https://git-scm.com/): Version control system to clone the repository and manage your code.
|
||||||
- [**Node.js**](https://nodejs.org/): Required for building the NextJS site.
|
- [**Node.js**](https://nodejs.org/): Required for building the NextJS site.
|
||||||
- [**npm**](https://www.npmjs.com/): Node package manager, which comes with Node.js.
|
- [**npm**](https://www.npmjs.com/): Node package manager, which comes with Node.js.
|
||||||
- **IDE of your choice**: You can use any text editor or IDE of your choice.
|
- [**IDE of your choice**](/contribute/docs/editing-with-vscode): You can use any text editor or IDE of your choice.
|
||||||
|
|
||||||
## 1. Fork the Repository
|
## 1. Fork the Repository
|
||||||
|
|
||||||
|
@ -42,7 +42,7 @@ This command installs all the necessary packages listed in the `package.json` fi
|
||||||
|
|
||||||
## 4. Open the Project in IDE
|
## 4. Open the Project in IDE
|
||||||
|
|
||||||
Open the cloned repository folder in your IDE to begin editing:
|
Open the cloned repository folder in your IDE to begin editing. If you're using Visual Studio Code, check out our [VS Code setup guide](/contribute/docs/editing-with-vscode) for detailed instructions.
|
||||||
|
|
||||||
1. Open IDE.
|
1. Open IDE.
|
||||||
2. Select "Open Folder" or "File > Open Folder".
|
2. Select "Open Folder" or "File > Open Folder".
|
||||||
|
@ -77,7 +77,17 @@ yarn dev
|
||||||
|
|
||||||
This command starts a local server running on `http://localhost:3000` that you can access from your browser. The site will automatically reload whenever you make changes to the Markdown files.
|
This command starts a local server running on `http://localhost:3000` that you can access from your browser. The site will automatically reload whenever you make changes to the Markdown files.
|
||||||
|
|
||||||
## 7. Commit and Push Your Changes
|
## 7. Check the Build
|
||||||
|
|
||||||
|
Before committing your changes, ensure the documentation site builds successfully:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run build
|
||||||
|
```
|
||||||
|
|
||||||
|
This command will build the static site. If there are any errors, fix them before proceeding.
|
||||||
|
|
||||||
|
## 8. Commit and Push Your Changes
|
||||||
|
|
||||||
Once you are satisfied with your changes, commit them to your local repository:
|
Once you are satisfied with your changes, commit them to your local repository:
|
||||||
|
|
||||||
|
@ -92,7 +102,7 @@ Push your changes to your forked repository:
|
||||||
git push origin main
|
git push origin main
|
||||||
```
|
```
|
||||||
|
|
||||||
## 8. Create a Pull Request
|
## 9. Create a Pull Request
|
||||||
|
|
||||||
After pushing your changes, go to the original Zen Browser Documentation Repository and submit a pull request:
|
After pushing your changes, go to the original Zen Browser Documentation Repository and submit a pull request:
|
||||||
|
|
||||||
|
@ -110,6 +120,7 @@ Your pull request will be reviewed by the maintainers, and you may be asked to m
|
||||||
- [Fumadocs Documentation](https://fumadocs.vercel.app/docs/ui)
|
- [Fumadocs Documentation](https://fumadocs.vercel.app/docs/ui)
|
||||||
- [Contribution Guidelines](/contribute/contributing)
|
- [Contribution Guidelines](/contribute/contributing)
|
||||||
- [Code of Conduct](/contribute/code-of-conduct)
|
- [Code of Conduct](/contribute/code-of-conduct)
|
||||||
|
- [Editing with VS Code](/contribute/docs/editing-with-vscode)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
7
content/docs/contribute/docs/meta.json
Normal file
7
content/docs/contribute/docs/meta.json
Normal file
|
@ -0,0 +1,7 @@
|
||||||
|
{
|
||||||
|
"title": "Docs",
|
||||||
|
"pages": [
|
||||||
|
"editing-with-vscode",
|
||||||
|
"..."
|
||||||
|
]
|
||||||
|
}
|
Loading…
Add table
Add a link
Reference in a new issue