mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-06-14 11:52:32 +03:00
Added documentation for Python Markdown
This commit is contained in:
squidfunk
parent
149b0dbc47
commit
30943cc629
6
docs/setup/extensions/index.md
Normal file
6
docs/setup/extensions/index.md
Normal file
@ -0,0 +1,6 @@
|
||||
---
|
||||
template: overrides/main.html
|
||||
title: Extensions
|
||||
---
|
||||
|
||||
Add minimal example.
|
||||
36
docs/setup/extensions/python-markdown-extensions.md
Normal file
36
docs/setup/extensions/python-markdown-extensions.md
Normal file
@ -0,0 +1,36 @@
|
||||
---
|
||||
template: overrides/main.html
|
||||
---
|
||||
|
||||
# Python Markdown Extensions
|
||||
|
||||
## Supported extensions
|
||||
|
||||
### Arithmatex
|
||||
|
||||
### Critic
|
||||
|
||||
### Details
|
||||
|
||||
### Emoji
|
||||
|
||||
### Highlight
|
||||
|
||||
### InlineHilite
|
||||
|
||||
### Snippets
|
||||
|
||||
### SuperFences
|
||||
|
||||
### Tabbed
|
||||
|
||||
### Tasklist
|
||||
|
||||
### Other
|
||||
|
||||
- Caret
|
||||
- Keys
|
||||
- MagicLink
|
||||
- Mark
|
||||
- SmartSymbols
|
||||
- Tilde
|
||||
350
docs/setup/extensions/python-markdown.md
Normal file
350
docs/setup/extensions/python-markdown.md
Normal file
@ -0,0 +1,350 @@
|
||||
---
|
||||
template: overrides/main.html
|
||||
---
|
||||
|
||||
# Python Markdown
|
||||
|
||||
Material for MkDocs supports a large number of [Python Markdown] extensions,
|
||||
which is part of what makes it so attractive for technical writing. Following
|
||||
is a list of all supported extensions, linking to the relevant sections of the
|
||||
[reference] for what features they need to be enabled.
|
||||
|
||||
[Python Markdown]: https://python-markdown.github.io/
|
||||
[reference]: ../../reference/abbreviations.md
|
||||
|
||||
## Supported extensions
|
||||
|
||||
The following [Python Markdown] extensions are supported by Material for
|
||||
MkDocs, and are therefore strongly recommended. See the [Extensions] page for
|
||||
a minimal configuration.
|
||||
|
||||
[Extensions]: index.md
|
||||
|
||||
### Abbreviations
|
||||
|
||||
[:octicons-workflow-24: Extension][Abbreviations] ·
|
||||
[:octicons-tag-24: 1.0.0 – present][Abbreviations added]
|
||||
|
||||
The [Abbreviations] extension adds the ability to add a small tooltip to an
|
||||
element, by wrapping it with an `abbr` tag. Note that only plain text is
|
||||
supported. Enable it via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- abbr
|
||||
```
|
||||
|
||||
No configuration options are available. See reference for usage:
|
||||
|
||||
- [Adding abbreviations]
|
||||
- [Adding a glossary]
|
||||
|
||||
[Abbreviations]: https://python-markdown.github.io/extensions/abbreviations/
|
||||
[Abbreviations added]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
|
||||
[Adding abbreviations]: ../../reference/abbreviations.md#adding-abbreviations
|
||||
[Adding a glossary]: ../../reference/abbreviations.md#adding-a-glossary
|
||||
|
||||
### Admonition
|
||||
|
||||
[:octicons-workflow-24: Extension][Admonition] ·
|
||||
[:octicons-tag-24: 0.1.0 – present][Admonition added]
|
||||
|
||||
The [Admonition] extension adds support for admonitions, more commonly known as
|
||||
_call-outs_, which can be added to Markdown by using a simple syntax. Enable it
|
||||
via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- admonition
|
||||
```
|
||||
|
||||
No configuration options are available. See reference for usage:
|
||||
|
||||
- [Changing the title]
|
||||
- [Removing the title]
|
||||
- [Supported types]
|
||||
|
||||
[Admonition]: https://python-markdown.github.io/extensions/admonition/
|
||||
[Admonition added]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
|
||||
[Changing the title]: ../../reference/admonitions.md#changing-the-title
|
||||
[Removing the title]: ../../reference/admonitions.md#removing-the-title
|
||||
[Supported types]: ../../reference/admonitions.md#supported-types
|
||||
|
||||
### Attribute Lists
|
||||
|
||||
[:octicons-workflow-24: Extension][Attribute Lists] ·
|
||||
[:octicons-tag-24: 0.1.0 – present][Attribute Lists added]
|
||||
|
||||
The [Attribute Lists] extension allows to add HTML attributes and CSS classes
|
||||
to [almost every][Attribute Lists limitations] Markdown inline- and block-level
|
||||
element with a special syntax. Enable it via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- attr_list
|
||||
```
|
||||
|
||||
No configuration options are available. See reference for usage:
|
||||
|
||||
- [Adding buttons]
|
||||
- [Adding icons with colors]
|
||||
- [Image alignment]
|
||||
- [Image lazy-loading]
|
||||
|
||||
[Attribute Lists]: https://python-markdown.github.io/extensions/attr_list/
|
||||
[Attribute Lists added]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
|
||||
[Attribute Lists limitations]: https://python-markdown.github.io/extensions/attr_list/#limitations
|
||||
[Adding buttons]: ../../reference/buttons.md#adding-buttons
|
||||
[Adding icons with colors]: ../../reference/buttons.md#with-colors
|
||||
[Image alignment]: ../../reference/images.md#image-alignment
|
||||
[Image lazy-loading]: ../../reference/images.md#image-lazy-loading
|
||||
|
||||
### Definition Lists
|
||||
|
||||
[:octicons-workflow-24: Extension][Definition Lists] ·
|
||||
[:octicons-tag-24: 1.1.0 – present][Definition Lists added]
|
||||
|
||||
The [Definition Lists] extension adds the ability to add definition lists (more
|
||||
commonly known as [description lists] `dl` in HTML) to any Markdown document.
|
||||
Enable it via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- def_list
|
||||
```
|
||||
|
||||
No configuration options are available. See reference for usage:
|
||||
|
||||
- [Using definition lists]
|
||||
|
||||
[Definition Lists]: https://python-markdown.github.io/extensions/definition_lists/
|
||||
[Definition Lists added]: 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-workflow-24: Extension][Footnotes] ·
|
||||
[:octicons-tag-24: 1.0.0 – present][Footnotes added]
|
||||
|
||||
The [Footnotes] extension allows to define footnotes inline with the content,
|
||||
which are then rendered after the content of the Markdown document. Enable it
|
||||
via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- footnotes
|
||||
```
|
||||
|
||||
No configuration options are supported. See reference for usage:
|
||||
|
||||
- [Adding footnote references]
|
||||
- [Adding footnote content]
|
||||
|
||||
[Footnotes]: https://python-markdown.github.io/extensions/footnotes/
|
||||
[Footnotes added]: 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
|
||||
|
||||
### Metadata
|
||||
|
||||
[:octicons-workflow-24: Extension][Metadata] ·
|
||||
[:octicons-tag-24: 1.0.0 – present][Metadata added]
|
||||
|
||||
The [Metadata] extension adds the ability to attach arbitrary key-value pairs
|
||||
to a Markdown document via front matter written in YAML syntax. It can be
|
||||
enabled via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- meta
|
||||
```
|
||||
|
||||
No configuration options are available. See reference for usage:
|
||||
|
||||
- [Setting the page title]
|
||||
- [Setting the page description]
|
||||
- [Hiding the sidebars]
|
||||
- [Adding tags]
|
||||
|
||||
[Metadata]: https://python-markdown.github.io/extensions/meta_data/
|
||||
[Metadata added]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
|
||||
[Setting the page title]: ../../reference/meta-tags.md#setting-the-page-title
|
||||
[Setting the page description]: ../../reference/meta-tags.md#setting-the-page-description
|
||||
[Hiding the sidebars]: ../../setup/setting-up-navigation.md#hiding-the-sidebars
|
||||
[Adding tags]: ../../setup/setting-up-tags.md#adding-tags
|
||||
|
||||
### Markdown in HTML
|
||||
|
||||
[:octicons-workflow-24: Extension][Markdown in HTML] ·
|
||||
[:octicons-tag-24: 0.1.0 – present][Markdown in HTML added]
|
||||
|
||||
The [Markdown in HTML] extension allows the author to write Markdown inside of
|
||||
HTML, which is useful for wrapping Markdown with custom markup. Enable it via
|
||||
`mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- md_in_html
|
||||
```
|
||||
|
||||
> By default, Markdown ignores any content within a raw HTML block-level
|
||||
> element. With the `md_in_html` extension enabled, the content of a raw HTML
|
||||
> block-level element can be parsed as Markdown by including a markdown
|
||||
> attribute on the opening tag. The markdown attribute will be stripped from
|
||||
> the output, while all other attributes will be preserved.
|
||||
|
||||
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 added]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
|
||||
[Image captions]: ../../reference/images.md#image-captions
|
||||
|
||||
### Table of Contents
|
||||
|
||||
[:octicons-workflow-24: Extension][Table of Contents] ·
|
||||
[:octicons-tag-24: 0.1.0 – present][Table of Contents added]
|
||||
|
||||
The [Table of Contents] extension generates a table of contents from a Markdown
|
||||
document, which Material for MkDocs will render as part of the resulting page.
|
||||
Enable it via `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- toc:
|
||||
permalink: true
|
||||
```
|
||||
|
||||
The following configuration options are supported:
|
||||
|
||||
`permalink`{ #permalink }
|
||||
|
||||
: :octicons-milestone-24: 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:
|
||||
|
||||
=== "¶"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- toc:
|
||||
permalink: true
|
||||
```
|
||||
|
||||
=== "⚓︎"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- toc:
|
||||
permalink: ⚓︎
|
||||
```
|
||||
|
||||
`slugify`{ #slugify }
|
||||
|
||||
: :octicons-milestone-24: Default: `headerid.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][Pymdownx Slug]:
|
||||
|
||||
=== "Unicode"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- toc:
|
||||
slugify: !!python/name:pymdownx.slugs.uslugify
|
||||
```
|
||||
|
||||
=== "Unicode, case-sensitive"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- toc:
|
||||
slugify: !!python/name:pymdownx.slugs.uslugify_cased
|
||||
```
|
||||
|
||||
`toc_depth`{ #toc_depth }
|
||||
|
||||
: :octicons-milestone-24: 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:
|
||||
|
||||
=== "Hide levels 4-6"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- toc:
|
||||
toc_depth: 3
|
||||
```
|
||||
|
||||
=== "Hide table of contents"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- toc:
|
||||
toc_depth: 0
|
||||
```
|
||||
|
||||
[Table of Contents]: https://python-markdown.github.io/extensions/toc/
|
||||
[Table of Contents added]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
|
||||
[Pymdownx Slug]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
|
||||
|
||||
### Tables
|
||||
|
||||
[:octicons-workflow-24: Extension][Tables] ·
|
||||
[:octicons-tag-24: 0.1.0 – present][Tables added]
|
||||
|
||||
The [Tables] extension adds the ability to create tables in Markdown documents
|
||||
by using a simple syntax. Enabled it via `mkdocs.yml` (albeit it should be
|
||||
enabled by default):
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- tables
|
||||
```
|
||||
|
||||
No configuration options are available. See reference for usage:
|
||||
|
||||
- [Using data tables]
|
||||
- [Column alignment]
|
||||
|
||||
[Tables]: https://python-markdown.github.io/extensions/tables/
|
||||
[Tables added]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
|
||||
[Using data tables]: ../../reference/data-tables.md#using-data-tables
|
||||
[Column alignment]: ../../reference/data-tables.md#column-alignment
|
||||
|
||||
## Superseded extensions
|
||||
|
||||
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-workflow-24: Extension][Fenced Code Blocks] ·
|
||||
[:octicons-tag-24: 0.1.0 – present][Fenced Code Blocks added]
|
||||
|
||||
Superseded by [SuperFences]. This extension might still work, but the
|
||||
[SuperFences] extension is superior in many ways, as it allows for arbitrary
|
||||
nesting, and therefore strongly recommended.
|
||||
|
||||
[Fenced Code Blocks]: https://python-markdown.github.io/extensions/fenced_code_blocks/
|
||||
[Fenced Code Blocks added]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
|
||||
[SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
|
||||
|
||||
### CodeHilite
|
||||
|
||||
[:octicons-workflow-24: Extension][CodeHilite] ·
|
||||
[:octicons-tag-24: 0.1.0 – 5.5.14][CodeHilite added]
|
||||
|
||||
Superseded by [Highlight]. Support for CodeHilite was dropped in version 6.0.0,
|
||||
as [Highlight] has a better integration with other great extensions like
|
||||
[SuperFences] and [InlineHilite].
|
||||
|
||||
[CodeHilite]: https://python-markdown.github.io/extensions/code_hilite/
|
||||
[CodeHilite added]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
|
||||
[Highlight]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
|
||||
[InlineHilite]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
|
||||
@ -196,6 +196,10 @@ nav:
|
||||
- Setting up the footer: setup/setting-up-the-footer.md
|
||||
- Adding a git repository: setup/adding-a-git-repository.md
|
||||
- Adding a comment system: setup/adding-a-comment-system.md
|
||||
- Extensions:
|
||||
- setup/extensions/index.md
|
||||
- Python Markdown: setup/extensions/python-markdown.md
|
||||
- Python Markdown Extensions: setup/extensions/python-markdown-extensions.md
|
||||
- Reference:
|
||||
- Abbreviations: reference/abbreviations.md
|
||||
- Admonitions: reference/admonitions.md
|
||||
|
||||
Loading…
Reference in New Issue
Block a user