diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6940540 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,21 @@ +# Contribute to this site + +This documentation site is built using [mdBook](https://rust-lang.github.io/mdBook/) and deployed to GitHub Pages. Changes merged into the `main` branch will automatically be built and deployed. + +Documentation can be edited directly in the GitHub web UI for existing pages. To create a new page, be sure to update `SUMMARY.md` as well. Once you're done with your changes, open a pull request for review. + +To understand more about how mdBook works, learn about the [anatomy of a book](https://rust-lang.github.io/mdBook/guide/creating.html#anatomy-of-a-book). One caveat for this repo is that the docs live at the root of the repo instead of in a `src/` folder. + +## Developing locally + +To build the site locally, clone this repository and install `mdbook` (follow the [official installation instructions](https://rust-lang.github.io/mdBook/guide/installation.html))[^1]. + +Once installed, use the `mdbook` command-line tool from the root of this repo. For example, to automatically start watching, building, and serving the site: + +```shell +mdbook serve +``` + +Then make your changes, preview them in your web browser (at [http://localhost:3000](http://localhost:3000) by default), commit, push, and open a pull request like any other git project. + +[^1]: Alternatively, download the binary from the [GitHub releases](https://github.com/rust-lang/mdBook/releases), unpack it, and drop it into `bin/` in this repo (which is .gitignored). Then prefix your `mdbook` commands with the path, e.g. `bin/mdbook serve`. diff --git a/README.md b/README.md index 2671470..7d5045d 100644 --- a/README.md +++ b/README.md @@ -16,5 +16,9 @@ This site hosts documentation and policies for the [ROOST] (Robust Open Online S By participating in our community, you agree to follow the [code of conduct](https://github.com/roostorg/.github/blob/main/CODE_OF_CONDUCT.md) and [contribution guidelines](https://github.com/roostorg/.github/blob/main/CONTRIBUTING.md). Please give them a read to familiarize yourself with them if you haven't already (or if it's been a while). +## Contribute to this site + +Learn [how to build and contribute](building.md) to this documentation. + [ROOST]: https://roost.tools [issues]: https://github.com/roostorg/community/issues diff --git a/SUMMARY.md b/SUMMARY.md index 246f523..af48c93 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -1,7 +1,12 @@ # Summary [Introduction](README.md) + - [Roadmap](roadmap.md) - [Roles](roles.md) - [Platforms](platforms.md) - [Documentation](documentation.md) + +--- + +[Contribute to this site](CONTRIBUTING.md)