Polkadot Wiki

The Source of Truth for Polkadot

• Contributing to Documentation
• Running Locally
  • Build
  • Start
  • Publish
• Style and Configuration Guide
  • Formatting
  • Search Engine
  • Automation
    • Deployments
    • GitHub Actions
  • Conditional Rendering
  • Inline React Components
• Internationalization
• License

---

The Polkadot Wiki is the central source of truth for Polkadot. It is a community-focused initiative led by Web3 Foundation to keep an up-to-date resource on the best information for learning, building, or maintaining on Polkadot.

Contributing to Documentation

The Technical Education team at Web3 Foundation are the primary maintainers of the Wiki and will review all issues and pull requests created on this repository. If you notice typos or grammatical errors, please feel free to create pull requests with these corrections directly. Larger contributions may start as issues to test the waters on the subject with the maintainers. It is generally preferable to create a pull request over an issue to propose a change to the Wiki content.

✨ The Wiki belongs to the community, help generate its identity. ✨

identity.mp4

📥 There will be an upcoming initiative that will promote and encourage contributions towards Polkadot-based content and documentation. In the meantime, feel free to share any ideas or feedback you may have for the Wiki by opening a Feature Request issue.

Keep engaged by checking out these common Polkadot ecosystem resources.

Running Locally

Both the Polkadot Wiki and the Kusama Guide are built from the source files in this repository. After cloning the source locally, you can start the websites with each of these respective commands (ensure you run yarn at the root of the repository first to install dependencies).

The Wiki uses Algolia search, which can be accessed locally by providing the correct App ID and API key. The app_id and api_key environment variables are needed for the Wiki to be built successfully. If you are an external contributor, set the variables with some values like shown below, which lets the Wiki repo build successfully (but disables the search bar).

export app_id="xxxxxx" api_key="xxxxxxx"

Using yarn, run:

yarn install

Build

🐦 Building the Kusama Guide:

yarn kusama:build

🟣 Building the Polkadot Wiki:

yarn polkadot:build

Start

🐦 Starting the Kusama Guide:

yarn kusama:start

🟣 Starting the Polkadot Wiki:

yarn polkadot:start

Publish

🐦 Publishing the Kusama Guide:

yarn kusama:publish-gh-pages

🟣 Publishing the Polkadot Wiki:

yarn polkadot:publish-gh-pages

Style and Configuration Guide

Use the style guide from the Substrate Knowledge Base

Formatting

Prettier is automatically run when making a local commit. Verify that all changes render as expected after making new commits by running the projects locally.

See the Conditional Rendering and React Components sections for additional details regarding how to properly format syntax for elements outside of the standard markdown library.

Search Engine

Algolia DocSearch is the search engine that is used, which is built into Docusaurus. Indexing via Algolia provides faster lookup; the actual configuration for lookup is located in another repository that Algolia DocSearch maintains.

We have enabled searching on the Wiki by declaring the algolia section in the siteConfig.js file in scripts, and defining an API key and index name that are provided by DocSearch.

  algolia: {
    apiKey: "53c6a4ab0d77c0755375a971c9b7cc3d",
    indexName: "kusama_guide",
    algoliaOptions: {
      facetFilters: ["language:LANGUAGE"],
    }, // Optional, if provided by Algolia
  }

If you would like to access and modify this, you can re-submit the documentation url via DocSearch Program, where they will send a JavaScript snippet that you can re-integrate into the configuration, similar to the one shown above.

Automation

Deployments

The Polkadot Wiki is built on the gh-pages branch and automatically deployed to GitHub Pages. The Kusama Wiki is also deployed to GitHub Pages (via a separate repository).

Development servers exist at https://staging.polkadot.network and https://staging.kusama.network. The servers will reflect the latest master commit or PR put up against the master branch by a member of the Technical Education team. A staging environment can be generated to reflect a specific branch by invoking the workflow_dispatch command via the GitHub UI and can then be reviewed by the team before proceeding to production. If all is well, the new commits on master are transferred into the production branch,prod, by rebasing master on prod. This is completed automatically every 24 hours or manually through a workflow_dispatch command. After these jobs are completed, the CICD production workflow will automatically deploy prod to the public sites: Polkadot Wiki and Kusama Guide, respectively.

GitHub Actions

Job	Description	Frequency
Audit Images	Searches for unreferenced images in the docs repository and archives them into /docs/assets/_legacy.	Monthly or Workflow Dispatch
Audit Links	Test all links in the docs for broken references and opens a new issue displaying results if any are found.	Monthly or Workflow Dispatch
Code QL Analysis	Tests for vulnerabilities across the codebase	Weekly, Push to master or Pull Request to master
Dependabot	Helps keep packages up-to-date with latest release.	Daily
Deploy Kusama Prod	Deploy Kusama docs to GitHub Pages (production).	Daily or Workflow Dispatch
Deploy Kusama Staging	Deploy Kusama docs to staging environment.	Workflow Dispatch
Deploy Polkadot Prod	Deploy Polkadot docs to GitHub Pages (production).	Daily or Workflow Dispatch
Deploy Polkadot Staging	Deploy Polkadot docs to staging environment.	Workflow Dispatch
Generate PDF	Generate a PDF for the docs and upload it to the static website.	Disabled Manually
Greetings	Greet first time contributors.	First Time Pull Request or Issue Creation
Jest Testing Coverage	Run a series of Jest tests related to React functionality.	Weekly or Workflow Dispatch
Pages and Build Deployment	Deploy Polkadot docs prod branch from GH Pages to public site. (This was originally setup through the GitHub settings menu, prior to GitHub Actions flows)	On Push to gh-pages branch
Prettier All	Run prettier over all docs to maintain styling standards.	Weekly or Workflow Dispatch
Status Badges	Update the commit history of various open source projects in the ecosystem.	Weekly or Workflow Dispatch

Conditional Rendering

The Polkadot Wiki does not support conditional rendering. If needed, use Tabs and TabItem to display values for Polkadot and Kusama.

Inline React Components

Occasionally you may require additional functionality that is outside of the scope of basic markdown. React components can be used inline in existing markdown documents as a solution, allowing you to render custom elements. This is currently the strategy used to retrieve live on-chain values and display them directly in the docs without the need to recompile or even reload the web app using RPCs.

If you are looking to invoke and embed data from 3rd party APIs or sources, checkout the Http-Request-Sample component. A full list of sample components can be found here.

Try and reuse existing components as much as possible instead of creating new ones to keep the code lean and comprehensive. It is also important to verify prettier has not modified the formatting of your component after making a commit.

Internationalization

❗ The Wiki is currently being reorganized and updated. Work will resume on translations after the Wiki revamp is completed.

License

The Polkadot Wiki is licensed under the GPL-3.0 free software license.