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:
- 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
- Import the template files into a local git repository or fork the template project using the web interface (see Step-by-Step).
- After adding some general information to the mkdocs configuration file
.gitlab-ci.yml
you can add new markdown files and folders indocs/
or modify existing ones along with further customizing the navigation and enabling versioning, if needed. - 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).
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)
.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..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..cloud.d/
is used by the build process for storing external resources from cloud listed insources.txt
.sources.txt
lists external cloud resources for additional documents (optional).repos.d
used to store embedded external repositories (git submodules) providing additional documents (optional)docs/
contains your documents (markdown files) and additional files, like images, data tables and other stuff..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.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 thedocs/
root folder.index.de.md
is the German variant of the Englishindex.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.mkdocs-requirements.txt
lists all required python packages for running mkdocs locally.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.ymloverrides/
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
- Joplin (free; for Linux/Windows/MacOS/Android/iOS; code editor with parallel preview),
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
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):
- Go into your project folder
- If not already under git control, initialize it
- Make sure you have a clean worktree and commit or stash possible changes.
- Fetch the latest doc-template from remote
- 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)!
- 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. - 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.
- If you have un-committed changes, stash them away or commit them with
git add
andgit commit
. - If you've just initialized the git project there is nothing to commit yet.
- See comment below about git enthusiasts and geeks.
- 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.
- 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. - With this merge the incoming files are intertwined with your own files but no commit is performed to provide an additional checkpoint.
- If the merge was successful, you can commit these changes
- Now go back to your original main branch 'master'
- Merge the temporary branch into your master branch.
- 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:
- The title of your documentation
- 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
orhttps://groupname.pages.geomar.de/myproject
) or via a dedicated domain (e.g.https://myproject.geomar.de
orhttps://myproject.edu
). See also Site Location
However, the URL must be placed at two locations: (1) parametersite_url
and (2) in eachlink
entry of theextra:alternate
section. - The authorship
- A copyright statement besides 'GEOMAR'
- A site description
- 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)
- Use your favorite editor to modify files.
- Assuming, you are in your mkdocs root folder.
- This adds actually all changes in the current working directory when using the
.
path indicator. - 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:
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
-
Add all necessary files to git's staging area and commit them, e.g. with
git add .
andgit commit
. -
Add a remote server repository (if not already done):
If the remote repository does not exist yet, you can create it automatically with the first push in the next step.
-
Push the current branch to the remote repository (e.g. master branch to origin):
-
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
- Visit the template project with your web browser
- Click on the Fork link and create a fork.
-
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.)
-
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:
- The title of your documentation
- 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
orhttps://groupname.pages.geomar.de/myproject
) or via a dedicated domain (e.g.https://myproject.geomar.de
orhttps://myproject.edu
). See also Site Location
However, the URL must be placed at two locations: (1) parametersite_url
and (2) in eachlink
entry of theextra:alternate
section. - The authorship
- A copyright statement besides 'GEOMAR'
- A site description
- Repository links and links to social networks and contact options
See Configuration: Build (mkdocs.yml) for more details.
Step 3 - Add content
- 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).
- Add new files to the
docs/
folder and modify the navigation in the respective.pages
file(s) if needed. - 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
- Make sure, your CI/CD runner settings as well as the Pages feature were configured properly.
- 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
:
# 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:
- Commit some changes to the repository
- 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.
./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
- For the default language (EN) replace 'mkdocs-GEOMAR-template' with your own project name in order to make the language chooser working correctly.
- 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 eitherhttps://git.geomar.de/docs/template-mkdocs/-/edit/master/docs/
for the inline-editor orhttps://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!):
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.
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:
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:
- Get all files that were not already processed for the navigation
nav:
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:
- Go into your project directory
- Make sure, you have a clean worktree (commit or stash your changes otherwise)
- Add an annotated tag for the new version with
git tag -a -m "YOUR COMMENT" LABEL
, whereLABEL
must start with the characterv
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'. - Commit your changes and push to the remote including tags (option
--tags
).
- Open your web browser and visit the web repository of your project, e.g. https://git.geomar.de/mynamespace/myproject.
- Under the header section, click on the "+" dropdown menu and choose "New tag"
-
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.
-
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:
- Open your web browser
- Go to the the web repository of your project
- From the project menu in the left sidebar choose "Seetings"> "CI/CD"
- Expand the section "Runners" by clicking on the title or Click the "Expand button"
- In the right column "enable shared runners for this project"
(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.
- Open your web browser
- Go to the the web repository of your project
- From the project menu in the left sidebar choose "Seetings"> "General"
- Expand the section "Visibility, project features, permissions" by clicking on the title or Click the "Expand button"
- In the feature list scroll down until you see "Pages" and enable the feature by clicking on the switch button.
-
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
.
# 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:
- Add git submodule remote in
.repos.d/
- Update the submodules (if necessary, i.e. older git version)
- Commit and submit
1. Add Submodule🔗
In the doc's root folder run:
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🔗
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)
- Go to the project directory and check if the working tree is clean (commit or stash current changes otherwise).
- Add the submodule. Notice, the masked blank
"\ "
in the target directory name (will be also used in the navigation menu) - 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':
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:
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
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
:
diff --git a/.gitignore b/.gitignore
index 7e72473..a66662f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
site/
aux/
.cache/
+~*
~*
) 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
:
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
$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
:
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
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.
After resolving all conflicts, you can resume with the merge process with:
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:
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
:
Example: Review diffs
.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:
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)\).
-
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. ↩↩
-
WYSIWYG - "What You See Is What You Get": Editor shows formatted text instantly, like in office apps. ↩
Created: November 2, 2020