starred/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2026-05-29 03:22:10 -04:00
Code Issues Packages Projects Releases Wiki Activity

Restructured documentation (#5692)

Browse Source
This commit is contained in:
Martin Donath
2023-09-14 19:09:18 +02:00
committed by GitHub
parent 19437db8fc
commit cd008fdf29
83 changed files with 6877 additions and 3354 deletions
Download Patch File Download Diff File Expand all files Collapse all files

91
docs/setup/extensions/python-markdown.md
View File

@@ -11,8 +11,8 @@ reference for which features they need to be enabled.
### Abbreviations
[:octicons-tag-24: 1.0.0][Abbreviations support] ·
[:octicons-workflow-24: Extension][Abbreviations]
<!-- md:version 1.0.0 -->
<!-- md:extension [abbr][Abbreviations] -->
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
@@ -29,16 +29,15 @@ No configuration options are available. See reference for usage:
- [Adding a glossary]
[Abbreviations]: https://python-markdown.github.io/extensions/abbreviations/
[Abbreviations support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[Adding abbreviations]: ../../reference/tooltips.md#adding-abbreviations
[Adding a glossary]: ../../reference/tooltips.md#adding-a-glossary
### Admonition
[:octicons-tag-24: 0.1.0][Admonition support] ·
[:octicons-workflow-24: Extension][Admonition]
<!-- md:version 0.1.0 -->
<!-- md:extension [admonition][Admonition] -->
The [Admonition] extension adds support for admonitions, more commonly known as
The [Admonition] extension adds support for admonitions, more commonly known as
_call-outs_, which can be defined in Markdown by using a simple syntax. Enable
it via `mkdocs.yml`:
@@ -55,7 +54,6 @@ No configuration options are available. See reference for usage:
- [Supported types]
[Admonition]: https://python-markdown.github.io/extensions/admonition/
[Admonition support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Adding admonitions]: ../../reference/admonitions.md#usage
[Changing the title]: ../../reference/admonitions.md#changing-the-title
[Removing the title]: ../../reference/admonitions.md#removing-the-title
@@ -63,8 +61,8 @@ No configuration options are available. See reference for usage:
### Attribute Lists
[:octicons-tag-24: 0.1.0][Attribute Lists support] ·
[:octicons-workflow-24: Extension][Attribute Lists]
<!-- md:version 0.1.0 -->
<!-- md:extension [attr_list][Attribute Lists] -->
The [Attribute Lists] extension allows to add HTML attributes and CSS classes
to [almost every][Attribute Lists limitations] Markdown inline- and block-level
@@ -87,7 +85,6 @@ No configuration options are available. See reference for usage:
- [Image lazy-loading]
[Attribute Lists]: https://python-markdown.github.io/extensions/attr_list/
[Attribute Lists support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Attribute Lists limitations]: https://python-markdown.github.io/extensions/attr_list/#limitations
[Using grids]: ../../reference/grids.md#using-grids
[Adding buttons]: ../../reference/buttons.md#adding-buttons
@@ -99,8 +96,8 @@ No configuration options are available. See reference for usage:
### Definition Lists
[:octicons-tag-24: 1.1.0][Definition Lists support] ·
[:octicons-workflow-24: Extension][Definition Lists]
<!-- md:version 1.1.0 -->
<!-- md:extension [def_list][Definition Lists] -->
The [Definition Lists] extension adds the ability to add definition lists (more
commonly known as [description lists] – `dl` in HTML) via Markdown to a
@@ -116,14 +113,13 @@ No configuration options are available. See reference for usage:
- [Using definition lists]
[Definition Lists]: https://python-markdown.github.io/extensions/definition_lists/
[Definition Lists support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0
[description lists]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl
[Using definition lists]: ../../reference/lists.md#using-definition-lists
### Footnotes
[:octicons-tag-24: 1.0.0][Footnotes support] ·
[:octicons-workflow-24: Extension][Footnotes]
<!-- md:version 1.0.0 -->
<!-- md:extension [footnotes][Footnotes] -->
The [Footnotes] extension allows to define inline footnotes, which are then
rendered below all Markdown content of a document. Enable it via `mkdocs.yml`:
@@ -139,14 +135,13 @@ No configuration options are supported. See reference for usage:
- [Adding footnote content]
[Footnotes]: https://python-markdown.github.io/extensions/footnotes/
[Footnotes support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
[Adding footnote references]: ../../reference/footnotes.md#adding-footnote-references
[Adding footnote content]: ../../reference/footnotes.md#adding-footnote-content
### Markdown in HTML
[:octicons-tag-24: 0.1.0][Markdown in HTML support] ·
[:octicons-workflow-24: Extension][Markdown in HTML]
<!-- md:version 0.1.0 -->
<!-- md:extension [md_in_html][Markdown in HTML] -->
The [Markdown in HTML] extension allows for writing Markdown inside of HTML,
which is useful for wrapping Markdown content with custom elements. Enable it
@@ -170,18 +165,17 @@ No configuration options are available. See reference for usage:
- [Image captions]
[Markdown in HTML]: https://python-markdown.github.io/extensions/md_in_html/
[Markdown in HTML support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Using annotations]: ../../reference/annotations.md#usage
[Using grids]: ../../reference/grids.md#usage
[Image captions]: ../../reference/images.md#image-captions
### Table of Contents
[:octicons-tag-24: 0.1.0][Table of Contents support] ·
[:octicons-workflow-24: Extension][Table of Contents]
<!-- md:version 0.1.0 -->
<!-- md:extension [toc][Table of Contents] -->
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
from a document, which Material for MkDocs will render as part of the resulting
page. Enable it via `mkdocs.yml`:
``` yaml
@@ -192,13 +186,12 @@ markdown_extensions:
The following configuration options are supported:
[`title`](#+toc.title){ #+toc.title }
<!-- md:option toc.title -->
: [:octicons-tag-24: 7.3.5][title support] ·
:octicons-milestone-24: Default: _automatically set_ – This option sets the
title of the table of contents in the right navigation sidebar, which is
normally automatically sourced from the translations for the [site language]
as set in `mkdocs.yml`:
: <!-- md:version 7.3.5 --> <!-- md:default computed --> –
This option sets the title of the table of contents in the right navigation
sidebar, which is normally automatically sourced from the translations for
the [site language] as set in `mkdocs.yml`:
``` yaml
markdown_extensions:
@@ -206,9 +199,9 @@ The following configuration options are supported:
title: On this page
```
[`permalink`](#+toc.permalink){ #+toc.permalink }
<!-- md:option toc.permalink -->
: :octicons-milestone-24: Default: `false` – This option adds an anchor link
: <!-- md:default `false` --> This option adds an anchor link
containing the paragraph symbol `` or another custom symbol at the end of
each headline, exactly like on the page you're currently viewing, which
Material for MkDocs will make appear on hover:
@@ -229,11 +222,11 @@ The following configuration options are supported:
permalink: ⚓︎
```
[`permalink_title`](#+toc.permalink_title){ #+toc.permalink_title }
<!-- md:option toc.permalink_title -->
: :octicons-milestone-24: Default: `Permanent link` – This option sets the
: <!-- md:default `Permanent link` --> This option sets the
title of the anchor link which is shown on hover and read by screen readers.
For accessibility reasons, it might be beneficial to change it to a more
For accessibility reasons, it might be beneficial to change it to a more
discernable name, stating that the anchor links to the section itself:
``` yaml
@@ -242,9 +235,9 @@ The following configuration options are supported:
permalink_title: Anchor link to this section for reference
```
[`slugify`](#+toc.slugify){ #+toc.slugify }
<!-- md:option toc.slugify -->
: :octicons-milestone-24: Default: `headerid.slugify` – This option allows for
: <!-- md:default `toc.slugify` --> This option allows for
customization of the slug function. For some languages, the default may not
produce good and readable identifiers – consider using another slug function
like for example those from [Python Markdown Extensions][Slugs]:
@@ -267,9 +260,9 @@ The following configuration options are supported:
slugify: !!python/object/apply:pymdownx.slugs.slugify
```
[`toc_depth`](#+toc.toc_depth){ #+toc.toc_depth }
<!-- md:option toc.toc_depth -->
: :octicons-milestone-24: Default: `6` – Define the range of levels to be
: <!-- md:default `6` --> Define the range of levels to be
included in the table of contents. This may be useful for project
documentation with deeply structured headings to decrease the length of the
table of contents, or to remove the table of contents altogether:
@@ -295,17 +288,15 @@ by Material for MkDocs, which is why they may yield unexpected results. Use
them at your own risk.
[Table of Contents]: https://python-markdown.github.io/extensions/toc/
[Table of Contents support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[title support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.5
[site language]: ../changing-the-language.md#site-language
[Slugs]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
### Tables
[:octicons-tag-24: 0.1.0][Tables support] ·
[:octicons-workflow-24: Extension][Tables]
<!-- md:version 0.1.0 -->
<!-- md:extension [tables][Tables] -->
The [Tables] extension adds the ability to create tables in Markdown by using a
The [Tables] extension adds the ability to create tables in Markdown by using a
simple syntax. Enable it via `mkdocs.yml` (albeit it should be enabled by
default):
@@ -320,36 +311,34 @@ No configuration options are available. See reference for usage:
- [Column alignment]
[Tables]: https://python-markdown.github.io/extensions/tables/
[Tables support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[Using data tables]: ../../reference/data-tables.md#usage
[Column alignment]: ../../reference/data-tables.md#column-alignment
## Superseded extensions
The following [Python Markdown] extensions are not (or might not be) supported
The following [Python Markdown] extensions are not (or might not be) supported
anymore, and are therefore not recommended for use. Instead, the alternatives
should be considered.
### Fenced Code Blocks
[:octicons-tag-24: 0.1.0][Fenced Code Blocks support] ·
[:octicons-workflow-24: Extension][Fenced Code Blocks]
<!-- md:version 0.1.0 -->
<!-- md:extension [fenced_code_blocks][Fenced Code Blocks] -->
Superseded by [SuperFences]. This extension might still work, but the
[SuperFences] extension is superior in many ways, as it allows for arbitrary
[SuperFences] extension is superior in many ways, as it allows for arbitrary
nesting, and is therefore recommended.
[Fenced Code Blocks]: https://python-markdown.github.io/extensions/fenced_code_blocks/
[Fenced Code Blocks support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
[SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
### CodeHilite
[:octicons-tag-24: 0.1.0 ... 5.5.14][CodeHilite support] ·
[:octicons-workflow-24: Extension][CodeHilite]
<!-- md:version 0.1.0 -->
<!-- md:extension [codehilite][CodeHilite] -->
Superseded by [Highlight]. Support for CodeHilite was dropped in
:octicons-tag-24: 6.0.0, as [Highlight] has a better integration with other
<!-- md:version 6.0.0 -->, as [Highlight] has a better integration with other
essential extensions like [SuperFences] and [InlineHilite].
[CodeHilite]: https://python-markdown.github.io/extensions/code_hilite/