/starknetbook

Mastering Starknet. By the Starknet community

Primary LanguageCSS

The Starknet Book

All Contributors

This repository contains the source for The Starknet Book.

Contribution

Every contribution, regardless of its size, plays a pivotal role in refining this work. Together, we advance the Starknet narrative.

  • General Guidelines:
    • Focus on enhancements directly related to the book's content.
    • For typos, errors, or improvements, you don't need a related issue to submit a PR.
    • Review specific areas of interest in the repository issues.

Setup

  1. Rust Packages:
    • Install the cargo toolchain via rustup.
    • Install mdBook and its translation extension:
cargo install mdbook --version 0.4.31 && cargo install mdbook-i18n-helpers --version 0.1.0
  1. Machine Packages:
  • For translations, install gettext: sudo apt install gettext.
  • On Mac, you can use brew install gettext to install.
  1. Repository Operations:
  • Clone the main repository: git clone https://github.com/starknet-edu/starknetbook && cd starknetbook.
  • Create and work on a branch in your fork. If you're unfamiliar, use this guide for assistance.
  • Once done, submit a PR to merge your edits. Ensure you tag a reviewer for feedback (@gianalarcon or @omarespejel).
  1. Formatting
  • Run npm i
  • Then after completing your documentation run npm run format
  • Finally run prettier --write .

Understanding the Book's Structure

The Starknet Book is optimized for mdBook:

  • src/SUMMARY.md: The book's structural outline. For adding chapters, modify this document.
  • src/: This directory holds individual chapters. Each is a markdown file, like ch35.md. Use subdirectories for added resources.
  • book.toml: The primary configuration file (regular contributors might not need to adjust this).

Editing Guidelines

Work Locally in English

Ensure all edits to Markdown files are in English.

  • Use mdbook serve to initiate a local server. Access the book at localhost:3000 or append --open to the command to launch a browser automatically: mdbook serve --open.
  • After editing, refresh the browser to see updates. When satisfied, push your changes through a PR.

Translations

Targeting a global readership, this book will undergo translations over time.

  • Initial Version Always in English: Always write files in the src directory in English. This consistency allows for smooth auto-translation.
  • Translation Process:
  • Launch a local server for the intended language, e.g., ./translations.sh es. Without specifying a language, only English translations get extracted.
  • Modify the translation file of interest, like po/es.po. Tools like poedit can be beneficial.
  • Commit changes only in the po/xx.po file. When opening a PR, start with the prefix i18n.

The translation work is inspired from Comprehensive Rust repository.

Initiating a New Translation

For starting translations in a new language:

  • Employ ./translations.sh new xx, replacing xx with your language code. This action generates a language file.
  • For updating the xx.po file, use ./translations.sh xx.
  • Avoid the above command if the xx.po file already exists (which means you are not initiating a new translation).

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Omar U. Espejel
Omar U. Espejel

πŸ’» πŸ“–
JameStark
JameStark

πŸ’» πŸ“–
GianMarco
GianMarco

πŸ’» πŸ“–
drspacemn
drspacemn

πŸ’» πŸ“–
Gyan
Gyan

πŸ“–
Steve Goodman
Steve Goodman

πŸ“–
David Barreto
David Barreto

πŸ“–
omahs
omahs

πŸ“–
Henri
Henri

πŸ“–
devnet0x
devnet0x

πŸ“–
cryptonerdcn
cryptonerdcn

πŸ“–
Raz Landau
Raz Landau

πŸ“–
Nadai
Nadai

πŸ“–
Cyndie Kamau
Cyndie Kamau

πŸ“–
Manmit Singh
Manmit Singh

πŸ“–
Shebin John
Shebin John

πŸ“–
Dalmas Nyaboga Ogembo
Dalmas Nyaboga Ogembo

πŸ“–
Adegbite Ademola Kelvin
Adegbite Ademola Kelvin

πŸ“–
Robert
Robert

πŸ“–
lorcan-codes
lorcan-codes

πŸ“–
Olivier Boulant
Olivier Boulant

πŸ“–
Lucas @ StarkWare
Lucas @ StarkWare

πŸ“–
Okoli Evans
Okoli Evans

πŸ“–
Esther Aladi Oche
Esther Aladi Oche

πŸ“– πŸ’»
faytey
faytey

πŸ“–
ccolorado
ccolorado

πŸ“–
Akinbola Kehinde
Akinbola Kehinde

πŸ“–
Louis Wang
Louis Wang

πŸ“–
Daniel Bejarano
Daniel Bejarano

πŸ“–
DamiΓ‘n PiΓ±ones
DamiΓ‘n PiΓ±ones

πŸ“–
Davide Silva
Davide Silva

πŸ“–
Asten
Asten

πŸ“–
Darlington Nnam
Darlington Nnam

πŸ“–
Idogwu Emmanuel Chinonso
Idogwu Emmanuel Chinonso

πŸ“–
machuwey
machuwey

πŸ’» πŸ“–

This project follows the all-contributors specification. Contributions of any kind welcome!