Skip to content

Updating the Online Docs

The STACK documentation is available online on docs.stack-assessment.org. The docs are automatically built whenever this repository is pushed to. This documentation details how to update the styling of the online docs.

What is not covered in this document

Instructions for updating the main website www.stack-assessment.org. The main website is built in the stack-web repository, and has its own documentation.

Framework

The website is built using MkDocs, a static site generator which converts STACK documentation, within the /doc directory, into HTML files and pushes them to the gh-pages branch. The website structure mirrors the file structure: the file doc/en/Authoring/Answer_Tests/index.md will be available on docs.stack-assessment.org/en/Authoring/Answer_tests/. Every sub-folder has an index.md file that will take that folder's name on the website: doc/en/Authoring/index.md will be available on docs.stack-assessment.org/en/Authoring/.

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 online docs uses the first option. The advantage is that new files are automatically added to the navigation bar when they are added to the repository. The disadvantage is that we cannot tweak the navigation bar manually. The online docs get around this with a number of workarounds.

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 Material Theme, mainly for its better search display and adaptive structure.

The site is hosted by GitHub Pages from the gh-pages branch. A 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.

STACK-specific Workarounds

The online docs use a number of workarounds to make MkDocs compatible with the STACK docs.

Dealing with the structure of the docs

MkDocs expects a single folder to contain all the website files, starting with an index.md file that is to be the landing page. However, STACK's docs have a different structure: doc contains the content folder, and the two language folders where the documentation is provided. The landing page is under en/index.md.

To work around this, we set doc to be the location of the docs, and use the plugin mkdocs-exclude to unwanted files from the navigation, such as /de and en/Site_map.md. We then use the plugin mkdocs-redirects to redirect the non-existing index.md file to the true landing page en/index.md. The effect of this is that docs.stack-assessment.org will always redirect to docs.stack-assessment.org/en/.

We also update the sidebar navigation, such that it does not show the en directory. This is done by overriding Material's nav-item partial in the site_overrides/partials/ directory.

Dealing with the theme

The online docs make a number of custom changes to the Material theme.

  • We use the basic MkDocs search algorithm, by including a script in the {% block config %} block under site_overrides/main.html
  • In site_overrides/partials/logo.html we customise how the STACK logo is shown. This is necessary, since the STACK logo is not square.
  • We add a custom footer in the {% block footer %} block under site_overrides/main.html. In here we copy Material's primary and secondary sidebar classes, such that the footer collapses when the sidebar navigation and search bar does. It was necessary to make an identical copy of the md-sidebar--primary class called md-sidebar--primary_footer, to avoid the sidebar breaking when zoomed.

Updating the documentation

When you change the documentation, the website automatically updates as well. This introduces some new limitations to the sort of elements that can be included in the documentation. This is documented in the Documentation file.

Updating the style

The online docs uses a custom CSS stylesheet which you can edit. This stylesheet builds upon the stylesheets of MkDocs and Material.

You can also edit the theme directly. Any file in the site_overrides folder will override files of the same name in Material's directory. The main.html file is designed to make it easy to override some predetermined blocks, but sometimes it is necessary to override files directly. Notice we directly override some of Material's partials.

Testing the website locally

Before adding major style changes to the online docs, you are encouraged to test your changes locally. For this, you will need to install MkDocs and all the required extensions.

  1. Install MkDocs, including its requirements.
  2. Install Material with pip install mkdocs-material
  3. Install the markdown extension with pip install https://github.com/mitya57/python-markdown-math/archive/master.zip
  4. Install the exclude plugin with pip install mkdocs-exclude
  5. Install the redirect plugin with pip install mkdocs-redirects

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 that 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.