Homepage for lecture "Simulation Software Engineering"

This repository contains the content of for the homepage of the "Simulation Software Engineering" lecture at the University of Stuttgart (Germany). The homepage is built on mkdocs, the "Material for MkDocs" theme, and corresponding plugins.

Structure of the repository

• mkdocs.yml: MkDocs configuration file
• docs/: The directory contains the Markdown files for the different pages of the homepage.
• .github/workflows/publish-homepage.yml: Definition file of GitHub action which builds the homepage on every successfull push to master. It can also be triggered manually.
• .github/workflows/markdownlint.yml: Definition file of GitHub action which checks the markdown files for proper formatting using markdownlint. More information is given below.
• README.md: The Readme file you are currently reading

Build homepage

Dependencies

• Python 3
• MkDocs
• Material for MkDocs theme
• Pygments
• Python Markdown Extensions

The tools used are all based on Python 3 so the easiest way to install the theme and all dependencies is to use pip. Running

pip install mkdocs-material

will install MkDocs, the theme, and the plugins.

Alternative ways of building the homepage using MkDocs and Material for MkDocs are described in the documentation of the theme.

Building the homepage locally

After installing all dependencies change into this directory (the directory containing the file named mkdocs.yml) and run mkdocs serve. This will start a local webserver on 127.0.0.1:8000. Type in this address in a browser to see the local version of the homepage. While mkdocs serve is running it will monitor the files for changes and rebuild the homepage as needed.

Linting

The markdown files can be checked using markdownlint. Once the linter is installed one can run it locally from the root of this repository using

mdl docs/

It will automatically read the markdownlint configuration of this repository. The linter is configured in the files .mdl.rb and .mdlrc. The majority of the configuration is done in .mdl.rb.

Link checking

We currently check links via awesome_bot. If you want to run the checks locally, you must install the awesome_bot gem and then run the following command from the root of the repository:

awesome_bot docs/*.md README.md --allow-dupe