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.

By clicking on the “Suggest an edit” icon in the top-right corner, while reading this book, you will be redirected to the relevant source code file to be referenced in an issue or edited in a pull request.

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 files
└── Part_B/         -> Part B files
└── Part.../        -> ...
└── SUMMARY.md, ... -> mdBook SUMMARY.md, cover, 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.md file 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:

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

Docker

The Algorand Specifications repository makes use of a Dockerfile.

To run the specs book as a container:

docker compose up

This will serve the specs book on localhost:3000.

Algorand Specifications