Added guide to running documentation website locally (#5059)

* Added guide to running documentation website locally

* Added link to mdBook's official documentation.

---------

Co-authored-by: psf <77138753+pkmnsnfrn@users.noreply.github.com>
This commit is contained in:
Eduardo Quezada 2024-08-14 10:10:58 -04:00 committed by GitHub
parent c625ac6d53
commit 00f8a4db15
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 55 additions and 0 deletions

View file

@ -3,6 +3,8 @@
- [README](./README.md) - [README](./README.md)
- [Installation](./INSTALL.md) - [Installation](./INSTALL.md)
- [Setting up WSL1 (Legacy Portion)](./legacy_WSL1_INSTALL.md) - [Setting up WSL1 (Legacy Portion)](./legacy_WSL1_INSTALL.md)
- [Run documentation site locally](local_mdbook/index.md)
- [Ubuntu WSL1/WSL2](local_mdbook/ubuntu_WSL.md)
- [AI Flags](./ai_flags.md) - [AI Flags](./ai_flags.md)
- [Tutorials]() - [Tutorials]()
- [How to add new AI Flags](./ai_logic.md) - [How to add new AI Flags](./ai_logic.md)

View file

@ -0,0 +1,2 @@
## Running documentation website locally
- [Ubuntu WSL1/WSL2](/docs/local_mdbook/ubuntu_WSL.md)

View file

@ -0,0 +1,51 @@
Note: For further information beyond this very basic guide, please visit mdBook's [official documentation](https://rust-lang.github.io/mdBook/).
## Running documentation website locally (Ubuntu WSL1/WSL2)
### Previous Requirements:
- Option 1: Install via Rust toolchain
- Install Rust toolchain if you don't have it via the `sudo apt install cargo` command.
- Install mdBook via the `cargo install mdbook` command. Once finished, this message will pop up, with {USER} being your Ubuntu
```
warning: be sure to add `/home/{USER}/.cargo/bin` to your PATH to be able to run the installed binaries
```
- Add `/home/{USER}/.cargo/bin` to your PATH (with {USER} being the Ubuntu username.)
- Run command `nano ~/.profile` to edit the file.
- Add the following lines, ***replacing {USER} with your Linux username.***
```diff
# set PATH so it includes user's private bin if it exists
if [ -d "$HOME/bin" ] ; then
PATH="$HOME/bin:$PATH"
fi
# set PATH so it includes user's private bin if it exists
if [ -d "$HOME/.local/bin" ] ; then
PATH="$HOME/.local/bin:$PATH"
fi
+# set PATH so it includes cargo bin if it exists
+if [ -d "/home/{USER}/.cargo/bin" ] ; then
+ PATH="/home/{USER}/.cargo/bin:$PATH"
+fi
```
- Run the `source ~/.profile` command to refresh the path in the current session.
- Option 2: Install downloaded binaries directly
- TODO: Add documentation of this process.
### Running the website
- Navigate to the `docs` folder on the repository.
- Run `mdbook serve`. Once started, you may now open the website on your browser by going to `http://127.0.0.1:3000`.
- Every change done to the `docs` folder will be reflected with an automatic refresh.
- To stop the server and go back to the terminal, press `Ctrl + C`.
### Modifying the website
- The navigation menu on the left is handled by `docs/SUMMARY.md`. Every file added needs to be added somewhere here in order to become visible, otherwise you'll get a 404 error.
- Any Markdown files (.md extension) added to the `docs/` directory will automatically be read by mdBook.
- To add Markdown files that are not in the `docs/` directory, you may create an empty `.md` file and add the following ***without the "----"***:
```md
{{ ----#include ../INSTALL.md}}`
```
This will include the `INSTALL.md` Markdown file from the root directory.
Once you're set up, you can now check your changes before pushing them to your repo! :D
We hope that this will make it easier for users to contribute to the documentation :)