This repository generates the main website for the STACK online assessment system, and makes it available on https://www.stack-assessment.org. Additions and modifications are welcomed.
- The framework of the main STACK website
- Updating the website
- Testing the website locally
Instructions for updating the docs website docs.stack-assessment.org. The online docs are generated directly from the main STACK repo, so that is also where you will find the STACK online Docs instructions.
The website is built using MkDocs, a static site generator. The site pages are written in a mixture of Markdown and html within the website_files directory. When the site is deployed, MkDocs will convert these files into HTML and push them to the gh-pages branch.
The website structure mirrors the file structure: the file website_files/Legal/Accessibility.md will be available on www.stack-assessment.org/Legal/Accessibility. Every sub-folder has an index.md file that will take that folder's name on the website: website_files/CaseStudies/index.md will be available on www.stack-assessment.org/CaseStudies/.
MkDocs is configured in the mkdocs.yml file. MkDocs has a full list of available configuration options. MkDocs can either generate the navigation bar automatically, or accept a custom navigation configuration in the nav variable. The main STACK website uses the second option. When new pages are added, they must be manually specified under the nav variable. Any files that are not specified in nav will be "hidden", that is, they cannot be accessed from the navigation bar, only from a direct link.
MkDocs cannot display MathJax out-of-the-box, so we use the markdown extension mdx_math, specified in mkdocs.yml, with the variable extra_javascript set to include MathJax.
MkDocs can accept a third-party theme, and the main STACK website uses the Bootstrap Theme, which uses all the website building tools of Bootstrap. This includes Bootstraps responsive grid system and its card styling. Parts of the theme can be overridden in the overrides folder. The main.html file is set up to extend the base Bootstrap theme, to for example, add a custom footer. A custom stylesheet is also added, under website_files/custom.css.
The site is hosted by GitHub Pages from the gh-pages branch. An workflow under .github ensures that MkDocs runs its command mkdocs gh-deploy every time the repository is pushed to, which rebuilds the website and pushes the built HTML piles to the gh-pages branch. This overrides all the files currently in the gh-pages branch, so you must never edit files directly in the gh-pages branch.
You can make small changes directly and push the changes. You do not need to download MkDocs or any of the extensions to update the website.
Only pages in the website_files directory will be included. You can write your page in markdown, and include html code. To include your page in the main navigation, remember to specify it in mkdocs.yml.
Links between pages are relative. If a link starts with / it will be taken relative to the root of the website, i.e. /CaseStudies/ always link to stack-assessment.org/CaseStudies/, while CaseStudies/ is a relative link that appends CaseStudies/ to the end of the current url. Absolute links to other websites must start with https://
When adding new content, please try to adhere to the WCAG 2.1 Accessibility Guidelines as much as possible. Please:
- Add alternative text to all non-text objects, in particular images. This can be done using the
alt=""tag. - Making sure elements are responsive to different page sizes.
- Use divs instead of tables as much as possible.
- Make use of Bootstrap's responsive grid system.
- Never use colour as the sole way of conveying a message.
- Use colours with contrast levels of at least 4:5:1.
Some work has already been done to make the website automatically be accessible. In particular, tables will collapse when the screen is small.
We keep track of the current state of Accessibility in our Accessibility document, which is available on the website to all users. Please ensure "Steps taken" is always up to date. You are invited to fix some of the "Known issues".
Before adding major changes to the website, you are encouraged to test your changes locally. For this, you will need to install MkDocs and all the required extensions.
- Install MkDocs, including its requirements.
- Install Bootstrap with
pip install mkdocs-bootstrap - Install the markdown extension with
pip install https://github.com/mitya57/python-markdown-math/archive/master.zip
You can run a local version of the website with the command mkdocs serve. This will make your local version available on the IP http://127.0.0.1:8000/.
Please test your changes work on:
- The following browsers: Chrome, Firefox, Safari, Edge.
- The following sizes: Computer, tablet, mobile. Chrome's "inspect" tool works well for this.