This repository contains the official specification for the Polkadot Protocol. The latest releases of the Polkadot Protocol Specification can be found on spec.polkadot.network or our GitHub Releases page.
Everyone, but specifically implementers and members of the Technical Fellowship, are welcome to open PRs to this repo and contribute to the specification. A PR is merged as soon as two members of the Spec Committee accept the PR.
The Spec Committee consists of Researchers, Researcher Engineers, and Implementers of the Polkadot Protocol that actively contribute (= opening/contributing to PRs or issues regarding the spec) to the specification. For now and compared to the Technical Fellowship, the Spec Committee's responsibility is clearly defined as maintaining the specification of the protocol. In case of inactivity for three months, members will be removed again.
Web3 Foundation
Quadrivium
Smoldot
Parity
To clone, build and serve the website locally, run the following commands:
git clone --recurse-submodules https://github.com/w3f/polkadot-spec
cd polkadot-spec
git submodule update --remote
cd website
npm i
npm run build # or build_with_kaitai to also rebuild kaitai SVG files
npm run serveIf you already have the repo cloned, remember to update it and the submodule before making any changes:
git pull
git submodule update --remoteBecause of the "complex" build, you can't see the changes in real time if you directly edit the docs folder. There are two workarounds:
-
use a Markdown plugin or editor (e.g., the extension Markdown All in One for VSCode) to see the changes in real time. You won't be able to see the placeholders rendered and other elements, but you'll be able to render the markdown and latex;
-
build the website the first time, then run
npm run startinstead ofnpm run serve,and edit the files inside thewebsite/docsfolder. This will allow you to see the changes in real time, but you have to remember to bring the changes inside thedocsfolder before committing. Also, in this way, you can't put the placeholders and other elements inside the markdown files ofwebsite/docsas they wouldn't be rendered.
You can find the markdown files inside the docs folder.
When building, the scripts inside preBuild will generate a docs folder, from which Docusaurus will render the website. Then, the rendered content will be modified by the plugins in the browser.
You can use LaTeX inside the markdown files using the following syntax:
$ LaTeX here $or
$$
LaTeX here
$$Inside preBuild, you can find the script numerationSystem. This will assign to several entities a number and substitute the placeholders inside the markdown files. This is done to avoid having to manually update the numbers when adding new entities.
This is the structure of the spec:
- Macro Chapter X
1. Chapter A
- Section 1.1
... subsections
- Section 1.2
2. Chapter B
- Section 2.1
... subsections
- Section 2.2
- Macro Chapter Y
etc.Example:
- Polkadot Host
1. Overview
1.1 Light Client
...
2. State and Transitions
...The entities involved are:
- Chapters
- Sections
- Definitions
- Algorithms
- Tables
- Images
Those defined as "Macro Chapters" will not be numbered.
To write a new chapter, use the following syntax:
---
title: -chap-num- Chapter Title
---
<!-- Chapter content here -->The placeholder -chap-num- will be replaced by the number assigned by numerationSystem.
If you add a chapter (or "Macro Chapter"), you must also add it to the sidebars.js file and adjust the numbers of the other chapters.
To write a new section, use the following syntax:
## -sec-num- Section name {#id-section-name}- Use a markdown header from H2 to H5 included, so the maximum depth is
a.b.c.d.e(H2 isa.b). - Put the placeholder
-sec-num-in the header, which will be replaced; - Add an id to the header, which will be used to reference the section.
To write a definition:
###### Definition -def-num- Runtime Pointer {#defn-runtime-pointer}- Use a markdown H6 header (######);
- Put the placeholder
-def-num-in the header; - Add an id to the header.
Then, you should include the definition content inside the custom admonition :::definition (you can find all the custom admonitions inside src/theme/Admonition/Types.js).
So the final result will be the following:
###### Definition -def-num- Runtime Pointer {#defn-runtime-pointer}
:::definition <!-- Open admonition -->
Definition content here
::: <!-- Close admonition -->To define an algorithm, use the same syntax as for definitions but with the placeholder -algo-num-:
###### Algorithm -algo-num- Aggregate-Key {#algo-aggregate-key}At the top of the page, you must include the Pseudocode component and the LaTeX algorithm you want to render:
---
title: -chap-num- States and Transitions
---
import Pseudocode from '@site/src/components/Pseudocode';
import aggregateKey from '!!raw-loader!@site/src/algorithms/aggregateKey.tex';After this, you can build the algorithm using the admonition :::algorithm, and using the Pseudocode component (refer to the file to know more about its props). This will be the final result:
---
title: -chap-num- States and Transitions
---
import Pseudocode from '@site/src/components/Pseudocode';
import aggregateKey from '!!raw-loader!@site/src/algorithms/aggregateKey.tex';
<!-- Page content here -->
###### Algorithm -algo-num- Aggregate-Key {#algo-aggregate-key}
:::algorithm
<Pseudocode
content={aggregateKey}
algID="aggregateKey"
options={{ "lineNumber": true }}
/>
<!-- Algorithm description here -->
:::To define a table or an image, use the same syntax as for definitions and algorithms (always using an H6 header) but with the placeholder -tab-num- or -img-num-:
###### Table -tab-num- Name {#tab-name}or
###### Image -img-num- Name {#img-name}For these two entities, you won't need to use any component or admonition.
To reference any of the entities from anywhere in the website, you have to use the following syntax:
[Entity -xxx-num-ref-](entity-page#entity-id)- Use a markdown link;
- Put the placeholder
-xxx-num-ref-in the text link, which will be replaced (xxxdepends on the entity, for example-def-num-ref-for definitions); - The link should point to the header id of the definition, with the page name as a prefix (if entity-page.md is a page, ".md" must be omitted).
The cited works are defined inside bibliography.bib. To cite a work, use the following syntax:
[@work-id]Automatically, the bibliography will be generated at the end of the page.
During the preBuild, the external links in the markdown files will be checked.
After the build, the internal links will be checked.
If any link is broken, the console will show a warning.
Refer to checkBrokenInternalLinks/index.ts and checkBrokenExternalLinks/index.ts.
Docusaurus docs: https://docusaurus.io/docs/category/guides
Kaitai docs: https://doc.kaitai.io/user_guide.html
Any code in this repository is licensed under the GPL 3.0, and any documentation or specification is licensed under the CC BY-SA 2.0.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent