diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 3ff95a251c69..3aa5609ea9be 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -3,6 +3,8 @@ - [README](./README.md) - [Installation](./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) - [Changelog](./CHANGELOG.md) - [1.9.x]() diff --git a/docs/local_mdbook/index.md b/docs/local_mdbook/index.md new file mode 100644 index 000000000000..ef362dc45f77 --- /dev/null +++ b/docs/local_mdbook/index.md @@ -0,0 +1,2 @@ +## Running documentation website locally +- [Ubuntu WSL1/WSL2](/docs/local_mdbook/ubuntu_WSL.md) diff --git a/docs/local_mdbook/ubuntu_WSL.md b/docs/local_mdbook/ubuntu_WSL.md new file mode 100644 index 000000000000..88ee2468e65f --- /dev/null +++ b/docs/local_mdbook/ubuntu_WSL.md @@ -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 :)