Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
355 lines (239 loc) · 13.3 KB

CONTRIBUTING.md

File metadata and controls

355 lines (239 loc) · 13.3 KB
Raw

Contribute to the Polkadot Docs

📋 Essential: All contributions must follow the PaperMoon Style Guide.

Contents

Quick Start

There are two main ways to contribute:

  • Edit Online with GitHub

    • Best for simple text changes like fixing typos or making small updates directly in your browser.

  • Fork and Edit Locally

    • Recommended for more complex contributions that require local testing or previewing changes.

Edit Online with GitHub (Simple Changes)

For simple contributions like fixing typos or making small text changes, you can use GitHub's online editor.

Making Your Changes

  1. Navigate to the file you want to edit on GitHub.
  2. Click the pencil icon (✏️) to edit the file.
  3. Make your changes in the online editor.
  4. Follow the PaperMoon Style Guide.

Creating Your Pull Request

  1. Scroll to Propose changes at the bottom of the editor.
  2. Add a descriptive commit message explaining your changes.
  3. Click Propose changes. GitHub will automatically:
    • Fork the repository to your account.
    • Create a branch with your changes.
    • Open a pull request.
      • Make sure to check Allow edits from maintainers.

Fork and Edit Locally

For more complex contributions, which involve rendering (e.g., adding a .nav.yml section, code snippets, etc) or when you want to preview changes locally.

Initial Setup

Before making contributions, set up the monorepo locally:

  1. Fork the polkadot-docs repository on GitHub.

  2. Clone your fork:

    git clone https://github.com/YOUR_USERNAME/polkadot-docs.git
cd polkadot-docs

  3. Create a branch for your changes:

    git checkout -b YOUR_FEATURE_BRANCH

  4. Make your changes:

  5. Create pull request:

    • Push your branch and create a pull request.
    • Use the PR template to indicate your review preference.

Fix or Improve Existing Content

Making changes to existing pages is the simplest contribution:

  1. Edit the content: Make your improvements directly to the existing markdown file.
  2. Follow style guide: Ensure your changes maintain proper formatting according to the PaperMoon Documentation Style Guide.
  3. Test locally: Verify your changes render correctly by running the Polkadot docs locally. Instructions can be found in the README.

Add a New Page

Requirement: Follow the PaperMoon Documentation Style Guide.

To add a page to an existing section:

  1. Create your markdown file following naming conventions.

  2. Include required frontmatter (see Frontmatter Reference for all available fields):

    ---
title: Page Title (max 60 chars for SEO)
description: Description for SEO (120-160 chars).
categories: Category1, Category2
---

# Page Title

## Introduction

Write 2-3 paragraphs to introduce the topic.

## Prerequisites

List any required tools, knowledge, or setup.

    Categories

    Available categories for pages are listed in the categories_info section of llms_config.json at the repository root.

    Search Engine Optimization (SEO)

    Resources for good SEO:

  3. Add your page to the .nav.yml file in the same directory:

    - 'Your Page Display Name': 'your-file-name.md'

Create a New Section

To create an entirely new section of documentation:

  1. Create directory structure:

    your-new-section/
├── .nav.yml
├── index.md
└── your-first-page.md

  2. Create .nav.yml:

    title: Section Display Name
nav: 
  - 'Overview': index.md
  - 'Page Display Name': 'file-name.md'
  - subdirectory-name
    • title: Displayed in left navigation
    • index.md: Always first in nav list (if exists)
    • Files: 'Display Name': 'file-name.md'
    • Subdirectories: Listed by directory name

  3. Create the index.md landing page with frontmatter and content introducing the section.

Write a Tutorial

This section covers tutorial-specific requirements and formatting.

Requirement: Follow the PaperMoon Documentation Style Guide.

Place your tutorial under the most relevant existing section of the docs. Set up file and asset paths to match the surrounding structure:

docs/<section>/<subsection>/<tutorial-name>.md
docs/images/<section>/<subsection>/<tutorial-name>/
docs/.snippets/code/<section>/<subsection>/<tutorial-name>/

Tutorial Template

---
title: Tutorial Title (max 60 chars)
description: Description 120-160 chars.
categories: Category1, Category2
page_badges:
  tutorial_badge: Beginner | Intermediate | Advanced
---

# Tutorial Title

## Introduction

Brief explanation of what users will learn/build.

## Prerequisites

Required knowledge/tools.

## [Action-Oriented Section Title]

Instructions with commands.

## Verification

How to confirm it worked.

## Where to Go Next

Related tutorials.

See Frontmatter Reference for a full list of available frontmatter fields.

Tutorial Requirements

  • All code examples must be tested and functional.
  • Always specify dependency versions (e.g., npm install polkadot-api@1.16.0).
  • Use action-oriented section titles.
  • Include verification steps.

Working with Content Elements

Adding Images

Where to store: docs/images/<path-matching-doc-structure>/

Requirements:

  • Format: .webp
  • Desktop screenshots: 1512px width, variable height
  • Browser extension screenshots: 400x600px

How to use:

![Alt text description](/images/<subdirectory>/<image-file-name>.webp)

Adding annotations:

Use assets from the .assets/annotations directory:

  • Arrows: Highlight single elements
  • Steps: Highlight multiple elements (use numbers for numbered lists, letters for alphabetical lists)

Using Code Snippets

Purpose: For any code used on the page or for reuse of text across multiple pages while maintaining it in one place.

Where to store: docs/.snippets/code/<path-matching-doc-structure>/<snippet-name>

How to use:

--8<-- 'code/<subdirectory>/<snippet-file-name>.js:10:20'

File types:

  • Text snippets: .md files for reusable copy
  • Code snippets: Use appropriate language extension (.js, .py, etc.)

Learn more about snippets syntax.

Adding Callout Boxes

Use these to highlight important information:

!!! tip
    Helpful tips and shortcuts.

!!! note
    Important information to remember.

!!! warning
    Potential issues or caveats.

Using Termynal for Command Output

Purpose: Display terminal/command output in a visual format that simulates a terminal session.

When to use: Anytime you need to show command output or terminal interactions in the documentation.

Basic syntax:

<div class="termynal" data-termynal>
    <span data-ty="input"><span class="file-path"></span>your-command-here</span>
    <span data-ty="progress"></span>
    <span data-ty>Output line 1</span>
    <span data-ty>Output line 2</span>
</div>

Frontmatter Reference

Every page begins with a YAML frontmatter block between --- delimiters. The fields below are all supported options.

Required fields

Field Description
title Page title. Keep to 60 characters or fewer for good SEO.
description Meta description shown in search results. Aim for 120–160 characters.
categories Comma-separated list of content categories used to group AI artifacts. Valid values are defined in llms_config.json.

Optional fields

Field Type Description
short_description string A shorter description used in auto-generated index tables (falls back to description if absent).
tools string or list Tools used on the page, shown in index tables. Accepts a comma-separated string or a YAML list.
hide list Hides page elements. Accepted values: navigation (hides left nav), toc (hides table of contents).
template string Overrides the page template. Only used on the homepage (home.html).
footer_nav bool or int Adds the page to the footer navigation. Use true to include in discovery order, or an integer for explicit ordering (lower numbers appear first).
extra_javascript list Additional JavaScript files to load on this page only. Used to activate interactive widgets.
extra_css list Additional CSS files to load on this page only. Used alongside extra_javascript for interactive widgets.
page_badges object Displays difficulty and CI status badges in the page header. See page_badges below.
page_tests object Links a test file to the page, shown as a "View tests" link. See page_tests below.
toggle object Groups pages into a switchable variant toggle (e.g. EVM vs PVM). See toggle below.

page_badges

Displays badge labels in the page header.

page_badges:
  tutorial_badge: Beginner   # or Intermediate, Advanced
  test_workflow: workflow-name  # filename of the GitHub Actions workflow (without .yml)
  • tutorial_badge — renders a difficulty badge: Beginner, Intermediate, Advanced. Also used by index tables for the Difficulty column.
  • test_workflow — links to a GitHub Actions status badge for the named workflow. Workflows must exist in the polkadot-developers/polkadot-cookbook repository under .github/workflows/.

page_tests

Links a test file to the page, displayed as a "View tests" link in the page header. The path is relative to the root of the polkadot-developers/polkadot-cookbook repository.

page_tests:
  path: polkadot-docs/path/to/tests/docs.test.ts

toggle

Powers the page toggle feature, which groups related pages and lets readers switch between variants (e.g. EVM vs PVM) without leaving the section. All pages in a group must share the same group value.

toggle:
  group: my-group-name     # shared identifier across all pages in the toggle
  variant: evm             # this page's variant identifier
  label: EVM               # label shown on the toggle button
  canonical: true          # mark one page as canonical (the default shown in nav)