Minecraft Bedrock Documentation Contributor

You are an expert at contributing to the Minecraft Bedrock Edition creator documentation repository (MicrosoftDocs/minecraft-creator). This repository contains markdown documentation for creators who build add-ons, worlds, and other content for Minecraft: Bedrock Edition.

Repository Structure

The repository is organized as follows:

- `latest/van/` - Vanilla sample files from github.com/mojang/bedrock-samples

- `samples/microsoft/minecraft-samples-main` - Minecraft Content Samples

- `samples/microsoft/minecraft-scripting-samples-main` - Minecraft Scripting Samples

Generated Content (Do Not Edit)

The following folders contain auto-generated content from source code and must NOT be edited directly:

Step-by-Step Instructions

1. Editing Form JSON Content

When working with JSON files in the `content/` folder:

1. **Understand the schema**: Reference `docs/dataform/IFormDefinition.ts` for the TypeScript definition of the JSON format

2. **CRITICAL: Never edit generated sections**:

- Do NOT modify `generated_doNotEdit` sub-nodes

- Do NOT modify `generatedSchema_doNotEdit` sub-nodes

3. **Make overrides correctly**:

- Add or edit override fields in the base of the JSON node

- Only create overrides if content will differ from generated sections

4. **Validate JSON syntax** before committing

2. Writing Markdown Documentation

When creating or editing markdown files:

1. **Follow Microsoft Style Guide**:

- Web version: https://learn.microsoft.com/en-us/style-guide/

- GitHub version: https://github.com/MicrosoftDocs/microsoft-style-guide/

2. **Validate consistency** against reference repositories:

- Cross-reference with vanilla sample files

- Check Minecraft Content Samples for examples

- Review Minecraft Scripting Samples for code patterns

3. **Use Minecraft Creator Tools** (github.com/mojang/minecraft-creator-tools) for additional context

4. **Avoid editing generated markdown** in ScriptAPI and Reference folders

3. Moving or Renaming Documents

When moving or renaming documentation files:

1. **Update redirects**: Edit `.openpublishing.redirection.json` file(s) to add necessary redirects

2. **Maintain link integrity**: Ensure all internal links point to correct locations

3. **Update table of contents**: Modify TOC.yml files accordingly

4. Adding New Documents

When creating new documentation:

1. **Place in correct location**: Put markdown files in appropriate `creator/` subfolder

2. **Update table of contents**: Add entries to TOC.yml files:

- Root TOC: `creator/TOC.yml`

- Localized TOC: Subfolder-specific `TOC.yml` files

3. **Follow naming conventions**: Use lowercase, hyphenated filenames

4. **Include proper frontmatter**: Add required metadata to markdown files

5. Validation and Quality Checks

Before submitting contributions:

1. **Check against vanilla samples**: Ensure technical accuracy with bedrock-samples

2. **Verify code examples**: Test any code snippets against scripting samples

3. **Review style compliance**: Confirm adherence to Microsoft Style Guide

4. **Check internal links**: Verify all cross-references work correctly

5. **Review additional guidelines**: Check `docs/` folder for specific standards

Important Constraints

Reference Resources

Usage Example

When asked to add documentation for a new Minecraft feature:

1. Research the feature in vanilla samples and scripting samples

2. Create a new markdown file in the appropriate `creator/` subfolder

3. Write content following Microsoft Style Guide

4. Add entry to relevant TOC.yml file

5. Include code examples validated against official samples

6. Cross-reference related documentation

7. Ensure all links and redirects are correct

When asked to update form JSON content:

1. Locate the JSON file in `content/` folder

2. Review the schema in `docs/dataform/IFormDefinition.ts`

3. Add override fields in the base JSON node (never in generated sections)

4. Validate JSON syntax

5. Ensure changes align with generated content where applicable