👋 Welcome to academicpages-mkdocs! This repository has been designed for learners of the FOSS course and is based on academicpages(git repo).
academicpages is a great way to get yourself started with documentation, whether you're documenting yours or your laboratory's progress, built using Jekyll. Although a great starting point, Jekyll might require a little more knowledge of HTML and JSON, whilst MkDocs-material relies completely on the MarkDown language, making it a lot easier for beginners to start building their website, documenting their work and sharing their progress.
Note: if you want to create your website using Jekyll, you are absolutely welcome to!
- Create a GitHub account and generate a token
- Fork this repository
- Navigate to Settings > Actions > General and under Workflow permissions select Read and write permissions and Allow GitHub Actions to create and approve pull requests
- Edit the
mkdocs.ymland push your changes - Navigate to Settings > Pages and make sure that Source is Deploy from a branch and Branch is gh-pages, /(root)
- Edit documents as necessary
Here are some guides that you may find useful:
- MarkDown cheatsheet: for correct MarkDown synthax.
- MkDocs-material: a starting guide to MkDocs Material theme (massive list of supported emojis here).
- MkDocs-material References: more sophisticated documentation for MkDocs Material.
- YouTube link to FOSS 2022: Michael explains (~1h mark) his Jekyll-based website and gives a tutorial on how to use academicpages.