Contribution Guidelines

The source of the Algorand Specification is released on the official GitHub Algorand Foundation repository.

If you would like to contribute, please consider submitting an issue or opening a pull request.

Important

All commits must be signed!

Typos

To fix typos, consider opening a pull request labeled “typo”. By clicking on the “Suggest an edit” icon in the top-right corner of the page containing the typo, you will be redirected to the relevant source code file to be edited in the pull request.

Issues

To report major issues, such as unclear contents, errors in mathematical formulas, broken rendering of the Web version or PDF version, broken rendering of diagrams, broken links, etc. please consider submitting a templated issue.

Source Code

The Algorand Specifications book is built with mdBook.

The source code is structured as follows:

.github/                  -> GitHub actions and CI/CD workflows
_archive/                 -> Legacy specification archive
src/                      -> mdBook source code
└── _include/             -> Code snippets, templates, TeX-macros, and examples
└── _excalidraw/          -> Excalidraw diagrams source code
└── _images/              -> SVG files
└── Part_A/               -> Part A normative files
    └── non-normative/    -> Part A non-normative files
└── Part_B/               -> Part B files
└── Part.../              -> ...
└── SUMMARY.md, ...       -> mdBook SUMMARY.md, COVER.md, prefix/suffix-chapters, etc.

Markdown

The book is written in CommonMark.

The CI pipeline enforces Markdown linting, formatting, and style checking with markdownlint.

Numbered Lists

Numbered lists MUST be defined with 1-only style.

📎 EXAMPLE
1. First item
1. Second item
1. Third item
Result:

First item

Second item

Third item

Tables

Table rows MUST use the same column widths.

📎 EXAMPLE

✅ Correct table format
| Month    | Savings |
|----------|---------|
| January  | €250    |
| February | €80     |
| March    | €420    |
❌ Wrong table format
| Month | Savings |
|----------|---------|
| January | €250 |
| February | €80 |
| March | €420 |
Result:

Month Savings

January €250

February €80

March €420

Month	Savings
January	€250
February	€80
March	€420

Consider aligning text in the columns to the left, right, or center by adding a colon : to the left, right, or on both sides of the dashes --- within the header row.

📎 EXAMPLE

| Name   | Quantity | Size |
|:-------|:--------:|-----:|
| Item A |    1     |    S |
| Item B |    5     |    M |
| Item C |    10    |   XL |

Result:

Name	Quantity	Size
Item A	1	S
Item B	5	M
Item C	10	XL

MathJax

Mathematical formulas are defined with MathJax.

mdBook MathJax documentation.

Inline Equations

Inline equations MUST include extra spaces in the MathJax delimiters.

📎 EXAMPLE

Equation: $ \int x dx = \frac{x^2}{2} + C $

✅ Correct inline delimiter
\$ \int x dx = \frac{x^2}{2} + C \$
❌ Wrong inline delimiter
\$\int x dx = \frac{x^2}{2} + C\$

Block Equations

Block equations MUST use the $$ delimiter (instead of \\[ ... \\]).

📎 EXAMPLE

Equation:

$$ \mu = \frac{1}{N} \sum_{i=0} x_i $$

✅ Correct block delimiter
$$
\mu = \frac{1}{N} \sum_{i=0} x_i
$$
❌ Wrong inline delimiter
\\[
\mu = \frac{1}{N} \sum_{i=0} x_i
\\]

TeX-Macros

TeX-macros are defined in the ./src/_include/tex-macros/ folder using the mdBook include feature.

TeX-macros are divided into functional blocks (e.g., pseudocode, operators, constants, etc.).

TeX-macros MUST be imported at the top of the consumer files using the mdBook.

TeX macros can be imported entirely or partially (e.g., just a functional block).

📎 EXAMPLE

Import all TeX-macros:
{{#include ./_include/tex-macros.md:all}}
Import just a block of TeX-macros (e.g., pseudocode commands):
{{#include ./_include/tex-macros.md:pseudocode}}

Block Styles

Block styles are defined in the ./src/_include/styles.md file using the mdBook include feature.

Block styles (e.g., examples, implementation notes, etc.) are “styled quote” blocks included in the book.

📎 EXAMPLE

This example block has been included with the following syntax:
{{#include ./_include/styles.md:example}}
> This example block has been included with the following syntax:

GitHub Links

Links to the go-algorand reference implementation or other repositories MUST be permalinks.

Diagrams

Structured Diagrams

Structured diagrams (e.g., flow charts, sequence diagrams, etc.) are defined with Mermaid “text-to-diagram” tool.

Unstructured Diagrams

Unstructured diagrams and images are drawn with Excalidraw.

Excalidraw images MUST be exported in .svg format without a background and saved in the ./src/_images/ folder.

Excalidraw images source code MUST be committed in the ./src/_excalidraw/ folder.

Installation

Clone the Algorand Specifications repository and install the git submodules:

SSH clone:

git clone --recurse-submodules [email protected]:algorandfoundation/specs.git
cd specs

HTTPS clone:

git clone --recurse-submodules https://github.com/algorandfoundation/specs.git
cd specs

Sync git submodules

If the Algorand Specifications repository is already cloned, sync the git submodules in the specs folder:

git submodule update --init --recursive

Build and Serve

Use the make command to build and serve the Algorand Specifications book locally or in a Docker container.

Use the make doctor command to check your environment for build dependencies.

In Container

To build and serve the book in a Docker container, the following dependencies are required:

Docker and Docker Compose.

Build the Docker image:

make docker-setup

Build and serve (hot reload) the book on localhost:3000:

make docker-serve

Locally

This section is for contributors who cannot / do not want to use Docker.

The PDF Book and release toolchain (Pandoc, mdbook-pandoc, LaTeX, etc.) are intentionally out of scope here.

To build and serve the book locally, the following dependencies are required:

Rust toolchain (cargo): install Rust with rustup.

Install the mdBook tools:

make setup

Ensure Cargo’s bin dir (usually ~/.cargo/bin) is on your PATH.

Build and serve the book (HTML) locally (hot reload) on localhost:3000:

make serve

Linting and Formatting

Linting and formatting are enforced with pre-commit.

To run pre-commit hooks locally, the following dependencies are required:

Python (python3 + pip): install pip.

Install pre-commit hooks:

make lint-setup

Run pre-commit hooks:

make lint

Link checker (lychee) requires Docker, it can be run optionally (outside make lint) with: pre-commit run lychee --all-files --verbose.

CI/CD and Release

The CI/CD and Release pipeline is defined in the .github/workflows/ files.

The CI runs on a Pull Request to:

Enforce linting and formatting;
Test the HTML book build;
Provide warnings for broken links;
Deploy the book preview to a temporary URL for review.

The CD pipeline deploys the book to https://specs.algorand.co on every push to the master branch.

The Release pipeline creates the release tag, builds the PDF Book, and publishes it as a release artifact.

Keyboard shortcuts

Algorand Specifications