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.
Macros Plugin Environment
General List
All available variables and filters within the macros plugin:
| Variable | Type | Content |
|---|---|---|
| extra | dict | voidc_repo_url = 'https://github.com/voidc-lab/voidc/blob/master' |
| config | MkDocsConfig | {'config_file_path': '/home/runner/work/try-pages/try-pages/mkdocs.yml', 'site_name': 'Try Pages', 'nav': [{'Welcome to MkDocs': 'index.md'}, {'Strange': ['strange.md']}, {'Tutorial': ['tutorial.md']}, {'Examples': ['examples.md']}], 'pages': None, 'exclude_docs': |
| environment | dict | system = 'Linux', system_version = '6.14.0-1017-azure', python_version = '3.14.3', mkdocs_version = '1.6.1', macros_plugin_version = '1.5.0', 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': '', 'j2_extensions': [], 'on_undefined': 'keep', 'on_error_fail': False, 'verbose': False} |
| git | dict | status = True, date [datetime], short_commit = 'e80b4e8', commit = 'e80b4e834711f844759d9146429dac2bce09c1ef', tag = '', short_tag = '', author = 'Dmitry Borodkin', author_email = 'borodkin-dn@yandex.ru', committer = 'Dmitry Borodkin', committer_email = 'borodkin-dn@yandex.ru', date_ISO = 'Tue Mar 17 17:05:15 2026 +0300', message = '...', raw = 'commit e80b4e834711f844759d9146429dac2bce09c1ef\nAuthor: Dmitry Borodkin |
| voidc_repo_url | str | 'https://github.com/voidc-lab/voidc/blob/master' |
| 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 [function], escape [function], 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 [function], 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='Welcome to MkDocs', url='/try-pages/') |
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 | '/home/runner/work/try-pages/try-pages/mkdocs.yml' |
| site_name | str | 'Try Pages' |
| nav | list | [{'Welcome to MkDocs': 'index.md'}, {'Strange': ['strange.md']}, {'Tutorial': ['tutorial.md']}, {'Examples': ['examples.md']}] |
| pages | NoneType | None |
| exclude_docs | GitIgnoreSpec | |
| draft_docs | NoneType | None |
| not_in_nav | NoneType | None |
| site_url | str | 'https://dmitry-borodkin.github.io/try-pages/' |
| site_description | NoneType | None |
| site_author | NoneType | None |
| theme | Theme | Theme(name='material', dirs=['/opt/hostedtoolcache/Python/3.14.3/x64/lib/python3.14/site-packages/material/templates', '/opt/hostedtoolcache/Python/3.14.3/x64/lib/python3.14/site-packages/mkdocs/templates'], static_templates={'sitemap.xml', '404.html'}, name='material', locale=Locale('en'), language='en', direction=None, features=['navigation.tabs', 'navigation.footer'], font={'text': 'Roboto', 'code': 'Roboto Mono'}, icon=None, favicon='img/black_square.svg', palette=[{'scheme': 'default', 'primary': 'white', 'toggle': {'icon': 'material/brightness-4', 'name': 'Switch to dark mode'}}, {'scheme': 'slate', 'primary': 'black', 'toggle': {'icon': 'material/brightness-4', 'name': 'Switch to light mode'}}], logo='img/black_square.svg') |
| docs_dir | str | '/home/runner/work/try-pages/try-pages/docs' |
| site_dir | str | '/home/runner/work/try-pages/try-pages/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 | NoneType | None |
| repo_name | NoneType | None |
| edit_uri_template | NoneType | None |
| edit_uri | NoneType | None |
| extra_css | list | ['stylesheets/extra.css'] |
| extra_javascript | list | [] |
| extra_templates | list | [] |
| markdown_extensions | list | ['toc', 'tables', 'fenced_code', 'pymdownx.tilde', 'pymdownx.emoji', 'pymdownx.highlight', 'pymdownx.inlinehilite', 'pymdownx.snippets', 'pymdownx.superfences'] |
| mdx_configs | dict | pymdownx.highlight [dict], pymdownx.snippets [dict] |
| strict | bool | False |
| remote_branch | str | 'gh-pages' |
| remote_name | str | 'origin' |
| extra | LegacyConfig | {'voidc_repo_url': 'https://github.com/voidc-lab/voidc/blob/master'} |
| plugins | PluginCollection | material/search [SearchPlugin], 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}} |
Macros
These macros have been defined programmatically for this environment (module or pluglets).
| Variable | Type | Content |
|---|---|---|
| context | function | (obj, var, value, 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 | True |
| date | datetime | datetime.datetime(2026, 3, 17, 17, 5, 15, tzinfo=tzoffset(None, 10800)) |
| short_commit | str | 'e80b4e8' |
| commit | str | 'e80b4e834711f844759d9146429dac2bce09c1ef' |
| tag | str | '' |
| short_tag | str | '' |
| author | str | 'Dmitry Borodkin' |
| author_email | str | 'borodkin-dn@yandex.ru' |
| committer | str | 'Dmitry Borodkin' |
| committer_email | str | 'borodkin-dn@yandex.ru' |
| date_ISO | str | 'Tue Mar 17 17:05:15 2026 +0300' |
| message | str | '...' |
| raw | str | 'commit e80b4e834711f844759d9146429dac2bce09c1ef\nAuthor: Dmitry Borodkin |
| root_dir | str | '/home/runner/work/try-pages/try-pages' |
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 = 'index.md', src_dir = '/home/runner/work/try-pages/try-pages/docs', dest_dir = '/home/runner/work/try-pages/try-pages/site', use_directory_urls = True, inclusion [InclusionLevel], name = 'index', dest_uri = 'index.html', page [Page], url = './', abs_src_path = '/home/runner/work/try-pages/try-pages/docs/index.md' |
| title | str | 'Welcome to MkDocs' |
| children | NoneType | None |
| previous_page | NoneType | None |
| next_page | Page | Page(title=[blank], url='/try-pages/strange/') |
| _Page__active | bool | False |
| update_date | str | '2026-03-17' |
| canonical_url | str | 'https://dmitry-borodkin.github.io/try-pages/' |
| abs_url | str | '/try-pages/' |
| 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---\n\n[hello_jit.void]({{voidc_repo_url}}/hello_jit.void)\n\n---\n\n{{ macros_info() }}\n\n\n' |
| _title_from_render | NoneType | None |
| content | NoneType | None |
| toc | list | [] |
| meta | dict | hide = ['footer'] |
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, var, var_type, content, 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 | function | (s) Replace the characters |
| escape | function | (s) 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 | function | (s) 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, item) 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, textwrap, line) 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. |