You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/content/docs/development/contribution-docs.md
+202-4Lines changed: 202 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,10 +3,208 @@ title: Contributing to the docs
3
3
description: A guide to help anyone contribute to OpenIPC's docs.
4
4
---
5
5
6
-
## Edit an existing guide
6
+
#Contributing to the OpenIPC Documentation
7
7
8
-
## Add a new guide
8
+
Thank you for contributing to the OpenIPC documentation! This guide will walk you through two main ways to contribute: **adding a new page** and **editing an existing page**. There’s also a section for setting up a local development environment if you want to test the site locally.
9
9
10
-
## Adjust general template
10
+
For local development, we use a `.node-version` file to ensure the correct version of Node.js is used. If you want to test your changes locally, you will need to install Node.js, Yarn, and a Node version manager.
11
11
12
-
## Local development
12
+
---
13
+
14
+
## Adding a New Page
15
+
16
+
### 1. Clone the Repository
17
+
- Clone the OpenIPC documentation repository to your local machine by running the following command:
18
+
```bash
19
+
git clone https://github.com/OpenIPC/docs.git
20
+
```
21
+
22
+
- Navigate into the project directory:
23
+
```bash
24
+
cd docs
25
+
```
26
+
27
+
### 2. Create a New Branch
28
+
- Create a new branch to work on your changes:
29
+
```bash
30
+
git checkout -b add-new-page
31
+
```
32
+
33
+
### 3. Choose the Right Section to Add Your Page
34
+
35
+
Use the following table to determine where to add your new page based on its content:
Please make sure the name of the file is in snake-case (no uppercase letters and uses '-'). This will become later the url of the page.
55
+
Do not forget to add the '.md' extension, so the site knows how to handle the file.
56
+
57
+
### 5. Add Frontmatter to Your Page
58
+
At the top of the new markdown file, include the required frontmatter. This helps Starlight process the page correctly.
59
+
60
+
```yaml
61
+
---
62
+
title: "New Feature Guide"
63
+
description: "A guide to the new feature introduced in the latest release."
64
+
---
65
+
```
66
+
67
+
-`title`: The title of your new page (appears in the navigation and as the page header).
68
+
-`description`: A brief summary of the page content.
69
+
70
+
### 6. Write Your Content
71
+
You can now add your content using Markdown. Here's a basic example:
72
+
73
+
```markdown
74
+
# New Feature Guide
75
+
76
+
This guide will walk you through the new feature introduced in the latest release of OpenIPC.
77
+
78
+
## Key Features
79
+
80
+
- Improved UI for better user experience
81
+
- Enhanced security protocols
82
+
- Support for additional camera models
83
+
84
+
### How to Enable the Feature
85
+
86
+
1. Open the OpenIPC dashboard.
87
+
2. Navigate to **Settings > Features**.
88
+
3. Enable the **New Feature** toggle.
89
+
90
+
For more details, check the [official documentation](https://docs.openipc.org).
91
+
```
92
+
93
+
### 7. Add Your Page to the Sidebar Navigation (If Required)
94
+
95
+
**Important**: If your page is part of a directory that has `autogenerate` enabled in the sidebar configuration (such as `use-cases`, `hardware`, `software`, or `reference`), you do **not** need to manually add your page to the sidebar. It will be automatically included.
96
+
97
+
However, for directories that do **not** use `autogenerate`, like `getting-started`, `development`, and `resources`, you'll need to manually add your page to the sidebar. Follow these steps:
98
+
99
+
- Open the `src/content/docs/config.ts` file.
100
+
- Add your new page to the appropriate section in the sidebar navigation. For example, if you added a new feature guide under "Development", you would update the config like this:
101
+
102
+
```typescript
103
+
{
104
+
label: "Development",
105
+
items: [
106
+
{
107
+
label: "Contribution Guidelines",
108
+
link: "/development/contribution-guidelines/",
109
+
badge: { text: "WIP", variant: "caution" },
110
+
},
111
+
{
112
+
label: "New Feature Guide", // Your new page
113
+
link: "/development/new-feature-guide/",
114
+
},
115
+
],
116
+
},
117
+
```
118
+
119
+
### 8. Commit Your Changes
120
+
Once you are satisfied with your new page, commit your changes:
121
+
```bash
122
+
git add .
123
+
git commit -m "Add new feature guide to development section"
124
+
```
125
+
126
+
### 9. Push to GitHub
127
+
Push your branch to the repository on GitHub:
128
+
```bash
129
+
git push origin add-new-page
130
+
```
131
+
132
+
### 10. Open a Pull Request
133
+
- Go to the repository on GitHub and open a Pull Request (PR) from your `add-new-page` branch to the `main` branch.
134
+
- In the PR description, briefly explain what changes you've made (e.g., "Added a new feature guide under the development section").
135
+
- Submit the PR for review.
136
+
137
+
---
138
+
139
+
## Editing an Existing Page
140
+
141
+
### 1. Navigate to the Page You Want to Edit
142
+
- Go to the [OpenIPC documentation site](https://docs.openipc.org).
143
+
- Find the page that you want to edit and click the **Edit page** button, as shown below:
This will take you directly to the corresponding markdown file in the GitHub repository.
148
+
149
+
### 2. Edit the Page on GitHub
150
+
You’ll be taken to the GitHub editor, where you can make changes directly to the file. The frontmatter at the top of the file contains important metadata (such as the title and description).
151
+
152
+
For example:
153
+
154
+
155
+
156
+
### 3. Propose Your Changes
157
+
Once you've made your edits:
158
+
- Scroll down to the **Propose changes** section.
159
+
- Add a short commit message that describes the update.
160
+
- Choose whether you want to commit directly to the main branch or create a new branch for the changes.
If you've created a new branch, click **Propose changes** to start a Pull Request (PR). In the PR description, explain what changes you made and why.
166
+
167
+
Once submitted, your changes will be reviewed by a maintainer and, if approved, merged into the main branch.
168
+
169
+
---
170
+
171
+
## Setting Up Local Development (Optional)
172
+
173
+
If you want to see how the site looks with your changes or make more extensive updates (such as design changes), you can set up the project locally. This step is **not required** for basic edits or adding pages, but it’s helpful if you want to test things out locally.
174
+
175
+
### 1. Install Node.js and Yarn
176
+
177
+
Since the project uses a `.node-version` file, you’ll need to use the correct Node.js version. We recommend using a Node.js version manager like `nvm` or `fnm`.
178
+
179
+
-**Install Node.js with `nvm`**: Follow the instructions on the [nvm GitHub repository](https://github.com/nvm-sh/nvm).
180
+
-**Install Node.js with `fnm`**: Follow the instructions on the [fnm GitHub repository](https://github.com/Schniz/fnm).
181
+
182
+
Once you have Node.js installed, you can install Yarn:
183
+
- Follow the installation instructions on the [official Yarn website](https://classic.yarnpkg.com/en/docs/install/).
184
+
185
+
### 2. Install Dependencies
186
+
- Navigate into the project directory:
187
+
```bash
188
+
cd docs
189
+
```
190
+
- Install the project dependencies using Yarn:
191
+
```bash
192
+
yarn install
193
+
```
194
+
195
+
### 3. Start the Development Server
196
+
- To preview your changes, run the Astro development server:
197
+
```bash
198
+
yarn dev
199
+
```
200
+
This will run the site locally at `http://localhost:3000`, where you can see your changes in real-time.
201
+
202
+
### 4. Make Changes Locally
203
+
- You can now make changes to the files and see how they look on your local server.
204
+
205
+
---
206
+
207
+
## Additional Resources
208
+
209
+
- For more details on adding pages, visit the official Starlight documentation on [Adding Pages](https://starlight.astro.build/guides/pages/).
210
+
- For authoring content guidelines, see the [Authoring Content Guide](https://starlight.astro.build/guides/authoring-content/).
0 commit comments