Skip to main content

Contributing to the Documentation

We welcome contributions to improve the Kube-Hetzner documentation! This guide will help you get started with contributing to the docs.

Documentation Structure​

The documentation is built using Docusaurus and is located in the docs/ directory. The main documentation files are in Markdown format with frontmatter for metadata.

Auto-Generated Documentation​

Important Note for Contributors: The main variables reference page (docs/configuration/terraform.md) is automatically generated from the Terraform module's code comments using terraform-docs. Do not edit this file manually, as your changes will be overwritten during the next documentation build.

If you need to update variable descriptions or add new variables:

  1. Update the comments in the Terraform module's variables.tf file
  2. Run terraform-docs to regenerate the documentation
  3. Commit both the source code changes and the regenerated documentation

Making Changes​

For New Documentation​

  1. Create a new Markdown file in the appropriate directory under docs/
  2. Add the required frontmatter:
    frontmatter.yaml
    ---
    sidebar_position: X
    ---
  3. Write your content using Markdown
  4. Update sidebars.ts to include the new page in the navigation

For Existing Documentation​

  1. Locate the relevant Markdown file in docs/
  2. Make your changes
  3. Ensure the content follows the established style and structure

Style Guidelines​

  • Use clear, concise language
  • Include code examples where appropriate
  • Use proper heading hierarchy (H1 for title, H2 for sections, etc.)
  • Include cross-references to related documentation
  • Test all code examples for accuracy

Testing Your Changes​

To preview your documentation changes locally:

  1. Navigate to the docu/ directory
  2. Install dependencies: npm install
  3. Start the development server: npm start
  4. Open http://localhost:3000 in your browser

Submitting Changes​

  1. Create a pull request with your changes
  2. Ensure all new pages are properly linked in the sidebar
  3. Verify that the documentation builds successfully
  4. Request review from maintainers

Areas for Contribution​

  • New Features: Document newly added features and configuration options
  • Examples: Add practical examples and use cases
  • Troubleshooting: Expand troubleshooting guides
  • Best Practices: Share best practices and recommendations
  • Tutorials: Create step-by-step guides for common tasks

Thank you for helping improve the Kube-Hetzner documentation!