diff --git a/CHANGELOG b/CHANGELOG index 25eb708ec..cafad008b 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -10,7 +10,7 @@ mkdocs-material-5.3.3 (2020-06-24) mkdocs-material-5.3.2 (2020-06-21) - * Improved search type-ahead experience with non-Latin characters + * Improved search typeahead experience with non-Latin characters * Fixed #1753: Japanese search doesn't work anymore mkdocs-material-5.3.1 (2020-06-20) diff --git a/docs/creating-your-site.md b/docs/creating-your-site.md index 628bd77ce..903d0e5b8 100644 --- a/docs/creating-your-site.md +++ b/docs/creating-your-site.md @@ -66,27 +66,29 @@ icons and much more: * [Changing colors][3] * [Changing the fonts][4] * [Changing the language][5] -* [Navigation][6] -* [Syntax highlighting][7] -* [Adding a landing page][8] -* [Adding an announcement bar][9] -* [Adding icons and emojis][10] -* [Adding footer links][11] -* [Adding site analytics][12] -* [Adding a comment system][13] +* [Setting up navigation][6] +* [Setting up site search][7] +* [Adding a git repository][8] +* [Adding icons and emojis][9] +* [Adding footer links][10] +* [Adding site analytics][11] +* [Adding a comment system][12] +* [Adding an announcement bar][13] +* [Adding a landing page][14] [2]: getting-started.md#installation [3]: guides/changing-colors.md [4]: guides/changing-the-fonts.md [5]: guides/changing-the-language.md - [6]: guides/navigation.md - [7]: guides/syntax-highlighting.md - [8]: guides/adding-a-landing-page.md - [9]: guides/adding-an-announcement-bar.md - [10]: guides/adding-icons-and-emojis.md - [11]: guides/adding-footer-links.md - [12]: guides/adding-site-analytics.md - [13]: guides/adding-a-comment-system.md + [6]: guides/setting-up-navigation.md + [7]: guides/setting-up-site-search.md + [8]: guides/adding-a-git-repository.md + [9]: guides/adding-icons-and-emojis.md + [10]: guides/adding-footer-links.md + [11]: guides/adding-site-analytics.md + [12]: guides/adding-a-comment-system.md + [13]: guides/adding-an-announcement-bar.md + [14]: guides/adding-a-landing-page.md ## Previewing as you write @@ -112,12 +114,12 @@ If you're running Material for MkDocs from within Docker, use: docker run --rm -it -p 8000:8000 -v "%cd%":/docs squidfunk/mkdocs-material ``` -Point your browser to [localhost:8000][14] and you should see: +Point your browser to [localhost:8000][15] and you should see: -[![Creating your site][15]][14] +[![Creating your site][16]][15] - [14]: http://localhost:8000 - [15]: assets/guides/creating-your-site.png + [15]: http://localhost:8000 + [16]: assets/guides/creating-your-site.png ## Building your site @@ -130,8 +132,8 @@ mkdocs build The contents of this directory make up your project documentation. There's no need for operating a database or server, as it is completely self-contained. -The site can be hosted on [GitHub Pages][16], [GitLab Pages][17], a CDN of your +The site can be hosted on [GitHub Pages][17], [GitLab Pages][18], a CDN of your choice or your private web space. - [16]: publishing-your-site.md#github-pages - [17]: publishing-your-site.md#gitlab-pages + [17]: publishing-your-site.md#github-pages + [18]: publishing-your-site.md#gitlab-pages diff --git a/docs/customization.md b/docs/customization.md index 6fed2d576..1f66e4e08 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -101,7 +101,7 @@ The directory layout of the theme is as follows: │ ├─ javascripts/ # JavaScript │ └─ stylesheets/ # Stylesheets ├─ partials/ -│ ├─ integrations/ # 3rd-party integrations +│ ├─ integrations/ # Third-party integrations │ ├─ language/ # Localized languages │ ├─ footer.html # Footer bar │ ├─ header.html # Header bar diff --git a/docs/extensions/admonition.md b/docs/extensions/admonition.md deleted file mode 100644 index 7edf96888..000000000 --- a/docs/extensions/admonition.md +++ /dev/null @@ -1,459 +0,0 @@ ---- -template: overrides/main.html ---- - -# Admonition - -[Admonition][1] is an extension included in the standard Markdown library that -makes it possible to add block-styled side content to your documentation, e.g. -summaries, notes, hints or warnings. - - [1]: https://python-markdown.github.io/extensions/admonition/ - -## Configuration - -Add the following lines to `mkdocs.yml`: - -``` yaml -markdown_extensions: - - admonition -``` - -## Usage - -Admonitions follow a simple syntax: every block is started with `!!!`, followed -by a single keyword which is used as the [type qualifier][2] of the block. The -content of the block then follows on the next line, indented by four spaces. - -Example: - -``` markdown -!!! note - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. -``` - -Result: - -!!! note - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. - - [2]: #types - -### Changing the title - -By default, the Admonition title will equal the type qualifier in titlecase. -However, it can be changed by adding a quoted string after the type qualifier. - -Example: - -``` markdown -!!! note "Phasellus posuere in sem ut cursus" - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. -``` - -Result: - -!!! note "Phasellus posuere in sem ut cursus" - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. - -### Removing the title - -Similar to [changing the title][3], the icon and title can be omitted by -providing an empty string after the type qualifier: - -Example: - -``` markdown -!!! note "" - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. -``` - -Result: - -!!! note "" - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. - - [3]: #changing-the-title - -### Embedded content - -Admonitions can contain all kinds of text content, including headlines, lists, -paragraphs and other blocks – except code blocks, because the parser from the -standard Markdown library does not account for those. - -The [PyMdown Extensions][4] package adds an extension called [SuperFences][5], -which makes it possible to nest code blocks within other blocks, respectively -Admonition blocks. - - [4]: https://facelessuser.github.io/pymdown-extensions - [5]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/ - -Example: - -!!! note - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. - - ``` mysql - SELECT - Employees.EmployeeID, - Employees.Name, - Employees.Salary, - Manager.Name AS Manager - FROM - Employees - LEFT JOIN - Employees AS Manager - ON - Employees.ManagerID = Manager.EmployeeID - WHERE - Employees.EmployeeID = '087652'; - ``` - - Nunc eu odio eleifend, blandit leo a, volutpat sapien. Phasellus posuere in - sem ut cursus. Nullam sit amet tincidunt ipsum, sit amet elementum turpis. - Etiam ipsum quam, mattis in purus vitae, lacinia fermentum enim. - -### Collapsible blocks - -The [Details][6] extension which is also part of the [PyMdown Extensions][4] -package adds support for rendering collapsible Admonition blocks. This is -useful for FAQs or content that is of secondary nature. - -Example: - -``` markdown -??? note "Phasellus posuere in sem ut cursus" - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. -``` - -Result: - -??? note "Phasellus posuere in sem ut cursus" - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. - -By adding a `+` sign directly after the start marker, blocks can be rendered -open by default. - - [6]: https://facelessuser.github.io/pymdown-extensions/extensions/details/ - -## Types - -Admonition supports user-defined type qualifiers which may influence the style -of the inserted block. Following is a list of type qualifiers provided by -Material for MkDocs, whereas the default type, and thus fallback for unknown -type qualifiers, is `note`. - -### Note - -Example: - -``` markdown -!!! note - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. -``` - -Result: - -!!! note - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. - -Qualifiers: - -* `note` -* `seealso` - -### Abstract - -Example: - -``` markdown -!!! abstract - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. -``` - -Result: - -!!! abstract - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. - -Qualifiers: - -* `abstract` -* `summary` -* `tldr` - -### Info - -Example: - -``` markdown -!!! info - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. -``` - -Result: - -!!! info - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. - -Qualifiers: - -* `info` -* `todo` - -### Tip - -Example: - -``` markdown -!!! tip - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. -``` - -Result: - -!!! tip - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. - -Qualifiers: - -* `tip` -* `hint` -* `important` - -### Success - -Example: - -``` markdown -!!! success - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. -``` - -Result: - -!!! success - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. - -Qualifiers: - -* `success` -* `check` -* `done` - -### Question - -Example: - -``` markdown -!!! question - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. -``` - -Result: - -!!! question - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. - -Qualifiers: - -* `question` -* `help` -* `faq` - -### Warning - -Example: - -``` markdown -!!! warning - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. -``` - -Result: - -!!! warning - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. - -Qualifiers: - -* `warning` -* `caution` -* `attention` - -### Failure - -Example: - -``` markdown -!!! failure - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. -``` - -Result: - -!!! failure - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. - -Qualifiers: - -* `failure` -* `fail` -* `missing` - -### Danger - -Example: - -``` markdown -!!! danger - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. -``` - -Result: - -!!! danger - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. - -Qualifiers: - -* `danger` -* `error` - -### Bug - -Example: - -``` markdown -!!! bug - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. -``` - -Result: - -!!! bug - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. - -Qualifiers: - -* `bug` - -### Example - -Example: - -``` markdown -!!! example - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. -``` - -Result: - -!!! example - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. - -Qualifiers: - -* `example` - -### Quote - -Example: - -``` markdown -!!! quote - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. -``` - -Result: - -!!! quote - - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. - -Qualifiers: - -* `quote` -* `cite` diff --git a/docs/extensions/footnotes.md b/docs/extensions/footnotes.md deleted file mode 100644 index 4f0b44f0f..000000000 --- a/docs/extensions/footnotes.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -template: overrides/main.html ---- - -# Footnotes - -[Footnotes][1] is another extension included in the standard Markdown library. -As the name says, it adds the ability to add inline footnotes to your -documentation. - - [1]: https://python-markdown.github.io/extensions/footnotes/ - -## Configuration - -Add the following lines to `mkdocs.yml`: - -``` yaml -markdown_extensions: - - footnotes -``` - -## Usage - -The markup for footnotes is similar to the standard Markdown markup for links. -A reference is inserted in the text, which can then be defined at any point in -the document. - -### Inserting the reference - -The footnote reference is enclosed in square brackets and starts with a caret, -followed by an arbitrary label which may contain numeric identifiers [1, 2, 3, -...] or names [Granovetter et al. 1998]. The rendered references are always -consecutive superscripted numbers. - -Example: - -``` markdown -Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2] -``` - -Result: - -Lorem ipsum[^1] dolor sit amet, consectetur adipiscing elit.[^2] - -### Inserting the content - -The footnote content is also declared with a label, which must match the label -used for the footnote reference. It can be inserted at an arbitrary position in -the document and is always rendered at the bottom of the page. Furthermore, a -backlink is automatically added to the footnote reference. - -#### on a single line - -Short statements can be written on the same line. - -Example: - -``` markdown -[^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit. -``` - -Result: - -Jump to footnote at the bottom of the page - - [^1]: Lorem ipsum dolor sit amet, consectetur adipiscing elit. - -#### on multiple lines - -Paragraphs should be written on the next line. As with all Markdown blocks, the -content must be indented by four spaces. - -Example: - -``` markdown -[^2]: - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor - massa, nec semper lorem quam in massa. -``` - -Result: - - [^2]: - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod - nulla. Curabitur feugiat, tortor non consequat finibus, justo purus - auctor massa, nec semper lorem quam in massa. - -Jump to footnote at the bottom of the page diff --git a/docs/extensions/metadata.md b/docs/extensions/metadata.md deleted file mode 100644 index fb6fd227a..000000000 --- a/docs/extensions/metadata.md +++ /dev/null @@ -1,135 +0,0 @@ ---- -template: overrides/main.html -hero: Set heroes with metadata -path: tree/master/docs/extensions -source: metadata.md ---- - -# Metadata - -[Metadata][1] is an extension included in the standard Markdown library that -makes it possible to control certain properties in a page-specific context, -e.g. the page title or description. - - [1]: https://python-markdown.github.io/extensions/meta_data/ - -## Configuration - -Add the following lines to `mkdocs.yml`: - -``` yaml -markdown_extensions: - - meta -``` - -## Usage - -Metadata is written as a series of key-value pairs at the beginning of the -Markdown document, delimited by a blank line which ends the metadata context. -Naturally, the metadata is stripped from the document before rendering the -actual page content and made available to the theme. - -Example: - -``` markdown ---- -title: Lorem ipsum dolor sit amet -description: Nullam urna elit, malesuada eget finibus ut, ac tortor. -path: path/to/file -source: file.js ---- - -# Headline - -... -``` - -See the next section which covers the supported metadata. - -### Setting a hero - -Material for MkDocs exposes a simple text-only page-local hero via Metadata, as -you can see on the current page when you scroll to the top. It's as simple as: - -``` markdown -hero: Set heroes with metadata -``` - -### Linking sources - -When a document is related to a specific source file and the `repo_url` is -defined inside the project's `mkdocs.yml`, the file can be linked using the -`source` key: - -``` markdown -source: file.js -``` - -The filename is appended to the `repo_url` set in `mkdocs.yml`, but can be -prefixed with a `path` to ensure correct path resolving. The name of the source -file is shown in the tooltip. - -Example: - -``` markdown -path: tree/master/docs/extensions -source: metadata.md -``` - -### Redirecting to another page - -It's sometimes necessary to move documents around in the navigation tree and -redirect users from the old URL to the new one. The `redirect` meta-tag allows -to create a redirection from the current document to the address specified in -the tag. - -For instance, if your document contains: - -``` markdown -redirect: /new/url -``` - -accessing that document's URL will automatically redirect to `/new/url`. - -### Overrides - -#### Page title - -The page title can be overridden on a per-document basis: - -``` markdown -title: Lorem ipsum dolor sit amet -``` - -This will set the `title` tag inside the document `head` for the current page -to the provided value. It will also override the default behavior of Material -for MkDocs which appends the site title using a dash as a separator to the page -title. - -#### Page description - -The page description can also be overridden on a per-document basis: - -``` yaml -description: Nullam urna elit, malesuada eget finibus ut, ac tortor. -``` - -This will set the `meta` tag containing the site description inside the -document `head` for the current page to the provided value. - -#### Disqus - -As described in the [getting started guide][3], Disqus can be enabled on a -per-document basis: - -``` markdown -disqus: your-shortname -``` - -Disqus can also be disabled for a specific page by setting it to an empty value: - -``` markdown -disqus: '' -``` - - [3]: ../getting-started.md#disqus diff --git a/docs/extensions/pymdown.md b/docs/extensions/pymdown.md deleted file mode 100644 index 40fdc8043..000000000 --- a/docs/extensions/pymdown.md +++ /dev/null @@ -1,375 +0,0 @@ ---- -template: overrides/main.html ---- - -# PyMdown Extensions - -[PyMdown Extensions][1] is a collection of Markdown extensions that add some -great missing features to the standard Markdown library. A compatible version -is always included with the theme. - - [1]: https://facelessuser.github.io/pymdown-extensions/ - -## Configuration - -The following list of extensions that are part of the PyMdown Extensions -package are recommended to be used together with Material for MkDocs: - -``` yaml -markdown_extensions: - - pymdownx.arithmatex - - pymdownx.betterem: - smart_enable: all - - pymdownx.caret - - pymdownx.critic - - pymdownx.details - - pymdownx.emoji: - emoji_index: !!python/name:materialx.emoji.twemoji - emoji_generator: !!python/name:materialx.emoji.to_svg - - pymdownx.inlinehilite - - pymdownx.magiclink - - pymdownx.mark - - pymdownx.smartsymbols - - pymdownx.superfences - - pymdownx.tasklist: - custom_checkbox: true - - pymdownx.tabbed - - pymdownx.tilde -``` - -## Usage - -### Arithmatex MathJax - - - -[Arithmatex][2] integrates Material for MkDocs with [MathJax][3] which parses -block-style and inline equations written in TeX markup and outputs them in -mathematical notation. See [this thread][4] for a short introduction and quick -reference on how to write equations in TeX syntax. - -Besides activating the extension in the `mkdocs.yml`, the MathJax JavaScript -runtime needs to be included. This can be done with [additional JavaScript][5]: - -``` yaml -extra_javascript: - - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-MML-AM_CHTML -``` - -If you want to override the default MathJax configuration, you can do this by -adding another JavaScript file __before__ the MathJax runtime which contains -the MathJax configuration, e.g.: - -``` js -window.MathJax = { - tex2jax: { - inlineMath: [ ["\\(","\\)"] ], - displayMath: [ ["\\[","\\]"] ] - }, - TeX: { - TagSide: "right", - TagIndent: ".8em", - MultLineWidth: "85%", - equationNumbers: { - autoNumber: "AMS", - }, - unicode: { - fonts: "STIXGeneral,'Arial Unicode MS'" - } - }, - displayAlign: "left", - showProcessingMessages: false, - messageStyle: "none" -}; -``` - -Then, add the following lines to `mkdocs.yml`: - -``` yaml -extra_javascript: - - javascripts/extra.js - - https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0/MathJax.js?config=TeX-MML-AM_CHTML -``` - - [2]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/ - [3]: https://www.mathjax.org/ - [4]: https://math.meta.stackexchange.com/questions/5020/mathjax-basic-tutorial-and-quick-reference - [5]: ../customization.md#additional-javascript - -#### Blocks - -Blocks are enclosed in `:::tex $$...$$` which are placed on separate lines. - -Example: - -``` tex -$$ -\frac{n!}{k!(n-k)!} = \binom{n}{k} -$$ -``` - -Result: - -$$ -\frac{n!}{k!(n-k)!} = \binom{n}{k} -$$ - -#### Inline - -Inline equations must be enclosed in `:::tex $...$`: - -Example: - -``` tex -Lorem ipsum dolor sit amet: $p(x|y) = \frac{p(y|x)p(x)}{p(y)}$ -``` - -Result: - -Lorem ipsum dolor sit amet: $p(x|y) = \frac{p(y|x)p(x)}{p(y)}$ - -### BetterEm - -[BetterEm][6] improves the handling of emphasis markup (__bold__ and _italic_) -within Markdown by providing a more sophisticated parser for better detecting -start and end tokens. Read the documentation for [usage notes][7]. - - [6]: https://facelessuser.github.io/pymdown-extensions/extensions/betterem/ - [7]: https://facelessuser.github.io/pymdown-extensions/usage_notes/ - -### Caret - -[Caret][8] makes it possible to highlight ^^inserted text^^. The portion of -text that should be marked as added must be enclosed in two carets `^^...^^`. - - [8]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/ - -### Critic - -[Critic][9] implements [Critic Markup][10], a Markdown extension that enables -the tracking of changes (additions, deletions and comments) on documents. -During compilation of the Markdown document, changes can be rendered (default), -accepted or rejected. - -Text can be {--deleted--} and replacement text {++added++}. This can also be -combined into {~~one~>a single~~} operation. {==Highlighting==} is also -possible {>>and comments can be added inline<<}. - -{== - -Formatting can also be applied to blocks, by putting the opening and closing -tags on separate lines and adding new lines between the tags and the content. - -==} - - [9]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/ - [10]: http://criticmarkup.com/ - -### Details - -[Details][11] adds [collapsible Admonition blocks][12] which can contain -arbitrary content using the HTML5 `details` and `summary` tags. Additionally, -all Admonition qualifiers can be used, e.g. `note`, `question`, `warning` etc.: - -??? question "How many Prolog programmers does it take to change a lightbulb?" - - Yes. - - [11]: https://facelessuser.github.io/pymdown-extensions/extensions/details/ - [12]: ../admonition/#collapsible-blocks - -### Emoji :tada: - -[Emoji][13] adds the ability to insert, well, emojis! :smile: - -By default, [Emoji][13] uses JoyPixles' emoji under the former name EmojiOne. -Recent versions of the extension lock support to an older version (2.2.7) due -to JoyPixels' newer, less permissible licenses included in later releases. This -restricts support to Unicode 9. To get the latest support for the current -Unicode version, you can use Twemoji instead which has a much more permissible -license. Simply override the default emoji index being used: - -``` yaml -markdown_extensions: - - pymdownx.emoji: - emoji_index: !!python/name:pymdownx.emoji.twemoji - emoji_generator: !!python/name:pymdownx.emoji.to_svg -``` - -To view all the available short names and emoji available, see -[Emoji's documentation][18] on your chosen index which includes links to the -files containing the short names and emoji associated with each supported -index. - -!!! warning "Legal disclaimer" - - Material has no affiliation with [JoyPixles][15] or [Twemoji][14], both - of which are licensed under [CC BY 4.0][16]. When including images or CSS - from either provider, please read their licenses to ensure proper - 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.twemoji - 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-16: – 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-16: – that's not all, we can also use [GitHub's Octicons][22] - - [13]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/ - [14]: https://twemoji.twitter.com/ - [15]: https://www.joypixels.com/ - [16]: https://creativecommons.org/licenses/by/4.0/legalcode - [17]: https://github.com/joypixels/emojione#emojione-version-2 - [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][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 -activated by prefixing inline code with a shebang and language identifier, -e.g. `#!js`. - - [23]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/ - -### MagicLink - -[MagicLink][24] detects links in Markdown and auto-generates the necessary -markup, so no special syntax is required. It auto-links `http[s]://` and -`ftp://` links, as well as references to email addresses. - - [24]: https://facelessuser.github.io/pymdown-extensions/extensions/magiclink/ - -### Mark - -[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 -enclosed in two equal signs `==...==`. - - [25]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/ - -### SmartSymbols - -[SmartSymbols][26] converts markup for special characters into their -corresponding symbols, e.g. arrows (<--, -->, <-->), trademark and copyright -symbols ((c), (tm), (r)) and fractions (1/2, 1/4, ...). - - [26]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/ - -### SuperFences - -[SuperFences][27] provides the ability to nest code blocks under blockquotes, -lists and other block elements, which the [Fenced Code Blocks][28] extension -from the standard Markdown library doesn't parse correctly. - -SuperFences does also allow [grouping code blocks with tabs][29]. - - [27]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/ - [28]: https://python-markdown.github.io/extensions/fenced_code_blocks/ - [29]: codehilite.md#grouping-code-blocks - -### Tabbed - -[Tabbed][30] adds support for creating tabbed groups of Markdown content. - -Example: - -``` markdown -=== "Fruit List" - - :apple: Apple - - :banana: Banana - - :kiwi: Kiwi - -=== "Fruit Table" - Fruit | Color - --------------- | ----- - :apple: Apple | Red - :banana: Banana | Yellow - :kiwi: Kiwi | Green -``` - -Result: - -=== "Fruit List" - - :apple: Apple - - :banana: Banana - - :kiwi: Kiwi - -=== "Fruit Table" - Fruit | Color - --------------- | ----- - :apple: Apple | Red - :banana: Banana | Yellow - :kiwi: Kiwi | Green - -[30]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/ - -### Tasklist - -[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. -Checkbox lists are like regular lists, but prefixed with `[ ]` for empty or -`[x]` for filled checkboxes. - -Example: - -``` markdown -* [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit -* [x] Nulla lobortis egestas semper -* [x] Curabitur elit nibh, euismod et ullamcorper at, iaculis feugiat est -* [ ] Vestibulum convallis sit amet nisi a tincidunt - * [x] In hac habitasse platea dictumst - * [x] In scelerisque nibh non dolor mollis congue sed et metus - * [x] Sed egestas felis quis elit dapibus, ac aliquet turpis mattis - * [ ] Praesent sed risus massa -* [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque -* [ ] Nulla vel eros venenatis, imperdiet enim id, faucibus nisi -``` - -Result: - -* [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit -* [x] Nulla lobortis egestas semper -* [x] Curabitur elit nibh, euismod et ullamcorper at, iaculis feugiat est -* [ ] Vestibulum convallis sit amet nisi a tincidunt - * [x] In hac habitasse platea dictumst - * [x] In scelerisque nibh non dolor mollis congue sed et metus - * [x] Sed egestas felis quis elit dapibus, ac aliquet turpis mattis - * [ ] Praesent sed risus massa -* [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque -* [ ] Nulla vel eros venenatis, imperdiet enim id, faucibus nisi - -[31]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/ - -### Tilde - -[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 -`~~...~~` and the extension will take care of the rest. - -[32]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/ diff --git a/docs/guides/changing-colors.md b/docs/guides/changing-colors.md index a932a27c2..99e148453 100644 --- a/docs/guides/changing-colors.md +++ b/docs/guides/changing-colors.md @@ -16,7 +16,7 @@ fit your brand identity by using [CSS variables][2]. ### Color scheme -[:octicons-file-code-24: Source][3] · :octicons-tools-24: Default: `default` +[:octicons-file-code-24: Source][3] · :octicons-milestone-24: Default: `default` Material for MkDocs supports two _color schemes_: a light mode, which is just called `default`, and a dark mode, which is called `slate`. The color scheme @@ -62,7 +62,7 @@ theme: ### Primary color -[:octicons-file-code-24: Source][4] · :octicons-tools-24: Default: `indigo` +[:octicons-file-code-24: Source][4] · :octicons-milestone-24: Default: `indigo` The _primary color_ is used for the header, the sidebar, text links and several other components. In order to change the primary color, set the following value @@ -117,7 +117,7 @@ color: ### Accent color -[:octicons-file-code-24: Source][5] · :octicons-tools-24: Default: `indigo` +[:octicons-file-code-24: Source][5] · :octicons-milestone-24: Default: `indigo` The _accent color_ is used to denote elements that can be interacted with, e.g. hovered links, buttons and scrollbars. It can be changed in `mkdocs.yml` by @@ -184,9 +184,12 @@ color: ## Customization -Material for MkDocs implements colors using [CSS variables][6] (custom +[:octicons-file-code-24: Source][6] · +:octicons-mortar-board-24: Difficulty: easy + +Material for MkDocs implements colors using [CSS variables][7] (custom properties). If you want to customize the colors beyond the palette (e.g. to -use your brand-specific colors), you can add an [additional stylesheet][7] and +use your brand-specific colors), you can add an [additional stylesheet][8] and tweak the following CSS variables: ``` css @@ -217,7 +220,7 @@ tweak the following CSS variables: } ``` -The colors of [code blocks][8], [admonitions][9], text links and the footer can +The colors of [code blocks][9], [admonitions][10], text links and the footer can be adjusted through dedicated CSS variables, which partly default to the base colors or neutral colors: @@ -245,7 +248,8 @@ colors or neutral colors: } ``` - [6]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties - [7]: ../customization.md#additional-stylesheets - [8]: ../extensions/codehilite.md - [9]: ../extensions/admonition.md + [6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/base/_colors.scss + [7]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties + [8]: ../customization.md#additional-stylesheets + [9]: ../writing/code-blocks.md + [10]: ../writing/admonitions.md diff --git a/docs/guides/changing-the-fonts.md b/docs/guides/changing-the-fonts.md index 31da850f2..a3b4b511f 100644 --- a/docs/guides/changing-the-fonts.md +++ b/docs/guides/changing-the-fonts.md @@ -15,7 +15,8 @@ should be used. ### Regular font -[:octicons-file-code-24: Source][2] · :octicons-tools-24: Default: [`Roboto`][3] +[:octicons-file-code-24: Source][2] · +:octicons-milestone-24: Default: [`Roboto`][3] The _regular font_ is used for all body copy, headlines, and essentially everything that does not need to be proportionally spaced. It can be set to any @@ -34,8 +35,8 @@ The typeface will be loaded in 300, 400, _400i_ and __700__. ### Proportional font -[:octicons-file-code-24: Source][2] · :octicons-tools-24: Default: -[`Roboto Mono`][4] +[:octicons-file-code-24: Source][2] · +:octicons-milestone-24: Default: [`Roboto Mono`][4] The _proportional font_ is used for code blocks and can be configured separately. Just like the regular font, it can be set to any valid [Google Font][1] from @@ -53,6 +54,9 @@ The typeface will be loaded in 400. ## Customization +[:octicons-file-code-24: Source][2] · +:octicons-mortar-board-24: Difficulty: easy + If you want to load fonts from other destinations or don't want to use Google Fonts for [data privacy][5] reasons, e.g. _due to GDPR_, add the following lines to `mkdocs.yml`: diff --git a/docs/guides/changing-the-language.md b/docs/guides/changing-the-language.md index 7f2d73cd7..0963ea2ed 100644 --- a/docs/guides/changing-the-language.md +++ b/docs/guides/changing-the-language.md @@ -12,7 +12,7 @@ search can be configured to use a language-specific stemmer (if available). ### Site language -[:octicons-file-code-24: Source][1] · :octicons-tools-24: Default: `en` +[:octicons-file-code-24: Source][1] · :octicons-milestone-24: Default: `en` You can set the language from `mkdocs.yml` with: @@ -23,18 +23,6 @@ theme: The following languages are supported: -