The guide to everything SoRo, in one repo
To change or add to the book, you'll need to folllow some basic steps below. These let you build the book and instantly commit your changes to GitHub Pages, the (free) static website host.
Installation (from mdbook-quickstart)
You should only have to do this once, but keep it in mind...
Clone the repo:
$ git clone https://github.com/Sooner-Rover-Team/soro-documentation
$ cd soro-documentation$ make hooksFollow the Install Rust guide.
$ make installDevelopment (again, from mdbook-quickstart
To start make changes to the book, navigate to the repo so you can run the make commands.
$ cd soro-documentation$ make helpStart dev server.
$ make serveOpen in the browser:
Deploy (yeah, it's from mdbook-quickstart)
Build your application and generate production-ready output in the ignored book directory.
$ make buildThat is useful to run locally to check the app builds correctly.
This project uses GitHub Actions for Continuous Integration / Continuous Deployment.
The flow runs the Build command as above then commits the output to the gh-pages branch. To serve the site, configure the Settings section of your repo so that GitHub Pages serves the root of the gh-pages branch.
See the workflow on GitHub:
- main.yml file.
See workflow runs here:
- Actions tab
Once you've done these things, you can finally start adding to the book.
The most important part of mdBook and this project is editing SUMMARY.md. It lets mdBook know how to generate the rest of the book.
To know what to do, you'll want to follow this guide from mdBook's official documentation.
The rest of this book just requires you to write markdown files. If you can write Slack or GitHub messages, then you already know markdown. But just in case, here's a cheatsheet and an inclusive example page!