List available variables
You can list all variables currently available by adding {{ macros_info() }}
to a page in your site. This is a good way to test if the plugin is working.
Here is the output for this site:
Macros Plugin Environment
General List
All available variables and filters within the macros plugin:
Variable | Type | Content |
---|---|---|
extra | dict | extraValueOne = 1, extraValueTwo = 'two' |
config | MkDocsConfig | {'config_file_path': 'C:\\Users\\debor\\Desktop\\code\\mkdocs-macros-yaml-examples\\mkdocs.yml', 'site_name': 'MkDocs Macros YAML Examples', 'nav': [{'Home': 'index.md'}, {'Setup': [{'Clone and run': 'clone-run.md'}, {'Avoid clashing with code examples': 'clashing-code.md'}, {'List available variables': 'macros-info.md'}]}, {'YAML sources': [{'Frontmatter': 'frontmatter.md'}, {'MkDocs file': 'mkdocs-file.md'}, {'External YAML files': 'external-yaml-files.md'}]}, {'Display YAML content': [{'Rows in a table': 'rows-table.md'}, {'Using macros': 'import-macro.md'}]}], 'pages': None, 'site_url': 'https://starfallprojects.github.io/mkdocs-macros-yaml-examples/', 'site_description': 'An example site to demo using mkdocs-macros-plugin with YAML to generate content.', 'site_author': 'Deborah Barnard', 'theme': Theme(name='material', dirs=['C:\\Users\\debor\\Desktop\\code\\mkdocs-macros-yaml-examples\\venv\\lib\\site-packages\\material', 'C:\\Users\\debor\\Desktop\\code\\mkdocs-macros-yaml-examples\\venv\\lib\\site-packages\\mkdocs\\templates'], static_templates=['sitemap.xml', '404.html'], name='material', locale=Locale(language='en', territory=''), language='en', direction=None, features=['navigation.sections'], palette={'primary': None, 'accent': None}, font={'text': 'Roboto', 'code': 'Roboto Mono'}, icon=None, favicon='assets/images/favicon.png'), 'docs_dir': 'C:\\Users\\debor\\Desktop\\code\\mkdocs-macros-yaml-examples\\src', 'site_dir': 'C:\\Users\\debor\\Desktop\\code\\mkdocs-macros-yaml-examples\\docs', 'copyright': None, 'google_analytics': None, 'dev_addr': _IpAddressValue(host='127.0.0.1', port=8000), 'use_directory_urls': True, 'repo_url': 'https://github.com/StarfallProjects/mkdocs-macros-yaml-examples', 'repo_name': 'GitHub', 'edit_uri_template': None, 'edit_uri': 'edit/master/docs/', 'extra_css': ['css/styles.css'], 'extra_javascript': [], 'extra_templates': [], 'markdown_extensions': ['toc', 'tables', 'fenced_code', 'admonition', 'pymdownx.details', 'pymdownx.highlight', 'pymdownx.inlinehilite', 'pymdownx.snippets', 'pymdownx.superfences'], 'mdx_configs': {'pymdownx.highlight': {'anchor_linenums': True}}, 'strict': False, 'remote_branch': 'gh-pages', 'remote_name': 'origin', 'extra': {'extraValueOne': 1, 'extraValueTwo': 'two'}, 'plugins': {'material/search': |
simpleYamlOne | int | 1 |
simpleYamlTwo | str | 'two' |
fruits | list | [{'name': 'apple', 'color': 'green', 'sweetness': '4/10'}, {'name': 'orange', 'color': 'orange', 'sweetness': '6/10'}, {'name': 'melon', 'color': 'yellow', 'sweetness': '8/10'}] |
environment | dict | system = 'Windows', system_version = '10', python_version = '3.10.2', mkdocs_version = '1.4.2', macros_plugin_version = '0.7.0', jinja2_version = '3.1.2' |
plugin | LegacyConfig | {'module_name': 'main', 'modules': [], 'include_dir': '', 'include_yaml': ['_yaml/simple-example.yml', '_yaml/large-example.yml'], 'j2_block_start_string': '', 'j2_block_end_string': '', 'j2_variable_start_string': '', 'j2_variable_end_string': '', 'on_undefined': 'keep', 'on_error_fail': False, 'verbose': False} |
git | dict | status = True, date [datetime], short_commit = '6cb4ac9', commit = '6cb4ac9cf971dc1b7840899b6f1e6dfb55879a6d', tag = '', author = 'StarfallProjects', author_email = 'starfallprojects@gmail.com', committer = 'StarfallProjects', committer_email = 'starfallprojects@gmail.com', date_ISO = 'Mon Jan 23 17:38:58 2023 +0000', message = 'add base url', raw = 'commit 6cb4ac9cf971dc1b7840899b6f1e6dfb55879a6d\nAuthor: StarfallProjects |
extraValueOne | int | 1 |
extraValueTwo | str | 'two' |
petstore | dict | openapi = '3.0.0', info [dict], servers = [{'url': 'http://petstore.swagger.io/v1'}], paths [dict], components [dict] |
macros | SuperDict | context [function], macros_info [function], now [function], fix_url [function] |
filters | dict | pretty [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 | Page(title='Home', url='/mkdocs-macros-yaml-examples/') Section(title='Setup') Page(title='Clone and run', url='/mkdocs-macros-yaml-examples/clone-run/') Page(title='Avoid clashing with code examples', url='/mkdocs-macros-yaml-examples/clashing-code/') Page(title='List available variables', url='/mkdocs-macros-yaml-examples/macros-info/') Section(title='YAML sources') Page(title='Frontmatter', url='/mkdocs-macros-yaml-examples/frontmatter/') Page(title='MkDocs file', url='/mkdocs-macros-yaml-examples/mkdocs-file/') Page(title='External YAML files', url='/mkdocs-macros-yaml-examples/external-yaml-files/') Section(title='Display YAML content') Page(title='Rows in a table', url='/mkdocs-macros-yaml-examples/rows-table/') Page(title='Using macros', url='/mkdocs-macros-yaml-examples/import-macro/') |
files | Files | |
page | Page | Page(title='List available variables', url='/mkdocs-macros-yaml-examples/macros-info/') |
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 | 'C:\\Users\\debor\\Desktop\\code\\mkdocs-macros-yaml-examples\\mkdocs.yml' |
site_name | str | 'MkDocs Macros YAML Examples' |
nav | list | [{'Home': 'index.md'}, {'Setup': [{'Clone and run': 'clone-run.md'}, {'Avoid clashing with code examples': 'clashing-code.md'}, {'List available variables': 'macros-info.md'}]}, {'YAML sources': [{'Frontmatter': 'frontmatter.md'}, {'MkDocs file': 'mkdocs-file.md'}, {'External YAML files': 'external-yaml-files.md'}]}, {'Display YAML content': [{'Rows in a table': 'rows-table.md'}, {'Using macros': 'import-macro.md'}]}] |
pages | NoneType | None |
site_url | str | 'https://starfallprojects.github.io/mkdocs-macros-yaml-examples/' |
site_description | str | 'An example site to demo using mkdocs-macros-plugin with YAML to generate content.' |
site_author | str | 'Deborah Barnard' |
theme | Theme | Theme(name='material', dirs=['C:\\Users\\debor\\Desktop\\code\\mkdocs-macros-yaml-examples\\venv\\lib\\site-packages\\material', 'C:\\Users\\debor\\Desktop\\code\\mkdocs-macros-yaml-examples\\venv\\lib\\site-packages\\mkdocs\\templates'], static_templates=['sitemap.xml', '404.html'], name='material', locale=Locale(language='en', territory=''), language='en', direction=None, features=['navigation.sections'], palette={'primary': None, 'accent': None}, font={'text': 'Roboto', 'code': 'Roboto Mono'}, icon=None, favicon='assets/images/favicon.png') |
docs_dir | str | 'C:\\Users\\debor\\Desktop\\code\\mkdocs-macros-yaml-examples\\src' |
site_dir | str | 'C:\\Users\\debor\\Desktop\\code\\mkdocs-macros-yaml-examples\\docs' |
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://github.com/StarfallProjects/mkdocs-macros-yaml-examples' |
repo_name | str | 'GitHub' |
edit_uri_template | NoneType | None |
edit_uri | str | 'edit/master/docs/' |
extra_css | list | ['css/styles.css'] |
extra_javascript | list | [] |
extra_templates | list | [] |
markdown_extensions | list | ['toc', 'tables', 'fenced_code', 'admonition', 'pymdownx.details', 'pymdownx.highlight', 'pymdownx.inlinehilite', 'pymdownx.snippets', 'pymdownx.superfences'] |
mdx_configs | dict | pymdownx.highlight [dict] |
strict | bool | False |
remote_branch | str | 'gh-pages' |
remote_name | str | 'origin' |
extra | LegacyConfig | {'extraValueOne': 1, 'extraValueTwo': 'two'} |
plugins | PluginCollection | material/search [SearchPlugin], macros [MacrosPlugin] |
hooks | dict | |
watch | list | [] |
Macros
These macros have been defined programmatically for this environment (module or pluglets).
Variable | Type | Content |
---|---|---|
context | function | (obj, e) Default mkdocs_macro List the defined variables |
macros_info | function | () Test/debug function: list useful documentation on the mkdocs_macro environment. |
now | function | () Get the current time (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 diretory. 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(2023, 1, 23, 17, 38, 58, tzinfo=tzutc()) |
short_commit | str | '6cb4ac9' |
commit | str | '6cb4ac9cf971dc1b7840899b6f1e6dfb55879a6d' |
tag | str | '' |
author | str | 'StarfallProjects' |
author_email | str | 'starfallprojects@gmail.com' |
committer | str | 'StarfallProjects' |
committer_email | str | 'starfallprojects@gmail.com' |
date_ISO | str | 'Mon Jan 23 17:38:58 2023 +0000' |
message | str | 'add base url' |
raw | str | 'commit 6cb4ac9cf971dc1b7840899b6f1e6dfb55879a6d\nAuthor: StarfallProjects |
root_dir | str | 'C:/Users/debor/Desktop/code/mkdocs-macros-yaml-examples' |
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 | page [Page], src_uri = 'macros-info.md', abs_src_path = 'C:\\Users\\debor\\Desktop\\code\\mkdocs-macros-yaml-examples\\src\\macros-info.md', name = 'macros-info', dest_uri = 'macros-info/index.html', abs_dest_path = 'C:\\Users\\debor\\Desktop\\code\\mkdocs-macros-yaml-examples\\docs\\macros-info\\index.html', url = 'macros-info/' |
title | str | 'List available variables' |
parent | Section | title = 'Setup', children = [Page(title='Clone and run', url='/mkdocs-macros-yaml-examples/clone-run/'), Page(title='Avoid clashing with code examples', url='/mkdocs-macros-yaml-examples/clashing-code/'), Page(title='List available variables', url='/mkdocs-macros-yaml-examples/macros-info/')], parent [NoneType], _Section__active = False |
children | NoneType | None |
previous_page | Page | Page(title='Avoid clashing with code examples', url='/mkdocs-macros-yaml-examples/clashing-code/') |
next_page | Page | Page(title='Frontmatter', url='/mkdocs-macros-yaml-examples/frontmatter/') |
_Page__active | bool | False |
update_date | str | '2023-01-23' |
canonical_url | str | 'https://starfallprojects.github.io/mkdocs-macros-yaml-examples/macros-info/' |
abs_url | str | '/mkdocs-macros-yaml-examples/macros-info/' |
edit_url | str | 'https://github.com/StarfallProjects/mkdocs-macros-yaml-examples/edit/master/docs/macros-info.md' |
markdown | str | '# List available variables\n\nYou can list all variables currently available by adding {% raw %}`{{ macros_info() }}`{% endraw %} to a page in your site. This is a good way to test if the plugin is working.\n\nHere is the output for this site:\n\n{{ macros_info() }}' |
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). |
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, value) 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 | (environment, value, case_sensitive, attribute, getter, seen, item, key) 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, rv) Create an SGML/XML attribute string based on the items in a dict. All values that are neither |
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. |