This is the template I've used for my 2020, 2021, and 2022 SANS Holiday Hack Challenge submissions. It's based on MkDocs and the MkDocs Material theme. The website based on this template and examples of winning reports and their repositories can be found at:
- Make a copy of this repository in your own GitHub account and configure it as Private. Forking the repository won't work because a forked repository's visibility can not be changed to Private.
- Clone the copy of the repository to your computer using
git clone <repository_url>. - Navigate into the folder using
cd <cloned_folder_name>. - Create a Python virtual environment using
python3 -m venv venv. - Activate the environment using
. ./venv/bin/activate(for a Bash shell environment). - Install the Python package dependencies using
pip install -r requirements. - Run
mkdocs serveto start a local copy of the website athttp://127.0.0.1:8000/.
Details such as the site name, site author, and contents of the sidebar navigation are configured in the mkdocs.yml file. The write-up itself and associated assets are located in the docs folder. The default configuration stores the write-up for each objective in a docs/objectives/oX.md file and associated images for that objective in a docs/img/objectives/oX/ folder. As you add content and make changes to files, MkDocs will automatically update the local copy of the website at http://127.0.0.1:8000/.
Note: More information on how to make changes to MkDocs settings or the Material theme configuration is available at https://www.mkdocs.org/user-guide/writing-your-docs/ and https://squidfunk.github.io/mkdocs-material/reference/, respectively.
IMPORTANT: Make sure to configure your copied GitHub repository as Private while SANS Holiday Hack Challenge is ongoing. This way, no solutions or spoilers are accidentally leaked to the public!
Once the submission deadline has passed you are free to share your finalized report with the world. Run the mkdocs gh-deploy command in a terminal to create all the required HTML assets and push them to a gh-pages branch on GitHub. To serve the HTML content as a website go the Pages section in the GitHub settings for the copied repository, select Deploy from a branch for the Source and make sure the Branch is set to gh-pages.
After a few minutes your write-up will be live at https://<username>.github.io/<repository>, with <username your GitHub username and <repository> the name of your GitHub repository where you copied the HolidayHackChallengeTemplate project to.