OpenOlat documentation

This is the documentation project for the Learning Management System OpenOlat.

OpenOlat is a web-based e-learning platform for teaching, learning, assessment and communication, an LMS, a learning management system. OpenOlat impresses with its simple and intuitive operation and rich feature set.

A sophisticated modular toolkit provides course authors with a wide range of didactic possibilities. Each OpenOlat installation can be individually extended, adapted to organizational needs, and integrated into existing IT infrastructures. The architecture is designed for minimal resource consumption, scalability and security in order to guarantee high system reliability.

Visit the OpenOlat project homepage and the OpenOlat documentation for more information. The documentation generated by this GIT project is published at https://docs.openolat.org.

Resources:

The OpenOlat documentation is based on MkDocs using the material theme and some plugins. The manual is written using the markdown syntax.

• https://daringfireball.net/projects/markdown/
• https://www.mkdocs.org
• https://squidfunk.github.io/mkdocs-material/
• https://github.com/backstage/mkdocs-monorepo-plugin
• https://github.com/ultrabug/mkdocs-static-i18n
• https://facelessuser.github.io/pymdown-extensions/
• Helpful markdown guide: https://markdownguide.org

File structure

• Landing page:
  • The page structure is defined in the mkdocs.yml file within the space
  • Page files are located in /docs/
• Sites
  • Contains all the manual sections (release notes, user manual, admin manual tech doc etc)
  • Each site
  • The page structure is defined in the mkdocs.ymlfile within the space
  • Page files are located in /docs/ folder within the site
  • For more info see the monorepo plugin docu
• i18n
  • Normal xyz.md files are in EN (default) since not all spaces are available in all languages
  • The corresponding DE version have the xyz.de.md file ending
  • The same file pattern applies to images as well.
  • For more info see the static i18n plugin docu

Referencing from OpenOlat

OpenOlat uses the page URL including anchors to link to specific areas of the documentation. Thus, changing page names and anchors must be modified in sync with the corresponding references within the OpenOlat code. The URL is derived from the page file name: about.md will lead to the URL ..../about/.

Normally markdown generates HTML anchors for each title element automatically. This is unhandy when writing a multi-language documentation where not only the link to pages but also the link to the dedicated chapter in the page must be linkable from OpenOlat. Thus, the anchors must be set explicitly using the attr-listattr-list markdown extension:

# This is a title {: #this-is-the-anchor-to-this-title }

The hierarchical structure of URL's is defined in the mkdocs.yml file.

Manual versions

The manual is published from the GIT master version on the server in the / directory. Whenever a new main OpenOlat version is published, the documentation is tagged with the same tag and a branch is created. This docu branch is then published in a version directory like 16.2.

Working on the documentation

Install docu development environment {: #install-dev}

MkDocs uses the Python programming language. You first need to install python3 and pip3 to use MkDocs.

MacOS: there are several ways to to install MkDocs on MacOS, one simple ways is to use the brew package manager. To continue you must first install brew.

# Basic Python 3 installation
brew install python

# Install MkDocs
pip3 install mkdocs

#Install MkDocs theme and plugins
pip3 install mkdocs-material
pip3 install mkdocs-monorepo-plugin   
pip3 install mkdocs-static-i18n
pip3 install mkdocs-git-revision-date-plugin

You need to install mkdocs-material >= version 8.2.

Update

From time to time you need to update everything:

# Basic Python 3 installation. Example how this is done on the mac
# Upgrade python really only if you need
brew upgrade python

# Update mkdocs if new releases have been published
pip3 install mkdocs -U
pip3 install mkdocs-material -U	
pip3 install mkdocs-monorepo-plugin -U
pip3 install mkdocs-static-i18n -U
pip3 install mkdocs-git-revision-date-plugin -U	

Upgrade

If new major versions are released you need to upgrade. Be careful with this, first check compatibility of the plugins with the new versions.

# Upgrade mkdocs if new releases have been published
pip3 install  --upgrade --force-reinstall mkdocs
pip3 install  --upgrade --force-reinstall mkdocs-material
pip3 install  --upgrade --force-reinstall mkdocs-monorepo-plugin
pip3 install  --upgrade --force-reinstall mkdocs-static-i18n
pip3 install  --upgrade --force-reinstall mkdocs-git-revision-date-plugin

MkDocs Material Insiders program

As of June 2023 we use features of the MkDocs Material Insiders program. You can still compile and test the documentation without the Insider membership, but some things will not work or look not a good as when compiled with the Insider code.

For publishing to a website, make sure you use the Insider repo of mkdocs-material.

Install the insider code like this:

# Clone the repository. Make sure your installed your SSH key in GitHub first
git clone ssh://git@github.com/squidfunk/mkdocs-material-insiders.git
# Install material from the sourcecode
pip install -e mkdocs-material-insiders

Updating the insider code:

# Update the repository
cd mkdocs-material-insiders
git pull
# Install material from the sourcecode
cd ..
pip install -e mkdocs-material-insiders -U

Markdown editor and Git client

Any Markdown editor and any Git client can be used. To make things simple we recommend to download Visual Code Studio that combines a Git client, a decent Markdown editor and a Markdown preview in one single tool. It is available for free for Mac, Windows and Linux.

On the Mac the installation is very simple:

brew install --cask visual-studio-code

More information about this topic can be found in the [https://docs.openolat.org/manual_dev/documentation/howto-visual-studio/](Working with Visual Studio Code) guide.

Git project URL

The public repository is available at the following Git URL:

https://github.com/OpenOLAT/OpenOLAT-docs.git

Note that this is a read-only repository. If you are frentix staff and want to modify the repo, please ask for our interal Git Repo.

Author documentation

Please read the OpenOlat manual documentation carefully, you will find tips and trick and usefull information.

Local preview

When editing the files it is recommended to start a local server to preview the changes. The server reloads the pages on every change. Since the manual is large, reloading of changes can take quite some time.

cd OpenOLAT-docs  
python3 -m mkdocs serve --dirtyreload

Now open http://127.0.0.1:8000/ in your browser to navigate and preview.

Export site as static HTML files

For publishing the documentation, compile it and publish it on your server.

cd OpenOLAT-docs
python3 -m mkdocs build
scp -r site/??* oodocs@docs.openolat.org:/home/oodocs/html/.