This webpage contains all the code for the Hydro Systems Book available here. Here's how it works.
Inside the src
folder there are a bunch of Markdown files (files that end in .md
). Markdown is a ubiquitious and easy to learn text format for creating rich text directly from a plain text file. In fact, this README.md
is written in Markdown. You can view the raw text file that generates these effects here. Spme useful resources to learn Markdown.
- A very brief summary of the Markdown format, just enough to get writing.
- A full tutorial of Markdown.
- A longer cheat sheet with the syntax for things like tables!
- Google / ChatGPT is always your friend if you're unsure of the Markdown syntax for something.
So how do these markdown files get assembled into a book? For this we use mdBook() a convenient library that provides a command line utility (downloadable here) to generate a website from the .md files. Run mdbook serve
to turn on the website locally and have it update as you write. When you upload ("push") your changes to this online repository, the live website will automatically be updated (re-"built").
The documentation for mdBook is great and provides information on e.g. how to create new chapters.
- Install Git.
- Clone this repository by running
git clone https://github.com/staadecker/hydro-systems-book
. This will download the latest version to your local computer. - Write the book! I.e. make edits to the Markdown (
.md
) files in thesrc
folder. - Save ("commit") your changes with
git commit -a -m "Some message describing the change"
- Upload ("push") your changes with
git push
. This will only work if you have write access permissions to the repository. (Those who don't can "fork" the repository, push their changes to their fork, and open a "pull request" to request that their changes get integrated into the main version).
- Find a better title than "Hydro Systems"
- Choose a license for the book
- Update the information in
book.toml
to ensure the metadata like the authors, book description, etc. are correct. - Build some interactive stuff!