This repository contains the source for The Starknet Book.
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.
- Rust Packages:
cargo install mdbook --version 0.4.31 && cargo install mdbook-i18n-helpers --version 0.1.0
- Machine Packages:
- For translations, install gettext:
sudo apt install gettext
. - On Mac, you can use
brew install gettext
to install.
- 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 (
l-henri
or@omarespejel
).
- Formatting
- Run
npm i
- Then after completing your documentation run
npm run format
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, likech35.md
. Use subdirectories for added resources.book.toml
: The primary configuration file (regular contributors might not need to adjust this).
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.
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 prefixi18n
.
The translation work is inspired from Comprehensive Rust repository.
For starting translations in a new language:
- Employ
./translations.sh new xx
, replacingxx
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).