action.skip

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.

You're reading index.md

You're currently reading the static html page generated from docs/index.md.

Use this file as the entry page for your documentation. Just modify its content. DO NOT RENAME IT! Keep its name "index.md".
But you are free to add further *.md files and/or sub-folders (each folder with their own index.md).


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:

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

No git client?

No problem, well, almost. There are alternative ways e.g. without a local git client or in combination with a shared cloud folder which are further described in Workflow and Requirements. But eventually, git itself is needed to make the site building working.

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 view1):

.
β”œβ”€β”€ .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.

Customized SSL Certificate required

Adding your own domain to a gitlab pages project means you'll need a SSL certificate for the secured htt protocoll (i.e. https). Please contact the helpdesk for more information on how to apply for additional domains.

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 workflows1).

The "Editor + Git" option is the preferred way of publishing your documentation. You'll edit your files locally and submit them to the server with your own git credentials. This requires at least:

  • access to https://git.geomar.de
  • a local git client
  • a text editor

You could also install mkdocs locally and run the local preview-server (see also preview requirements below) before committing and pushing to the remote server.

The "Git Web IDE" option forgos any additional local installation except for a web browser. You can create your documentation project and edit the relevant files purely from within the web interface of the git server. You only need:

  • access to https://git.geomar.de

The "Cloud Folder" option is a nice way to allow authors for editing files but without dealing with git. Instead of a repository, users can store and edit their files in a shared cloud folder on https://cloud.geomar.de with all the pros and cons of such collaborative file sharing. However, git credentials are still needed to setup the respective git project and to register the cloud folder. It is therefore rather a solution for contributors to an existing project than for project managers.

  • access to a folder on https://cloud.geomar.de that is shared with the git project
  • access to https://git.geomar.de (for setting up the project)

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; WYSIWYG2)
    • 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).

mkdocs-requirements.txt
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

Tip

If you're going to test mkdocs on your own machine, please make sure, that the required python packages are installed. It is also recommended to create a virtual environment for that matter, so you do not interfer with your default python environment. Just invoke the following commands (this example uses explicitly version 3 of python and thus python3 and pip3 as commands):

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

The virtual environment can be left with the command

deactivate

Step-by-StepπŸ”—

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

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

βœ… 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.
    Fork the template project by clicking on the fork link
  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.)

    Set some project details for the fork.

  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.

From the file browser open mkdocs.yml by clicking on it.

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

Open the current file in an editor by clicking either on "Edit" or "Web IDE"

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).
    Start the Web IDE to modify the repository's content
  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.

Re-run the last successfully run job to trigger the build process.


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.

./mkdocs.yml

Below, the first part of the configuration file mkdocs.yml is shown which is meant to be customized by the user.

Please, note that the YML format is highly indent-sensitive.

# 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

site_name

The site_name appears in the page header and the browser window title.

site_url

The site_url is needed to render internal links correctly. Insert here the Domain-URL from the "Pages" configuration page in your project's settings on git.geomar.de, e.g. https://docs.pages.git.geomar.de/ if the project is located in the git-namespace (group) "docs".

site_author

The site_author can be a single name, a group name or a list of multiple authors.

copyright

The copyright has to include "GEOMAR". Other than that you could add your name, the name of a working group, or the funding project's name, if needed.

site_description

The site_description is currently only used for the html meta header and provides additional information for search crawlers (e.e. Google, Bing, DuckDuckGo,...) about the content of this web site.

MkDocs-material <=8.5.5

This works only with mkdocs-material <= 8.5.5. The internal search plugin in mkdocs-material >= 8.5.6 does not support the pre-build indexing anymore (b/c dirty-load feature). The remaining multi-language support does neither support staying on the same page while switching language nor a translation of navigation items. Therefore, multi-language support will be disabled in this template until a more pratical solution is found.

The default language is English. There is support for German as an alternative language which can be selected from the language chooser menu in the top bar. Since the mulilingual support via i18n plugin adds a prefix to the URL path for each language except the default, the project name must also be included in those prefixes to be consistent with the gitlab-pages URLs (note, the project name of group pages does not appear in the final URL and therefore must not be included in those link definitions).

Please go to the extra.alternate section of the mkdocs.yml file and modify the link:-entries accordingly. I.e., replace the text 'mkdocs-GEOMAR-template' with the name of your own project:

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
  1. For the default language (EN) replace 'mkdocs-GEOMAR-template' with your own project name in order to make the language chooser working correctly.
  2. For the alternative language (DE) also replace 'mkdocs-GEOMAR-template' with your own project name in order to make the language chooser working correctly but keep the "/de".

If you want to see a link in the upper right corner of the browser window pointing to the project repository and maybe also a pen-icon on each page for a direct editing link (e.g. pointing to the web IDE URL), fill in the following paramters. Otherwise keep them blank:

repo_name

The repo_name is the display title for the repository link (typically the project's name).

repo_url

The repo_url points to the web repository of the project, e.g. https://git.geomar.de/docs/template-mkdocs.

edit_url

The edit_url points to the web-edit interface for the specific file, e.g. for this template project it could be either

  • https://git.geomar.de/docs/template-mkdocs/-/edit/master/docs/ for the inline-editor or
  • https://git.geomar.de/-/ide/project/docs/template-mkdocs/edit/master/-/docs/ for the web IDE of gitlab.

You can add some social media links at the right corner of the footer on each page. The are defined in the extra.social: section as an unsorted list (items start with a '-') whith three parameters per entry (each in a separate line; respect the indent!):

extra:
  social:
    - icon: 
      link:
      name:

icon

The icon can be taken from the list of embedded icons (see the icons-emojis in the mkdocs-material manual for more information).

link

The link parameter defines the link target URL.

name

The link name appears as a tooltip when hovering with your mouse pointer over the link.

Keep all three parameters blank or remove the three lines completely to hide/remove the icon.

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.

mkdocs.yml
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:

  1. Go into your project directory
  2. Make sure, you have a clean worktree (commit or stash your changes otherwise)
  3. Add an annotated tag for the new version with git tag -a -m "YOUR COMMENT" LABEL , where LABEL must start with the character v followed by a semantic versioning number, e.g. 1.0 or 2.1 (it is recommended to only use major and minor release numbers and dropping the patch number, that is [major].[minor].[patch]).
    Notice, without the option -a you'd create only a lightweight pointer instead of a full git object which is much more preferable over such simple 'bookmarks'.
  4. Commit your changes and push to the remote including tags (option --tags).
Example:
cd my-project
git tag -a -m "Version comment" v1.0
git push --follow-tags origin
  1. Open your web browser and visit the web repository of your project, e.g. https://git.geomar.de/mynamespace/myproject.
  2. Under the header section, click on the "+" dropdown menu and choose "New tag"
  3. Fill out the "New Tag" form:

    Tag name

    use semantic versioning numbers (m.n.p) prepended by the character 'v', e.g. v1.0.0

    Create from

    Assuming you only have the master branch, keep this "as is".

    Message

    Explain the new tag in a few words (relevant for the git log). More details can be given in the release notes if needed.

    Release notes

    A version tag can be seen as a synonym for a release. Therefore you can insert here any detail that is relevant for this version/release.

  4. Click on "Create tag".

Adding the new tag will trigger a new build of your pages.

Versioning cannot be controlled via cloud. Please choose one of the other two workflows to specify different versions directly in git.


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"

CI/CD Settings in the gitlab project menu.

Enabling runners in the gitlab project settings.

(2) Set visibility level of gitlab-pages

Pages VisibilityπŸ”—

In order to publish your html pages, you have to mak sure, that the feature is enabled and the visibility level is as aspired.

  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"> "General"
  4. Expand the section "Visibility, project features, permissions" by clicking on the title or Click the "Expand button"
  5. In the feature list scroll down until you see "Pages" and enable the feature by clicking on the switch button.
  6. Next to the button you'll see a drop-down menu for the visibility level. In general that means:

    "Only Project Members"

    This level requires an account on git.geomar.de and the user must be a member of the project (or group the project is part of).

    "Everyone with Access"

    Users are not required to be a member of the project or group but they still need an account on git.geomar.de to access the pages.

    "Everyone"

    Everyone with or without an acccount on git.geomar.de can access the pages (PUBLIC)

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.

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

Define CI variable share1 and mask its value

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.

IMPORTANT

REMOTE_URL should be a relative path, like ../PROJECT.git for a project in the same name space as your documentation repository or ../NAMESPACE/PROJECT.git for a project in a different name space but still on the same host. If you're going to add an external repository, make sure, the CI runner has access (i.e. the project must be public or you provide access credentials/tokens in the CI/CD settings or by specifying an URL that already contains a deploy token).

GIT_LFS_SKIP_SMUDGE

GIT_LFS_SKIP_SMUDGE=1 in front of the add command ensures that no LFS files (Large File Support) are actually downloaded from the submodule's repository since these files can be really big and we are only interested in the documentation files (docs/*) and not in the data files. Instead only placeholders are written to disk using the data files' name and containing the object's SHA256 hash for reference.

2. Retrieve updates from submoduleπŸ”—

$ GIT_LFS_SKIP_SMUDGE=1 git submodule update --init --recursive
EXAMPLE: Add an extra git repo as submodule
$ 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)
  1. Go to the project directory and check if the working tree is clean (commit or stash current changes otherwise).
  2. Add the submodule. Notice, the masked blank "\ " in the target directory name (will be also used in the navigation menu)
  3. After adding the submodule information in the previous step, the actual content of the repository must be imported by initializing and updating the submodule.

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

A merge conflict occurres while updating template files
$ 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

In this example, there are five new images in docs/img/ folder, while .gitignore, .gitlab-ci.yml and mkdocs.yml were modified by the merge since git could clearly identify the respective changes and there were no conflicts with line-related local changes. The changes in the file docs/index.md however are much more complex and were therefore not automatically merged by git. The last file ~mkdocs.yml might be a local backup of the configuration file and should be kept.

Those changes in .gitignore, .gitlab-ci.yml and mkdocs.yml should be further investigated.

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:

Diff Mark Meaning
<<<<<<< INCOMING-REF The content below this mark until the separator is provided by the INCOMING_REF (e.g. FETCH_HEAD or simply HEAD). Also called "their version" or "theirs".
======= Separator between their version above and ours below.
>>>>>>> WORKTREE-REF Marks the end of the detected differences in that section. From the separator down to this mark it's the version that is compared with the incoming one. Also called "our version" or "ours". WORKTREE_REF refers often to the latest commit in the worktree.

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.

Example: Restore local docs/ after merge
$ 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/

The changes in docs/ disappeared from the list except for the new docs/img/ folder which appears now as 'untracked'. Since this is not used by the user's documentation you could either delete it or keep it, both works in this case.

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
in the project's root folder. The output gives you a list of un-committed changes.

Example: Merging status
$ 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/

In this example, you have three files that were modified by the merge without any conflicts and one file labeled as "unmerged" which indicates a merge conflict. The third item is the docs/img folder which was created during the merge process but is not used locally (untracked so far).

Example: Review changes (without obvious conflict)

.gitignore:

$ 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/
+~*
A pattern for backupfiles (~*) were added to the list of objects to be ignored by git. This would ignore such files in the future (note, that ~mkdocs.yml was already committed).

.gitlab-ci.yml:

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
A new line was added to the CI-Script which checks for the existence of the custom gitlab-environment variable $auxpkg and installs it. This allows installing additional packages (or replacements of existing packages) via CI-job control.

Example: Review file with merge conflicts

mkdocs.yml:

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 &copy; 2020 GEOMAR
+copyright: Copyright &copy; 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

This is a typical example for a file, where you want to keep your own modifications (in the upper part) while those changes in the lower part should be imported. This file must be edited/merged by hand using a mergetool or by removing the diff marks and those parts that should not be kept.

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.

diff A <> B vs B <> A

The general direction of comparison with diff is from left to the right, which means, diff shows those actions that must be applied to the A (left) in order to get B (right) as a result.

The first argument in git diff is equivalent to A (left side) and the second (optional) argument specifies the object in The option -R is needed here, because diff compares the commit's tree form the first argument FETCH_HEAD with the actual worktree (an implicit third argument which cannot be specified). In order to show the changes that would be applied if the commit's tree was imported, both sides (arguments) must be swapped with this option.

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 .
Note:

Example: List diffs
$ 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

In this example, there are three files we have to investigate: .gitignore, .gitlab.yml and mkdocs.yml.

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

git diff FETCH_HEAD file
Example: Review diffs

.gitignore:

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/
+~*

A pattern for backupfiles (~*) were added to the list of objects to be ignores by git. This would ignore new such files in the future (note, that ~mkdocs.yml was already committed).

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{.}}
$$

\[ \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)\).


  1. This is one of a very few mkdocs-material Insider features and may not be available to you in the current view of this page, unless you purchase your own insider license for the build. ↩↩

  2. WYSIWYG - "What You See Is What You Get": Editor shows formatted text instantly, like in office apps. ↩


Last update: July 20, 2023 by Author's name in meta header Markus Scheinert
Created: November 2, 2020