diff --git a/content/docs/contribute/docs/editing-with-vscode.mdx b/content/docs/contribute/docs/editing-with-vscode.mdx new file mode 100644 index 0000000..1a1225f --- /dev/null +++ b/content/docs/contribute/docs/editing-with-vscode.mdx @@ -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 + + When adding images, reference them from `/assets` (not `/public/assets`). Example: + ``` + ![Example Image](/assets/user-manual/image.png) + ``` + + +3. **Using Fumadocs Components**: + - Our documentation uses [Fumadocs UI](https://fumadocs.vercel.app/docs/ui) components like ``, ``, ``, etc. + - You can use these components directly within your `.mdx` files. + - **Global Components:** Components like `` are globally available and don't require an explicit import. + - **Imported Components:** Components like `` or `` 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. \ No newline at end of file diff --git a/content/docs/contribute/docs.mdx b/content/docs/contribute/docs/index.mdx similarity index 84% rename from content/docs/contribute/docs.mdx rename to content/docs/contribute/docs/index.mdx index 30ed3fa..a1cc231 100644 --- a/content/docs/contribute/docs.mdx +++ b/content/docs/contribute/docs/index.mdx @@ -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. - [**Node.js**](https://nodejs.org/): Required for building the NextJS site. - [**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 @@ -42,7 +42,7 @@ This command installs all the necessary packages listed in the `package.json` fi ## 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. 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. -## 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: @@ -92,7 +102,7 @@ Push your changes to your forked repository: 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: @@ -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) - [Contribution Guidelines](/contribute/contributing) - [Code of Conduct](/contribute/code-of-conduct) +- [Editing with VS Code](/contribute/docs/editing-with-vscode) --- diff --git a/content/docs/contribute/docs/meta.json b/content/docs/contribute/docs/meta.json new file mode 100644 index 0000000..8f451aa --- /dev/null +++ b/content/docs/contribute/docs/meta.json @@ -0,0 +1,7 @@ +{ + "title": "Docs", + "pages": [ + "editing-with-vscode", + "..." + ] +} \ No newline at end of file