How to Contribute

We welcome contributions to the HexOS documentation!
Whether you have a new guide, found an error you want to correct, here's how to get started:

Setup

1. Fork this repository - Click the "Fork" button in the top right

   

2. Clone your fork locally:

   git clone https://github.com/YOUR_USERNAME/hexos-docs.git
   cd hexos-docs

3. Install dependencies:

   npm install

4. Create a new branch from dev:

   git checkout dev
   git pull origin dev
   git checkout -b your-feature-name

Making Changes

1. Make your changes to the documentation

2. Test locally with npm run docs:dev

3. Test your changes don't break the build with npm run docs:build

4. Commit your changes with a clear message:

   git add .
   git commit -m "add detailed information for feature/bug fix"

Submitting Your Contribution

1. Push to your fork:

   git push origin your-feature-name

2. Open a Pull Request against the dev branch (not main)

3. Fill out the PR template with details about your changes

4. Wait for review and address any feedback

   Note: It may take time for our team to review contributions, so don't worry if your pull request isn't immediately accepted. We appreciate your patience!

Using GitHub in the Browser

If you prefer to make contributions directly in your browser without cloning the repository, here are some helpful tips:

Switch to the Dev Branch

Before making any changes, make sure you're working on the dev branch:

Click the branch selector and choose dev before creating or editing files.

Preview Your Changes with PullPreview

When you open a pull request, our repository automatically generates a live preview of your changes using PullPreview. This lets you see exactly how your changes will look on the live site before they're merged.

How to Access Your Preview

1. After opening your pull request, scroll down to the checks section at the bottom

2. Look for the PullPreview check in the list

3. Click on Details next to the PullPreview check

   

4. Once the preview is ready, you'll see a success message with a link to your preview site

   

5. Click the preview link to open your live preview in a new tab

   

If the Preview Build Fails

Sometimes the preview build might fail. This is usually due to broken links or build errors. Here's how to troubleshoot:

1. Click Details on the failed PullPreview check

   

2. Review the error logs to identify the issue. Common problems include:

   • Broken links: Links pointing to pages that don't exist
   • Dead links: External URLs that are no longer valid
   • Build errors: Syntax errors in markdown or configuration
   

3. Fix the issues in your pull request by making additional commits

4. The preview will automatically rebuild once you push new changes

TIP

PullPreview can take a minute or two to build. Be patient! If it's taking longer than expected, check the logs by clicking Details on the check.

Need Help?

If you have any questions or need assistance, be sure to check out the HexOS Community forums where you can get help from other contributors and the HexOS team.