Editing this documentation
About
This documentation website is build using MkDocs and the Material for MkDocs theme.
Background info
The website is automatically built when changes are detected in it's GitHub repository, found on the HOURCAR GitHub. Cloudflare Pages monitors this repository, and will automatically rebuild the website when changes are detected on the main branch, generating the properly formatted .html files and hosting them on Cloudflare Pages.
This website is protected by Cloudflare Access, ensuring that only users who authenticate with their @hourcar.org Microsoft 365 account are permitted to read the content on this site.
All content on this site is written in Markdown. A formatting and syntax reference guide for Markdown can be found here. Markdown is designed to be forgiving, easy to learn, and easy to read. You will likely be able to understand how to write and edit the documentation by looking at the existing code.
Contributions to this website can be made directly through the GitHub web interface. Please contact Gunnar Aas for an invitation to our GitHub.
Local development
Editing or developing this documentation site locally requires some experience and comfort with the terminal (command line) and an text editor/IDE. mkdocs, the software powering this site, requires python3 be installed on your computer to run locally.
Doing this enables you to preview changes in an isolated environment, highly recommended if your contributions are more complicated than plain text.
Software Requirements
You'll need the following on your computer:
- Python
- Visual Studio Code
- Some nice to have extensions for Visual Studio Code are:
- GitHub Desktop
- This application currently does not install correctly from the Company Portal. Instead, please install it by running the following command in Terminal:
winget install GitHub.GitHubDesktop
- This application currently does not install correctly from the Company Portal. Instead, please install it by running the following command in Terminal:
Setup
Open GitHub Desktop and login. This will clone the repository to your computer.
Open VisualStudio Code. In the Explorer tab, open the hourcar-docs folder. It likely is located inside a folder named GitHub.
Install Python dependencies by running the command in your terminal. You can use the terminal inside VisualStudio Code by going to Terminal -> New Terminal.
python -m pip install -r requirements.txt
Editing and Previewing
Open the document you want to make changes to in VisualStudio Code. Make the desired edits and save.
Edits can be tested locally be cloning the folder and running command terminal:
python -m mkdocs serve
The live preview of the site should be available at http://localhost:8000, or the link printed in your terminal output. It will update every time you save your file on VisualStudio Code.
Source Control and Merging with Main
Git Definitions
-
Commit
-
Push
-
Pull