Welcome to MkDocs
For full documentation visit mkdocs.org.
Commands
mkdocs new [dir-name]- Create a new project.mkdocs serve- Start the live-reloading docs server.mkdocs build- Build the documentation site.mkdocs -h- Print help message and exit.
Project layout
mkdocs.yml # The configuration file.
docs/
index.md # The documentation homepage.
... # Other markdown pages, images and other files.
Documentation
Themes
- https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes
- Starlette Admin - can be used as admin site Link
Auto-generate Documentation from Code
- https://pypi.org/project/pymkdocs
- https://racingpost.netlify.app/host-https-realpython.com/python-project-documentation-with-mkdocs/#
Variable List
Macros Plugin Environment
General List
All available variables and filters within the macros plugin:
| Variable | Type | Content |
|---|---|---|
| extra | dict | |
| config | MkDocsConfig | {'config_file_path': './docs/mkdocs.yml', 'site_name': 'ImageTransformSvc', 'nav': ['API.md', 'README.md', {'SETUP': ['setup/SETUP.md', 'setup/GCP-JOBS.md', 'setup/GCP-RUN.md', 'setup/GCP-RUN-Celery.md', 'setup/LOGGING.md', 'setup/SETTINGS.md', 'setup/DICOM-METADATA.md']}, 'DEVELOPMENT.md', {'RELEASES': ['releases/v1.4.1.md', 'releases/v1.4.0.md', 'releases/v1.3.3.md', 'releases/v1.3.2.md', 'releases/v1.3.1.md', 'releases/v1.3.0.md', 'releases/v1.1.0.md', 'releases/v1.0.5.md', 'releases/v1.0.4.md', 'releases/v1.0.3.md', 'releases/v1.0.2.md', 'releases/v1.0.1.md', 'releases/v1.0.0.md', 'releases/v0.9.0.md']}, {'mkDocs Intro': 'MkDOCS.md'}], 'pages': None, 'exclude_docs': None, 'draft_docs': None, 'not_in_nav': None, 'site_url': None, 'site_description': None, 'site_author': None, 'theme': Theme(name='material', dirs=['./docs/theme-overrides', '/usr/local/lib/python3.10/dist-packages/material/templates', '/usr/local/lib/python3.10/dist-packages/mkdocs/templates'], static_templates={'404.html', 'sitemap.xml'}, name='material', locale=Locale('en'), language='en', direction=None, features=['navigation.instant', 'navigation.tracking', 'navigation.tabs', 'navigation.tabs.sticky', 'navigation.sections', 'navigation.top', 'toc.integrate', 'search.suggest', 'navigation.footer', 'content.tabs.link', 'content.code.copy', 'content.code.select'], font={'text': 'Montserrat'}, icon={'admonition': {'note': 'material/note', 'abstract': 'fontawesome/solid/diagram-project', 'info': 'octicons/info-16', 'tip': 'octicons/squirrel-16', 'success': 'octicons/check-16', 'question': 'octicons/question-16', 'warning': 'octicons/alert-16', 'failure': 'octicons/x-circle-16', 'danger': 'octicons/zap-16', 'bug': 'octicons/bug-16', 'example': 'octicons/beaker-16', 'quote': 'octicons/quote-16'}}, favicon='assets/images/favicon.png', logo='assets/images/gestalt_logo.png', palette=[{'scheme': 'default', 'toggle': {'icon': 'material/brightness-7', 'name': 'Switch to dark mode'}}, {'scheme': 'slate', 'toggle': {'icon': 'material/brightness-4', 'name': 'Switch to light mode'}}]), 'docs_dir': '/code/docs/docs', 'site_dir': '/code/docs/site', 'copyright': None, 'google_analytics': None, 'dev_addr': _IpAddressValue(host='127.0.0.1', port=8000), 'use_directory_urls': True, 'repo_url': 'https://gestaltdiagnostics.visualstudio.com/Gestalt%20AI/_git/ImageTransformSvc', 'repo_name': 'Gestaltdiagnostics', 'edit_uri_template': None, 'edit_uri': None, 'extra_css': [], 'extra_javascript': ['https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js', 'assets/javascripts/tablesort.js'], 'extra_templates': [], 'markdown_extensions': ['toc', 'tables', 'fenced_code', 'admonition', 'pymdownx.highlight', 'pymdownx.inlinehilite', 'pymdownx.snippets', 'pymdownx.superfences', 'pymdownx.details', 'attr_list', 'pymdownx.emoji', 'pymdownx.tabbed', 'pymdownx.critic', 'pymdownx.caret', 'pymdownx.keys', 'pymdownx.mark', 'pymdownx.tilde', 'def_list', 'pymdownx.tasklist'], 'mdx_configs': {'pymdownx.highlight': {'anchor_linenums': True, 'line_spans': '__span', 'pygments_lang_class': True}, 'pymdownx.superfences': {'custom_fences': [{'name': 'mermaid', 'class': 'mermaid', 'format': |
| environment | dict | system = 'Linux', system_version = '6.6.87.2-microsoft-standard-WSL2', python_version = '3.10.12', mkdocs_version = '1.6.1', macros_plugin_version = '1.3.9', jinja2_version = '3.1.6' |
| plugin | LegacyConfig | {'module_name': 'main', 'modules': [], 'render_by_default': True, 'force_render_paths': '', 'include_dir': '', 'include_yaml': [], 'j2_block_start_string': '', 'j2_block_end_string': '', 'j2_variable_start_string': '', 'j2_variable_end_string': '', 'j2_comment_start_string': '', 'j2_comment_end_string': '', 'on_undefined': 'keep', 'on_error_fail': False, 'verbose': False} |
| git | dict | status = False, date [NoneType], short_commit = "# Unexpected error '['git', 'rev-parse', '--short', 'HEAD']': [Errno 2] No such file or directory: 'git'", commit = "# Unexpected error '['git', 'rev-parse', 'HEAD']': [Errno 2] No such file or directory: 'git'", tag = "# Unexpected error '['git', 'describe', '--tags']': [Errno 2] No such file or directory: 'git'", short_tag = "# Unexpected error '['git', 'describe', '--tags', '--abbrev=0']': [Errno 2] No such file or directory: 'git'", author = "# Unexpected error '['git', 'log', '-1', '--pretty=format:%an']': [Errno 2] No such file or directory: 'git'", author_email = "# Unexpected error '['git', 'log', '-1', '--pretty=format:%ae']': [Errno 2] No such file or directory: 'git'", committer = "# Unexpected error '['git', 'log', '-1', '--pretty=format:%cn']': [Errno 2] No such file or directory: 'git'", committer_email = "# Unexpected error '['git', 'log', '-1', '--pretty=format:%ce']': [Errno 2] No such file or directory: 'git'", date_ISO = "# Unexpected error '['git', 'log', '-1', '--pretty=format:%cd']': [Errno 2] No such file or directory: 'git'", message = "# Unexpected error '['git', 'log', '-1', '--pretty=format:%B']': [Errno 2] No such file or directory: 'git'", raw = "# Unexpected error '['git', 'log', '-1']': [Errno 2] No such file or directory: 'git'", root_dir = "# Unexpected error '['git', 'rev-parse', '--show-toplevel']': [Errno 2] No such file or directory: 'git'" |
| macros | SuperDict | context [function], macros_info [function], now [function], fix_url [function] |
| filters | dict | pretty [function], relative_url [function] |
| filters_builtin | dict | abs [builtin_function_or_method], attr [function], batch [function], capitalize [function], center [function], count [builtin_function_or_method], d [function], default [function], dictsort [function], e [builtin_function_or_method], escape [builtin_function_or_method], filesizeformat [function], first [function], float [function], forceescape [function], format [function], groupby [function], indent [function], int [function], join [function], last [function], length [builtin_function_or_method], list [function], lower [function], items [function], map [function], min [function], max [function], pprint [function], random [function], reject [function], rejectattr [function], replace [function], reverse [function], round [function], safe [function], select [function], selectattr [function], slice [function], sort [function], string [builtin_function_or_method], striptags [function], sum [function], title [function], trim [function], truncate [function], unique [function], upper [function], urlencode [function], urlize [function], wordcount [function], wordwrap [function], xmlattr [function], tojson [function] |
| navigation | Navigation | |
| files | Files | |
| page | Page | Page(title='mkDocs Intro', url='MkDOCS/') |
Config Information
Standard MkDocs configuration information. Do not try to modify.
e.g. {{ config.docs_dir }}
See also the MkDocs documentation on the config object.
| Variable | Type | Content |
|---|---|---|
| config_file_path | str | './docs/mkdocs.yml' |
| site_name | str | 'ImageTransformSvc' |
| nav | list | ['API.md', 'README.md', {'SETUP': ['setup/SETUP.md', 'setup/GCP-JOBS.md', 'setup/GCP-RUN.md', 'setup/GCP-RUN-Celery.md', 'setup/LOGGING.md', 'setup/SETTINGS.md', 'setup/DICOM-METADATA.md']}, 'DEVELOPMENT.md', {'RELEASES': ['releases/v1.4.1.md', 'releases/v1.4.0.md', 'releases/v1.3.3.md', 'releases/v1.3.2.md', 'releases/v1.3.1.md', 'releases/v1.3.0.md', 'releases/v1.1.0.md', 'releases/v1.0.5.md', 'releases/v1.0.4.md', 'releases/v1.0.3.md', 'releases/v1.0.2.md', 'releases/v1.0.1.md', 'releases/v1.0.0.md', 'releases/v0.9.0.md']}, {'mkDocs Intro': 'MkDOCS.md'}] |
| pages | NoneType | None |
| exclude_docs | NoneType | None |
| draft_docs | NoneType | None |
| not_in_nav | NoneType | None |
| site_url | NoneType | None |
| site_description | NoneType | None |
| site_author | NoneType | None |
| theme | Theme | Theme(name='material', dirs=['./docs/theme-overrides', '/usr/local/lib/python3.10/dist-packages/material/templates', '/usr/local/lib/python3.10/dist-packages/mkdocs/templates'], static_templates={'404.html', 'sitemap.xml'}, name='material', locale=Locale('en'), language='en', direction=None, features=['navigation.instant', 'navigation.tracking', 'navigation.tabs', 'navigation.tabs.sticky', 'navigation.sections', 'navigation.top', 'toc.integrate', 'search.suggest', 'navigation.footer', 'content.tabs.link', 'content.code.copy', 'content.code.select'], font={'text': 'Montserrat'}, icon={'admonition': {'note': 'material/note', 'abstract': 'fontawesome/solid/diagram-project', 'info': 'octicons/info-16', 'tip': 'octicons/squirrel-16', 'success': 'octicons/check-16', 'question': 'octicons/question-16', 'warning': 'octicons/alert-16', 'failure': 'octicons/x-circle-16', 'danger': 'octicons/zap-16', 'bug': 'octicons/bug-16', 'example': 'octicons/beaker-16', 'quote': 'octicons/quote-16'}}, favicon='assets/images/favicon.png', logo='assets/images/gestalt_logo.png', palette=[{'scheme': 'default', 'toggle': {'icon': 'material/brightness-7', 'name': 'Switch to dark mode'}}, {'scheme': 'slate', 'toggle': {'icon': 'material/brightness-4', 'name': 'Switch to light mode'}}]) |
| docs_dir | str | '/code/docs/docs' |
| site_dir | str | '/code/docs/site' |
| copyright | NoneType | None |
| google_analytics | NoneType | None |
| dev_addr | _IpAddressValue | _IpAddressValue(host='127.0.0.1', port=8000) |
| use_directory_urls | bool | True |
| repo_url | str | 'https://gestaltdiagnostics.visualstudio.com/Gestalt%20AI/_git/ImageTransformSvc' |
| repo_name | str | 'Gestaltdiagnostics' |
| edit_uri_template | NoneType | None |
| edit_uri | NoneType | None |
| extra_css | list | [] |
| extra_javascript | list | ['https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js', 'assets/javascripts/tablesort.js'] |
| extra_templates | list | [] |
| markdown_extensions | list | ['toc', 'tables', 'fenced_code', 'admonition', 'pymdownx.highlight', 'pymdownx.inlinehilite', 'pymdownx.snippets', 'pymdownx.superfences', 'pymdownx.details', 'attr_list', 'pymdownx.emoji', 'pymdownx.tabbed', 'pymdownx.critic', 'pymdownx.caret', 'pymdownx.keys', 'pymdownx.mark', 'pymdownx.tilde', 'def_list', 'pymdownx.tasklist'] |
| mdx_configs | dict | pymdownx.highlight [dict], pymdownx.superfences [dict], pymdownx.emoji [dict], pymdownx.tabbed [dict], pymdownx.tasklist [dict] |
| strict | bool | False |
| remote_branch | str | 'gh-pages' |
| remote_name | str | 'origin' |
| extra | LegacyConfig | {} |
| plugins | PluginCollection | material/search [SearchPlugin], render_swagger [SwaggerPlugin], macros [MacrosPlugin] |
| hooks | dict | |
| watch | list | [] |
| validation | Validation | {'nav': {'omitted_files': 20, 'not_found': 30, 'absolute_links': 20}, 'links': {'not_found': 30, 'absolute_links': 20, 'unrecognized_links': 20, 'anchors': 20}} |
| user_directory_urls | bool | True |
Macros
These macros have been defined programmatically for this environment (module or pluglets).
| Variable | Type | Content |
|---|---|---|
| context | function | (obj, e) Default Mkdocs-Macro: List an object (by default the variables) |
| macros_info | function | () Test/debug function: list useful documentation on the mkdocs_macro environment. |
| now | function | () Default Mkdocs-Macro: Get the current time (at the moment of the project build). It returns a datetime object. Used alone, it provides a timestamp. To get the year use |
| fix_url | function | (url, r) If url is relative, fix it so that it points to the docs directory. This is necessary because relative links in markdown must be adapted in html ('img/foo.png' => '../img/img.png'). |
Git Information
Information available on the last commit and the git repository containing the documentation project:
e.g. {{ git.message }}
| Variable | Type | Content |
|---|---|---|
| status | bool | False |
| date | NoneType | None |
| short_commit | str | "# Unexpected error '['git', 'rev-parse', '--short', 'HEAD']': [Errno 2] No such file or directory: 'git'" |
| commit | str | "# Unexpected error '['git', 'rev-parse', 'HEAD']': [Errno 2] No such file or directory: 'git'" |
| tag | str | "# Unexpected error '['git', 'describe', '--tags']': [Errno 2] No such file or directory: 'git'" |
| short_tag | str | "# Unexpected error '['git', 'describe', '--tags', '--abbrev=0']': [Errno 2] No such file or directory: 'git'" |
| author | str | "# Unexpected error '['git', 'log', '-1', '--pretty=format:%an']': [Errno 2] No such file or directory: 'git'" |
| author_email | str | "# Unexpected error '['git', 'log', '-1', '--pretty=format:%ae']': [Errno 2] No such file or directory: 'git'" |
| committer | str | "# Unexpected error '['git', 'log', '-1', '--pretty=format:%cn']': [Errno 2] No such file or directory: 'git'" |
| committer_email | str | "# Unexpected error '['git', 'log', '-1', '--pretty=format:%ce']': [Errno 2] No such file or directory: 'git'" |
| date_ISO | str | "# Unexpected error '['git', 'log', '-1', '--pretty=format:%cd']': [Errno 2] No such file or directory: 'git'" |
| message | str | "# Unexpected error '['git', 'log', '-1', '--pretty=format:%B']': [Errno 2] No such file or directory: 'git'" |
| raw | str | "# Unexpected error '['git', 'log', '-1']': [Errno 2] No such file or directory: 'git'" |
| root_dir | str | "# Unexpected error '['git', 'rev-parse', '--show-toplevel']': [Errno 2] No such file or directory: 'git'" |
Page Attributes
Provided by MkDocs. These attributes change for every page (the attributes shown are for this page).
e.g. {{ page.title }}
See also the MkDocs documentation on the page object.
| Variable | Type | Content |
|---|---|---|
| file | File | src_uri = 'MkDOCS.md', src_dir = '/code/docs/docs', dest_dir = '/code/docs/site', use_directory_urls = True, inclusion [InclusionLevel], name = 'MkDOCS', dest_uri = 'MkDOCS/index.html', page [Page], abs_src_path = '/code/docs/docs/MkDOCS.md', url = 'MkDOCS/' |
| title | str | 'mkDocs Intro' |
| children | NoneType | None |
| previous_page | Page | Page(title=[blank], url='releases/v0.9.0/') |
| next_page | NoneType | None |
| _Page__active | bool | False |
| update_date | str | '2025-08-18' |
| canonical_url | NoneType | None |
| abs_url | NoneType | None |
| edit_url | NoneType | None |
| markdown | str | '# Welcome to MkDocs\n\nFor full documentation visit [mkdocs.org](https://www.mkdocs.org).\n\n## Commands\n\n* `mkdocs new [dir-name]` - Create a new project.\n* `mkdocs serve` - Start the live-reloading docs server.\n* `mkdocs build` - Build the documentation site.\n* `mkdocs -h` - Print help message and exit.\n\n## Project layout\n\n mkdocs.yml # The configuration file.\n docs/\n index.md # The documentation homepage.\n ... # Other markdown pages, images and other files.\n\n## Documentation\n- Material for Mkdocs [Link](https://squidfunk.github.io/mkdocs-material/reference/S)\n - Alternate Documentation [Link](https://t.pxeger.com/mkdocs-material/reference/variables/)\n- Mkdocs Macros [Link](https://mkdocs-macros-plugin.readthedocs.io/en/latest/)\n\n## Themes\n\n- [https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes](https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes)\n- Starlette Admin - can be used as admin site [Link](https://jowilf.github.io/starlette-admin/)\n\n## Auto-generate Documentation from Code\n- https://pypi.org/project/pymkdocs\n- https://racingpost.netlify.app/host-https-realpython.com/python-project-documentation-with-mkdocs/#\n\n## Variable List\n\n{{ macros_info() }}\n\n' |
| _title_from_render | NoneType | None |
| content | NoneType | None |
| toc | list | [] |
| meta | dict |
To have all titles of all pages, use:
Plugin Filters
These filters are provided as a standard by the macros plugin.
| Variable | Type | Content |
|---|---|---|
| pretty | function | (var_list, rows, header, e) Default Mkdocs-Macro: Prettify a dictionary or object (used for environment documentation, or debugging). |
| relative_url | function | (path) Default Mkdocs-Macro: convert the path of any page according to MkDoc's internal logic, into a URL relative to the current page (implements the |
Builtin Jinja2 Filters
These filters are provided by Jinja2 as a standard.
See also the Jinja2 documentation on builtin filters.
| Variable | Type | Content |
|---|---|---|
| abs | builtin_function_or_method | Return the absolute value of the argument. |
| attr | function | (environment, obj, name) Get an attribute of an object. |
| batch | function | (value, linecount, fill_with, tmp, item) A filter that batches items. It works pretty much like |
| capitalize | function | (s) Capitalize a value. The first character will be uppercase, all others lowercase. |
| center | function | (value, width) Centers the value in a field of a given width. |
| count | builtin_function_or_method | Return the number of items in a container. |
| d | function | (value, default_value, boolean) If the value is undefined it will return the passed default value, otherwise the value of the variable. |
| default | function | (value, default_value, boolean) If the value is undefined it will return the passed default value, otherwise the value of the variable. |
| dictsort | function | (value, case_sensitive, by, reverse, sort_func) Sort a dict and yield (key, value) pairs. Python dicts may not be in the order you want to display them in, so sort them first. |
| e | builtin_function_or_method | Replace the characters |
| escape | builtin_function_or_method | Replace the characters |
| filesizeformat | function | (value, binary, bytes, base, prefixes, i, prefix, unit) Format the value like a 'human-readable' file size (i.e. 13 kB, 4.1 MB, 102 Bytes, etc). Per default decimal prefixes are used (Mega, Giga, etc.), if the second parameter is set to |
| first | function | (args, kwargs, b) Return the first item of a sequence. |
| float | function | (value, default) Convert the value into a floating point number. If the conversion doesn't work it will return |
| forceescape | function | (value) Enforce HTML escaping. This will probably double escape variables. |
| format | function | (value, args, kwargs) Apply the given values to a |
| groupby | function | (args, kwargs, b) Group a sequence of objects by an attribute using Python's :func: |
| indent | function | (s, width, first, blank, newline, rv, lines) Return a copy of the string with each line indented by 4 spaces. The first line and blank lines are not indented by default. |
| int | function | (value, default, base) Convert the value into an integer. If the conversion doesn't work it will return |
| join | function | (args, kwargs, b) Return a string which is the concatenation of the strings in the sequence. The separator between elements is an empty string per default, you can define it with the optional parameter. |
| last | function | (environment, seq) Return the last item of a sequence. |
| length | builtin_function_or_method | Return the number of items in a container. |
| list | function | (args, kwargs, b) Convert the value into a list. If it was a string the returned list will be a list of characters. |
| lower | function | (s) Convert a value to lowercase. |
| items | function | (value) Return an iterator over the |
| map | function | (args, kwargs, b) Applies a filter on a sequence of objects or looks up an attribute. This is useful when dealing with lists of objects but you are really only interested in a certain value of it. |
| min | function | (environment, value, case_sensitive, attribute) Return the smallest item from the sequence. |
| max | function | (environment, value, case_sensitive, attribute) Return the largest item from the sequence. |
| pprint | function | (value) Pretty print a variable. Useful for debugging. |
| random | function | (context, seq) Return a random item from the sequence. |
| reject | function | (args, kwargs, b) Filters a sequence of objects by applying a test to each object, and rejecting the objects with the test succeeding. |
| rejectattr | function | (args, kwargs, b) Filters a sequence of objects by applying a test to the specified attribute of each object, and rejecting the objects with the test succeeding. |
| replace | function | (eval_ctx, s, old, new, count) Return a copy of the value with all occurrences of a substring replaced with a new one. The first argument is the substring that should be replaced, the second is the replacement string. If the optional third argument |
| reverse | function | (value, rv, e) Reverse the object or return an iterator that iterates over it the other way round. |
| round | function | (value, precision, method, func) Round the number to a given precision. The first parameter specifies the precision (default is |
| safe | function | (value) Mark the value as safe which means that in an environment with automatic escaping enabled this variable will not be escaped. |
| select | function | (args, kwargs, b) Filters a sequence of objects by applying a test to each object, and only selecting the objects with the test succeeding. |
| selectattr | function | (args, kwargs, b) Filters a sequence of objects by applying a test to the specified attribute of each object, and only selecting the objects with the test succeeding. |
| slice | function | (args, kwargs, b) Slice an iterator and return a list of lists containing those items. Useful if you want to create a div containing three ul tags that represent columns. |
| sort | function | (environment, value, reverse, case_sensitive, attribute, key_func) Sort an iterable using Python's :func: |
| string | builtin_function_or_method | Convert an object to a string if it isn't already. This preserves a :class: |
| striptags | function | (value) Strip SGML/XML tags and replace adjacent whitespace by one space. |
| sum | function | (args, kwargs, b) Returns the sum of a sequence of numbers plus the value of parameter 'start' (which defaults to 0). When the sequence is empty it returns start. |
| title | function | (s) Return a titlecased version of the value. I.e. words will start with uppercase letters, all remaining characters are lowercase. |
| trim | function | (value, chars) Strip leading and trailing characters, by default whitespace. |
| truncate | function | (env, s, length, killwords, end, leeway, result) Return a truncated copy of the string. The length is specified with the first parameter which defaults to |
| unique | function | (args, kwargs, b) Returns a list of unique items from the given iterable. |
| upper | function | (s) Convert a value to uppercase. |
| urlencode | function | (value, items) Quote data for use in a URL path or query using UTF-8. |
| urlize | function | (eval_ctx, value, trim_url_limit, nofollow, target, rel, extra_schemes, policies, rel_parts, scheme, rv) Convert URLs in text into clickable links. |
| wordcount | function | (s) Count the words in that string. |
| wordwrap | function | (environment, s, width, break_long_words, wrapstring, break_on_hyphens) Wrap a string to the given width. Existing newlines are treated as paragraphs to be wrapped separately. |
| xmlattr | function | (eval_ctx, d, autospace, items, key, value, rv) Create an SGML/XML attribute string based on the items in a dict. |
| tojson | function | (eval_ctx, value, indent, policies, dumps, kwargs) Serialize an object to a string of JSON, and mark it safe to render in HTML. This filter is only for use in HTML documents. |