Working with Visual Studio Code

Setup

Follow the steps below to checkout and work on the OpenOlat documentation using Visual Studio Code for non-techies. To learn more about the structure and how to test and compile the documentation please refere to documentation README.

Make sure you installed the development environment first.

1) Install Visual Code Studio

Download and install the software from the Visual Code Studio website. It is available for free for Mac, Windows and Linux.

On the Mac the installation is very simple:

brew install --cask visual-studio-code

2) Clone the OpenOlat-docs repository

The public repository is available at the following Git URL:

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

Note

The repository at GitHub is a read-only repository. If you are frentix staff and want to modify the repo, please ask for our interal Git Repo. Ask the Sys-Admin staff how to generate an SSH key to access the repository.

Modifying pages

1) Open a page for editing

Use the project explorer to find the page you want to edit.

Tip

It is best to edit the different language versions at the same time. Additional languages of pages have the same page name and the language code in the file ending. E.g. index.md for the English page and index.de.md for the German version.

2) Open a local preview

There are two ways of using the Visual Studio Code preview feature: 1. Side-by-Side 2. In separate tab

Choose which fits better to your workflow / screen size

Preview Side-by-Side

Preview in separate tab

Push changes to the repository

1) Review changes before pushing

Pull changes from the server

It is important to always pull changes from the server before you start the

Important

Please, always pull before you stage, commit or push stuff. This is important to reduce the problems of conflicts.

Review the changes you made

Review every file you changed. Always. You can always go back to the editor or revert your changes.

Attention

Carefully review all your changes and test them with python3 -m mkdocs serve with your browser before you commit and push your changes! You need write permissions on the repository for beeing able to push.

2) Stage and commit your changes

Next step is to prepare your canges for the repository. This is done by staging and then commiting the changes to your local repository clone. At this point everything is still local on your computer and not on the server.

Stage

Commit

Next is to commit the staged changes to you local repository

Hint

Add a meaningfull message that helps other team members to understand the scope of your change. If the change is about an OpenOlat issue, add the issue to the message. Example: OO-5897 Adding more screnshots to Visual-Studio-Code howto

3) Sync and push the changes to the server

You are ready to go now. One last step is to sync and push your changes.

Help: I have a conflict!

Ask your tech staff for help to fix this.

Help: Revert and go back

You can always revert your changes and go back to the last version from the server