Create your own book

Creating a static book with stepcode is as simple as writing standard Markdown.

Cloning the Repository

As stepcode is made in Python, you must clone the repository and install the dependencies to use it. You can do this with the following commands:

git clone
cd stepcode

To easily manage dependencies and virtual environments, we recommend using uv. To install the dependencies and run the project, use:

uv sync
uv run src/main.py

Creating Your Book

To create your book, create a folder. There you must have a stepcode.toml:

[book]
name = "My book"
author = "Me of course"

chapters = [
    # here you must list all the chapters of your book, in order.
    "blog/first-post.md",
    "blog/second-post.md",

    "cooking/first-recipe.md",
]

and a index.md in the root of the folder:

---
title: 'My book'
---

# Create your own book

Hi

You can also add custom css to override the default stepcode theme, just create a user.css file in the root of your book folder and it will be automatically included in the generated site.

:root {
  --accent-color: rgb(60, 101, 162);
}

nix

If you are a nix user, the repo flake exposes a devShell to download all the dependencies and have a ready to use environment. You can enter it with:

nix develop .

Template

These examples are available in the template folder of the repository. Furthermore, the template book is available with nix using:

nix flake new --template github:daniqss/stepcode#book my-book

Building the Book

Instructions on how to build and host your book can be found in the README.md of the repository. If you don't want to deal with our code in local, just use the template that we provide, that will automatically build and deploy your book to Github Pages on every push to the main branch.

uv run src/main.py <YOUR_FOLDER>

In Github Pages

If you want to host your book on Github Pages, you can copy our workflow If you're using the template, it already contains a workflow that will automatically build and deploy your book to Github Pages on every push to the main branch. You can customize it as you wish, but make sure to update the path to the book in the workflow.