Documentation Resources

External Resources

Our documentation is built on Material for MkDocs. Both Material and MkDocs provide extensive documentation of their own:

• Material Documentation
• MkDocs Documentation

MkDocs utilizes Markdown, a simple text formatting language. Many resources exist online to teach the basics of Markdown, there's even an interactive Markdown tutorial that can be completed in about 10 minutes.

Markdown tables can be a bit of hassle to create manually, but a handy tool is available to help: Tables Generator.

Enabled Features

Material provides a wide range of built-in features that we can enable or disable as needed. Below is a list of the currently enabled features and accompanying information.

Feature	Use
content.action.edit and content.action.view	Adds edit and view code action buttons
content.tooltips	When improved tooltips are enabled, Material for MkDocs replaces the browser's rendering logic for title attribute with beautiful little tooltips.
content.code.copy	Code blocks can automatically render a button on the right side to allow the user to copy a code block's contents to the clipboard.
content.code.annotate	Code annotations offer a comfortable and friendly way to attach arbitrary content to specific sections of code blocks by adding numeric markers in block and inline comments in the language of the code block.
navigation.top	A back-to-top button can be shown when the user, after scrolling down, starts to scroll up again. It's rendered centered and just below the header.
navigation.indexes	When section index pages are enabled, documents can be directly attached to sections, which is particularly useful for providing overview pages.
navigation.tabs	When tabs are enabled, top-level sections are rendered in a menu layer below the header for viewports above 1220px, but remain as-is on mobile.

Enabled Extensions

Material provides a wide range of helpful Markdown extensions that provide further functionality to our documentation. Below is a list of the currently enabled extensions and accompanying information.

Extension	Use	Extra Information
abbr	The Abbreviations extension adds the ability to add a small tooltip to an element, by wrapping it with an abbr tag. Only plain text (no markup) is supported.
pymdownx.snippets	The Snippets extension adds the ability to embed content from arbitrary files into a document, including other documents or source files, by using a simple syntax.	The snippets extension also allows us to utilize the glossary function of the abbr extension. Adding an abbreviation to docs-resources/includes/abbreviations.md will make it global.
admonition	Admonitions, also known as call-outs, are an excellent choice for including side content without significantly interrupting the document flow.
pymdownx.details	The Details extension supercharges the Admonition extension, making the resulting call-outs collapsible, allowing them to be opened and closed by the user.
pymdownx.superfences	The SuperFences extension allows for arbitrary nesting of code and content blocks inside each other, including admonitions, tabs, lists and all other elements.	We do not utilize the custom_fences option.
pymdownx.tilde	Tilde optionally adds two different features which are syntactically built around the ~ character: delete which inserts	Tilde optionally adds two different features which are syntactically built around the ~ character: delete which inserts <del></del> tags and subscript which inserts <sub></sub> tags.
pymdownx.highlight	The Highlight extension adds support for syntax highlighting of code blocks (with the help of SuperFences) and inline code blocks (with the help of InlineHilite).	* anchor-linenums enabled * line-spans enabled * pygments_lang_class enabled
pymdownx.inlinehilite	The InlineHilite extension add support for syntax highlighting of inline code blocks. It's built on top of the Highlight extension, from which it sources its configuration.
pymdownx.tabbed	The Tabbed extension allows the usage of content tabs, a simple way to group related content and code blocks under accessible tabs.	* alternate_style enabled
attr_list	The Attribute Lists extension allows to add HTML attributes and CSS classes to almost every Markdown inline- and block-level element with a special syntax.
pymdownx.emoji	This configuration enables the use of icons and emojis by using simple shortcodes which can be discovered through the icon search.	Custom icons stored in docs-resources/.icons
md_in_html	The Markdown in HTML extension allows for writing Markdown inside of HTML, which is useful for wrapping Markdown content with custom elements.
toc	The Table of Contents extension automatically generates a table of contents from a document, which Material for MkDocs will render as part of the resulting page
tasklist	The Tasklist extension allows for the usage of GitHub Flavored Markdown inspired task lists, following the same syntactical conventions

Custom ClanGen Assets

We currently have custom icons set up, which can be utilized across the entire documentation. Below is a table displaying all current icons.

Icon	Markdown
	:clangen-arrow-left:
	:clangen-arrow-left-double:
	:clangen-arrow-right:
	:clangen-cat-head:
	:clangen-clan-blank:
	:clangen-clan-question:
	:clangen-clan-strike:
	:clangen-dice:
	:clangen-droplet:
	:clangen-herb:
	:clangen-leaf:
	:clangen-log:
	:clangen-magnify:
	:clangen-mouse:
	:clangen-paw:
	:clangen-scratches:
	:clangen-snowflake:
	:clangen-sprout:
	:clangen-starclan:
	:clangen-sun: