Contributing

This guide helps you understand how to contribute to the Nordcraft documentation. Whether you're adding a completely new page or updating existing content, following these guidelines ensures consistency across the documentation.

The Nordcraft documentation is organized into sections and individual pages:

• Sections: Main categories like "Get started," "Components," or "Styling"
• Pages: Individual documents that can be within sections or standalone (like the "About" page)

Each section and page corresponds to a folder in the GitHub repository:

• Sections and pages are numbered (01, 02, 03...) to determine their order in the side menu
• The content of each page is stored in an index.md markdown file
• All related images are placed in the same folder as the page's index.md file

1. 1

   Identify which section your page belongs to
2. 2

   Create a new folder with the appropriate number (to maintain order) and name
   • For example: 05-the-editor for the main section
   • Or 05-the-editor/03-bottom-bar for a page within a section
3. 3

   Create an index.md file within this folder

Each documentation page needs:

1. 1

   YAML frontmatter at the top of the file with:
   • title: Page title in sentence case (used for the page's title)
   • description: Brief overview of the page's content (used for the page's meta description, keep this to under 155 characters if possible)
2. 2

   Main content with properly structured headings and content, starting with an H1 heading that matches the title

Each page must begin with YAML frontmatter at the very top of the file between triple dashes:

---
title: Page title
description: Brief description explaining what this page covers.
---

• The title is used for SEO metadata and should be in Sentence case
• The description should be a brief overview (1-2 sentences) that helps with SEO
• After the frontmatter, your content should start with an H1 heading that matches the title

• H1 (#): Used for the main title of the page (matching the frontmatter title), each page should have only one H1 heading
• H2 (##): Used for subsections within the main sections
• H3 (###): Used for topics within subsections
• H4 (####): Used for detailed points within topics (use sparingly)

When writing headings, use sentence case (use a capital letter for the first word of the heading only), except where other words require specific capitalization, such as Nordcraft or GitHub.

• Use bold to emphasize important terms
• Use italics sparingly for emphasis
• Keep paragraphs short (3-5 sentences maximum)
• Use American English spellings

• Use backticks for inline code: variable
• Use [kbd] For UI buttons and keyboard shortcuts: Button Name

• Internal documentation links: [Page Name](/path/to/page#section)
• External links: [Resource Name](https://example.com)

• Use bullet points for non-sequential items
• Use numbered lists for sequential steps
• Keep list items parallel in structure

Callouts highlight important information. Use them in this format:

Include images with an image title and aspect ratio:

![Image title|16/9](image-name.webp)

For screenshots that link to the Nordcraft editor (allowing readers to see it live in the editor):

![Image title|16/9](image-name.webp){https://toddle.dev/projects/docs_examples/branches/main/...}

Image requirements:

• All images should be in WebP format
• Images should have a 16/9 aspect ratio
• Create two versions of each image:
  • Standard version: 800px width (e.g., image-name.webp)
  • Large version: 3200px width with "-large" suffix (e.g., image-name-large.webp)
• Place all images in the same folder as the page's index.md file
• If a link is included, ensure that it points to the main branch

For component examples, use the following format:

Example requirements:

• Examples must be built in the docs_examples Nordcraft project
• Each example is implemented as a separate web component
• Always link to the main branch in the editorUrl
• Set an appropriate height value in rem units
• Add a description after the height (separated by a new line) that will be displayed within the example window

To embed YouTube videos in the documentation, use the following format:

Enable youtube videos Privacy policy

Make sure to:

• Use the correct YouTube video ID (the part after v= in the YouTube URL)
• Include a descriptive title that explains what the video demonstrates

• Always write "Nordcraft" with a capital "N"
• Use consistent terminology for features and concepts
• Avoid marketing language and unnecessary superlatives like "powerful" or "best"
• Don't include version information that will become outdated

1. 1

   Introduction: Begin with a brief explanation of the feature or concept
2. 2

   Main content: Explain key concepts with clear examples or images
3. 3

   Related information: Link to relevant documentation throughout the page where appropriate

Each page should be self-contained and understandable on its own, while still connecting to the broader documentation through relevant links.

Depending on the page type, consider including:

• Definition: What is this feature?
• Purpose: Why would someone use it?
• Example: How does it work in practice?
• Steps: How to implement it
• Best practices: Tips for optimal usage
• Common issues: Troubleshooting guidance

• Clear and concise: Use simple, direct language
• Formal but approachable: Professional but not academic
• Action-oriented: Focus on how to use features
• Use present tense and use active voice: Address the reader directly ("you")

Keep in mind the following when updating or adding documentation:

• Do not use unnecessary words or marketing language
• Do not include placeholder text or TODOs
• Do not reference personal opinions or subjective assessments
• Do not create circular references or links to non-existent pages
• Do not include screenshots that reveal user data
• Do not use inconsistent formatting or terminology

• Use front end and back end when referring to a noun e.g. "View your changes on the front end."
• Use front-end and back-end when using those phrases as an adjective e.g. "Paste the URL of your back-end API into the input field."

Since the Nordcraft documentation is hosted on GitHub, you will need to follow standard Git workflows to contribute:

1. 1

   Fork the repository: Create your own copy of the documentation repository
2. 2

   Clone locally: Download your fork to your local machine
3. 3

   Create a branch: Make a new branch for your contribution
4. 4

   Make changes: Edit or add files following the guidelines in this document
5. 5

   Test your changes:
   • Use the preview feature to verify your documentation looks correct
   • Test all links to ensure they point to valid pages
   • Review your content for clarity, accuracy, and completeness
   • Check that images display properly and have appropriate title
   • Verify that all examples work correctly, demonstrate the intended functionality and have working links to the editor
   • Ensure all formatting is consistent with the documentation guidelines
6. 6

   Commit and push: Save your changes and push them to your fork
7. 7

   Create a pull request: Submit your changes from your fork to the main repository and complete the pull request template provided

When submitting a pull request (PR):

1. 1

   Ensure relevance: PRs should address an existing issue or have been discussed with the team beforehand
2. 2

   Provide a clear title: Summarize what your changes accomplish
3. 3

   Add a detailed description: Explain the purpose of your changes
4. 4

   Complete the issue template checklists: Check off items you have completed that are relevant to the PR
5. 5

   Reference issues: If your changes address an existing issue, reference it
6. 6

   Be responsive: Watch for comments or requests for changes from reviewers

After submitting your pull request, the Nordcraft team will review your contribution. They may suggest changes or improvements before merging your work into the main documentation.

We use Prettier to automatically format the documentation in markdown and the proxy worker. We have included a script you can run in your terminal to auto format files to make sure your pull request gets approved.

To use Prettier on your machine, we suggest installing the Prettier extension in your IDE and enabling formatting on save.

1. 1

   To install dependencies to use the script, run bun i in the root of the repository.
2. 2

   Run bun prettier in your terminal to validate your changes
3. 3

   Run bun prettier:write in your terminal to auto format all files

To preview documentation pages while you're working on them:

1. 1

   Add the query parameter ?mode=preview to the URL of any documentation page
2. 2

   A preview configuration panel will appear at the bottom of the page
3. 3

   Enter the following information in the input fields:
   • Repository owner (e.g. nordcraftdev)
   • Repository name (e.g. documentation)
   • Branch name (e.g. main or your feature branch)
4. 4

   Click the Update button to load and preview the documentation from your specified source

This preview feature allows you to see how your changes will look before they're published, making it easier to identify and fix formatting issues.

By participating in the Nordcraft documentation project, you agree to abide by the project's Code of Conduct. This ensures a welcoming and inclusive environment for all contributors.

If you have questions about contributing to the documentation or need assistance with your contributions:

• Open a new issue in the Nordcraft documentation repository for discussion
• Contact the Nordcraft team in the Nordcraft Discord
• Ask in the community forums or discussion areas

The Nordcraft team is committed to helping new contributors and appreciates your efforts to improve the Nordcraft documentation.