helixml / docs

Contributing to helixml/docs

This guide outlines the steps you can take to contribute to the helixml/docs project.

Setting up your Development Environment

The project uses a devcontainer configuration. This is a recommended approach for setting up your local development environment. It ensures that your environment is properly configured, providing the necessary tools and dependencies.

  1. Install Visual Studio Code: If you haven’t already, install Visual Studio Code from the official website.

  2. Install the Remote - Containers Extension: Go to the Visual Studio Code Extensions Marketplace and install the Remote - Containers extension.

  3. Open the Project in a Container: Once the extension is installed, you can open the helixml/docs project in a container. To do this:

  • Open the project folder in Visual Studio Code.
  • Click on the green “Remote-Containers: Open Folder in Container” icon in the bottom left corner of the Visual Studio Code window.
  • Choose the appropriate container configuration. This will launch a new container with all the necessary dependencies and tools.

Contributing to the Project

Making Changes

  1. Fork the Repository: Create a fork of the helixml/docs repository on GitHub.

  2. Create a Branch: Create a new branch based on the main branch. It is recommended to use descriptive branch names that clearly indicate the purpose of your changes.

  3. Make Your Changes: Implement your changes and additions to the project files. Ensure to follow the existing coding style and conventions.

  4. Commit Your Changes: Stage and commit your changes using Git with clear, concise commit messages that explain the purpose of the changes.

  5. Push Your Branch: Push your branch to your forked repository.

  6. Open a Pull Request: Create a pull request from your branch to the main branch of the original repository.

Testing Your Changes

While there are no specific testing commands provided in the project, it is recommended to:

  • Run the project locally: Use the hugo serve command to run the project and preview your changes.
  • Manually test: Thoroughly test your changes by navigating through the website, verifying all functionalities and ensuring they work as expected.

Reviewing Your Pull Request

Once you’ve opened a pull request, the project maintainers will review your changes. They will provide feedback and address any potential issues. Be prepared to respond to comments and make necessary adjustments based on the feedback received.

Deploying Changes

The helixml/docs website is deployed using Netlify. Once your pull request is merged, the changes will automatically be deployed to the live website. You can monitor the deployment status on the Netlify website.

Updating the Theme and Dependencies

The project uses the Hugo framework for generating its static files. To update the theme and its dependencies, use the following commands:

hugo mod get -u
hugo mod tidy

Refer to the official Hugo module documentation for detailed information on updating modules.

CSS Notes

  • Prefix all color-related Tailwind CSS classes with hx-.
  • For example, instead of text-red-500, use hx-text-red-500.

Contributing Further

Contributing to helixml/docs can involve various tasks, such as:

  • Writing Documentation: Improve existing documentation or create new documentation for features, functionalities, or tutorials.
  • Fixing Bugs: Identify and fix issues reported by users or discovered during testing.
  • Improving Features: Enhance existing features or implement new features based on user needs or feedback.

By following these guidelines, you can contribute to the helixml/docs project and help make it better.