Cool_Tools/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-11-24 07:30:12 +01:00
Code Issues Releases Wiki Activity

Integrated with mkdocs-material-extensions

Browse Source
This commit is contained in:
squidfunk 2020-04-12 19:58:22 +02:00
parent 7da5010d69
commit f90644dac5
10 changed files with 114 additions and 67 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

77
docs/extensions/pymdown.md
View File

@ -24,8 +24,8 @@ markdown_extensions:
- pymdownx.critic - pymdownx.critic
- pymdownx.details - pymdownx.details
- pymdownx.emoji: - pymdownx.emoji:
emoji_index: !!python/name:pymdownx.emoji.twemoji emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:pymdownx.emoji.to_svg emoji_generator: !!python/name:materialx.emoji.to_svg
- pymdownx.inlinehilite - pymdownx.inlinehilite
- pymdownx.magiclink - pymdownx.magiclink
- pymdownx.mark - pymdownx.mark
@ -208,61 +208,94 @@ index.
from either provider, please read their licenses to ensure proper from either provider, please read their licenses to ensure proper
attribution: [EmojiOne][17] or [Twemoji][14]. attribution: [EmojiOne][17] or [Twemoji][14].
### Icons :hatching_chick:
In addition, you can embed the Material Design icons, Fontawesome icons and
GitHub's Octicons directly from Markdown by using [Material for MkDocs's custom
emoji index][19]. It extends the Twemoji index with new short names that access
any of the included icons. To use the custom index, you need to use
`materialx.emoji` instead of `pymdownx.emoji`:
``` yaml
markdown_extensions:
- pymdownx.emoji:
emoji_index: !!python/name:materialx.emoji.material
emoji_generator: !!python/name:materialx.emoji.to_svg
```
Example:
``` markdown
* :material-account-circle: – we can use Material Design icons
* :fontawesome-regular-laugh-wink: – we can also use FontAwesome icons
* :octicons-octoface: – that's not all, we can also use GitHub's Octicons
```
Result:
* :material-account-circle: – we can use [Material Design icons][20]
* :fontawesome-regular-laugh-wink: – we can also use [FontAwesome icons][21]
* :octicons-octoface: – that's not all, we can also use [GitHub's Octicons][22]
[13]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/ [13]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
[14]: https://twemoji.twitter.com/ [14]: https://twemoji.twitter.com/
[15]: https://www.joypixels.com/ [15]: https://www.joypixels.com/
[16]: https://creativecommons.org/licenses/by/4.0/legalcode [16]: https://creativecommons.org/licenses/by/4.0/legalcode
[17]: https://github.com/joypixels/emojione#emojione-version-2 [17]: https://github.com/joypixels/emojione#emojione-version-2
[18]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#default-emoji-indexes [18]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#default-emoji-indexes
[19]: https://github.com/facelessuser/mkdocs-material-extensions
[20]: https://material.io/resources/icons/
[21]: https://fontawesome.com/icons?d=gallery&m=free
[22]: https://octicons.github.com/
### InlineHilite ### InlineHilite
[InlineHilite][19] adds support for inline code highlighting. It's useful for [InlineHilite][23] adds support for inline code highlighting. It's useful for
short snippets included within body copy, e.g. `#!js var test = 0;` and can be short snippets included within body copy, e.g. `#!js var test = 0;` and can be
activated by prefixing inline code with a shebang and language identifier, activated by prefixing inline code with a shebang and language identifier,
e.g. `#!js`. e.g. `#!js`.
[19]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/ [23]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
### MagicLink ### MagicLink
[MagicLink][20] detects links in Markdown and auto-generates the necessary [MagicLink][24] detects links in Markdown and auto-generates the necessary
markup, so no special syntax is required. It auto-links `http[s]://` and markup, so no special syntax is required. It auto-links `http[s]://` and
`ftp://` links, as well as references to email addresses. `ftp://` links, as well as references to email addresses.
[20]: https://facelessuser.github.io/pymdown-extensions/extensions/magiclink/ [24]: https://facelessuser.github.io/pymdown-extensions/extensions/magiclink/
### Mark ### Mark
[Mark][21] adds the ability to ==highlight text== like it was marked with a [Mark][25] adds the ability to ==highlight text== like it was marked with a
==text marker==. The portion of text that should be highlighted must be ==text marker==. The portion of text that should be highlighted must be
enclosed in two equal signs `==...==`. enclosed in two equal signs `==...==`.
[21]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/ [25]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
### SmartSymbols ### SmartSymbols
[SmartSymbols][22] converts markup for special characters into their [SmartSymbols][26] converts markup for special characters into their
corresponding symbols, e.g. arrows (<--, -->, <-->), trademark and copyright corresponding symbols, e.g. arrows (<--, -->, <-->), trademark and copyright
symbols ((c), (tm), (r)) and fractions (1/2, 1/4, ...). symbols ((c), (tm), (r)) and fractions (1/2, 1/4, ...).
[22]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/ [26]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
### SuperFences ### SuperFences
[SuperFences][23] provides the ability to nest code blocks under blockquotes, [SuperFences][27] provides the ability to nest code blocks under blockquotes,
lists and other block elements, which the [Fenced Code Blocks][24] extension lists and other block elements, which the [Fenced Code Blocks][28] extension
from the standard Markdown library doesn't parse correctly. from the standard Markdown library doesn't parse correctly.
SuperFences does also allow [grouping code blocks with tabs][25]. SuperFences does also allow [grouping code blocks with tabs][29].
[23]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/ [27]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
[24]: https://python-markdown.github.io/extensions/fenced_code_blocks/ [28]: https://python-markdown.github.io/extensions/fenced_code_blocks/
[25]: codehilite.md#grouping-code-blocks [29]: codehilite.md#grouping-code-blocks
### Tabbed ### Tabbed
[Tabbed][26] adds support for creating tabbed groups of Markdown content. [Tabbed][30] adds support for creating tabbed groups of Markdown content.
Example: Example:
@ -294,11 +327,11 @@ Result:
:banana: Banana | Yellow :banana: Banana | Yellow
:kiwi: Kiwi | Green :kiwi: Kiwi | Green
[26]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/ [30]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
### Tasklist ### Tasklist
[Tasklist][27] adds support for styled checkbox lists. This is useful for [Tasklist][31] adds support for styled checkbox lists. This is useful for
keeping track of tasks and showing what has been done and has yet to be done. keeping track of tasks and showing what has been done and has yet to be done.
Checkbox lists are like regular lists, but prefixed with `[ ]` for empty or Checkbox lists are like regular lists, but prefixed with `[ ]` for empty or
`[x]` for filled checkboxes. `[x]` for filled checkboxes.
@ -331,12 +364,12 @@ Result:
* [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque * [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
* [ ] Nulla vel eros venenatis, imperdiet enim id, faucibus nisi * [ ] Nulla vel eros venenatis, imperdiet enim id, faucibus nisi
[27]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/ [31]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/
### Tilde ### Tilde
[Tilde][28] provides an easy way to ~~strike through~~ cross out text. [Tilde][32] provides an easy way to ~~strike through~~ cross out text.
The portion of text that should be erased must be enclosed in two tildes The portion of text that should be erased must be enclosed in two tildes
`~~...~~` and the extension will take care of the rest. `~~...~~` and the extension will take care of the rest.
[28]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/ [32]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/

70
docs/getting-started.md
View File

@ -532,12 +532,16 @@ made. Icon sets which are bundled with Material for MkDocs:
* [Material Design icons][16]: 3.8k icons * [Material Design icons][16]: 3.8k icons
* [FontAwesome icons][17]: 1.5k icons * [FontAwesome icons][17]: 1.5k icons
* [GitHub octicons][18]: 200 icons * [GitHub's Octicons][18]: 200 icons
__You can also use icons [directly from :fontawesome-brands-markdown:
Markdown][19]!__
[15]: #adding-social-links [15]: #adding-social-links
[16]: https://material.io/resources/icons/ [16]: https://material.io/resources/icons/
[17]: https://fontawesome.com/icons?d=gallery&m=free [17]: https://fontawesome.com/icons?d=gallery&m=free
[18]: https://octicons.github.com/ [18]: https://octicons.github.com/
[19]: extensions/pymdown.md#icons
### Logo ### Logo
@ -589,16 +593,16 @@ Note that the repository icon can be explicitly set through `theme.icon.repo`.
If the `repo_url` is set to a GitHub or BitBucket repository, and the If the `repo_url` is set to a GitHub or BitBucket repository, and the
`repo_name` is set to *GitHub* or *BitBucket* (implied by default), an `repo_name` is set to *GitHub* or *BitBucket* (implied by default), an
edit button will appear at the top of every article. This is the automatic edit button will appear at the top of every article. This is the automatic
behavior that MkDocs implements. See the [MkDocs documentation][19] on more behavior that MkDocs implements. See the [MkDocs documentation][20] on more
guidance regarding the `edit_uri` attribute, which defines whether the edit guidance regarding the `edit_uri` attribute, which defines whether the edit
button is shown or not. button is shown or not.
[19]: https://www.mkdocs.org/user-guide/configuration/#edit_uri [20]: https://www.mkdocs.org/user-guide/configuration/#edit_uri
### Adding social links ### Adding social links
Social accounts can be linked in the footer of the documentation using the Social accounts can be linked in the footer of the documentation using the
[icons][20] which are bundled with the theme. Note that each `icon` must point [icons][21] which are bundled with the theme. Note that each `icon` must point
to a valid path (without the trailing `.svg`) relative to the `.icons` folder to a valid path (without the trailing `.svg`) relative to the `.icons` folder
which comes with the theme: which comes with the theme:
@ -613,11 +617,11 @@ extra:
link: https://linkedin.com/in/squidfunk link: https://linkedin.com/in/squidfunk
``` ```
[20]: #icons [21]: #icons
### Adding a Web App Manifest ### Adding a Web App Manifest
A [Web App Manifest][21] is a simple JSON file that tells the browser about your A [Web App Manifest][22] is a simple JSON file that tells the browser about your
web application and how it should behave when installed on the user's mobile web application and how it should behave when installed on the user's mobile
device or desktop. You can specify such a manifest in `mkdocs.yml`: device or desktop. You can specify such a manifest in `mkdocs.yml`:
@ -626,7 +630,7 @@ extra:
manifest: manifest.webmanifest manifest: manifest.webmanifest
``` ```
[21]: https://developers.google.com/web/fundamentals/web-app-manifest/ [22]: https://developers.google.com/web/fundamentals/web-app-manifest/
## Integrations ## Integrations
@ -654,7 +658,7 @@ search tracking:
### Disqus ### Disqus
Material for MkDocs is integrated with [Disqus][22], so if you want to add a Material for MkDocs is integrated with [Disqus][23], so if you want to add a
comments section to your documentation set the *shortname* of your Disqus comments section to your documentation set the *shortname* of your Disqus
project in `mkdocs.yml`: project in `mkdocs.yml`:
@ -671,10 +675,10 @@ necessary JavaScript is automatically included.
Note that `site_url` must be set in `mkdocs.yml` for the Disqus integration Note that `site_url` must be set in `mkdocs.yml` for the Disqus integration
to load properly. to load properly.
Disqus can also be enabled or disabled for specific pages using [Metadata][23]. Disqus can also be enabled or disabled for specific pages using [Metadata][24].
[22]: https://disqus.com [23]: https://disqus.com
[23]: extensions/metadata.md#disqus [24]: extensions/metadata.md#disqus
## Extensions ## Extensions
@ -694,19 +698,19 @@ markdown_extensions:
See the following list of extensions supported by Material for MkDocs including See the following list of extensions supported by Material for MkDocs including
some more information on configuration and usage: some more information on configuration and usage:
* [Admonition][24] * [Admonition][25]
* [Codehilite][25] * [Codehilite][26]
* [Footnotes][26] * [Footnotes][27]
* [Metadata][27] * [Metadata][28]
* [Permalinks][28] * [Permalinks][29]
* [PyMdown Extensions][29] * [PyMdown Extensions][30]
[24]: extensions/admonition.md [25]: extensions/admonition.md
[25]: extensions/codehilite.md [26]: extensions/codehilite.md
[26]: extensions/footnotes.md [27]: extensions/footnotes.md
[27]: extensions/metadata.md [28]: extensions/metadata.md
[28]: extensions/permalinks.md [29]: extensions/permalinks.md
[29]: extensions/pymdown.md [30]: extensions/pymdown.md
## Plugins ## Plugins
@ -715,16 +719,16 @@ steps that sit between the theme and your documentation. For more information,
see the following list of plugins tested and supported by Material for MkDocs see the following list of plugins tested and supported by Material for MkDocs
including more information regarding installation and usage: including more information regarding installation and usage:
* [Search][30] (enabled by default) * [Search][31] (enabled by default)
* [Minification][31] * [Minification][32]
* [Revision date][32] * [Revision date][33]
* [Awesome pages][33] * [Awesome pages][34]
For further reference, the MkDocs wiki contains a list of all For further reference, the MkDocs wiki contains a list of all
[available plugins][34]. [available plugins][35].
[30]: plugins/search.md [31]: plugins/search.md
[31]: plugins/minification.md [32]: plugins/minification.md
[32]: plugins/revision-date.md [33]: plugins/revision-date.md
[33]: plugins/awesome-pages.md [34]: plugins/awesome-pages.md
[34]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins [35]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins

4
material/assets/manifest.json
View File

@ -5,8 +5,8 @@
"assets/javascripts/vendor.js.map": "assets/javascripts/vendor.606193c2.min.js.map", "assets/javascripts/vendor.js.map": "assets/javascripts/vendor.606193c2.min.js.map",
"assets/javascripts/worker/search.js": "assets/javascripts/worker/search.7f7c8775.min.js", "assets/javascripts/worker/search.js": "assets/javascripts/worker/search.7f7c8775.min.js",
"assets/javascripts/worker/search.js.map": "assets/javascripts/worker/search.7f7c8775.min.js.map", "assets/javascripts/worker/search.js.map": "assets/javascripts/worker/search.7f7c8775.min.js.map",
"assets/stylesheets/main.css": "assets/stylesheets/main.c1a4d03f.min.css", "assets/stylesheets/main.css": "assets/stylesheets/main.d35c4a9f.min.css",
"assets/stylesheets/main.css.map": "assets/stylesheets/main.c1a4d03f.min.css.map", "assets/stylesheets/main.css.map": "assets/stylesheets/main.d35c4a9f.min.css.map",
"assets/stylesheets/palette.css": "assets/stylesheets/palette.fdbf4049.min.css", "assets/stylesheets/palette.css": "assets/stylesheets/palette.fdbf4049.min.css",
"assets/stylesheets/palette.css.map": "assets/stylesheets/palette.fdbf4049.min.css.map" "assets/stylesheets/palette.css.map": "assets/stylesheets/palette.fdbf4049.min.css.map"
} }

1
material/assets/stylesheets/main.c1a4d03f.min.css.map
View File

File diff suppressed because one or more lines are too long

4
material/assets/stylesheets/main.c1a4d03f.min.css → material/assets/stylesheets/main.d35c4a9f.min.css vendored
View File

File diff suppressed because one or more lines are too long

1
material/assets/stylesheets/main.d35c4a9f.min.css.map Normal file
View File

File diff suppressed because one or more lines are too long

2
material/base.html
View File

@ -41,7 +41,7 @@
{% endif %} {% endif %}
{% endblock %} {% endblock %}
{% block styles %} {% block styles %}
<link rel="stylesheet" href="{{ 'assets/stylesheets/main.c1a4d03f.min.css' | url }}"> <link rel="stylesheet" href="{{ 'assets/stylesheets/main.d35c4a9f.min.css' | url }}">
{% if palette.primary or palette.accent %} {% if palette.primary or palette.accent %}
<link rel="stylesheet" href="{{ 'assets/stylesheets/palette.fdbf4049.min.css' | url }}"> <link rel="stylesheet" href="{{ 'assets/stylesheets/palette.fdbf4049.min.css' | url }}">
{% endif %} {% endif %}

4
mkdocs.yml
View File

@ -103,8 +103,8 @@ markdown_extensions:
- pymdownx.critic - pymdownx.critic
- pymdownx.details - pymdownx.details
- pymdownx.emoji: - pymdownx.emoji:
emoji_index: !!python/name:pymdownx.emoji.twemoji emoji_index: !!python/name:materialx.emoji.twemoji
emoji_generator: !!python/name:pymdownx.emoji.to_svg emoji_generator: !!python/name:materialx.emoji.to_svg
# - pymdownx.highlight: # - pymdownx.highlight:
# linenums_style: pymdownx-inline # linenums_style: pymdownx-inline
- pymdownx.inlinehilite - pymdownx.inlinehilite

1
requirements.txt
View File

@ -23,3 +23,4 @@ mkdocs>=1.1
Pygments>=2.4 Pygments>=2.4
markdown>=3.2 markdown>=3.2
pymdown-extensions>=7.0 pymdown-extensions>=7.0
mkdocs-material-extensions>=1.0b1

17
src/assets/stylesheets/extensions/pymdown/_emoji.scss
View File

@ -27,15 +27,24 @@
// Scoped in typesetted content to match specificity of regular content // Scoped in typesetted content to match specificity of regular content
.md-typeset { .md-typeset {
// Correct alignment of emojis // Emojis
.emojione, img.emojione,
.twemoji, img.twemoji,
.gemoji { img.gemoji {
width: px2em(18px); width: px2em(18px);
vertical-align: -15%; vertical-align: -15%;
} }
// Inlined SVG icons via mkdocs-material-extensions
span.twemoji { span.twemoji {
display: inline-block; display: inline-block;
height: px2em(18px);
vertical-align: text-top;
// Icon
svg {
width: px2em(18px);
fill: currentColor;
}
} }
} }