|
|
|
## Structure
|
|
|
|
|
|
|
|
When importing the template files, you'll get an additional folder (`docs/`) and some new files (`*.yml`). Therefore, check if you have already files/folders with the same name and if so, you may consider renaming befor the import:
|
|
|
|
|
|
|
|
* `docs/`
|
|
|
|
* `img/`
|
|
|
|
* `favicon-32x32.png`
|
|
|
|
* ``*.md`
|
|
|
|
* `*.css`
|
|
|
|
* `mkdocs-examples/`
|
|
|
|
* `overrides/`
|
|
|
|
* ``mkdocs.yml`
|
|
|
|
* `.gitlab-ci.yml`
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### docs/
|
|
|
|
|
|
|
|
The `docs/` folder contains your documentation files formatted as Markdown (`.md` suffix). You can have as many files as you like. The menu structure however is set in the `mkdocs.yml` file.
|
|
|
|
|
|
|
|
There is also a `docs/img/` sub-folder, which contains images for your documentation. There is already a GEOMAR-Logo as **`favicon-32x32.png`**.
|
|
|
|
|
|
|
|
Additional CSS rules can be found in `docs/extra.css` and other user-stylesheet files.
|
|
|
|
|
|
|
|
### mkdocs.yml + mkdocs-examples/
|
|
|
|
|
|
|
|
The MkDocs confguration is defined in the`mkdocs.yml` file. The parameters therein can be split into several sections:
|
|
|
|
|
|
|
|
* Project
|
|
|
|
* Repository
|
|
|
|
* Social Media Links
|
|
|
|
* Navigation
|
|
|
|
* Theme
|
|
|
|
* Extensions
|
|
|
|
* Plugins
|
|
|
|
|
|
|
|
The **mkdocs-examples/** folder contains configuration files for (1) adding a repository link in the header, (2) adding social media links in the footer and (3) adding versioning and an archive linke in the menu.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
#### + Project
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
#========================================
|
|
|
|
# (*) 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/
|
|
|
|
|
|
|
|
# (*) 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
|
|
|
|
site_description: >-
|
|
|
|
DESCRIPTION
|
|
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
#### + Repository
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
#========================================
|
|
|
|
# ( ) 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:
|
|
|
|
repo_url: https://git.geomar.de/
|
|
|
|
edit_uri: ""
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
#### + Social Media Links
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
#========================================
|
|
|
|
# ( ) Social Media Links
|
|
|
|
#========================================
|
|
|
|
# social:
|
|
|
|
# - icon: material/home
|
|
|
|
# link: https://www.geomar.de/
|
|
|
|
# name: 'Homepage'
|
|
|
|
# - icon: fontawesome/solid/paper-plane
|
|
|
|
# link: mailto:
|
|
|
|
# - icon: fontawesome/brands/slack
|
|
|
|
# link: https://
|
|
|
|
# name: ''
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
#### + Navigation
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
#========================================
|
|
|
|
# (*) Navigation
|
|
|
|
#========================================
|
|
|
|
use_directory_urls: false
|
|
|
|
nav:
|
|
|
|
- 'Main':
|
|
|
|
- intro.md
|
|
|
|
- other.md
|
|
|
|
- 'Tutorial':
|
|
|
|
- chapter-01.md
|
|
|
|
- 'Chapter 2':
|
|
|
|
- chapter-2-1.md
|
|
|
|
- chapter-2-2.md
|
|
|
|
- 'Chapter 3':
|
|
|
|
- chapter-3-1.md
|
|
|
|
- 'Reference':
|
|
|
|
- api.md
|
|
|
|
- modules.md
|
|
|
|
- 'Contact':
|
|
|
|
- 'contact.md'
|
|
|
|
- 'Archive':
|
|
|
|
- 'archive.md'
|
|
|
|
- 'releasenote.md'
|
|
|
|
- 'Version Selector': "../"
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
#### + Theme
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
#========================================
|
|
|
|
# ( ) Theme
|
|
|
|
#========================================
|
|
|
|
# Replace logo + favicon for your own logo; default: GEOMAR logo
|
|
|
|
#
|
|
|
|
theme:
|
|
|
|
name: material
|
|
|
|
logo: 'img/favicon-32x32.png'
|
|
|
|
favicon: 'img/favicon-32x32.png'
|
|
|
|
palette:
|
|
|
|
scheme: geomar
|
|
|
|
primary: dark
|
|
|
|
accent: '#00589c'
|
|
|
|
features:
|
|
|
|
- navigation.tabs
|
|
|
|
- search.highlight
|
|
|
|
icon:
|
|
|
|
repo: fontawesome/brands/github
|
|
|
|
extra_css:
|
|
|
|
- extra.css
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
#### + Extensions
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
#========================================
|
|
|
|
# (/) Extensions
|
|
|
|
#========================================
|
|
|
|
markdown_extensions:
|
|
|
|
- admonition
|
|
|
|
- attr_list
|
|
|
|
- markdown_captions
|
|
|
|
- footnotes
|
|
|
|
- codehilite:
|
|
|
|
guess_lang: false
|
|
|
|
- pymdownx.details
|
|
|
|
- pymdownx.superfences
|
|
|
|
- pymdownx.tasklist:
|
|
|
|
custom_checkbox: true
|
|
|
|
- pymdownx.tabbed
|
|
|
|
- pymdownx.critic
|
|
|
|
- pymdownx.snippets
|
|
|
|
- pymdownx.emoji:
|
|
|
|
emoji_index: !!python/name:materialx.emoji.twemoji
|
|
|
|
emoji_generator: !!python/name:materialx.emoji.to_svg
|
|
|
|
- markdown_include.include
|
|
|
|
- toc:
|
|
|
|
permalink: "🔗"
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
#### + Plugins
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
#========================================
|
|
|
|
# (*), (/) Plugins
|
|
|
|
#========================================
|
|
|
|
# Uncomment or comment the 'mkdocs-versioning' section in order to enable/disable
|
|
|
|
# the display of different versions/releases for the documentary
|
|
|
|
# See
|
|
|
|
#
|
|
|
|
plugins:
|
|
|
|
- search
|
|
|
|
- mkdocstrings:
|
|
|
|
default_handler: python
|
|
|
|
handlers:
|
|
|
|
python:
|
|
|
|
setup_commands:
|
|
|
|
- import sys
|
|
|
|
- sys.path.append("src")
|
|
|
|
rendering:
|
|
|
|
show_source: false
|
|
|
|
custom_templates: templates
|
|
|
|
watch:
|
|
|
|
- src/my_package
|
|
|
|
# Set/Disable Versioning feature here:
|
|
|
|
# use the same name conventions for refering to the current version as
|
|
|
|
# you've used for tagging the versions in git, e.g. "v1.0.1"
|
|
|
|
- mkdocs-versioning:
|
|
|
|
version: v0.0.19
|
|
|
|
exclude_from_nav: ["img"]
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
### overrides/
|
|
|
|
|
|
|
|
In par with the mkdocs document structure, the user can create their own template files. This is used to add a Disclaimer and Privacy link in the footer: `overrides/partials/footer.html`. |
|
|
|
\ No newline at end of file |
