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 | feature [dict], social = [{'type': 'globe', 'link': 'https://www.voronenko.info'}, {'type': 'github-alt', 'link': 'https://github.com/voronenko'}, {'type': 'twitter', 'link': 'https://twitter.com/slavko'}, {'type': 'linkedin', 'link': 'https://www.linkedin.com/in/voronenkovyacheslav/'}] |
| config | Config | config_file_path = '/home/runner/work/runbooks-mkdocs/runbooks-mkdocs/mkdocs.yml', site_name = 'project docs', nav [NoneType], pages [NoneType], site_url = '', site_description [NoneType], site_author [NoneType], theme [Theme], docs_dir = '/home/runner/work/runbooks-mkdocs/runbooks-mkdocs/docs', site_dir = '/home/runner/work/runbooks-mkdocs/runbooks-mkdocs/public', copyright [NoneType], google_analytics [NoneType], dev_addr [Address], use_directory_urls = True, repo_url = '', repo_name = '', edit_uri = '', extra_css = ['css/ansi-colours.css', 'css/jupyter-cells.css', 'css/pandas-dataframe.css'], extra_javascript = [], extra_templates = [], markdown_extensions = ['toc', 'tables', 'fenced_code', 'admonition', 'fontawesome_markdown', 'plantuml_markdown', 'codehilite', 'markdown.extensions.admonition', 'markdown.extensions.codehilite', 'markdown.extensions.def_list', 'markdown.extensions.footnotes', 'markdown.extensions.meta', 'markdown.extensions.toc', 'nl2br', 'pymdownx.arithmatex', 'pymdownx.betterem', 'pymdownx.caret', 'pymdownx.critic', 'pymdownx.emoji', 'pymdownx.inlinehilite', 'pymdownx.magiclink', 'pymdownx.mark', 'pymdownx.smartsymbols', 'pymdownx.superfences', 'pymdownx.tasklist', 'pymdownx.tilde'], mdx_configs [dict], strict = False, remote_branch = 'gh-pages', remote_name = 'origin', extra [SubConfig], plugins [PluginCollection], notebook_exporter [HTMLExporter] |
| environment | dict | system = 'Linux', system_version = '5.4.0-1032-azure', python_version = '3.6.12', mkdocs_version = '1.1.2', macros_plugin_version = '0.4.20', jinja2_version = '2.11.2' |
| plugin | Config | module_name = 'main', modules = [], include_dir = '', include_yaml = [], j2_block_start_string = '', j2_block_end_string = '', j2_variable_start_string = '', j2_variable_end_string = '' |
| git | dict | status = True, date [datetime], short_commit = '4e93caf', commit = '4e93cafce95378fda26592b737555a61a014313d', author = 'Vyacheslav', tag = '', date_ISO = '2021-01-22 14:26:30 +0100', message = 'improve(github workflow)\n\nbumped publishing action to 3.7.3', raw = 'commit 4e93cafce95378fda26592b737555a61a014313d\nAuthor: Vyacheslav |
| 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'). |
| feature | dict | tabs = False |
| social | list | [{'type': 'globe', 'link': 'https://www.voronenko.info'}, {'type': 'github-alt', 'link': 'https://github.com/voronenko'}, {'type': 'twitter', 'link': 'https://twitter.com/slavko'}, {'type': 'linkedin', 'link': 'https://www.linkedin.com/in/voronenkovyacheslav/'}] |
| hello | str | 'hello' |
| baz | str | 'buz' |
| 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], 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='Welcome to MkDocs', url='.') Section(title='Architecture') Page(title=[blank], url='architecture/') Section(title='Decisions') Page(title=[blank], url='architecture/decisions/0001-record-architecture-decisions/') Page(title=[blank], url='architecture/decisions/0002-use-sphinx-as-our-knowledge-base-system/') Page(title=[blank], url='architecture/decisions/0003-use-plantuml-for-diagramming/') Page(title=[blank], url='architecture/decisions/0004-use-mkdocs-as-a-knowledge-base-system/') Page(title=[blank], url='architecture/decisions/0005-use-plantuml-for-diagramming-with-use-of-stdlib/') Section(title='Diagrams') Section(title='Plantuml misc') Page(title=[blank], url='diagrams/plantuml-misc/colorized/') Page(title=[blank], url='diagrams/plantuml-misc/colorized2/') Page(title=[blank], url='diagrams/plantuml-misc/colorized3/') Page(title=[blank], url='diagrams/plantuml-misc/colorized4/') Page(title=[blank], url='diagrams/plantuml-misc/colorized5/') Page(title=[blank], url='diagrams/plantuml-misc/colorized6/') Page(title=[blank], url='diagrams/plantuml-misc/colorized7/') Page(title=[blank], url='diagrams/plantuml-misc/colorized8/') Page(title=[blank], url='diagrams/plantuml-misc/colorized9/') Page(title=[blank], url='diagrams/plantuml-misc/risksystem/') Page(title=[blank], url='diagrams/plantuml-misc/risksystem2/') Page(title=[blank], url='diagrams/plantuml-misc/risksystem3/') Page(title=[blank], url='diagrams/plantuml-misc/somesystem/') Page(title=[blank], url='diagrams/plantuml-misc/somesystem10/') Page(title=[blank], url='diagrams/plantuml-misc/somesystem11/') Page(title=[blank], url='diagrams/plantuml-misc/somesystem12/') Page(title=[blank], url='diagrams/plantuml-misc/somesystem14/') Page(title=[blank], url='diagrams/plantuml-misc/somesystem2/') Page(title=[blank], url='diagrams/plantuml-misc/somesystem3/') Page(title=[blank], url='diagrams/plantuml-misc/somesystem4/') Page(title=[blank], url='diagrams/plantuml-misc/somesystem5/') Page(title=[blank], url='diagrams/plantuml-misc/somesystem6/') Page(title=[blank], url='diagrams/plantuml-misc/somesystem7/') Page(title=[blank], url='diagrams/plantuml-misc/somesystem8/') Page(title=[blank], url='diagrams/plantuml-misc/somesystem9/') Page(title=[blank], url='diagrams/plantuml-misc/systemcontext/') Page(title=[blank], url='diagrams/plantuml-misc/webportal/') Page(title=[blank], url='diagrams/plantuml-misc/wetclinic/') Section(title='Elements') Page(title=[blank], url='elements/admonition/') Page(title=[blank], url='elements/codehilite/') Page(title=[blank], url='elements/footnotes/') Page(title=[blank], url='elements/metadata/') Page(title=[blank], url='elements/permalinks/') Page(title=[blank], url='elements/pymdown/') Section(title='Notebooks') Page(title=[blank], url='notebooks/diagrams/') Page(title=[blank], url='notebooks/routing-list/') Section(title='Theory') Page(title=[blank], url='theory/') |
| page | Page | Page(title='Welcome to MkDocs', url='.') |
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/runbooks-mkdocs/runbooks-mkdocs/mkdocs.yml' |
| site_name | str | 'project docs' |
| nav | NoneType | None |
| pages | NoneType | None |
| site_url | str | '' |
| site_description | NoneType | None |
| site_author | NoneType | None |
| theme | Theme | Theme(name='material', dirs=['/home/runner/.local/share/virtualenvs/runbooks-mkdocs-mlBZcEzP/lib/python3.6/site-packages/material', '/home/runner/.local/share/virtualenvs/runbooks-mkdocs-mlBZcEzP/lib/python3.6/site-packages/mkdocs/templates'], static_templates=['sitemap.xml', '404.html'], language='en', direction=None, feature={'tabs': False}, palette={'primary': 'blue-grey', 'accent': 'light-blue'}, font={'text': 'Ubuntu', 'code': 'Ubuntu Mono'}, favicon='assets/images/favicon.png', logo={'icon': '\ue80c'}, include_search_page=False, search_index_only=True) |
| docs_dir | str | '/home/runner/work/runbooks-mkdocs/runbooks-mkdocs/docs' |
| site_dir | str | '/home/runner/work/runbooks-mkdocs/runbooks-mkdocs/public' |
| copyright | NoneType | None |
| google_analytics | NoneType | None |
| dev_addr | Address | Address(host='127.0.0.1', port=8000) |
| use_directory_urls | bool | True |
| repo_url | str | '' |
| repo_name | str | '' |
| edit_uri | str | '' |
| extra_css | list | ['css/ansi-colours.css', 'css/jupyter-cells.css', 'css/pandas-dataframe.css'] |
| extra_javascript | list | [] |
| extra_templates | list | [] |
| markdown_extensions | list | ['toc', 'tables', 'fenced_code', 'admonition', 'fontawesome_markdown', 'plantuml_markdown', 'codehilite', 'markdown.extensions.admonition', 'markdown.extensions.codehilite', 'markdown.extensions.def_list', 'markdown.extensions.footnotes', 'markdown.extensions.meta', 'markdown.extensions.toc', 'nl2br', 'pymdownx.arithmatex', 'pymdownx.betterem', 'pymdownx.caret', 'pymdownx.critic', 'pymdownx.emoji', 'pymdownx.inlinehilite', 'pymdownx.magiclink', 'pymdownx.mark', 'pymdownx.smartsymbols', 'pymdownx.superfences', 'pymdownx.tasklist', 'pymdownx.tilde'] |
| mdx_configs | dict | markdown.extensions.codehilite [dict], markdown.extensions.toc [dict], pymdownx.betterem [dict], pymdownx.emoji [dict], pymdownx.tasklist [dict], toc [dict] |
| strict | bool | False |
| remote_branch | str | 'gh-pages' |
| remote_name | str | 'origin' |
| extra | SubConfig | {'feature': {'tabs': False}, 'social': [{'type': 'globe', 'link': 'https://www.voronenko.info'}, {'type': 'github-alt', 'link': 'https://github.com/voronenko'}, {'type': 'twitter', 'link': 'https://twitter.com/slavko'}, {'type': 'linkedin', 'link': 'https://www.linkedin.com/in/voronenkovyacheslav/'}]} |
| plugins | PluginCollection | build_plantuml [BuildPlantumlPlugin], exclude [Exclude], macros [MacrosPlugin], mknotebooks [Plugin], autolinks [AutoLinksPlugin], redirects [RedirectPlugin], mkdocs-simple-hooks [SimpleHooksPlugin], blog [Blog], table-reader [TableReaderPlugin] |
| notebook_exporter | HTMLExporter |
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(2021, 1, 22, 14, 26, 30, tzinfo=tzoffset(None, 3600)) |
| short_commit | str | '4e93caf' |
| commit | str | '4e93cafce95378fda26592b737555a61a014313d' |
| author | str | 'Vyacheslav' |
| tag | str | '' |
| date_ISO | str | '2021-01-22 14:26:30 +0100' |
| message | str | 'improve(github workflow)\n\nbumped publishing action to 3.7.3' |
| raw | str | 'commit 4e93cafce95378fda26592b737555a61a014313d\nAuthor: Vyacheslav |
| root_dir | str | '/home/runner/work/runbooks-mkdocs/runbooks-mkdocs' |
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_path = 'index.md', abs_src_path = '/home/runner/work/runbooks-mkdocs/runbooks-mkdocs/docs/index.md', name = 'index', dest_path = 'index.html', abs_dest_path = '/home/runner/work/runbooks-mkdocs/runbooks-mkdocs/public/index.html', url = '.' |
| title | str | 'Welcome to MkDocs' |
| parent | NoneType | None |
| children | NoneType | None |
| previous_page | NoneType | None |
| next_page | Page | Page(title=[blank], url='architecture/') |
| _Page__active | bool | False |
| is_section | bool | False |
| is_page | bool | True |
| is_link | bool | False |
| update_date | str | '2021-01-22' |
| 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\n```plantuml format="png" classes="uml myDiagram" alt="My super diagram placeholder" title="My super diagram"\nBob->Alice : hello\n```\n\n```plantuml format="png" classes="uml myDiagram" alt="My super diagram placeholder" title="My super diagram"\nBob<-Alice : hello\n```\n\n{{ macros_info() }}\n' |
| content | NoneType | None |
| toc | list | [] |
| meta | dict |
To have all titles of all pages, use:
{% for page in navigation.pages %}
- {{ page.title }}
{% endfor% }
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. Because python dicts are unsorted you may want to use this function to order them by either key or value. |
| e | builtin_function_or_method | escape(s) -> markup |
| escape | builtin_function_or_method | escape(s) -> markup |
| 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 | (environment, seq) 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 | (environment, value, attribute, expr) Group a sequence of objects by an attribute using Python's :func: |
| indent | function | (s, width, first, blank, indentfirst, 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 | (eval_ctx, value, d, attribute, do_escape, idx, item) 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 | (value) 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. |
| map | function | (args, kwargs, seq, func, item) 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, verbose) Pretty print a variable. Useful for debugging. |
| random | function | (context, seq) Return a random item from the sequence. |
| reject | function | (args, kwargs) Filters a sequence of objects by applying a test to each object, and rejecting the objects with the test succeeding. |
| rejectattr | function | (args, kwargs) 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) 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) 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) 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 | (value, slices, fill_with, seq, length, items_per_slice, slices_with_extra, offset, slice_number, start, end, tmp) 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 | soft_unicode(object) -> string |
| striptags | function | (value) Strip SGML/XML tags and replace adjacent whitespace by one space. |
| sum | function | (environment, iterable, attribute, start) 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, policies, rv) Converts URLs in plain 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, dumper, options) Dumps a structure to JSON so that it's safe to use in |