Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
263 lines (180 loc) · 6.91 KB

CONTRIBUTING.md

File metadata and controls

263 lines (180 loc) · 6.91 KB

Contributing to Hytale Modding Documentation

Thank you for your interest in contributing to the Hytale Modding Documentation project! This is a community-driven initiative, and we welcome contributions from modders, developers, designers, and documentation enthusiasts of all skill levels.

Table of Contents

Website Guides

Alongside this, you are requested to follow our guides related to contributing on our website:

Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

How Can I Contribute?

Reporting Issues

  • Documentation Errors: Found a typo, broken link, or incorrect information? Open an issue!
  • Missing Content: Notice a topic that should be covered? Suggest it!
  • Technical Issues: Encountering bugs with the site itself? Let us know!

When reporting issues, please:

  • Use a clear and descriptive title
  • Provide as much relevant information as possible
  • Include screenshots if applicable
  • Tag the issue appropriately

Suggesting Enhancements

We welcome suggestions for new features or improvements:

  • Search existing issues first to avoid duplicates
  • Clearly describe the enhancement and its benefits
  • Explain why this would be useful to the Hytale modding community

Contributing Documentation

Documentation contributions are the heart of this project:

  1. Improving Existing Docs

    • Fix typos and grammatical errors
    • Clarify confusing explanations
    • Update outdated information
    • Add examples and code snippets

  2. Writing New Content

    • Server plugin development guides
    • Data asset configuration tutorials
    • Blockbench modeling workflows
    • Visual scripting documentation
    • Best practices and patterns

  3. Adding Examples

    • Code examples for Java plugins
    • JSON configuration samples
    • Step-by-step tutorials
    • Real-world use cases

Getting Started

Prerequisites

  • Node.js 18.x or higher
  • Bun package manager (install with npm install -g bun)
  • Git
  • A text editor (VS Code, Cursor, etc.)

Local Development Setup

  1. Fork the repository on GitHub

  2. Clone your fork:

git clone https://github.com/YOUR_USERNAME/site.git
cd site
  1. Add the upstream repository:
git remote add upstream https://github.com/HytaleModding/site.git
  1. Install dependencies:
bun install
  1. Start the development server:
bun run dev
  1. Open http://localhost:3000 in your browser

BEFORE you start to work on your addition, you need to switch to the dev branch using:

git checkout dev

Documentation Guidelines

File Structure

  • Place documentation files in content/docs/en
  • Use kebab-case for file names: server-first-dev.mdx
  • Organize related content in subdirectories
  • Update meta.json files for navigation

MDX Format

Documentation files use MDX (Markdown + JSX):

---
title: Your Page Title
description: A brief description of the content
---

## Introduction

Your content here...

Content Guidelines

  1. Accuracy First

    • Verify information against official Hytale sources
    • Link to official blog posts when relevant
    • Clearly mark speculation or unconfirmed information

  2. Clear and Concise

    • Write for your audience (beginners to advanced)
    • Use simple language where possible
    • Break complex topics into digestible sections
    • Include code examples and screenshots

  3. Well-Structured

    • Use proper heading hierarchy (h2, h3, h4)
    • Include a table of contents for long pages
    • Add cross-references to related pages
    • Use callouts for important notes

  4. Code Examples

    • Provide complete, working examples
    • Include comments explaining key concepts
    • Follow Java and JSON best practices
    • Test your code before submitting

Submitting Changes

Branch Workflow

  1. Create a new branch for your changes:
git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix
  1. Make your changes and commit:
git add .
git commit -m "feat: Add clear, descriptive commit message that follow conventional commits"
  1. Push to your fork:
git push origin feature/your-feature-name
  1. Open a Pull Request on GitHub

Pull Request Guidelines

You must include a GitHub issue number while making a PR, attach your GitHub issue by prefixing your PR title with GH-<issue number>

Commit Messages

We use Conventional Commits, and you are supposed to use those commits while contributing to us. Your PR will not be accepted if you do not use conventional commits

Style Guide

Markdown Styling

  • Use **bold** for emphasis
  • Use *italic* for slight emphasis
  • Use code for inline code, file names, and commands
  • Use code blocks with language tags:
public class ExamplePlugin {
    // Your code here
}

Writing Style

  • Write in second person (you/your) when addressing readers
  • Use active voice
  • Keep sentences concise
  • Use lists for multiple items
  • Add examples to illustrate concepts

Technical Terms

  • Hytale: Always capitalize
  • Blockbench: Capitalize as proper noun
  • Java: Capitalize (programming language)
  • JSON: All caps
  • MDX: All caps

Links

  • Use descriptive link text (not "click here")
  • Link to official Hytale sources when possible
  • Use relative links for internal pages: [Quick Start](/docs/quick-start)

Community

Getting Help

  • Discord: Join our Discord for help while writing guides, remember, we are here to help you if you want to contribute!
  • GitHub Discussions: Ask questions and share ideas
  • Issues: Report bugs and request features

Recognition

Contributors are recognized in several ways:

  • Listed in the repository's contributors
  • Building a portfolio of documentation work
  • If you wrote a guide, it'll show that you are the author at the end of the page.

Questions?

If you have questions not covered in this guide:

Thank you for contributing to Hytale Modding Documentation! Your efforts help the entire community learn and grow together.