mkdocs-GEOMAR-template🔗

Writing documentation can be a real hassle - But NOT ANYMORE!

With the GEOMAR Template for MkDocs + GitLab Pages you can create static web pages for your documentation project in less than 5 minutes!*

*) In the case you have no account on git.geomar.de yet, it will take longer than 5 minutes.

Introduction🔗

In order to make things easier for authors, readers and host (GEOMAR), this template repository provides all the information and configuration files you'll need to create static html pages for your documentation under *.pages.geomar.de. It is based on mkdocs-material, a sepcial theme for MkDocs, and provides the following features:

• MkDocs features
• MkDocs-Material features (incl. some Insider-features, if paid version is available)
• several python-markdown extensions (see the YML configuration file)
• GEOMAR corporate design colors & fonts
• Single instance presentation or multiple releases/versions (git tags)
• Integrates seamless into GEOMARdoc
• Uses a pre-build docker image for the build process - no worries about software dependencies

The final pages are build remotely on git.geomar.de following the Continuous Integration (CI) approach.

Usage🔗

All you have to do is

1. Import the template files into a local git repository or fork the template project using the web interface (see Step-by-Step).
2. After adding some general information to the mkdocs configuration file .gitlab-ci.yml you can add new markdown files and folders in docs/ or modify existing ones along with further customizing the navigation and enabling versioning, if needed.
3. Then commit these changes to the repository and push them to https://git.geomar.de. After two adjustments to the project settings via web interface to enable the gitlab-pages feature, you're good to see the resulting pages under *.pages.geomar.de/* (The exact URL depends on the project's name and namespace and can be found via the project's "Settings">"Pages" menu on the git server.

Before committing your changes you could check the resulting pages running a local preview-server. But this is optional and requires a few extra steps and software (see Requirements: Local Preview Server).

Step-by-Step

Details🔗

Contents of the template🔗

The template comes with several files and folders in a specific folder structure as shown below (Click on the highlighted numbers right next to each item to get more information or see the numerated list of comments below, if the "annotated code block" feature is not available in your current view¹):

.
├── .gitignore  #(1)
├── .gitlab-ci.yml  #(2)
├── .cloud.d/   #(3)
│   └── sources.txt  #(4)
├── .repos.d/  #(5)
├── docs/  #(6)
│   ├── .pages  #(7)
│   ├── index.md  #(8)
│   └── index.de.md  #(9)
├── mkdocs-requirements.txt  #(10)
├── mkdocs.yml  #(11)
└── overrides/  #(12)

1. .gitignore lists glob patterns of matching file and direcotry names which should be ignored by git and should therefore not be committed to the repository.
2. .gitlab-ci.yml is some kind of a batch script used by the continuous integration mechanism of gitlab. It contains instructions how to build the static pages.
3. .cloud.d/ is used by the build process for storing external resources from cloud listed in sources.txt.
4. sources.txt lists external cloud resources for additional documents (optional)
5. .repos.d used to store embedded external repositories (git submodules) providing additional documents (optional)
6. docs/ contains your documents (markdown files) and additional files, like images, data tables and other stuff.
7. .pages defines the structure in the navigation menu for the directory this file is located in. Can also be used to rename the title of its parent folder in the navigation menu. If omitted, the file directory tree is used in alpha-numerical order as a navigation hierarchy.
8. index.md is the folder's entry-page. In this case the top-level entry page (homepage) of the whole project since it is located in the docs/ root folder.
9. index.de.md is the German variant of the English index.md file. The label .de in the file name indicates that this is a language variant of a file with the same name but the language label ommitted.
10. mkdocs-requirements.txt lists all required python packages for running mkdocs locally.
11. mkdocs.yml is the mkdocs configuration files. Here you can define the title and site URL of the documentation, a short description, as well as authorship and repository details. You can also add some social network links to the footer or manipulate the overall appearance of your documentation. See also Configuration: mkdocs.yml
12. overrides/ contains some theme-specific modifications of the underlying Jinja-template files. Nothing to do for you in this directory, unless you have a good reason for it, of course.

Site Location (final URL)🔗

Under which URL will your site be presented? In general, this dependes on whether you are going to use the default gitlab-pages setup or you have your own domain.

Default🔗

All pages that were successfully build will be deployed to and served by https://pages.geomar.de For this purpose gitlab creates automatically a subdomain for the namespace the respective git project is located under (i.e. your user name or some group name) and adds the project name as a suffix to the path. The exact URL for your documentation will look like one of these:

• https://USER-NAME.pages.geomar.de/PROJECT-NAME
• https://GROUP-NAME.pages.geomar.de/PROJECT-NAME

It is also possible to create a site for the entire group without the project-suffix which requires the git project to be named in a specific way (see the gitlab pages guide , in particular: domain names, urls and base urls ):

• https://GROU-PNAME.pages.geomar.de

User Domain🔗

Besides the deafult, you can also use your own domain (or GEOMAR subdomain) to deliver your site, e.g. for a research project.

• https://PROJECT.geomar.de
• https://PROJECT.de

In this case, your pages are still deployed to the pages.geomar.de server but they will be also accessible through additional domains which can be defined in the "Settings">"Pages" Section of your git project. Keep in mind that you have to modify the site_url and the alternative language links in mkdocs.yml, too.

Workflow & Requirements🔗

The requirements regarding your working environment depend on your workflow and access permissions to central services. Three different workflows are currently supported (Choose the tab with the workflow that fits you best and read further on - your choice is taken into account in the description below wherever instructions differ between these workflows¹).

Notes:

• If you do not have access to the git server yet, you can sign up for an account on the data-management portal which will include access to the git server.
• The git client can be a command-line tool or some fancy GUI program. No matter which client you are going to use, make sure you are familiar with the different ways how to access git projects.
• The editor can be any text editor but you may want to try one that provides special support for markdown files. Here is a list of such programs:
  • Joplin (free; for Linux/Windows/MacOS/Android/iOS; code editor with parallel preview),
    Also for terminals (MacOS, Linux, Windows). incl. E2EE
  • Typora (paid, 15-days trial; for Linux/Windows/MacOS; WYSIWYG²)
  • Haroopad (free but kind of abandoned project; for Linux/Windows/MacOS)
  • iWriter (paid; for MacOS/iOS)
  • iA Writer (paid; for MacOS/iOS/Android/Windows)
  • Any ASCII Text Editor

Local Preview Server🔗

If you're going to write your content locally (A), you may want to check the resulting static web pages before committing to the repository. You can have such a preview when running mkdocs locally in the server mode(see section preview step below).

Mkdocs itself is a python program that requires several packages (also depending on the used features) which are listed in mkdocs-requirements.txt in the template's root folder (see also the folded code box below). The automatic build process (CI) factors those packages already in since it uses a specialized Docker Image (mkdocs_docker). But if you are going to run mkdocs by yourself (e.g. for the preview server), make sure those packages are installed properly (see section preview step).

Markdown 
markdown-blockdiag
markdown-captions
mike
mkdocs 
mkdocs-autorefs 
mkdocs-awesome-pages-plugin
mkdocs-bibtex
mkdocs-git-authors-plugin
mkdocs-git-revision-date-localized-plugin
mkdocs-git-revision-date-plugin
# mkdocs-gitlab-plugin
mkdocs-include-markdown-plugin
mkdocs-literate-nav
mkdocs-macros-plugin 
mkdocs-macros-test 
mkdocs-material>=6.0.2
mkdocs-material-extensions
mkdocs-mermaid2-plugin
git+https://github.com/jldiaz/mkdocs-plugin-tags.git
mkdocs-static-i18n
mkdocs-table-reader-plugin
mkdocs-tooltips
mkdocs-versioning
mkdocstrings
pymdown-extensions
python-frontmatter

python3 -m venv ~/venv-mkdocs
source ~/venv-mkdocs/bin/activate
cd /path/to/my/documentation-project
pip3 install -r mkdocs-requirements.txt

deactivate

Step-by-Step🔗

For a description of the different workflows, please see Workflow & Requirements.

(A) Text Editor + Git Client(B) Git Web IDE(C) Cloud Folder

Since the "Editor + Git" approach uses git for checking files in and out, the following steps assume you're familiar with git and you have a working git environment on your local host.

Step 1 - Import the template

Assuming you have already an existing project folder either for a software development or for some special topic. In order to prepare it for a mkdocs-based documentation, perform the following steps using a recent git client (e.g. version >~ 2.20):

1. Go into your project folder
2. If not already under git control, initialize it
3. Make sure you have a clean worktree and commit or stash possible changes.
4. Fetch the latest doc-template from remote
5. Merge the incoming files with your own files and in the case of conflicts solve them manually;
   see Appendix Merge Conflict or common git manuals, e.g.:
   • Gitlab: Merge Conflicts
   • Github: Merge Conflicts
   • Atlassian: Merge Conflicts

Now you should find the template files in your directory as described in the Contents section above.

Example

The following example starts from an existing directory (/path/to/my/documentation-project) which is not under git control yet but has already some files in it.

cd /path/to/my/documentation-project # (1)!

git init .   # (2)!

git status   # (3)!
git add .
git commit -m "insert here your commit message"   # (4)!

git checkout -b incoming                          # (5)!

git fetch https://git.geomar.de/docs/mkdocs-GEOMAR-template.git  # (6)!
git diff --name-status FETCH_HEAD                                         # (7)!
git merge --squash --allow-unrelated-histories --no-commit FETCH_HEAD --   # (8)!
git commit                # (9)!

git checkout master       # (10)!
git merge incoming        # (11)!

git branch -D incoming    # (12)!

1. Go to your project's directory or create a new one before. If you develop some software, you have to place the template files and folders into the root folder of that repository in order to get the automatic build process (CI) running. At least the .gitlab-ci.yml file must be placed in the root folder but then the build process must be reviewed assiduously and some path specifications must be adjusted.
2. If the project folder is not already under git control, initialize it first. If the initializing was successful or the folder is already under git control, don't forget to add and commit (or stash) your changes so you end up with a clean working directory.
3. If you have un-committed changes, stash them away or commit them with git add and git commit.
4. If you've just initialized the git project there is nothing to commit yet.
5. See comment below about git enthusiasts and geeks.
6. Import the template by fetching the respective repository and intertwine (merge) the incoming files with your own. Please note, you have to do both a fetch and a merge. Fetching alone does not write any files into your working directory.
7. Before merging it is allways a good idea to review possible changes before actually changing any files. The newer version of the template files is stored in the virtual ref FETCH_HEAD. Therefore a short statistics of what will change can be shown with the git diff command and the --name-status option.
8. With this merge the incoming files are intertwined with your own files but no commit is performed to provide an additional checkpoint.
9. If the merge was successful, you can commit these changes
10. Now go back to your original main branch 'master'
11. Merge the temporary branch into your master branch.
12. Finally, the temporary 'incoming' branch can be deleted.

For git-enthusiasts: Like in the example above, do not just merge external stuff into your own work. First, create a new branch (from a clean working tree) check this new branch out, perform the merge and commit these changes. This way, you transform the changes from outside into something under your own control. If you were successful go back to your primary branch (e.g. master) via checkout and merge it with the temporary branch. Although this procedure requires a few more steps it provides you with another safety level against unwanted (or for you unmanagable) changes.

For real but cautious git-geeks: Instead of switching branches, create the new branch as a kind of savepoint to come back to if things get too messy and do the merge directly in your primary branch.

Note: No new git remote was added

No new remote, pointing to the template repository, was registered for your local git project. Instead, the template files were imported as if they were copied from somewhere else into your project folder. Therefore no simple updates viagit pull can be performed, but you can re-fetch and re-merge if and when a newer version of the template is available using the same fetch&merge commands from above.

Step 2 - Configure

Before builing the static pages, mkdocs must be configured. In the mkdocs.yml file you have to specify:

1. The title of your documentation
2. The basename of your site URL (depends on whether you are going to publish your site only via pages.geomar.de (e.g. https://myname.pages.geomar.de/myproject or https://groupname.pages.geomar.de/myproject) or via a dedicated domain (e.g. https://myproject.geomar.de or https://myproject.edu). See also Site Location
   However, the URL must be placed at two locations: (1) parameter site_url and (2) in each link entry of the extra:alternate section.
3. The authorship
4. A copyright statement besides 'GEOMAR'
5. A site description
6. Repository links and links to social networks and contact options

See Configuration: Build (mkdocs.yml) for more details.

Step 3 - Add content

For adding new content to your documentation add new sub-folders (if needed) and new markdown files (*.md) to the docs/ folder and commit these changes.

Optional: You can easily modify the navigation menu if the default does not satisfy your expectations. By default, the folder structure is used to form sections and sub-sections while files in those folders are listed in alpha-numerical order of their title. See Navigation for more details.

Example

vi docs/introduction.md     #(1)
mkdir docs/section1         #(1)
vi docs/section1/index.md

git add .                        #(3)
git commit -m "adding section1"  #(4)

1. Use your favorite editor to modify files.
2. Assuming, you are in your mkdocs root folder.
3. This adds actually all changes in the current working directory when using the . path indicator.
4. Keep your commit comments simple but meaningful

Step 3.1 - Local preview (optional)

If mkdocs is available on your local system (c.f. Local Preview Server), you can run a preview server from where the configuration file mkdocs.yml is stored with:

mkdocs serve

and view the resulting pages with your web browser (see the output of the mkdocs command for the correct URL; something like http://127.0.0.1:8000)

Step 4 - Publish

1. Add all necessary files to git's staging area and commit them, e.g. with git add . and git commit.

2. Add a remote server repository (if not already done):

   git remote add origin git@git.geomar.de:/NAMESPACE/PROJECT-NAME.git
   

   If the remote repository does not exist yet, you can create it automatically with the first push in the next step.

3. Push the current branch to the remote repository (e.g. master branch to origin):

   git push -u origin master
   

4. If this is the first time, you've committed a CI-script (.gitlab-ci.yml) to the remote repository, you'll have to enable a CI-runner first: Use your web browser to go to your gitlab repository and go to Settings > CI/CD and expand the Runners section therein. Activate the shared runners in the right column. See also Setup Gitlab Pages for details on that matter.

In some cases you may not have access to a local machine with a working git client. If so, you can fork the template project and proceed from there using the gitlab web interface.

Step 1 - Fork the template project

1. Visit the template project with your web browser
2. Click on the Fork link and create a fork.

   

3. On the fork seetings page rename the project from the template's name to your own choice and select an appropriate namespace. You can also add a description already. The 'slug' should be identical with the project's name. Finally, choose a visibility level for the new project (the visibility level for the static webpages will be set later during the "Publish" step.)

   

4. Click on "Fork project"

Step 2 - Configure

Before builing the static pages, mkdocs must be configured. Open the "Repository">Files" view of the git project in your browser and click on the file mkdocs.yml.

Now click either on the "Edit" or the "Web IDE" button to open the file in an editor.

In the file you have to specify:

1. The title of your documentation
2. The basename of your site URL (depends on whether you are going to publish your site only via pages.geomar.de (e.g. https://myname.pages.geomar.de/myproject or https://groupname.pages.geomar.de/myproject) or via a dedicated domain (e.g. https://myproject.geomar.de or https://myproject.edu). See also Site Location
   However, the URL must be placed at two locations: (1) parameter site_url and (2) in each link entry of the extra:alternate section.
3. The authorship
4. A copyright statement besides 'GEOMAR'
5. A site description
6. Repository links and links to social networks and contact options

See Configuration: Build (mkdocs.yml) for more details.

Step 3 - Add content

1. In the newly created project click on the Web IDE link (see the Web IDE on the Gitlab Help pages for how to use the the Web IDE).

   

2. Add new files to the docs/ folder and modify the navigation in the respective .pages file(s) if needed.
3. Commit your changes to the master branch or create a new branch but do not forget to merge this new branch with master afterward. Otherwise you will not see your changes in the final pages.

Step 4 - Publish

1. Make sure, your CI/CD runner settings as well as the Pages feature were configured properly.
2. If your build job was successful, visit the static web pages under https://namespace.pages.geomar.de/project-name (or whatever domain you have defined in the settings). See "Seetings">"Pages" for the correct URL.

Step 5 - Detach fork (optional)

A fork of a git project is a copy of the original project but in a different namespace. The relation to the origin is often kept to allow fetching future updates from that origin and to provide pull requests to the original project.

Be reminded, that future updates cannot be imported easily (only with a local git client) after removing the fork relationsship!

Go to "Settings">"General", scroll down and expand the "Advanced" section. Then click on the "Remove fork relationship" button and confirm.

In order to set up the obligatory git repository follow the instructions either in workflow A (Text Editor + Git Client) or B (Git Web IDE).

In addition to "Step 3" you can then add your shared resources:

Step 3.1 - Add share

In order to add content from a cloud share you have to add the respective download link to the file .cloud.d/sources.txt:

.cloud.d/sources.txt

# Add the URLs to your cloud shares below, each in a separate line.
# Comments are written in separate lines and start with #. 
# Inline-comments, e.g. trailing an URL, are not allowed.
# Blank lines (or white space only) are allowed.
# 
# Make sure, you add a DOWNLOADABLE resources, e.g. to a ZIP archive.
# In case of the GEOMAR cloud your URL should look like the EXAMPLE 
# below. However, the "/donwload" suffix may be ommitted for GEOMAR cloud.
#
# EXAMPLE:      https://cloud.geomar.de/a/hjf1KS8re6sB77j/download
#           or  https://cloud.geomar.de/a/hjf1KS8re6sB77j
#
# The URL can also be provided by a CI Variable:
#
# EXAMPLE:      $share1
#

https://cloud.geomar.de/s/KiKNzKQ2x5RXsmj

# $share1

Step 4 - Publish: Trigger Build Job by Hand

Currently, the build process does not recognize whether files in the cloud resource were changed. The user must therefore trigger the build process by hand. There are at least two options to do so:

1. Commit some changes to the repository
2. Re-run the last "pages" job.

While the first option can be derived from the work-flows A or B, the latter is trivial, too: Just open the jobs overview from the "CI/CD">"Jobs" menu and click on the button at the right end of the upper most successfully run job.

Configuration🔗

Build (mkdocs.yml)🔗

The mkdocs.yml file in the template repository is the configuration file for the mkdocs building process. Here you can define the title and site URL of the documentation, a short description, as well as authorship and repository details. You can also add some social network links to the footer or manipulate the overall appearance of your documentation.

User Parameters🔗

Only the first half of the configuration file is meant to be customized by the user. If you're familiar with mkdocs-material and its features as well as how to handle theme settings, you are free to modify the other parameters too, of course.

# YAML configuration file for GEOMAR Documentation using mkdocs-material.
#
# Project Home: https://git.geomar.de/docs/template-mkdocs
#         Help: https://docs.pages.git.geomar.de/template-mkdocs
#
# 2020-11-02 Markus Scheinert, GEOMAR (mscheinert@geomar.de)
#
#------------------------------------------------------------------------------

# (*): Mandatory Settings
# ( ): Optional Settings
# (/): No modifications by users required/experts only


#========================================
# (*)  Project:
#========================================

# (*) site_name: 
#----------------------------------------
# Title of documentation
site_name: change TITLE in mkdocs.yml

# (*) site_url: 
#----------------------------------------
# URL for this documentation; e.g. https://docs.pages.geomar.de/MYPROJECT
site_url: https://docs.pages.geomar.de/mkdocs-GEOMAR-template/

# (*) site_author: 
#----------------------------------------
# Name of the person in charge/author of this documentary
site_author: AUTHOR

# (*) copyright:
#----------------------------------------
# Copyright statement
copyright: Copyright © 2020 GEOMAR, YOUR NAME

# (*) site_description:
#----------------------------------------
# A short description on what the documentation is about.
# Use "site_description: >-" syntax to add multiple lines, each line indented
# until the first unindented line
site_description: >-
  INSERT HERE DESCRIPTION OF THIS DOCUMENTATION
  You can use multiple lines


#========================================
# ( ) Repository
#========================================
# Name and URL of repository for this documentary + quick link uri to edit file
# Leave them empty to DISABLE quick-edit link and repo link.
# 
repo_name: mkdocs-GEOMAR-template
repo_url: https://git.geomar.de/docs/mkdocs-GEOMAR-template
edit_uri: https://git.geomar.de/-/ide/project/docs/mkdocs-GEOMAR-template/edit/master/-/docs/

#========================================
# ( ) Extras
#========================================

extra:
  #========================================
  # ( ) Social Media Links
  #========================================      
  social:
    - icon: material/home
      link: https://www.geomar.de/
      name: 'Homepage'
    - icon: fontawesome/solid/paper-plane
      link: ''
      name: 'email'
    - icon: mattermost/mattermost-logo
      link: https://mattermost.geomar.de
      name: 'Mattermost Chat'
    - icon: nextcloud/nextcloud-logo
      link: https://cloud.geomar.de/
      name: 'GEOMAR Cloud'

  #========================================
  # ( ) Language Switch
  #========================================      
  alternate:
    # Switch to English
    - name: English
      link: /mkdocs-GEOMAR-template/
      lang: en
    # Switch to German
    - name: Deutsch
      link: /mkdocs-GEOMAR-template/de
      lang: de

The following settings are either required, recommended or optional

extra:
  alternate:
    # Switch to English
    - name: English
      link: /mkdocs-GEOMAR-template/     #(1)
      lang: en
    # Switch to German
    - name: Deutsch
      link: /mkdocs-GEOMAR-template/de   #(2)
      lang: de

extra:
  social:
    - icon: 
      link:
      name:

Navigation (.pages )🔗

Instead of defining the navigation for every item in the central configuration file mkdocs.yml this template uses the awesome-pages plugin for mkdocs which allows the navigation menu to be defined via .pages files in each folder in docs/.

A simple .pages files looks like:

nav:
    - index.md
    - ...

which lists the index.md file as a first item in the respective section (top-level or sub-folder) and then the rest (all other) *.md files) recursively, indicated by the ellipsis ....

Unfortunately, this syntax is not sensitive to the choice of the localization (language), which is English by default and optional German (e.g. index.de.md instead of index.md). But there is a workaround.

Multilingual Navigation🔗

You can use the 'rest' indicator (ellipsis ...) and apply a filter mask (|) to cover all available languages for a specific file, like this:

nav:
    - ... | index.*md #(1)
    - ...

1. Get all files that were not already processed for the navigationnav: and search for files that match the given glob pattern.

The example above would then point either to /index.html (= index.md) or /de/index.html (=index.de.md), depending on the chosen language (drop-down menu in the header bar).

Folder Title🔗

You can also define a new folder title in .pages but be aware of the fact that currently there is no other multi-lingual support than the project-wide i18n nav-translation array in the configuration file mkdocs.yml (a dependency from the related mkdocs-static-i18n plugin which adds the multilingual support). Just browse to the plugins.i18n.nav_translations.de: section and add your own translations.

The following example shows how German translations for the English terms "Basics", "Data Coverage", "Step by Step", "About" and "A-Z Knowledge Base" were added to the list.

plugins:
    - i18n:
        default_language: en
        languages:
          de: Deutsch
        nav_translations:
          de:
            Basics: Grundlagen
            Data Coverage: Datenumfang
            Step by Step: Schritt für Schritt
            About: Über
            A-Z Knowledge Base: A-Z Wissensdatenbank

Versioning (git tag)🔗

In some cases you may want to provide different versions of your documentation, either for different software releases or just to keep track of changes and allow users to also refer to older revisions.

Unfortunately, versioning is only possible using git (no "Cloud" solution). Depending on the chosen workflow, you have to perform the following steps:

cd my-project
git tag -a -m "Version comment" v1.0
git push --follow-tags origin

Setup Gitlab Pages🔗

In order to build and publish your static html pages, you have to adjust two settings for the respective git project on git.geomar.de:

(1) Enable CI runners

Runners🔗

Runners are dedicated daemon processes, that can be used to run CI scripts, controlled by the project's .gitlab-ci.yml file. These runners are disabled by default. Enabling runners for a git project means telling the runner process to monitor certain project events (e.g. a push, commit or merge) and invoking a new CI process for that project, if needed. In order to enable them you have to follow these steps:

1. Open your web browser
2. Go to the the web repository of your project
3. From the project menu in the left sidebar choose "Seetings"> "CI/CD"
4. Expand the section "Runners" by clicking on the title or Click the "Expand button"
5. In the right column "enable shared runners for this project"

When everything is set up correctly, you'll see a link in "Settings">"Pages".

Additional document resources🔗

Cloud Shares🔗

As stated in Workflow & Requirements already, the git project manager can add a cloud share as a source for additional documents. The embedding is controlled via the file .cloud.d/sources.txt.

# Add the URLs to your cloud shares below, each in a separate line.
# Comments are written in separate lines and start with #. 
# Inline-comments, e.g. trailing an URL, are not allowed.
# Blank lines (or white space only) are allowed.
# 
# Make sure, you add a DOWNLOADABLE resources, e.g. to a ZIP archive.
# In case of the GEOMAR cloud your URL should look like the EXAMPLE 
# below. However, the "/donwload" suffix may be ommitted for GEOMAR cloud.
#
# EXAMPLE:      https://cloud.geomar.de/a/hjf1KS8re6sB77j/download
#           or  https://cloud.geomar.de/a/hjf1KS8re6sB77j
#
# The URL can also be provided by a CI Variable:
#
# EXAMPLE:      $share1
#

https://cloud.geomar.de/s/KiKNzKQ2x5RXsmj

# $share1

Visible resource URL

Notice, that the share-link is fully visible to everyone with read-access to the repository. If you rather prefer hiding the cloud-URL, being only visible to repository managers, make sure that the actual URL is stored in a CI-Variable while sources.txt only contains a reference to the variable.

# EXAMPLE:      https://cloud.geomar.de/a/hjf1KS8re6sB77j/download
#           or  https://cloud.geomar.de/a/hjf1KS8re6sB77j
#

$share1

Before running the CI job (e.g. before "git push") add the CI-variable share1. In the web repository of your git project go to "Settings">"CI/CD" and expand the "Variables" section. Therein click on "Add Variable" and fill in the required information, e.g.:

• Key: share1
• Value: https://cloud.geomar.de/a/hjf1KS8re6sB77j/download
• Type: Variable
• Mask variable: :fontawesome-regular-check-square:

Git Repositories🔗

Another way of adding extra sources for documents is embedding other documentation projects (or git projects in general) using git submodules.

Currently there is no simple way of adding git-submodules to your repository using the web interface. You have to use a local git client and push your changes to the remote repository by hand.

In order to embed other mkdocs projects in your own docs, you have to:

1. Add git submodule remote in .repos.d/
2. Update the submodules (if necessary, i.e. older git version)
3. Commit and submit

1. Add Submodule🔗

In the doc's root folder run:

GIT_LFS_SKIP_SMUDGE=1 git submodule add REMOTE_URL .repos.d/CHAPTER_NAME

with REMOTE_URL being the URL pointing to the remote repository that you wish to include and CHAPTER_NAME the local folder name which will be also used as the item name in the navigation menu.

2. Retrieve updates from submodule🔗

$ GIT_LFS_SKIP_SMUDGE=1 git submodule update --init --recursive

$ cd /path/to/my/project    #(1)
$ git status
$ git submodule add ../NAMESPACE/AUXPROJECT.git .repos.d/AUX\ Project  #(2)
$ git submodule update --init --recursive                              #(3)

3. Commit & Submit🔗

Commit your changes and push them to remote, e.g. 'origin':

$ git add.
$ git commit -m "adding submodule AUXPROJECT"
$ git push origin master

APPENDIX🔗

Merge Conflict🔗

When bringing in updates from the central git project of this template into your own project you may experience a 'merge conflict' since git cannot decide by itself, which version/change to keep and which to ommit. The user must therefore solve these conflicts by hand. You can avoid some of the merge conflicts, when reviewing the incoming changes before merging.

When the merge has been initiated already a quick overview of the conflicting parts can be listed with git status as shown in the example

$ cd /path/to/my/project-root-folder
$ git fetch https://git.geomar.de/docs/mkdocs-GEOMAR-template.git
From https://git.geomar.de/docs/mkdocs-GEOMAR-template
 * branch            HEAD       -> FETCH_HEAD
$ git merge --allow-unrelated-histories --no-ff --no-commit FETCH_HEAD --
Removing ~mkdocs.yml
Auto-merging docs/index.md
CONFLICT (content): Merge conflict in docs/index.md
Automatic merge failed; fix conflicts and then commit the result.

$ git status
On branch master
You have unmerged paths.
(fix conflicts and run "git commit")
(use "git merge --abort" to abort the merge)

Changes to be committed:
        modified:   .gitignore
        modified:   .gitlab-ci.yml
        new file:   docs/img/gitlab-menu-settings-cicd.png
        new file:   docs/img/template-webrepo-IDE.png
        new file:   docs/img/template-webrepo-fork.png
        new file:   docs/img/template-webrepo-forking.png
        new file:   docs/img/template-webrepo.png
        modified:   mkdocs.yml
        deleted:    ~mkdocs.yml

Unmerged paths:
(use "git add <file>..." to mark resolution)
        both modified:   docs/index.md

When a merge conflict occures, git puts both versions (the current state of a file and the incoming version) into the actual file on disk which can then be investigated (and solved) using a simple text editor. The two different versions in the file can be identified on the basis of three different marks by convention:

There can be multiple sets of diff-marks in one file. Since this is common practice, there are many tools available (many of them providing a GUI) which can help to deal with such diff-files.

Solving Strategy🔗

You should always review incoming changes very carefully. However, when it comes to the documentation itself, you can easily reject all changes from the template's docs/ folder.

docs/-Folder🔗

Since the template only comes with the root index.md file and its German counterpart index.de.md and maybe a few images in docs/img/ you can easily run the following command from within the project's root folder when a merge conflict occurred:

git reset HEAD docs
git checkout -- docs

This rewinds possible changes to files in docs/ that may have been applied during a merge. Notice, that new files that were introduced by the merge will still be present and must be deleted by hand.

$ cd /path/to/my/project-root-folder
$ git reset HEAD docs
$ git checkout -- docs

$ git status
On branch master
All conflicts fixed but you are still merging.
(use "git commit" to conclude merge)

Changes to be committed:
        modified:   .gitignore
        modified:   .gitlab-ci.yml
        modified:   mkdocs.yml
        deleted:    ~mkdocs.yml

Untracked files:
(use "git add <file>..." to include in what will be committed)
        docs/img/

Other files and folders🔗

Changes reagrding other files than those in docs/ should be reviewed carefully. When the merge has been started already (that's why you have to solve merge conflicts) you can review the changes that were made by the merge so far. First, run

git status --long

$ git status --long
On branch master
You have unmerged paths.
  (fix conflicts and run "git commit")
  (use "git merge --abort" to abort the merge)

Changes to be committed:
        modified:   .gitignore
        modified:   .gitlab-ci.yml
        deleted:    ~mkdocs.yml

Unmerged paths:
  (use "git add <file>..." to mark resolution)
        both modified:   mkdocs.yml

Untracked files:
  (use "git add <file>..." to include in what will be committed)
        docs/img/

$ git diff HEAD .gitignore

diff --git a/.gitignore b/.gitignore
index 7e72473..a66662f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
 site/
 aux/
 .cache/
+~*

git diff HEAD .gitlab-ci.yml

diff --git b/.gitlab-ci.yml a/.gitlab-ci.yml
index d9efdc3..9868047 100644
--- b/.gitlab-ci.yml
+++ a/.gitlab-ci.yml
@@ -14,6 +14,7 @@ pages:
    - pip install -U pip
    - pip install -U Markdown mkdocs mkdocs-material>=6.0.2 mkdocs-material-extensions 
    - pip install -r mkdocs-requirements.txt
+    - if [ ! -z $auxpkg ]; then eval "pip install $auxpkg"; fi
    #
    #- if [[ -d repos ]]; then find repos/ -name index\* -exec sed -i '/---/,/---/s/ *- navigation//;' {} \; fi
    #- if $CLOUD_SOURCE; then pwd && wget -O tmp.zip $CLOUD_SOURCE && unzip -o tmp.zip -d cloud/ && rm tmp.zip; fi

git diff HEAD mkdocs.yml

diff --git b/mkdocs.yml a/mkdocs.yml
index 0bdd5df..3ccd1b3 100644
--- b/mkdocs.yml
+++ a/mkdocs.yml
@@ -19,22 +19,22 @@
# (*) site_name: 
#----------------------------------------
# Title of documentation
-site_name: MYDOCS2
+site_name: change TITLE in mkdocs.yml

# (*) site_url: 
#----------------------------------------
# URL for this documentation; e.g. https://docs.pages.geomar.de/MYPROJECT
-site_url: https://docs.pages.geomar.de/mydocs2
+site_url: https://docs.pages.geomar.de/mkdocs-GEOMAR-template/

# (*) site_author: 
#----------------------------------------
# Name of the person in charge/author of this documentary
-site_author: Markus Scheinert
+site_author: AUTHOR

# (*) copyright:
#----------------------------------------
# Copyright statement
-copyright: Copyright © 2020 GEOMAR
+copyright: Copyright © 2020 GEOMAR, YOUR NAME

# (*) site_description:
#----------------------------------------
@@ -52,9 +52,9 @@ site_description: >-
# Name and URL of repository for this documentary + quick link uri to edit file
# Leave them empty to DISABLE quick-edit link and repo link.
# 
-repo_name: 
-repo_url: 
-edit_uri: 
+repo_name: mkdocs-GEOMAR-template
+repo_url: https://git.geomar.de/docs/mkdocs-GEOMAR-template
+edit_uri: https://git.geomar.de/-/ide/project/docs/mkdocs-GEOMAR-template/edit/master/-/docs/

#========================================
# ( ) Extras
@@ -78,20 +78,20 @@ extra:
    link: https://cloud.geomar.de/
    name: 'GEOMAR Cloud'

-  # end of user-customization
#========================================
# ( ) Language Switch
#========================================      
alternate:
    # Switch to English
    - name: English
-      link: /mydocs2/
+      link: /mkdocs-GEOMAR-template/
    lang: en
    # Switch to German
    - name: Deutsch
-      link: /mydocs2/de
+      link: /mkdocs-GEOMAR-template/de
    lang: de

+  # end of user-customization

@@ -140,7 +140,7 @@ theme:
    note: octicons/tag-16
    abstract: octicons/checklist-16
    info: octicons/info-16
-      tip: octicons/squirrel-16
+      #tip: octicons/squirrel-16
    success: octicons/check-16
    question: octicons/question-16
    warning: octicons/alert-16

git mergetool mkdocs.yml

After resolving all conflicts, you can resume with the merge process with:

git merge --continue

which effectively put the resolved files to the staging area and commits all staged changes.

Review before Merge🔗

In some cases it's a good idea to check what will change due to a merge berfore the actual merge is started. This can be done right after fetching the updates from the central template repository. Instead of reviewing the differences between the HEAD ref (latest commit or 'ours') and the current worktree (equivalent to 'theirs'), the comparison is run against the current worktree ('ours') using the FETCH_HEAD ref ('theirs') as the basis.

If you haven't merged yet the updates from the template repository (captured in FETCH_HEAD) into your local worktree, start with a list of objects that might be affected by the merge simply by invoking the command:

git diff -R --name-status FETCH_HEAD .

$ git diff -R --name-status FETCH_HEAD
M       .gitignore
M       .gitlab-ci.yml
A       docs/img/gitlab-menu-settings-cicd.png
A       docs/img/template-webrepo-IDE.png
A       docs/img/template-webrepo-fork.png
A       docs/img/template-webrepo-forking.png
A       docs/img/template-webrepo.png
M       docs/index.md
M       mkdocs.yml
D       ~mkdocs.yml

If there are any files to be reviewed, run on eachfile:

git diff FETCH_HEAD file

git diff -R FETCH_HEAD .gitignore

diff --git b/.gitignore a/.gitignore
index 7e72473..a66662f 100644
--- b/.gitignore
+++ a/.gitignore
@@ -1,3 +1,4 @@
site/
aux/
.cache/
+~*

Showcases🔗

Math Syntax🔗

You can use Latex syntax to write math formulae in Mkdocs-Material Markdown thanks to the MathJax extension:

Block format:

$$
\operatorname{ker} f=\{g\in G:f(g)=e_{H}\}{\mbox{.}}
$$

Inline format:

The homomorphism $f$ is injective if and only if its kernel is only the 
singleton set $e_G$, because otherwise $\exists a,b\in G$ with $a\neq b$ such 
that $f(a)=f(b)$.

The homomorphism \(f\) is injective if and only if its kernel is only the singleton set \(e_G\), because otherwise \(\exists a,b\in G\) with \(a\neq b\) such that \(f(a)=f(b)\).