This book is part of our monorepo hosted on GitHub. It is built using mdBook, and it's contents are located in the book/ directory.

The structure is simple: there is a which lists all of the available pages, and defines the structure of the sidebar. When you add a link to this file, a matching .md file will automatically be generated.

Running the book

Open the integrated terminal in a Codespace and run the following command:

make run-book

A browser will open showing a local copy of this book. Simply edit the contents of the book/ directory, and your changes will be reflected live in the browser. (Despite running in the cloud, your Codespace will transparently map the ports to your localhost so that you can access the live book at localhost:3000.)

Book running locally So meta

Getting your changes published

Before publishing your changes, make sure they pass the linter. To do this, run the following command inside the ./book/ directory.

mdbook test

After your changes pass the linter without error, simple create a pull request on GitHub with your changes to the book/, and when it gets merged your changes are automatically published by the CI.


We use Commonmark flavored markdown syntax, plus GFM tables, GFM task lists, GFM strikethrough, and footnotes. In addition to that, we have some special syntax for image captions and H1 emoji:

Image captions

If you want to add a caption to an image, you should add an italics line right below it, like this:

![Composable Face](./composable-face.png)
*Composable Finance: The Face of DeFi's Future*

Composable Face Composable Finance: The Face of DeFi's Future

H1 emoji

Sometimes, you may want to have an emoji in the H1 title (like on the introduction page) in order to do this, use the following syntax:

# **👋** Introduction

👋 Introduction

Common Errors

By default, mdbook will attempt to lint code blocks with rustc. To avoid this, either specify another language or add ignore to your codeblocks. More details here.