| @@ -0,0 +1,140 @@ | ||
| --- | ||
| template: overrides/main.html | ||
| --- | ||
|
|
||
| # Creating your site | ||
|
|
||
| After you've [installed][1] Material for MkDocs, you can bootstrap your project | ||
| documentation using the `mkdocs` executable. Go to the directory where you want | ||
| your project to be located and enter: | ||
|
|
||
| ``` | ||
| mkdocs new . | ||
| ``` | ||
|
|
||
| Alternatively, if you're running Material for MkDocs from within Docker, use: | ||
|
|
||
| === "Unix" | ||
|
|
||
| ``` | ||
| docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new . | ||
| ``` | ||
|
|
||
| === "Windows" | ||
|
|
||
| ``` | ||
| docker run --rm -it -v "%cd%":/docs squidfunk/mkdocs-material new . | ||
| ``` | ||
|
|
||
| This will create the following structure: | ||
|
|
||
| ``` | ||
| . | ||
| ├─ docs/ | ||
| │ └─ index.md | ||
| └─ mkdocs.yml | ||
| ``` | ||
|
|
||
| [1]: getting-started.md | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Minimal configuration | ||
|
|
||
| Depending on your [installation method][2], you can now add the following lines | ||
| to `mkdocs.yml` in your project root. If you installed Material for MkDocs using | ||
| `pip` or `docker`, add: | ||
|
|
||
| ``` yaml | ||
| theme: | ||
| name: material | ||
| ``` | ||
|
|
||
| If you cloned Material for MkDocs from GitHub, add: | ||
|
|
||
| ``` yaml | ||
| theme: | ||
| name: null | ||
| custom_dir: mkdocs-material/material | ||
| ``` | ||
|
|
||
| ### Advanced configuration | ||
|
|
||
| Material for MkDocs comes with a lot of configuration options. The _setup_ | ||
| section explains in great detail how to configure and customize colors, fonts, | ||
| icons and much more: | ||
|
|
||
| * [Changing the colors][3] | ||
| * [Changing the fonts][4] | ||
| * [Changing the language][5] | ||
| * [Changing the logo and icons][6] | ||
| * [Setting up navigation][7] | ||
| * [Setting up site search][8] | ||
| * [Setting up site analytics][9] | ||
| * [Setting up the header][10] | ||
| * [Adding social links][11] | ||
| * [Adding a git repository][12] | ||
| * [Adding a comment system][13] | ||
| <!-- * [Adding a landing page][14] --> | ||
|
|
||
| [2]: getting-started.md#installation | ||
| [3]: setup/changing-the-colors.md | ||
| [4]: setup/changing-the-fonts.md | ||
| [5]: setup/changing-the-language.md | ||
| [6]: setup/changing-the-logo-and-icons.md | ||
| [7]: setup/setting-up-navigation.md | ||
| [8]: setup/setting-up-site-search.md | ||
| [9]: setup/setting-up-site-analytics.md | ||
| [10]: setup/setting-up-the-header.md | ||
| [11]: setup/adding-social-links.md | ||
| [12]: setup/adding-a-git-repository.md | ||
| [13]: setup/adding-a-comment-system.md | ||
| <!--[14]: setup/adding-a-landing-page.md--> | ||
|
|
||
| ## Previewing as you write | ||
|
|
||
| MkDocs includes a live preview server, so you can preview your changes as you | ||
| write your documentation. The server will automatically rebuild the site upon | ||
| saving. Start it with: | ||
|
|
||
| ``` | ||
| mkdocs serve | ||
| ``` | ||
|
|
||
| If you're running Material for MkDocs from within Docker, use: | ||
|
|
||
| === "Unix" | ||
|
|
||
| ``` | ||
| docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material | ||
| ``` | ||
|
|
||
| === "Windows" | ||
|
|
||
| ``` | ||
| docker run --rm -it -p 8000:8000 -v "%cd%":/docs squidfunk/mkdocs-material | ||
| ``` | ||
|
|
||
| Point your browser to [localhost:8000][15] and you should see: | ||
|
|
||
| [![Creating your site][16]][15] | ||
|
|
||
| [15]: http://localhost:8000 | ||
| [16]: assets/screenshots/creating-your-site.png | ||
|
|
||
| ## Building your site | ||
|
|
||
| When you're finished editing, you can build a static site from your Markdown | ||
| files with: | ||
|
|
||
| ``` | ||
| 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][17], [GitLab Pages][18], a CDN of your | ||
| choice or your private web space. | ||
|
|
||
| [17]: publishing-your-site.md#github-pages | ||
| [18]: publishing-your-site.md#gitlab-pages |
| @@ -0,0 +1,136 @@ | ||
| --- | ||
| template: overrides/main.html | ||
| --- | ||
|
|
||
| # Deprecations | ||
|
|
||
| This page includes a list of deprecations, indicating which features of Material | ||
| for MkDocs were replaced with newer, more flexible alternatives, and thus should | ||
| not be used anymore. | ||
|
|
||
| ## Front matter | ||
|
|
||
| ### Redirect | ||
|
|
||
| :octicons-archive-24: Deprecated: 5.5 · | ||
| :octicons-trash-24: Removed: 6.0 | ||
|
|
||
| The `redirect` key, which could be added via [Metadata][1], allowed to | ||
| specify a redirect from within a document to a new address, which is a good | ||
| idea when moving content around: | ||
|
|
||
| ``` markdown | ||
| --- | ||
| redirect: /path/to/new/file | ||
| --- | ||
| ``` | ||
|
|
||
| The [redirects][2] plugin provides the ability to define redirect mappings via | ||
| `mkdocs.yml`, which is considered to be a much better solution to achieve the | ||
| same result. It can be installed with `pip`: | ||
|
|
||
| ``` | ||
| pip install mkdocs-redirects | ||
| ``` | ||
|
|
||
| Redirect mappings can then be added to `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| plugins: | ||
| - redirects: | ||
| redirect_maps: | ||
| path/to/old/file.md: path/to/new/file.md | ||
| ``` | ||
|
|
||
| [1]: reference/meta-tags.md#metadata | ||
| [2]: https://github.com/datarobot/mkdocs-redirects | ||
|
|
||
| ### Source link | ||
|
|
||
| :octicons-archive-24: Deprecated: 5.5 · | ||
| :octicons-trash-24: Removed: 6.0 | ||
|
|
||
| The `source` and `path` keys, which could be added via [Metadata][1], showed | ||
| a source icon at the top right corner of a document, linking a document to a | ||
| single source file: | ||
|
|
||
| ``` markdown | ||
| --- | ||
| path: tree/master/docs | ||
| source: deprecations.md | ||
| --- | ||
| ``` | ||
|
|
||
| Only a single source file could be linked, which is useless if a document refers | ||
| to multiple files (or multiple sections within a single file). A more flexible | ||
| approach is to use the new [icon integration][3]: | ||
|
|
||
| ``` markdown | ||
| [:octicons-file-code-24: Source](https://github.com/squidfunk/mkdocs-material/blob/master/docs/deprecations.md) | ||
| ``` | ||
|
|
||
| This will render as [:octicons-file-code-24: Source][4], which can be included | ||
| at arbitrary positions in any document. | ||
|
|
||
| [3]: setup/changing-the-logo-and-icons.md#icons | ||
| [4]: https://github.com/squidfunk/mkdocs-material/blob/master/docs/deprecations.md | ||
|
|
||
| ### Hero | ||
|
|
||
| :octicons-archive-24: Deprecated: 5.5 · | ||
| :octicons-trash-24: Removed: 6.0 | ||
|
|
||
| The `hero` key, which could be added via [Metadata][1], allowed to render a | ||
| simple, text-only and page-local teaser text as part of a document. It could | ||
| be set from front matter with: | ||
|
|
||
| ``` markdown | ||
| --- | ||
| hero: Lorem ipsum dolor sit amet | ||
| --- | ||
| ``` | ||
|
|
||
| The recommended way is to [override the `hero` block][5] via [theme | ||
| extension][6] for a specific page, which has the nice side effect that hero | ||
| templates can be shared among multiple pages: | ||
|
|
||
| === "Markdown" | ||
|
|
||
| ``` markdown | ||
| --- | ||
| template: overrides/hero.html | ||
| --- | ||
| ``` | ||
|
|
||
| === "Template" | ||
|
|
||
| ``` html | ||
| {% block hero %} | ||
| <!-- Add custom hero here --> | ||
| {% endblock %} | ||
| ``` | ||
|
|
||
| [5]: customization.md#overriding-blocks | ||
| [6]: customization.md#extending-the-theme | ||
|
|
||
| ## Docker image | ||
|
|
||
| ### Bundled plugins | ||
|
|
||
| :octicons-archive-24: Deprecated: 5.5 · | ||
| :octicons-trash-24: Removed: 6.0 | ||
|
|
||
| Over the last years, the Docker image has continually increased in size. For CI | ||
| it's important that download times are as short as possible, which is why the | ||
| following plugins will be removed: | ||
|
|
||
| - [mkdocs-awesome-pages-plugin][7] | ||
| - [mkdocs-git-revision-date-localized-plugin][8] | ||
|
|
||
| Note that it's trivial to install plugins inside the Docker image before | ||
| building your documentation. See the [installation guide][9] for a step-by-step | ||
| guide. | ||
|
|
||
| [7]: https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin | ||
| [8]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin | ||
| [9]: getting-started.md#with-docker |
| @@ -0,0 +1,176 @@ | ||
| --- | ||
| template: overrides/main.html | ||
| --- | ||
|
|
||
| # <span hidden>Insiders</span> :logo: :material-plus: :octicons-heart-fill-24:{: .tx-heart } | ||
|
|
||
| Material for MkDocs uses the [sponsorware][1] release strategy, which means | ||
| that _new features are first exclusively released to sponsors_ as part of | ||
| __Material for MkDocs Insiders__. Read on to learn [how sponsorship works][2], | ||
| and how you can [become a sponsor][3]. | ||
|
|
||
| [1]: https://github.com/sponsorware/docs | ||
| [2]: #how-sponsorship-works | ||
| [3]: #how-to-become-a-sponsor | ||
|
|
||
| <div style="width:100%;height:0px;position:relative;padding-bottom:56.138%;"> | ||
| <iframe src="https://streamable.com/e/lz4me5" frameborder="0" width="100%" height="100%" allowfullscreen style="width:100%;height:100%;position:absolute;left:0px;top:0px;overflow:hidden;"></iframe> | ||
| </div> | ||
| <p style="text-align: center; font-style: oblique"> | ||
| A demo is worth a thousand words — check it out at <br /> | ||
| <a href="https://squidfunk.github.io/mkdocs-material-insiders/"> | ||
| squidfunk.github.io/mkdocs-material-insiders | ||
| </a> | ||
| </p> | ||
|
|
||
| ## How sponsorship works | ||
|
|
||
| New features will first land in Material for MkDocs Insiders, which means that | ||
| _sponsors will have access immediately_. Every feature is tied to a funding | ||
| goal in monthly subscriptions. If a funding goal is hit, the features that are | ||
| tied to it are merged back into Material for MkDocs and released for general | ||
| availability. Bugfixes will always be released simultaneously in both editions. | ||
|
|
||
| See the [roadmap][4] for a list of already available and upcoming features, and | ||
| for demonstration purposes, [the official documentation][5] built with Material | ||
| for MkDocs Insiders. | ||
|
|
||
| [4]: #roadmap | ||
| [5]: https://squidfunk.github.io/mkdocs-material-insiders/ | ||
|
|
||
| ## How to become a sponsor | ||
|
|
||
| So you've decided to become a sponsor? Great! You're just __three easy steps__ | ||
| away from enjoying the latest features of Material for MkDocs Insiders. | ||
| Complete the following steps and you're in: | ||
|
|
||
| - Visit [squidfunk's sponsor profile][6] and pick a tier that includes exclusive | ||
| access to squidfunk's sponsorware, which is _any tier from $10/month_. Select | ||
| the tier and complete the checkout. | ||
| - Within 24 hours, you will become a collaborator of the private Material for | ||
| MkDocs Insiders GitHub repository, a fork of Material for MkDocs with | ||
| [brand new and exclusive features][7]. | ||
| - Create a [personal access token][8], which allows installing Material for | ||
| MkDocs Insiders from any destination, including other CI providers like | ||
| [GitLab][9] or [Bitbucket][10]. | ||
|
|
||
| __Congratulations! :partying_face: You're now officially a sponsor and will | ||
| get updates for Material for MkDocs Insiders, until you decide to cancel your | ||
| monthly subscription, which you can do at any time.__ | ||
|
|
||
| [6]: https://github.com/sponsors/squidfunk | ||
| [7]: #roadmap | ||
| [8]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token | ||
| [9]: https://gitlab.com | ||
| [10]: https://bitbucket.org | ||
|
|
||
| ## Roadmap | ||
|
|
||
| The following list of funding goals – named after varieties of chili peppers | ||
| [I'm growing on my balcony][11] – shows which features are already available | ||
| in Material for MkDocs Insiders. | ||
|
|
||
| [11]: https://www.instagram.com/squidfunk/ | ||
|
|
||
| ### Madame Jeanette | ||
|
|
||
| [:octicons-flame-24: Funding goal: __$500__][6] · | ||
| :octicons-unlock-24: Status: _released_ | ||
|
|
||
| New features and improvements for _search_, including: | ||
|
|
||
| - [x] Improved search result grouping (pages + headings) | ||
| - [x] Improved search result relevance and scoring | ||
| - [x] Display of missing query terms in search results | ||
|
|
||
| ### Prairie Fire | ||
|
|
||
| [:octicons-flame-24: Funding goal: __$1,000__][6] · | ||
| :octicons-lock-24: Status: _exclusive_ | ||
|
|
||
| New features and improvements for _content and toc_, including: | ||
|
|
||
| - [x] Highlighting of matched search terms in content area | ||
| - [x] Navigation can always be expanded via configuration | ||
| - [x] Header can be automatically hidden on scrolling | ||
| - [x] Table of contents can be automatically hidden when empty | ||
| - [ ] Table of contents can be moved into navigation for more space | ||
| - [ ] Table of contents shows which sections have search results | ||
| - [ ] Table of contents auto-collapses and expands only the active section | ||
| - [ ] Better support for wide screens, i.e. more horizontal space | ||
| - [ ] ... more to come | ||
|
|
||
| ### Bhut Jolokia | ||
|
|
||
| [:octicons-flame-24: Funding goal: __$1,500__][6] · | ||
| :octicons-lock-24: Status: _exclusive_ | ||
|
|
||
| New features and improvements for _hosting multiple versions_, including: | ||
|
|
||
| - [ ] Support for multiple languages of documents | ||
| - [ ] Support for multiple versions of documents | ||
| - [ ] Support for one or more management plugins | ||
| - [ ] ... more to come | ||
|
|
||
| ### Black Pearl | ||
|
|
||
| [:octicons-flame-24: Funding goal: __$2,000__][6] · | ||
| :octicons-lock-24: Status: _exclusive_ | ||
|
|
||
| New features and improvements for _user preferences_, including: | ||
|
|
||
| - [x] Support for user-toggleable themes | ||
| - [ ] Support for user-toggleable code-block styles (light/dark) | ||
| - [ ] Display last searches when search is empty | ||
| - [ ] Improved search result summaries | ||
| - [ ] ... more to come | ||
|
|
||
| ### Caribbean Red | ||
|
|
||
| [:octicons-flame-24: Funding goal: __$3,000__][6] · | ||
| :octicons-lock-24: Status: _exclusive_ | ||
|
|
||
| Alternative, completely different _vertical layout_, optimized to read | ||
| documentation and code side-by-side, e.g. for the documentation of APIs with | ||
| the same functionality as Material for MkDocs. | ||
|
|
||
| ## Frequently asked questions | ||
|
|
||
| ### Compatibility | ||
|
|
||
| _We're running an open source project and want to make sure that users can build | ||
| the documentation without having access to Insiders. Is that still possible?_ | ||
|
|
||
| Yes. Material for MkDocs Insiders strives to be compatible with Material for | ||
| MkDocs, so all new features are implemented as feature flags and all | ||
| improvements (e.g. search) do not require any changes to existing configuration. | ||
| This means that your users will be able to build the docs locally with the | ||
| regular version and when they push their changes to CI/CD, they will be built | ||
| with Material for MkDocs Insiders. For this reason, it's recommended to | ||
| [install Insiders][12] only in CI, as you don't want to expose your `GH_TOKEN` | ||
| to users. | ||
|
|
||
| ### Terms | ||
|
|
||
| _We're using Material for MkDocs to build the developer documentation of a | ||
| commercial project. Can we use Material for MkDocs Insiders under the same | ||
| terms?_ | ||
|
|
||
| Yes. Whether you're an individual or a company, you may use _Material for MkDocs | ||
| Insiders_ precisely under the same terms as Material for MkDocs, which are given | ||
| by the [MIT license][13]. However, we kindly ask you to respect the following | ||
| guidelines: | ||
|
|
||
| - Please __don't distribute the source code__ from Material for MkDocs Insiders. | ||
| You may freely use it for public, private or commercial projects, fork it, | ||
| mirror it, do whatever you want with it, but please don't release the source | ||
| code, as it would cannibalize the sponsorware strategy. | ||
|
|
||
| - If you cancel your subscription, you're removed as a collaborator and will | ||
| miss out on future updates of Material for MkDocs Insiders. However, you may | ||
| __use the latest version__ that's available to you __as long as you like__. | ||
| Just remember that __[GitHub deletes private forks][14]__. | ||
|
|
||
| [12]: publishing-your-site.md#github-pages | ||
| [13]: license.md | ||
| [14]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository |
| @@ -0,0 +1,143 @@ | ||
| --- | ||
| template: overrides/main.html | ||
| --- | ||
|
|
||
| # Publishing your site | ||
|
|
||
| The great thing about hosting project documentation in a `git` repository is | ||
| the ability to deploy it automatically when new changes are pushed. MkDocs | ||
| makes this ridiculously simple. | ||
|
|
||
| ## GitHub Pages | ||
|
|
||
| If you're already hosting your code on GitHub, [GitHub Pages][1] is certainly | ||
| the most convenient way to publish your project documentation. It's free of | ||
| charge and pretty easy to set up. | ||
|
|
||
| [1]: https://pages.github.com/ | ||
|
|
||
| ### with GitHub Actions | ||
|
|
||
| Using [GitHub Actions][2] you can automate the deployment of your project | ||
| documentation. At the root of your repository, create a new GitHub Actions | ||
| workflow, e.g. `.github/workflows/ci.yml`, and copy and paste the following | ||
| contents: | ||
|
|
||
| === "Material for MkDocs" | ||
|
|
||
| ``` yaml | ||
| name: ci | ||
| on: | ||
| push: | ||
| branches: | ||
| - master | ||
| jobs: | ||
| deploy: | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - uses: actions/checkout@v2 | ||
| - uses: actions/setup-python@v2 | ||
| with: | ||
| python-version: 3.x | ||
| - run: pip install mkdocs-material | ||
| - run: mkdocs gh-deploy --force | ||
| ``` | ||
|
|
||
| === "Insiders" | ||
|
|
||
| ``` yaml | ||
| name: ci | ||
| on: | ||
| push: | ||
| branches: | ||
| - master | ||
| jobs: | ||
| deploy: | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - uses: actions/checkout@v2 | ||
| - uses: actions/setup-python@v2 | ||
| with: | ||
| python-version: 3.x | ||
| - run: pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git | ||
| - run: mkdocs gh-deploy --force | ||
| env: | ||
| GH_TOKEN: ${{ secrets.GH_TOKEN }} | ||
| ``` | ||
|
|
||
| Now, when a new commit is pushed to `master`, the static site is automatically | ||
| built and deployed. Commit and push the file to your repository to see the | ||
| workflow in action. | ||
|
|
||
| Your documentation should shortly appear at `<username>.github.io/<repository>`. | ||
|
|
||
| _Remember to set the_ `GH_TOKEN` _environment variable to the value of your | ||
| [personal access token][3] when using [Material for MkDocs Insiders][4], which | ||
| can be done using [secrets][5]._ | ||
|
|
||
| [2]: https://github.com/features/actions | ||
| [3]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token | ||
| [4]: insiders.md | ||
| [5]: https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets | ||
|
|
||
| ### with MkDocs | ||
|
|
||
| If you prefer to deploy your project documentation manually, you can just invoke | ||
| the following command from the directory containing the `mkdocs.yml` file: | ||
|
|
||
| ``` | ||
| mkdocs gh-deploy --force | ||
| ``` | ||
|
|
||
| ## GitLab Pages | ||
|
|
||
| If you're hosting your code on GitLab, deploying to [GitLab Pages][6] can be | ||
| done by using the [GitLab CI][7] task runner. At the root of your repository, | ||
| create a task definition named `.gitlab-ci.yml` and copy and paste the | ||
| following contents: | ||
|
|
||
| === "Material for MkDocs" | ||
|
|
||
| ``` yaml | ||
| image: python:latest | ||
| deploy: | ||
| stage: deploy | ||
| only: | ||
| - master | ||
| script: | ||
| - pip install mkdocs-material | ||
| - mkdocs build --site-dir public | ||
| artifacts: | ||
| paths: | ||
| - public | ||
| ``` | ||
|
|
||
| === "Insiders" | ||
|
|
||
| ``` yaml | ||
| image: python:latest | ||
| deploy: | ||
| stage: deploy | ||
| only: | ||
| - master | ||
| script: | ||
| - pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git | ||
| - mkdocs build --site-dir public | ||
| artifacts: | ||
| paths: | ||
| - public | ||
| ``` | ||
|
|
||
| Now, when a new commit is pushed to `master`, the static site is automatically | ||
| built and deployed. Commit and push the file to your repository to see the | ||
| workflow in action. | ||
|
|
||
| Your documentation should shortly appear at `<username>.gitlab.io/<repository>`. | ||
|
|
||
| _Remember to set the_ `GH_TOKEN` _environment variable to the value of your | ||
| [personal access token][3] when using [Material for MkDocs Insiders][4], which | ||
| can be done using [masked custom variables][8]._ | ||
|
|
||
| [6]: https://gitlab.com/pages | ||
| [7]: https://docs.gitlab.com/ee/ci/ | ||
| [8]: https://docs.gitlab.com/ee/ci/variables/#create-a-custom-variable-in-the-ui |
| @@ -0,0 +1,99 @@ | ||
| --- | ||
| template: overrides/main.html | ||
| --- | ||
|
|
||
| # Abbreviations | ||
|
|
||
| Technical documentation often incurs the usage of a lot of acronyms, which may | ||
| need additional explanation, especially for new user of your project. For these | ||
| matters, Material for MkDocs uses a combination of Markdown extensions to | ||
| enable site-wide glossaries. | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Abbreviations | ||
|
|
||
| The [Abbreviations][1] extension, which is part of the standard Markdown | ||
| library, allows to __add additional content to parts of the text which are then | ||
| shown on hover__, e.g. for glossaries: | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - abbr | ||
| ``` | ||
|
|
||
| [1]: https://python-markdown.github.io/extensions/abbreviations/ | ||
|
|
||
| ### Snippets | ||
|
|
||
| The [Snippets][2] extension, which is part of [Python Markdown Extensions][3], | ||
| allows to __insert content from other files__ or other, regular content, and can | ||
| be enabled via `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - pymdownx.snippets | ||
| ``` | ||
|
|
||
| [2]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/ | ||
| [3]: https://facelessuser.github.io/pymdown-extensions/ | ||
|
|
||
| ## Usage | ||
|
|
||
| ### Adding abbreviations | ||
|
|
||
| When the [Abbreviations][4] extension is enabled, abbreviations can be defined | ||
| with a special syntax similar to URLs and [footnotes][5] at any point in the | ||
| Markdown document. | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| The HTML specification is maintained by the W3C. | ||
|
|
||
| *[HTML]: Hyper Text Markup Language | ||
| *[W3C]: World Wide Web Consortium | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| The HTML specification is maintained by the W3C. | ||
|
|
||
| *[HTML]: Hyper Text Markup Language | ||
| *[W3C]: World Wide Web Consortium | ||
|
|
||
| [4]: #abbreviations_1 | ||
| [5]: footnotes.md | ||
|
|
||
| ### Adding a glossary | ||
|
|
||
| When [Snippets][6] is enabled, content from other files can be embedded, which | ||
| is especially useful to include abbreviations from a central file – a glossary – | ||
| and embed them into any other file. | ||
|
|
||
| _Example_: | ||
|
|
||
| === "docs/page.md" | ||
|
|
||
| ```` markdown | ||
| The HTML specification is maintained by the W3C. | ||
|
|
||
| --8<-- "includes/abbreviations.md" | ||
| ```` | ||
|
|
||
| === "includes/abbreviations.md" | ||
|
|
||
| ```` markdown | ||
| *[HTML]: Hyper Text Markup Language | ||
| *[W3C]: World Wide Web Consortium | ||
| ```` | ||
|
|
||
| _Result_: | ||
|
|
||
| The HTML specification is maintained by the W3C. | ||
|
|
||
| _Remember to locate the Markdown file containing the definitions outside of the_ | ||
| `docs` _folder (here_ `includes` _is used), or MkDocs may complain about an | ||
| unreferenced file._ | ||
|
|
||
| [6]: #snippets |
| @@ -0,0 +1,83 @@ | ||
| --- | ||
| template: overrides/main.html | ||
| --- | ||
|
|
||
| # Buttons | ||
|
|
||
| Material for MkDocs provides dedicated styles for primary and secondary buttons | ||
| that can be added to any link, `label` or `button` element. This is especially | ||
| useful for documents or landing pages with dedicated _call-to-actions_. | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Attribute List | ||
|
|
||
| The [Attribute List][1] extension, which is part of the standard Markdown | ||
| library, allows to __add HTML attributes and CSS classes to Markdown elements__, | ||
| and can be enabled via `mkdocs.yml` | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - attr_list | ||
| ``` | ||
|
|
||
| [1]: https://python-markdown.github.io/extensions/attr_list/ | ||
|
|
||
| ## Usage | ||
|
|
||
| ### Adding buttons | ||
|
|
||
| When the [Attribute List][2] extension is enabled, any clickable element can be | ||
| converted into a button by adding the `.md-button` CSS class, which will receive | ||
| the selected [primary color][3]. | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| [Subscribe to our mailing list](#){: .md-button } | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| [Subscribe to our mailing list][4]{: .md-button } | ||
|
|
||
| [2]: #attribute-list | ||
| [3]: ../setup/changing-the-colors.md#primary-color | ||
| [4]: javascript:app.dialog$.next("Done!") | ||
|
|
||
| ### Adding primary buttons | ||
|
|
||
| If you want to display a filled, primary button (like on the [landing page][5] | ||
| of Material for MkDocs), add both the `.md-button` and `.md-button--primary` | ||
| CSS classes. | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| [Subscribe to our mailing list](#){: .md-button .md-button--primary } | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| [Subscribe to our mailing list][4]{: .md-button .md-button--primary } | ||
|
|
||
| [5]: ../index.md | ||
|
|
||
| ### Adding icon buttons | ||
|
|
||
| Of course, icons can be added to both types of buttons by using the [regular | ||
| icon syntax][6] and referencing a valid path to [any icon bundled with the | ||
| theme][7]. | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| [Submit :fontawesome-solid-paper-plane:](#){: .md-button .md-button--primary } | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| [Submit :fontawesome-solid-paper-plane:][4]{: .md-button .md-button--primary } | ||
|
|
||
| [6]: icons-emojis.md#using-icons | ||
| [7]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons |
| @@ -0,0 +1,387 @@ | ||
| --- | ||
| template: overrides/main.html | ||
| --- | ||
|
|
||
| # Code blocks | ||
|
|
||
| Code blocks and examples are an essential part of technical project | ||
| documentation. Material for MkDocs provides different ways to set up syntax | ||
| highlighting for code blocks, either during build time using [Pygments][1] or | ||
| during runtime using a JavaScript syntax highlighter. | ||
|
|
||
| [1]: https://pygments.org | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Highlight | ||
|
|
||
| [:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3] · | ||
| :octicons-zap-24: Supersedes: [CodeHilite][4] | ||
|
|
||
| The [Highlight][3] extension, which is part of [Python Markdown Extensions][5], | ||
| integrates with Material for MkDocs and provides several options for | ||
| configuring syntax highlighting of code blocks: | ||
|
|
||
| `use_pygments`{: #use-pygments } | ||
|
|
||
| : :octicons-milestone-24: Default: `true` – This option allows to control | ||
| whether highlighting should be carried out during build time by | ||
| [Pygments][1] or runtime with a JavaScript highlighter. Remember to add the | ||
| necessary [additional stylesheets][6] and [JavaScript][7] if you want to | ||
| use the latter: | ||
|
|
||
| === "Pygments" | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - pymdownx.highlight | ||
| - pymdownx.superfences | ||
| ``` | ||
|
|
||
| === "JavaScript" | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - pymdownx.highlight: | ||
| use_pygments: false | ||
| ``` | ||
|
|
||
| ??? example "Syntax highlighting with Highlight.js" | ||
|
|
||
| [Highlight.js][8] can be integrated by creating an [additional | ||
| JavaScript][7] file initializing the highlighter and including the | ||
| respective stylesheet and JavaScript from a [CDN][9] serving | ||
| Highlight.js in `mkdocs.yml`: | ||
|
|
||
| === "docs/javascripts/config.js" | ||
|
|
||
| ``` js | ||
| hljs.initHighlighting() | ||
| ``` | ||
|
|
||
| === "mkdocs.yml" | ||
|
|
||
| ``` yaml | ||
| extra_javascript: | ||
| - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/highlight.min.js | ||
| - javascripts/config.js | ||
| extra_css: | ||
| - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/styles/default.min.css | ||
| ``` | ||
|
|
||
| Note that Highlight.js has no affiliation with the Highlight extension. | ||
|
|
||
| `linenums`{: #linenums } | ||
|
|
||
| : :octicons-milestone-24: Default: `false` – This option will add line numbers | ||
| to _all_ code blocks. If you wish to add line numbers to _some_, but not all | ||
| code blocks, consult the section on [adding line numbers][10] later in this | ||
| document, which also contains some tips on working with line numbers: | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - pymdownx.highlight: | ||
| linenums: true | ||
| ``` | ||
|
|
||
| `linenums_style`{: #linenums-style } | ||
|
|
||
| : :octicons-milestone-24: Default: `table` – The Highlight extension provides | ||
| three ways to add line numbers, all of which are supported by Material for | ||
| MkDocs. While `table` wraps a code block in a table, `inline` and | ||
| `pymdownx.inline` render line numbers as part of the line itself: | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - pymdownx.highlight: | ||
| linenums_style: pymdownx.inline | ||
| ``` | ||
|
|
||
| Note that `inline` will put line numbers next to the actual code, which | ||
| means that they will be included when selecting text with the cursor or | ||
| copying a code block to the clipboard. Thus, the usage of `table` or | ||
| `pymdownx.inline` is recommended. | ||
|
|
||
| _Material for MkDocs doesn't provide official support for the other options of | ||
| this extension, so they may be supported but can also yield weird results. Use | ||
| them at your own risk._ | ||
|
|
||
| [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss | ||
| [3]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/ | ||
| [4]: https://python-markdown.github.io/extensions/code_hilite/ | ||
| [5]: https://facelessuser.github.io/pymdown-extensions/ | ||
| [6]: ../customization.md#additional-css | ||
| [7]: ../customization.md#additional-javascript | ||
| [8]: https://highlightjs.org/ | ||
| [9]: https://cdnjs.com/libraries/highlight.js/ | ||
| [10]: #adding-line-numbers | ||
|
|
||
| ### InlineHilite | ||
|
|
||
| [:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][11] | ||
|
|
||
| The [InlineHilite][11] extension, which is part of [Python Markdown | ||
| Extensions][5] also integrates with Material for MkDocs and adds support for | ||
| __syntax highlighting of inline code blocks__. It's built on top of the | ||
| [Highlight][3] extension and can be enabled via `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - pymdownx.inlinehilite | ||
| ``` | ||
|
|
||
| See the section on [inline code blocks][12] for usage information. | ||
|
|
||
| [11]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/ | ||
| [12]: #highlighting-inline-code-blocks | ||
|
|
||
| ### Keys | ||
|
|
||
| [:octicons-file-code-24: Source][13] · [:octicons-workflow-24: Extension][14] | ||
|
|
||
| The [Keys][14] extension, which is part of [Python Markdown Extensions][5], | ||
| allows for inserting __keyboard keys__, e.g. ++ctrl+alt+delete++ , and | ||
| can be enabled via `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - pymdownx.keys | ||
| ``` | ||
|
|
||
| [13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_keys.scss | ||
| [14]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/ | ||
|
|
||
| ### SuperFences | ||
|
|
||
| The [SuperFences][15] extension, which is also part of [Python Markdown | ||
| Extensions][5], allows for the __nesting of code blocks inside other blocks__, | ||
| and is therefore strongly recommended: | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - pymdownx.superfences | ||
| ``` | ||
|
|
||
| [15]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/ | ||
|
|
||
| ### Snippets | ||
|
|
||
| The [Snippets][16] extension, which is also part of [Python Markdown | ||
| Extensions][5], allows to __insert content from other files__ or other, regular | ||
| content, and can be enabled via `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - pymdownx.snippets | ||
| ``` | ||
|
|
||
| [16]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/ | ||
|
|
||
| ## Usage | ||
|
|
||
| This section discusses how to use different syntax highlighting features with | ||
| [Pygments][1] – the default highlighter – so they don't apply when using | ||
| a JavaScript syntax highlighter. | ||
|
|
||
| ### Specifying the language | ||
|
|
||
| Code blocks must be enclosed with two separate lines containing three backticks. | ||
| To add code highlighting to those blocks, add the language short name directly | ||
| after the opening block. See the [list of available lexers][17] to find the | ||
| short name for a given language. | ||
|
|
||
| _Example_: | ||
|
|
||
| ```` markdown | ||
| ``` python | ||
| import tensorflow as tf | ||
| ``` | ||
| ```` | ||
|
|
||
| _Result_: | ||
|
|
||
| ``` python | ||
| import tensorflow as tf | ||
| ``` | ||
|
|
||
| [17]: https://pygments.org/docs/lexers/ | ||
|
|
||
| ### Adding line numbers | ||
|
|
||
| Line numbers can be added to a code block by using the `linenums="<start>"` | ||
| option directly after the short name, whereas `<start>` represents the starting | ||
| line number. A code block can start from a line number other than `1`, which | ||
| allows splitting large code blocks for readability. | ||
|
|
||
| _Example_: | ||
|
|
||
| ```` markdown | ||
| ``` python linenums="1" | ||
| def bubble_sort(items): | ||
| for i in range(len(items)): | ||
| for j in range(len(items) - 1 - i): | ||
| if items[j] > items[j + 1]: | ||
| items[j], items[j + 1] = items[j + 1], items[j] | ||
| ``` | ||
| ```` | ||
|
|
||
| _Result_: | ||
|
|
||
| ``` python linenums="1" | ||
| def bubble_sort(items): | ||
| for i in range(len(items)): | ||
| for j in range(len(items) - 1 - i): | ||
| if items[j] > items[j + 1]: | ||
| items[j], items[j + 1] = items[j + 1], items[j] | ||
| ``` | ||
|
|
||
| ### Highlighting specific lines | ||
|
|
||
| Specific lines can be highlighted by passing the line numbers to the `hl_lines` | ||
| argument placed right after the language short name. Note that line counts start | ||
| at `1`, regardless of the starting line number specified as part of `linenums`. | ||
|
|
||
| _Example_: | ||
|
|
||
| ```` markdown | ||
| ``` python hl_lines="2 3" | ||
| def bubble_sort(items): | ||
| for i in range(len(items)): | ||
| for j in range(len(items) - 1 - i): | ||
| if items[j] > items[j + 1]: | ||
| items[j], items[j + 1] = items[j + 1], items[j] | ||
| ``` | ||
| ```` | ||
|
|
||
| _Result_: | ||
|
|
||
| ``` python hl_lines="2 3" | ||
| def bubble_sort(items): | ||
| for i in range(len(items)): | ||
| for j in range(len(items) - 1 - i): | ||
| if items[j] > items[j + 1]: | ||
| items[j], items[j + 1] = items[j + 1], items[j] | ||
| ``` | ||
|
|
||
| ### Highlighting inline code blocks | ||
|
|
||
| When [InlineHilite][18] is enabled, inline code blocks can be highlighted by | ||
| prefixing them with a shebang-like sequence, i.e. `#!`, directly followed by | ||
| the [language short name][17]. | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| The `#!python range()` function is used to generate a sequence of numbers. | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| The `#!python range()` function is used to generate a sequence of numbers. | ||
|
|
||
| [18]: #inlinehilite | ||
|
|
||
| ### Adding keyboard keys | ||
|
|
||
| When [Keys][19] is enabled, keyboard keys can be rendered with a simple syntax. | ||
| Consult the [Python Markdown Extensions][16] documentation to learn about all | ||
| available key codes. | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| ++ctrl+alt+del++ | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| ++ctrl+alt+del++ | ||
|
|
||
| [19]: #keys | ||
|
|
||
| ### Embedding external files | ||
|
|
||
| _Also known as transcludes or file transclusion in [MultiMarkdown][20]_. | ||
|
|
||
| When [Snippets][21] is enabled, content from other files can be embedded, which | ||
| is especially useful to reference and embed the contents of source files | ||
| directly into your project documentation. | ||
|
|
||
| _Example_: | ||
|
|
||
| ```` markdown | ||
| ``` | ||
| --8<-- ".browserslistrc" | ||
| ``` | ||
| ```` | ||
|
|
||
| _Result_: | ||
|
|
||
| ``` | ||
| --8<-- ".browserslistrc" | ||
| ``` | ||
|
|
||
| Note that [Snippets][21] is not limited to code blocks, but can be used anywhere | ||
| from a document to move repeating content to separate files, which is also | ||
| explained in the [official documentation][16]. | ||
|
|
||
| [20]: https://fletcher.github.io/MultiMarkdown-5/transclusion.html | ||
| [21]: #snippets | ||
|
|
||
| ## Customization | ||
|
|
||
| ### Custom syntax theme | ||
|
|
||
| [:octicons-file-code-24: Source][22] · | ||
| :octicons-mortar-board-24: Difficulty: _easy_ | ||
|
|
||
| If [Pygments][23] is used, Material for MkDocs provides the [styles for code | ||
| blocks][22], which are built with a custom and well-balanced palette that works | ||
| equally well for both [color schemes][24]: | ||
|
|
||
| * :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-number-color) " } `--md-code-hl-number-color` | ||
| * :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-special-color) " } `--md-code-hl-special-color` | ||
| * :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-function-color) " } `--md-code-hl-function-color` | ||
| * :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-constant-color) " } `--md-code-hl-constant-color` | ||
| * :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-keyword-color) " } `--md-code-hl-keyword-color` | ||
| * :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-string-color) " } `--md-code-hl-string-color` | ||
| * :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-name-color) " } `--md-code-hl-name-color` | ||
| * :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-operator-color) " } `--md-code-hl-operator-color` | ||
| * :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-punctuation-color) " } `--md-code-hl-punctuation-color` | ||
| * :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-comment-color) " } `--md-code-hl-comment-color` | ||
| * :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-generic-color) " } `--md-code-hl-generic-color` | ||
| * :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-variable-color) " } `--md-code-hl-variable-color` | ||
|
|
||
| Code block foreground, background and line highlight colors are defined via: | ||
|
|
||
| * :material-checkbox-blank-circle:{: style="color: var(--md-code-fg-color) " } `--md-code-fg-color` | ||
| * :material-checkbox-blank-circle:{: style="color: var(--md-code-bg-color) " } `--md-code-bg-color` | ||
| * :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-color) " } `--md-code-hl-color` | ||
|
|
||
| Let's say you want to change the color of `#!js "strings"`. While there are | ||
| several [types of string tokens][25], Material for MkDocs assigns a single color | ||
| to most of them. | ||
|
|
||
| Create an [additional stylesheet][6], and add: | ||
|
|
||
| ``` css | ||
| :root > * { | ||
| --md-code-hl-string-color: #0FF1CE; | ||
| } | ||
| ``` | ||
|
|
||
| If you want to tweak a specific type of string, i.e. ``#!js `backticks` ``, you | ||
| can lookup the specific class name in the [syntax theme definition][26], and | ||
| override it as part of your additional stylesheet: | ||
|
|
||
| ``` css | ||
| .highlight .sb { | ||
| color: #0FF1CE; | ||
| } | ||
| ``` | ||
|
|
||
| [22]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss#L60-L73 | ||
| [23]: #use-pygments | ||
| [24]: ../setup/changing-the-colors.md#color-scheme | ||
| [25]: https://pygments.org/docs/tokens/#literals | ||
| [26]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_codehilite.scss#L42 |
| @@ -0,0 +1,218 @@ | ||
| --- | ||
| template: overrides/main.html | ||
| --- | ||
|
|
||
| # Content tabs | ||
|
|
||
| Sometimes, it's desirable to group alternative content under different tabs, | ||
| e.g. when describing how to access an API from different languages or | ||
| environments. Material for MkDocs allows for beautiful and functional tabs, grouping code blocks and other content. | ||
|
|
||
| ## Configuration | ||
|
|
||
| ### Tabbed | ||
|
|
||
| [:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2] | ||
|
|
||
| The [Tabbed][2] extension, which is part of [Python Markdown Extensions][3], | ||
| integrates with Material for MkDocs and can be enabled via `mkdocs.yml`: | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - pymdownx.tabbed | ||
| ``` | ||
|
|
||
| [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_tabbed.scss | ||
| [2]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/ | ||
| [3]: https://facelessuser.github.io/pymdown-extensions/ | ||
|
|
||
| ### SuperFences | ||
|
|
||
| The [SuperFences][4] extension, which is also part of [Python Markdown | ||
| Extensions][3], allows for the __nesting of code and content blocks inside | ||
| tabs__, and is therefore strongly recommended: | ||
|
|
||
| ``` yaml | ||
| markdown_extensions: | ||
| - pymdownx.superfences | ||
| ``` | ||
|
|
||
| [4]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/ | ||
|
|
||
| ## Usage | ||
|
|
||
| ### Grouping code blocks | ||
|
|
||
| Code blocks are one of the primary targets to be grouped, and can be considered | ||
| a special case of content tabs, as tabs with a single code block are always | ||
| rendered without horizontal spacing. | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` | ||
| === "C" | ||
| ``` c | ||
| #include <stdio.h> | ||
| int main(void) { | ||
| printf("Hello world!\n"); | ||
| return 0; | ||
| } | ||
| ``` | ||
|
|
||
| === "C++" | ||
|
|
||
| ``` c++ | ||
| #include <iostream> | ||
| int main(void) { | ||
| std::cout << "Hello world!" << std::endl; | ||
| return 0; | ||
| } | ||
| ``` | ||
| ``` | ||
| _Result_: | ||
| === "C" | ||
| ``` c | ||
| #include <stdio.h> | ||
| int main(void) { | ||
| printf("Hello world!\n"); | ||
| return 0; | ||
| } | ||
| ``` | ||
|
|
||
| === "C++" | ||
|
|
||
| ``` c++ | ||
| #include <iostream> | ||
| int main(void) { | ||
| std::cout << "Hello world!" << std::endl; | ||
| return 0; | ||
| } | ||
| ``` | ||
|
|
||
| ### Grouping other content | ||
|
|
||
| When a content tab contains more than one code block, it is rendered with | ||
| horizontal spacing. Vertical spacing is never added, but can be achieved | ||
| by nesting tabs in other blocks. | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` | ||
| === "Unordered list" | ||
| * Sed sagittis eleifend rutrum | ||
| * Donec vitae suscipit est | ||
| * Nulla tempor lobortis orci | ||
| === "Ordered list" | ||
| 1. Sed sagittis eleifend rutrum | ||
| 2. Donec vitae suscipit est | ||
| 3. Nulla tempor lobortis orci | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| === "Unordered list" | ||
|
|
||
| * Sed sagittis eleifend rutrum | ||
| * Donec vitae suscipit est | ||
| * Nulla tempor lobortis orci | ||
|
|
||
| === "Ordered list" | ||
|
|
||
| 1. Sed sagittis eleifend rutrum | ||
| 2. Donec vitae suscipit est | ||
| 3. Nulla tempor lobortis orci | ||
|
|
||
| ### Embedded content | ||
|
|
||
| When [SuperFences][5] is enabled, content tabs can contain arbitrary nested | ||
| content, including further content tabs, and can be nested in other blocks like | ||
| [admonitions][6], [details][7] or blockquotes: | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| !!! example | ||
|
|
||
| === "Unordered List" | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| * Sed sagittis eleifend rutrum | ||
| * Donec vitae suscipit est | ||
| * Nulla tempor lobortis orci | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| * Sed sagittis eleifend rutrum | ||
| * Donec vitae suscipit est | ||
| * Nulla tempor lobortis orci | ||
|
|
||
| === "Ordered List" | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| 1. Sed sagittis eleifend rutrum | ||
| 2. Donec vitae suscipit est | ||
| 3. Nulla tempor lobortis orci | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| 1. Sed sagittis eleifend rutrum | ||
| 2. Donec vitae suscipit est | ||
| 3. Nulla tempor lobortis orci | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| !!! example | ||
|
|
||
| === "Unordered List" | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| * Sed sagittis eleifend rutrum | ||
| * Donec vitae suscipit est | ||
| * Nulla tempor lobortis orci | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| * Sed sagittis eleifend rutrum | ||
| * Donec vitae suscipit est | ||
| * Nulla tempor lobortis orci | ||
|
|
||
| === "Ordered List" | ||
|
|
||
| _Example_: | ||
|
|
||
| ``` markdown | ||
| 1. Sed sagittis eleifend rutrum | ||
| 2. Donec vitae suscipit est | ||
| 3. Nulla tempor lobortis orci | ||
| ``` | ||
|
|
||
| _Result_: | ||
|
|
||
| 1. Sed sagittis eleifend rutrum | ||
| 2. Donec vitae suscipit est | ||
| 3. Nulla tempor lobortis orci | ||
|
|
||
| [5]: #superfences | ||
| [6]: admonitions.md | ||
| [7]: admonitions.md#details |