OpenSourceArk/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-06-14 11:52:32 +03:00
Code Issues Packages Projects Releases Wiki Activity

Updated documentation

Browse Source
This commit is contained in:
squidfunk 2020-12-21 17:38:58 +01:00
parent 7a9147cfb7
commit 65b41bbc9d
42 changed files with 730 additions and 733 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
CHANGELOG
View File

@ -1,13 +1,13 @@
mkdocs-material-6.1.7+insiders-1.13.1 (2020-12-20) mkdocs-material-6.1.7+insiders-1.13.1 (2020-12-20)
* Removed horizontal scrollbars on language and version selector * Fixed horizontal scrollbars for language and version selection
* Fixed type conversion in JavaScript config (#6) * Fixed type conversion in JavaScript config (#6)
mkdocs-material-6.1.7+insiders-1.13.0 (2020-12-13) mkdocs-material-6.1.7+insiders-1.13.0 (2020-12-13)
* Refactored navigation tabs to simplify grouping behavior
* Added support for sticky navigation tabs * Added support for sticky navigation tabs
* Added support for arbitrary links in navigation tabs * Added support for arbitrary links in navigation tabs
* Refactored navigation tabs to simplify grouping behavior
* Fixed #2098: Subsequent active subsection not highlighted correctly * Fixed #2098: Subsequent active subsection not highlighted correctly
mkdocs-material-6.1.7+insiders-1.12.1 (2020-12-08) mkdocs-material-6.1.7+insiders-1.12.1 (2020-12-08)

BIN
docs/assets/screenshots/color-palette-toggle.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 132 KiB

94
docs/changelog.md
View File

@ -4,100 +4,6 @@ template: overrides/main.html
# Changelog # Changelog
## Material for MkDocs Insiders
### 1.13.1 <small>_ December 13, 2020</small>
- Removed horizontal scrollbars on language and version selector
- Fixed type conversion in JavaScript config
### 1.13.0 <small>_ December 13, 2020</small>
- Refactored navigation tabs to simplify grouping behavior
- Added support for sticky navigation tabs
- Added support for arbitrary links in navigation tabs
- Fixed #2098: Subsequent active subsection not highlighted correctly
### 1.12.1 <small>_ December 8, 2020</small>
- Fixed empty language selector being shown
### 1.12.0 <small>_ December 6, 2020</small>
- Added support for adding a language selector
### 1.11.2 <small>_ November 29, 2020</small>
- Fixed #2068: Search highlight interprets code blocks as JavaScript
### 1.11.1 <small>_ November 29, 2020</small>
- Refactored styling to be more stable and easier to adjust
- Fixed some styling regressions from latest features
### 1.11.0 <small>_ November 22, 2020</small>
- Added support for rendering admonitions as inline blocks
### 1.10.0 <small>_ November 15, 2020</small>
- Added support for integrating table of contents into navigation
### 1.9.0 <small>_ November 7, 2020</small>
- Added support for hiding navigation and table of contents on any page
- Removed autohiding table of contents when empty
### 1.8.0 <small>_ November 1, 2020</small>
- Added support for navigation sections
- Fixed appearance of inactive search suggestions
### 1.7.0 <small>_ October 25, 2020</small>
- Added support for deploying multiple versions
- Fixed alignment of sidebar when content area is too small
### 1.6.0 <small>_ October 11, 2020</small>
- Added support for search suggestions to save keystrokes
- Added support for removing __Made with Material for MkDocs__ from footer
- Fixed #1915: search should go to first result by pressing ++enter++
### 1.5.1 <small>_ September 21, 2020</small>
- Fixed content area stretching to whole width for long code blocks
### 1.5.0 <small>_ September 19, 2020</small>
- Added support for autohiding table of contents when empty
### 1.4.1 <small>_ September 6, 2020</small>
- Improved typeahead and search result relevance and scoring
### 1.4.0 <small>_ August 30, 2020</small>
- Added support for autohiding header on scroll
### 1.3.0 <small>_ August 26, 2020</small>
- Added support for user-selectable color palettes
### 1.2.0 <small>_ August 11, 2020</small>
- Added feature to expand navigation by default
### 1.1.0 <small>_ August 3, 2020</small>
- Added highlighting of search results
### 1.0.0 <small>_ July 14, 2020</small>
- Added grouping of search results
- Added missing query terms to search result
- Improved search result relevance and scoring
## Material for MkDocs ## Material for MkDocs
### 6.1.7 <small>_ December 6, 2020</small> ### 6.1.7 <small>_ December 6, 2020</small>

99
docs/changelog/insiders.md Normal file
View File

@ -0,0 +1,99 @@
---
template: overrides/main.html
---
# Changelog
## Material for MkDocs Insiders
### 1.13.1 <small>_ December 20, 2020</small>
- Removed horizontal scrollbars on language and version selector
- Fixed type conversion in JavaScript config
### 1.13.0 <small>_ December 13, 2020</small>
- Refactored navigation tabs to simplify grouping behavior
- Added support for sticky navigation tabs
- Added support for arbitrary links in navigation tabs
- Fixed #2098: Subsequent active subsection not highlighted correctly
### 1.12.1 <small>_ December 8, 2020</small>
- Fixed empty language selector being shown
### 1.12.0 <small>_ December 6, 2020</small>
- Added support for adding a language selector
### 1.11.2 <small>_ November 29, 2020</small>
- Fixed #2068: Search highlight interprets code blocks as JavaScript
### 1.11.1 <small>_ November 29, 2020</small>
- Refactored styling to be more stable and easier to adjust
- Fixed some styling regressions from latest features
### 1.11.0 <small>_ November 22, 2020</small>
- Added support for rendering admonitions as inline blocks
### 1.10.0 <small>_ November 15, 2020</small>
- Added support for integrating table of contents into navigation
### 1.9.0 <small>_ November 7, 2020</small>
- Added support for hiding navigation and table of contents on any page
- Removed autohiding table of contents when empty
### 1.8.0 <small>_ November 1, 2020</small>
- Added support for navigation sections
- Fixed appearance of inactive search suggestions
### 1.7.0 <small>_ October 25, 2020</small>
- Added support for deploying multiple versions
- Fixed alignment of sidebar when content area is too small
### 1.6.0 <small>_ October 11, 2020</small>
- Added support for search suggestions to save keystrokes
- Added support for removing __Made with Material for MkDocs__ from footer
- Fixed #1915: search should go to first result by pressing ++enter++
### 1.5.1 <small>_ September 21, 2020</small>
- Fixed content area stretching to whole width for long code blocks
### 1.5.0 <small>_ September 19, 2020</small>
- Added support for autohiding table of contents when empty
### 1.4.1 <small>_ September 6, 2020</small>
- Improved typeahead and search result relevance and scoring
### 1.4.0 <small>_ August 30, 2020</small>
- Added support for autohiding header on scroll
### 1.3.0 <small>_ August 26, 2020</small>
- Added support for user-selectable color palettes
### 1.2.0 <small>_ August 11, 2020</small>
- Added feature to expand navigation by default
### 1.1.0 <small>_ August 3, 2020</small>
- Added highlighting of search results
### 1.0.0 <small>_ July 14, 2020</small>
- Added grouping of search results
- Added missing query terms to search result
- Improved search result relevance and scoring

10
docs/creating-your-site.md
View File

@ -87,9 +87,11 @@ defaults, because_ [`mkdocs_theme.yml`][3] _is not loaded automatically as
### Advanced configuration ### Advanced configuration
Material for MkDocs comes with a lot of configuration options. The _setup_ Material for MkDocs comes with many configuration options. The _setup_ section
section explains in great detail how to configure and customize colors, fonts, explains in great detail how to configure and customize colors, fonts, icons
icons and much more: and much more:
<div class="tx-columns" markdown="1">
- [Changing the colors][5] - [Changing the colors][5]
- [Changing the fonts][6] - [Changing the fonts][6]
@ -104,6 +106,8 @@ icons and much more:
- [Adding a git repository][15] - [Adding a git repository][15]
- [Adding a comment system][16] - [Adding a comment system][16]
</div>
[5]: setup/changing-the-colors.md [5]: setup/changing-the-colors.md
[6]: setup/changing-the-fonts.md [6]: setup/changing-the-fonts.md
[7]: setup/changing-the-language.md [7]: setup/changing-the-language.md

48
docs/getting-started.md
View File

@ -40,9 +40,16 @@ This will automatically install compatible versions of all dependencies:
Material for MkDocs always strives to support the latest versions, so there's Material for MkDocs always strives to support the latest versions, so there's
no need to install those packages separately. no need to install those packages separately.
_Note that in order to install [Material for MkDocs Insiders][8], you'll _Note that in order to install [Insiders][8], you'll need to [become a
need to [become a sponsor][9], create a personal access token[^1], and sponsor][9], create a personal access token[^1], and set the_ `GH_TOKEN`
set the_ `GH_TOKEN` _environment variable to the token's value._ _environment variable to the token's value._
[^1]:
In order to use `pip` to install from the private repository over HTTPS, the
[personal access token][14] requires the [`repo`][15] scope. The creation
and usage of an access token is only necessary when installing Insiders
over HTTPS, which is the recommended way when building from within a CI/CD
workflow, e.g. using [GitHub Pages][16] or [GitLab Pages][17].
[5]: https://python-markdown.github.io/ [5]: https://python-markdown.github.io/
[6]: https://pygments.org/ [6]: https://pygments.org/
@ -78,15 +85,22 @@ The following plugins are bundled with the Docker image:
- [mkdocs-minify-plugin][11] - [mkdocs-minify-plugin][11]
- [mkdocs-redirects][12] - [mkdocs-redirects][12]
_Note that in order to install [Material for MkDocs Insiders][8], you'll _Note that in order to install [Insiders][8], you'll need to [become a
need to [become a sponsor][9], create a personal access token[^2], and sponsor][9], create a personal access token[^2], and set the_ `GH_TOKEN`
set the_ `GH_TOKEN` _environment variable to the token's value._ _environment variable to the token's value._
[^2]:
If you want to use `docker` to pull the private Docker image from the
[GitHub Container Registry][18], the [personal access token][14] requires
the [`read:packages`][15] scope. Note that you need to login before pulling
the Docker image. As an example, see the [`publish`][19] workflow of the
Material for MkDocs repository.
[10]: https://hub.docker.com/r/squidfunk/mkdocs-material/ [10]: https://hub.docker.com/r/squidfunk/mkdocs-material/
[11]: https://github.com/byrnereese/mkdocs-minify-plugin [11]: https://github.com/byrnereese/mkdocs-minify-plugin
[12]: https://github.com/datarobot/mkdocs-redirects [12]: https://github.com/datarobot/mkdocs-redirects
??? question "How can I add plugins to the Docker image?" ??? question "How to add plugins to the Docker image?"
Material for MkDocs bundles useful and common plugins while trying not to Material for MkDocs bundles useful and common plugins while trying not to
blow up the size of the official image. If the plugin you want to use is blow up the size of the official image. If the plugin you want to use is
@ -131,28 +145,14 @@ from `git`, you must install all required dependencies yourself:
pip install -r mkdocs-material/requirements.txt pip install -r mkdocs-material/requirements.txt
``` ```
_Note that in order to install [Material for MkDocs Insiders][8], you'll _Note that in order to install [Insiders][8], you'll need to [become a
need to [become a sponsor][9]._ sponsor][9]._
[13]: https://github.com/squidfunk/mkdocs-material [13]: https://github.com/squidfunk/mkdocs-material
[^1]:
In order to use `pip` to install from the private repository over HTTPS, the
[personal access token][14] requires the [`repo`][15] scope. The creation
and usage of an access token is only necessary when installing Insiders
over HTTPS, which is the recommended way when building from within a CI/CD
workflow, e.g. using [GitHub Pages][16] or [GitLab Pages][17].
[^2]:
If you want to use `docker` to pull the private Docker image from the
[GitHub Container Registry][18], the [personal access token][14] requires
the [`read:packages`][15] scope. Note that you need to login before pulling
the Docker image. As an example, see the [`publish`][19] workflow of the
Material for MkDocs repository.
[14]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token [14]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
[15]: https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes [15]: https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes
[16]: publishing-your-site.md#github-pages [16]: publishing-your-site.md#github-pages
[17]: publishing-your-site.md#gitlab-pages [17]: publishing-your-site.md#gitlab-pages
[18]: https://docs.github.com/en/free-pro-team@latest/packages/getting-started-with-github-container-registry/about-github-container-registry [18]: https://docs.github.com/en/free-pro-team@latest/packages/getting-started-with-github-container-registry/about-github-container-registry
[19]: https://github.com/squidfunk/mkdocs-material/blob/master/.github/workflows/publish.yml#L72-L77 [19]: https://github.com/squidfunk/mkdocs-material/blob/master/.github/workflows/publish.yml

369
docs/insiders.md
View File

@ -4,267 +4,230 @@ template: overrides/main.html
# <span hidden>Insiders</span> :logo: :material-plus: :octicons-heart-fill-24:{: .tx-heart } # <span hidden>Insiders</span> :logo: :material-plus: :octicons-heart-fill-24:{: .tx-heart }
Material for MkDocs uses the [sponsorware][1] release strategy, which means Material for MkDocs uses the _sponsorware_ release strategy, which means
that _new features are first exclusively released to sponsors_ as part of that _new features are first exclusively released to sponsors_ as part of
__Material for MkDocs Insiders__. Read on to learn [how sponsorship works][2], __Insiders__. Read on to learn [how sponsorship works][1], and how easy it is
and how you can [become a sponsor][3]. to [get access to Insiders][2].
[1]: https://github.com/sponsorware/docs <figure class="tx-video" markdown="1">
[2]: #how-sponsorship-works <div class="tx-video__inner">
[3]: #how-to-become-a-sponsor <iframe src="https://streamable.com/e/b6ij21" allowfullscreen></iframe>
</div>
<figcaption markdown="1">
A demo is worth a thousand words — check it out at
[squidfunk.github.io/mkdocs-material-insiders][3]
</figcaption>
</figure>
<div style="width:100%;height:0px;position:relative;padding-bottom:56.138%;"> [1]: #how-sponsorship-works
<iframe src="https://streamable.com/e/b6ij21" frameborder="0" width="100%" height="100%" allowfullscreen style="width:100%;height:100%;position:absolute;left:0px;top:0px;overflow:hidden;"></iframe> [2]: #how-to-become-a-sponsor
</div> [3]: https://squidfunk.github.io/mkdocs-material-insiders/
<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 ## How sponsorship works
New features will first land in Material for MkDocs Insiders, which means that New features first land in Insiders, which means that _sponsors will have access
_sponsors will have access immediately_. Every feature is tied to a funding immediately_. Every feature is tied to a funding goal in monthly subscriptions.
goal in monthly subscriptions. If a funding goal is hit, the features that are When a funding goal is hit, the features that are tied to it are merged back
tied to it are merged back into Material for MkDocs and released for general into Material for MkDocs and released for general availability. Bugfixes are
availability. Bugfixes will always be released simultaneously in both editions. always released simultaneously in both editions.
See the [roadmap][4] for a list of already available and upcoming features, and _Don't want to sponsor? No problem, Material for MkDocs already has tons of
for demonstration purposes, [the official documentation][5] built with Material features available, so chances are that most of your requirements are already
for MkDocs Insiders. satisfied. See the [list of exclusive features][4] to learn which features are
currently only available to sponsors._
[4]: #roadmap [4]: #exclusive-features
[5]: https://squidfunk.github.io/mkdocs-material-insiders/
<div class="tx-sponsor" hidden>
<h3>Join <span class="tx-sponsor__count"></span> awesome sponsors</h3>
<div class="tx-sponsor__list"></div>
<p>
You can sponsor publicly or privately. As a public sponsor, you'll be listed
here with your GitHub avatar, showing your support for Material for MkDocs!
</p>
<a class="md-button md-button--primary" href="https://github.com/sponsors/squidfunk">
<span class="twemoji tx-heart"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M14 20.408c-.492.308-.903.546-1.192.709-.153.086-.308.17-.463.252h-.002a.75.75 0 01-.686 0 16.709 16.709 0 01-.465-.252 31.147 31.147 0 01-4.803-3.34C3.8 15.572 1 12.331 1 8.513 1 5.052 3.829 2.5 6.736 2.5 9.03 2.5 10.881 3.726 12 5.605 13.12 3.726 14.97 2.5 17.264 2.5 20.17 2.5 23 5.052 23 8.514c0 3.818-2.801 7.06-5.389 9.262A31.146 31.146 0 0114 20.408z"></path></svg> </span> &nbsp; Become a sponsor
</a>
</div>
<script>
fetch("https://gpiqp43wvb.execute-api.us-east-1.amazonaws.com/_/").then(function(e){return e.json()}).then(function(e){var t=document.querySelector(".tx-sponsor__list"),n=0;for(var o of e.sponsors)if("PUBLIC"===o.type){var s;(s=document.createElement("a")).href=o.url,s.title="@"+o.name,s.className="tx-sponsor__item",t.appendChild(s);var r=document.createElement("img");r.src=o.image,s.appendChild(r)}else n++;(s=document.createElement("a")).href="https://github.com/sponsors/squidfunk",s.title="[private]",s.innerText="+"+n,s.className="tx-sponsor__item tx-sponsor__item--private",t.appendChild(s),document.querySelector(".tx-sponsor__count").innerText=e.sponsors.length,document.querySelector(".tx-sponsor").removeAttribute("hidden")}).catch(console.log);
</script>
<style>
.tx-sponsor {
margin: 2em 0;
}
.tx-sponsor .md-button {
background-color: #e91e63;
border-color: #e91e63;
}
.tx-sponsor__list {
overflow: auto;
}
.tx-sponsor__item {
display: block;
float: left;
width: 3.2rem;
height: 3.2rem;
margin: 0.1rem;
border-radius: 100%;
overflow: hidden;
}
.tx-sponsor__item img {
display: block;
width: 100%;
height: auto;
}
.md-typeset .tx-sponsor__item--private {
background: #CCC;
color: #666;
font-size: 1.2rem;
line-height: 3.2rem;
text-align: center;
font-weight: bold;
}
</style>
## How to become a sponsor ## How to become a sponsor
So you've decided to become a sponsor? Great! You're just __three easy steps__ You can become a sponsor using your individual or organization's GitHub account.
away from enjoying the latest features of Material for MkDocs Insiders. Just visit __[squidfunk's sponsor profile][5]__, pick any tier __from
Complete the following steps and you're in: $10/month__, and complete the checkout. Then, after a few hours, @squidfunk will
add you as a collaborator to the super-secret private GitHub repositority
containing the Insiders edition, which contains all [brand new and exclusive
features][4].
- Visit [squidfunk's sponsor profile][6] and pick a tier that includes exclusive __Important__: If you're sponsoring @squidfunk through a GitHub organization,
access to squidfunk's sponsorware, which is _any tier from $10/month_. Select please send a short email to sponsors@squidfunk.com with the name of your
the tier and complete the checkout. organization and the account that should be added as a collaborator.[^1]
- 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 [^1]:
get updates for Material for MkDocs Insiders, until you decide to cancel your It's currently not possible to grant access to each member of an
monthly subscription, which you can do at any time.__ organization, as GitHub only allows for adding users. Thus, after
sponsoring, please send an email to sponsors@squidfunk.com, stating which
??? info "Sponsoring via a GitHub organization?" account should become a collaborator of the Insiders repository. We're
working on a solution which will make access to organizations much simpler.
If you sponsor @squidfunk through a GitHub organization (which is currently To ensure that access is not tied to a particular individual GitHub account,
in beta), please note that it's not possible to grant access to all
organization members, as GitHub does not allow to do that. Thus, after
sponsoring, please send an email to sponsors@squidfunk.com, explaining
which account should become a collaborator of the Insiders repository.
To ensure that access is not tied to a particular individual, it's best to
create a bot account (i.e. a GitHub account that is not tied to a specific create a bot account (i.e. a GitHub account that is not tied to a specific
individual), and use that for the sponsoring. After being added to the list individual), and use this account for the sponsoring. After being added to
of collaborators, the bot account can create a private fork of the private the list of collaborators, the bot account can create a private fork of the
Insiders GitHub repository, effectively granting access to all members. private Insiders GitHub repository, and grant access to all members of the
organizations.
[6]: https://github.com/sponsors/squidfunk You can cancel your sponsorship anytime.[^2]
[7]: #available-features
[8]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
[9]: https://gitlab.com
[10]: https://bitbucket.org
## Available features [^2]:
All charges are processed by GitHub through Stripe. As we don't receive any
information regarding your payment, and GitHub doesn't offer refunds,
sponsorships are also non-refundable. If you cancel your sponsorship, GitHub
schedules a cancellation request which will become effective at the end of
the billing cycle, which ends at the 22nd of a month for monthly
sponsorships. This means that even though you cancel your sponsorship, you
will keep your access to Insiders as long as your cancellation isn't
effective.
The following list shows which features are currently only available in Material [:octicons-heart-fill-24:{: .tx-heart } &nbsp; Join our <span class="tx-insiders-count"></span> awesome sponsors][5]{: .md-button .md-button--primary .tx-insiders-button }
for MkDocs Insiders. You can click on each feature to learn more about it:
- [x] [Remove _Made with Material for MkDocs_ from footer][11] <div class="tx-insiders-container" markdown="1" hidden>
- [x] [Support for user-toggleable themes (light/dark mode switch)][12] <div class="tx-insiders-list"></div>
- [x] [Support for deploying multiple versions][13] _If you sponsor publicly, you're automatically added here with a link to
- [x] [Support for deploying multiple languages][22] your profile and avatar to show your support for Material for MkDocs.
- [x] [Search suggestions help to save keystrokes][14] Alternatively, if you wish to keep your sponsorship private, you'll be a
- [x] [Highlighting of matched search terms in content area][15] silent +1. You can select visibility during checkout and change it
- [x] Search goes to first result on ++enter++ (I'm feeling lucky) afterwards._
- [x] [Navigation tabs can be made sticky][23] </div>
- [x] [Navigation can be grouped into sections][17]
- [x] [Navigation can be always expanded][17]
- [x] [Navigation and table of contents can be hidden][18]
- [x] [Table of contents can be integrated into navigation][19]
- [x] [Header can be automatically hidden on scrolling][20]
- [x] [Support for Admonitions as inline blocks][21]
[11]: setup/setting-up-the-footer.md#remove-generator <script>
[12]: setup/changing-the-colors.md#color-palette-toggle fetch("https://gpiqp43wvb.execute-api.us-east-1.amazonaws.com/_/").then(function(e){return e.json()}).then(function(e){var t=document.querySelector(".tx-insiders-list"),n=0;for(var o of e.sponsors)if("PUBLIC"===o.type){var s;(s=document.createElement("a")).href=o.url,s.title="@"+o.name,s.className="tx-insiders-list__item",t.appendChild(s);var r=document.createElement("img");r.src=o.image,s.appendChild(r)}else n++;(s=document.createElement("a")).href="https://github.com/sponsors/squidfunk",s.title="[private]",s.innerText="+"+n,s.className="tx-insiders-list__item tx-insiders-list__item--private",t.appendChild(s),document.querySelector(".tx-insiders-count").innerText=e.sponsors.length,document.querySelector(".tx-insiders-container").removeAttribute("hidden"),document.querySelector('.tx-insiders-total').innerText=" – $ "+e.total.toString().replace(/(\d)(?=(\d{3})+(?!\d))/g, "$1,")}).catch(console.log);
[13]: setup/setting-up-versioning.md#versioning </script>
[14]: setup/setting-up-site-search.md#search-suggestions
[15]: setup/setting-up-site-search.md#search-highlighting
[16]: setup/setting-up-navigation.md#navigation-sections
[17]: setup/setting-up-navigation.md#navigation-expansion
[18]: setup/setting-up-navigation.md#hide-the-sidebars
[19]: setup/setting-up-navigation.md#navigation-integration
[20]: setup/setting-up-the-header.md#automatic-hiding
[21]: reference/admonitions.md#inline-blocks
[22]: setup/changing-the-language.md#site-language-selector
[23]: setup/setting-up-navigation.md#sticky-navigation-tabs
## Roadmap [5]: https://github.com/sponsors/squidfunk
The following list of funding goals – named after varieties of chili peppers ## Exclusive features
[I'm growing on my balcony][24] – shows which features are already available
in Material for MkDocs Insiders.
[24]: https://www.instagram.com/squidfunk/ The following features are currently exclusively available to sponsors:
### Madame Jeanette <div class="tx-columns" markdown="1">
[:octicons-flame-24: Funding goal: __$500__][6] · - [x] [Color palette toggle][15]
:octicons-unlock-24: Status: _Generally available_ - [x] [Versioning][14]
- [x] [Site language selection][13]
- [x] [Sticky navigation tabs][18]
- [x] [Search suggestions][16]
- [x] [Search highlighting][17]
- [x] [Admonition inline blocks][12]
- [x] [Remove generator notice][19]
- [x] Improved search result grouping (pages + headings) </div>
- [x] Improved search result relevance and scoring
- [x] Display of missing query terms in search results
### Prairie Fire _New features are added to this list every few weeks, so be sure to come back
from time to time to learn about what's new, or follow [@squidfunk on
:fontawesome-brands-twitter:{: .twitter } Twitter][6] to stay updated._
[:octicons-flame-24: Funding goal: __$1,000__][6] · [6]: https://twitter.com/squidfunk
:octicons-lock-24: Status: _Insiders only_
- [x] [Navigation can be grouped into sections][16] ## Funding<span class="tx-insiders-total"></span>
- [x] [Navigation can be always expanded][17]
- [x] [Navigation and table of contents can be hidden][18]
- [x] [Table of contents can be integrated into navigation][19]
- [x] [Header can be automatically hidden on scrolling][20]
### Bhut Jolokia ### Goals
[:octicons-flame-24: Funding goal: __$1,500__][6] · Following is a list of funding goals. When a funding goal is hit, the features
:octicons-lock-24: Status: _Insiders only_ that are tied to it are merged back into Material for MkDocs and released to
the public for general availability.
- [x] [Support for Admonitions as inline blocks][21] #### $ 1,500 – Bhut Jolokia
- [x] [Support for deploying multiple versions][13]
- [x] [Support for deploying multiple languages][22]
### Black Pearl - [x] [Admonition inline blocks][12]
- [x] [Site language selection][13]
- [x] [Versioning][14]
[:octicons-flame-24: Funding goal: __$2,000__][6] · [12]: reference/admonitions.md#inline-blocks
:octicons-lock-24: Status: _Insiders only_ [13]: setup/changing-the-language.md#site-language-selector
[14]: setup/setting-up-versioning.md#versioning
- [x] [Support for user-toggleable themes (light/dark mode switch)][12] #### $ 2,000 – Black Pearl
- [ ] Support for user-toggleable code-block styles (light/dark mode switch)
- [ ] Table of contents auto-collapses and expands only the active section
### Biquinho Vermelho - [x] Deep linking of search results
- [x] [Color palette toggle][15]
- [ ] Code block palette toggle
[:octicons-flame-24: Funding goal: __$2,500__][6] · [15]: setup/changing-the-colors.md#color-palette-toggle
:octicons-lock-24: Status: _Insiders only_
- [x] [Search suggestions help to save keystrokes][14] #### $ 2,500 – Biquinho Vermelho
- [x] [Highlighting of matched search terms in content area][15]
- [x] Search goes to first result on ++enter++ (I'm feeling lucky) - [x] [Search suggestions][16]
- [ ] Table of contents shows which sections have search results - [x] [Search highlighting][17]
- [ ] Support for displaying a user's last searches - [ ] List of last searches
[16]: setup/setting-up-site-search.md#search-suggestions
[17]: setup/setting-up-site-search.md#search-highlighting
#### $ 3,000 – Caribbean Red
- [x] [Sticky navigation tabs][18]
- [x] [Remove generator notice][19]
[18]: setup/setting-up-navigation.md#sticky-navigation-tabs
[19]: setup/setting-up-the-footer.md#remove-generator
#### Future
- [ ] [Material for MkDocs Live Edit][20]
- [ ] Improved search result summaries - [ ] Improved search result summaries
- [ ] Table of contents auto-collapse
- [ ] Table of contents shows which sections have search results
- [ ] New layouts and styles (e.g. vertical)
- [ ] ... and much more ...
### Caribbean Red [20]: https://twitter.com/squidfunk/status/1338252230265360391
[:octicons-flame-24: Funding goal: __$3,000__][6] · ### Goals completed
:octicons-lock-24: Status: _Insiders only_
- [x] [Navigation tabs can be made sticky][23] #### $ 500 – Madame Jeanette
- [x] [Remove _Made with Material for MkDocs_ from footer][11]
- [ ] Brand-new and exclusive vertical layout - [x] Improved search result grouping
- [x] Improved search result relevance and scoring
- [x] Missing query terms in search results
#### $ 1,000 – Prairie Fire
- [x] [Navigation sections][7]
- [x] [Navigation expansion][8]
- [x] [Hiding the sidebars][9]
- [x] [Table of contents in navigation][10]
- [x] [Header hides on scroll][11]
[7]: setup/setting-up-navigation.md#navigation-sections
[8]: setup/setting-up-navigation.md#navigation-expansion
[9]: setup/setting-up-navigation.md#hide-the-sidebars
[10]: setup/setting-up-navigation.md#navigation-integration
[11]: setup/setting-up-the-header.md#automatic-hiding
## Frequently asked questions ## Frequently asked questions
### Compatibility ### Compatibility
_We're running an open source project and want to make sure that users can build _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?_ the documentation without having access to Insiders. Is this still possible?_
Yes. Material for MkDocs Insiders strives to be compatible with Material for Yes. Insiders is compatible with Material for MkDocs. All new features are
MkDocs, so all new features are implemented as feature flags and all implemented behind feature flags; all configuration changes are
improvements (e.g. search) do not require any changes to existing configuration. backward-compatible. This means that your users will be able to build the
This means that your users will be able to build the docs locally with the documentation locally with Material for MkDocs and when they push their changes,
regular version and when they push their changes to CI/CD, they will be built it can be built with Insiders (e.g. as part of GitHub Actions). Thus, it's
with Material for MkDocs Insiders. For this reason, it's recommended to recommended to [install Insiders][21] only in CI, as you don't want to expose
[install Insiders][25] only in CI, as you don't want to expose your `GH_TOKEN` your `GH_TOKEN` to users.
to users.
[25]: publishing-your-site.md#github-pages [21]: publishing-your-site.md#github-pages
### Terms ### Terms
_We're using Material for MkDocs to build the developer documentation of a _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 commercial project. Can we use Insiders under the same terms and conditions?_
terms?_
Yes. Whether you're an individual or a company, you may use _Material for MkDocs 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 Insiders_ precisely under the same terms as Material for MkDocs, which are given
by the [MIT license][26]. However, we kindly ask you to respect the following by the [MIT license][22]. However, we kindly ask you to respect the following
guidelines: guidelines:
- Please __don't distribute the source code__ from Material for MkDocs Insiders. - Please __don't distribute the source code__ of Insiders. You may freely use
You may freely use it for public, private or commercial projects, fork it, it for public, private or commercial projects, fork it, mirror it, do whatever
mirror it, do whatever you want with it, but please don't release the source you want with it, but please don't release the source code, as it would
code, as it would cannibalize the sponsorware strategy. counteract the sponsorware strategy.
- If you cancel your subscription, you're removed as a collaborator and will - 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 miss out on future updates of Insiders. However, you may __use the latest
__use the latest version__ that's available to you __as long as you like__. version__ that's available to you __as long as you like__. Just remember that
Just remember that __[GitHub deletes private forks][27]__. [GitHub deletes private forks][23].
[26]: license.md [22]: license.md
[27]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository [23]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository

10
docs/publishing-your-site.md
View File

@ -75,8 +75,8 @@ to your repository to see the workflow in action.
Your documentation should shortly appear at `<username>.github.io/<repository>`. Your documentation should shortly appear at `<username>.github.io/<repository>`.
_Remember to set the_ `GH_TOKEN` _environment variable to the value of your _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 [personal access token][3] when deploying [Insiders][4], which can be done
can be done using [secrets][5]._ using [secrets][5]._
[2]: https://github.com/features/actions [2]: https://github.com/features/actions
[3]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token [3]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
@ -119,7 +119,7 @@ following contents:
``` yaml ``` yaml
image: python:latest image: python:latest
deploy: pages:
stage: deploy stage: deploy
only: only:
- master - master
@ -138,8 +138,8 @@ workflow in action.
Your documentation should shortly appear at `<username>.gitlab.io/<repository>`. Your documentation should shortly appear at `<username>.gitlab.io/<repository>`.
_Remember to set the_ `GH_TOKEN` _environment variable to the value of your _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 [personal access token][3] when deploying [Insiders][4], which can be done
can be done using [masked custom variables][8]._ using [masked custom variables][8]._
[6]: https://gitlab.com/pages [6]: https://gitlab.com/pages
[7]: https://docs.gitlab.com/ee/ci/ [7]: https://docs.gitlab.com/ee/ci/

25
docs/reference/abbreviations.md
View File

@ -13,7 +13,9 @@ enable site-wide glossaries.
### Abbreviations ### Abbreviations
The [Abbreviations][1] extension, which is part of the standard Markdown [:octicons-file-code-24: Source][1] · [:octicons-workflow-24: Extension][2]
The [Abbreviations][2] extension, which is part of the standard Markdown
library, allows to __add additional content to parts of the text which are then library, allows to __add additional content to parts of the text which are then
shown on hover__, e.g. for glossaries: shown on hover__, e.g. for glossaries:
@ -22,11 +24,12 @@ markdown_extensions:
- abbr - abbr
``` ```
[1]: https://python-markdown.github.io/extensions/abbreviations/ [1]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_typeset.scss
[2]: https://python-markdown.github.io/extensions/abbreviations/
### Snippets ### Snippets
The [Snippets][2] extension, which is part of [Python Markdown Extensions][3], The [Snippets][3] extension, which is part of [Python Markdown Extensions][4],
allows to __insert content from other files__ or other, regular content, and can allows to __insert content from other files__ or other, regular content, and can
be enabled via `mkdocs.yml`: be enabled via `mkdocs.yml`:
@ -35,15 +38,15 @@ markdown_extensions:
- pymdownx.snippets - pymdownx.snippets
``` ```
[2]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/ [3]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
[3]: https://facelessuser.github.io/pymdown-extensions/ [4]: https://facelessuser.github.io/pymdown-extensions/
## Usage ## Usage
### Adding abbreviations ### Adding abbreviations
When the [Abbreviations][4] extension is enabled, abbreviations can be defined When the [Abbreviations][5] extension is enabled, abbreviations can be defined
with a special syntax similar to URLs and [footnotes][5] at any point in the with a special syntax similar to URLs and [footnotes][6] at any point in the
Markdown document. Markdown document.
_Example_: _Example_:
@ -62,12 +65,12 @@ The HTML specification is maintained by the W3C.
*[HTML]: Hyper Text Markup Language *[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium *[W3C]: World Wide Web Consortium
[4]: #abbreviations_1 [5]: #abbreviations_1
[5]: footnotes.md [6]: footnotes.md
### Adding a glossary ### Adding a glossary
When [Snippets][6] is enabled, content from other files can be embedded, which When [Snippets][7] is enabled, content from other files can be embedded, which
is especially useful to include abbreviations from a central file – a glossary – is especially useful to include abbreviations from a central file – a glossary –
and embed them into any other file. and embed them into any other file.
@ -96,4 +99,4 @@ _Remember to locate the Markdown file containing the definitions outside of the_
`docs` _folder (here_ `includes` _is used), or MkDocs may complain about an `docs` _folder (here_ `includes` _is used), or MkDocs may complain about an
unreferenced file._ unreferenced file._
[6]: #snippets [7]: #snippets

4
docs/reference/code-blocks.md
View File

@ -380,8 +380,8 @@ override it as part of your additional stylesheet:
} }
``` ```
[22]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss#L60-L73 [22]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss#
[23]: #use-pygments [23]: #use-pygments
[24]: ../setup/changing-the-colors.md#color-scheme [24]: ../setup/changing-the-colors.md#color-scheme
[25]: https://pygments.org/docs/tokens/#literals [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 [26]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_codehilite.scss

22
docs/reference/icons-emojis.md
View File

@ -91,19 +91,19 @@ _Example_:
``` ```
- :material-account-circle: – `.icons/material/account-circle.svg` - :material-account-circle: – `.icons/material/account-circle.svg`
- :fontawesome-regular-laugh-wink: – `.icons/fontawesome/regular/laugh-wink.svg` - :fontawesome-regular-laugh-wink: – `.icons/fontawesome/regular/laugh-wink.svg`
- :octicons-octoface-16: – `.icons/octicons/octoface-16.svg` - :octicons-octoface-24: – `.icons/octicons/octoface-24.svg`
``` ```
_Result_: _Result_:
- :material-account-circle: – [`.icons/material/account-circle.svg`][14] - :material-account-circle: – [`.icons/material/account-circle.svg`][14]
- :fontawesome-regular-laugh-wink: – [`.icons/fontawesome/regular/laugh-wink.svg`][15] - :fontawesome-regular-laugh-wink: – [`.icons/fontawesome/regular/laugh-wink.svg`][15]
- :octicons-octoface-16: – [`.icons/octicons/octoface-16.svg`][16] - :octicons-octoface-24: – [`.icons/octicons/octoface-24.svg`][16]
[13]: #emoji [13]: #emoji
[14]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/material/account-circle.svg [14]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/material/account-circle.svg
[15]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/fontawesome/regular/laugh-wink.svg [15]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/fontawesome/regular/laugh-wink.svg
[16]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/octicons/octoface-16.svg [16]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/octicons/octoface-24.svg
#### with colors #### with colors
@ -178,20 +178,6 @@ and adding the dedicated CSS class to the icon:
Then, simply add the CSS class to the icon. Then, simply add the CSS class to the icon.
<style>
@keyframes heart {
0%, 40%, 80%, 100% {
transform: scale(1);
}
20%, 60% {
transform: scale(1.15);
}
}
.heart {
animation: heart 1000ms infinite;
}
</style>
_Example_: _Example_:
``` markdown ``` markdown
@ -200,7 +186,7 @@ _Example_:
_Result_: _Result_:
:octicons-heart-fill-24:{: .heart } :octicons-heart-fill-24:{: .tx-heart }
[20]: #with-colors [20]: #with-colors
[21]: https://developer.mozilla.org/en-US/docs/Web/CSS/animation [21]: https://developer.mozilla.org/en-US/docs/Web/CSS/animation

3
docs/setup/adding-a-comment-system.md
View File

@ -55,6 +55,7 @@ Markdown document, delimited by a blank line which ends the YAML context.
### Selective integration ### Selective integration
[:octicons-file-code-24: Source][2] · [:octicons-file-code-24: Source][2] ·
:octicons-note-24: Metadata ·
:octicons-mortar-board-24: Difficulty: _easy_ :octicons-mortar-board-24: Difficulty: _easy_
If the [Metadata][7] extension is enabled, you can disable or enable Disqus for If the [Metadata][7] extension is enabled, you can disable or enable Disqus for
@ -96,6 +97,6 @@ In order to integrate another JavaScript-based comment system provider, you can
{% endblock %} {% endblock %}
``` ```
[8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L325-L328 [8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
[9]: ../customization.md#extending-the-theme [9]: ../customization.md#extending-the-theme
[10]: ../customization.md#overriding-blocks [10]: ../customization.md#overriding-blocks

2
docs/setup/adding-a-git-repository.md
View File

@ -93,7 +93,7 @@ behavior can be changed by setting [`edit_uri`][9] in `mkdocs.yml`:
edit_uri: "" edit_uri: ""
``` ```
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L292-L301 [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
[6]: https://github.com/ [6]: https://github.com/
[7]: https://about.gitlab.com/ [7]: https://about.gitlab.com/
[8]: https://bitbucket.org/ [8]: https://bitbucket.org/

75
docs/setup/changing-the-colors.md
View File

@ -30,8 +30,7 @@ theme:
scheme: default scheme: default
``` ```
:material-cursor-default-click-outline: Click on a tile to change the color _Click on a tile to change the color scheme_:
scheme:
<div class="tx-switch"> <div class="tx-switch">
<button data-md-color-scheme="default"><code>default</code></button> <button data-md-color-scheme="default"><code>default</code></button>
@ -76,8 +75,7 @@ theme:
primary: indigo primary: indigo
``` ```
:material-cursor-default-click-outline: Click on a tile to change the primary _Click on a tile to change the primary color_:
color:
<div class="tx-switch"> <div class="tx-switch">
<button data-md-color-primary="red"><code>red</code></button> <button data-md-color-primary="red"><code>red</code></button>
@ -131,8 +129,7 @@ theme:
accent: indigo accent: indigo
``` ```
:material-cursor-default-click-outline: Click on a tile to change the accent _Click on a tile to change the accent color_:
color:
<style> <style>
.md-typeset button[data-md-color-accent] > code { .md-typeset button[data-md-color-accent] > code {
@ -186,23 +183,27 @@ color:
### Color palette toggle ### Color palette toggle
[:octicons-file-code-24: Source][6] · [:octicons-file-code-24: Source][6] ·
:octicons-beaker-24: Experimental · :octicons-beaker-24: Experimental ·
[:octicons-heart-fill-24:{: .tx-heart } Insiders only][6]{: .tx-insiders } [:octicons-heart-fill-24:{: .tx-heart } Insiders only][6]{: .tx-insiders }
[Material for MkDocs Insiders][6] makes it possible to define multiple color [Insiders][6] can easily add multiple color palettes, including a [scheme][8],
palettes, including a [scheme][7], [primary][8] and [accent][9] color each, and [primary][9] and [accent][10] color each, and let the user choose. A color
let the user choose. Define them via `mkdocs.yml`: palette toggle can be added via `mkdocs.yml`:
``` yaml ``` yaml
theme: theme:
palette: palette:
# Toggle light mode
- scheme: default - scheme: default
primary: indigo primary: indigo
accent: indigo accent: indigo
toggle: toggle:
icon: material/toggle-switch icon: material/toggle-switch
name: Switch to light mode name: Switch to light mode
# Toggle dark mode
- scheme: slate - scheme: slate
primary: blue primary: blue
accent: blue accent: blue
@ -211,6 +212,16 @@ theme:
name: Switch to dark mode name: Switch to dark mode
``` ```
This will render a color palette toggle in the header next to the search bar:
<figure markdown="1">
[![Color palette toggle][11]][11]
<figcaption markdown="1">
A demo is worth a thousand words — check it out at
[squidfunk.github.io/mkdocs-material-insiders][7]
</figcaption>
</figure>
The `toggle` field allows to specify an `icon` and `name` for each palette. The The `toggle` field allows to specify an `icon` and `name` for each palette. The
toggle is rendered next to the search bar and will cycle through all defined toggle is rendered next to the search bar and will cycle through all defined
color palettes: color palettes:
@ -219,7 +230,7 @@ color palettes:
: :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required – : :octicons-milestone-24: Default: _none_ · :octicons-alert-24: Required –
This field must point to a valid icon path referencing [any icon bundled This field must point to a valid icon path referencing [any icon bundled
with the theme][10], or the build will not succeed. Some popular with the theme][12], or the build will not succeed. Some popular
combinations: combinations:
* :material-toggle-switch-off-outline: + :material-toggle-switch: – `material/toggle-switch-off-outline` + `material/toggle-switch` * :material-toggle-switch-off-outline: + :material-toggle-switch: – `material/toggle-switch-off-outline` + `material/toggle-switch`
@ -233,28 +244,24 @@ color palettes:
This field is used as the toggle's `title` attribute and should be set to a This field is used as the toggle's `title` attribute and should be set to a
discernable name to improve accessibility. discernable name to improve accessibility.
[Try this feature][11]{: .md-button .md-button--primary }
_This feature is enabled on the [official documentation][11] built with
Insiders._
[6]: ../insiders.md [6]: ../insiders.md
[7]: #color-scheme [7]: https://squidfunk.github.io/mkdocs-material-insiders/setup/changing-the-colors
[8]: #primary-color [8]: #color-scheme
[9]: #accent-color [9]: #primary-color
[10]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons [10]: #accent-color
[11]: https://squidfunk.github.io/mkdocs-material-insiders/setup/changing-the-colors [11]: ../assets/screenshots/color-palette-toggle.png
[12]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
## Customization ## Customization
### Custom colors ### Custom colors
[:octicons-file-code-24: Source][12] · [:octicons-file-code-24: Source][13] ·
:octicons-mortar-board-24: Difficulty: _easy_ :octicons-mortar-board-24: Difficulty: _easy_
Material for MkDocs implements colors using [CSS variables][13] (custom Material for MkDocs implements colors using [CSS variables][14] (custom
properties). If you want to customize the colors beyond the palette (e.g. to 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][14] and use your brand-specific colors), you can add an [additional stylesheet][15] and
tweak the values of the CSS variables. tweak the values of the CSS variables.
Let's say you're :fontawesome-brands-youtube:{: style="color: #EE0F0F" } Let's say you're :fontawesome-brands-youtube:{: style="color: #EE0F0F" }
@ -269,23 +276,23 @@ add:
} }
``` ```
See the file containing the [color definitions][12] for a list of all CSS See the file containing the [color definitions][13] for a list of all CSS
variables. variables.
[12]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss [13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
[13]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties [14]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
[14]: ../customization.md#additional-css [15]: ../customization.md#additional-css
### Custom color schemes ### Custom color schemes
[:octicons-file-code-24: Source][3] · [:octicons-file-code-24: Source][13] ·
:octicons-mortar-board-24: Difficulty: _easy_ :octicons-mortar-board-24: Difficulty: _easy_
Besides overriding specific colors, you can create your own, named color scheme Besides overriding specific colors, you can create your own, named color scheme
by wrapping the definitions in the `#!css [data-md-color-scheme="..."]` by wrapping the definitions in the `#!css [data-md-color-scheme="..."]`
[attribute selector][15], which you can then set via `mkdocs.yml` as described [attribute selector][16], which you can then set via `mkdocs.yml` as described
in the [color schemes][7] section: in the [color schemes][8] section:
``` css ``` css
[data-md-color-scheme="youtube"] { [data-md-color-scheme="youtube"] {
@ -305,4 +312,4 @@ can tune the `slate` theme with:
} }
``` ```
[15]: https://www.w3.org/TR/selectors-4/#attribute-selectors [16]: https://www.w3.org/TR/selectors-4/#attribute-selectors

2
docs/setup/changing-the-fonts.md
View File

@ -30,7 +30,7 @@ theme:
The typeface will be loaded in 300, 400, _400i_ and __700__. The typeface will be loaded in 300, 400, _400i_ and __700__.
[2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L107-L132 [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
[3]: https://fonts.google.com/specimen/Roboto [3]: https://fonts.google.com/specimen/Roboto
### Proportional font ### Proportional font

141
docs/setup/changing-the-language.md
View File

@ -24,58 +24,56 @@ theme:
The following languages are supported: The following languages are supported:
<ul class="tx-columns"> <div class="tx-columns" markdown="1">
<li><code>af</code> – Afrikaans</li>
<li><code>ar</code> – Arabic</li> - `af` – Afrikaans
<li><code>bn</code> – Bengali (Bangla)</li> - `ar` – Arabic
<li><code>ca</code> – Catalan</li> - `bn` – Bengali (Bangla)
<li><code>cs</code> – Czech</li> - `ca` – Catalan
<li><code>da</code> – Danish</li> - `cs` – Czech
<li><code>de</code> – German</li> - `da` – Danish
<li><code>en</code> – English</li> - `de` – German
<li><code>eo</code> – Esperanto</li> - `en` – English
<li><code>es</code> – Spanish</li> - `eo` – Esperanto
<li><code>et</code> – Estonian</li> - `es` – Spanish
<li><code>fa</code> – Persian (Farsi)</li> - `et` – Estonian
<li><code>fi</code> – Finnish</li> - `fa` – Persian (Farsi)
<li><code>fr</code> – French</li> - `fi` – Finnish
<li><code>gl</code> – Galician</li> - `fr` – French
<li><code>gr</code> – Greek</li> - `gl` – Galician
<li><code>he</code> – Hebrew</li> - `gr` – Greek
<li><code>hi</code> – Hindi</li> - `he` – Hebrew
<li><code>hr</code> – Croatian</li> - `hi` – Hindi
<li><code>hu</code> – Hungarian</li> - `hr` – Croatian
<li><code>id</code> – Indonesian</li> - `hu` – Hungarian
<li><code>it</code> – Italian</li> - `id` – Indonesian
<li><code>ja</code> – Japanese</li> - `it` – Italian
<li><code>ka</code> – Georgian</li> - `ja` – Japanese
<li><code>kr</code> – Korean</li> - `ka` – Georgian
<li><code>my</code> – Burmese</li> - `kr` – Korean
<li><code>nl</code> – Dutch</li> - `my` – Burmese
<li><code>nn</code> – Norwegian (Nynorsk)</li> - `nl` – Dutch
<li><code>no</code> – Norwegian</li> - `nn` – Norwegian (Nynorsk)
<li><code>pl</code> – Polish</li> - `no` – Norwegian
<li><code>pt</code> – Portuguese</li> - `pl` – Polish
<li><code>ro</code> – Romanian</li> - `pt` – Portuguese
<li><code>ru</code> – Russian</li> - `ro` – Romanian
<li><code>sh</code> – Serbo-Croatian</li> - `ru` – Russian
<li><code>si</code> – Slovenian</li> - `sh` – Serbo-Croatian
<li><code>sk</code> – Slovak</li> - `si` – Slovenian
<li><code>sr</code> – Serbian</li> - `sk` – Slovak
<li><code>sv</code> – Swedish</li> - `sr` – Serbian
<li><code>th</code> – Thai</li> - `sv` – Swedish
<li><code>tr</code> – Turkish</li> - `th` – Thai
<li><code>uk</code> – Ukrainian</li> - `tr` – Turkish
<li><code>vi</code> – Vietnamese</li> - `uk` – Ukrainian
<li><code>zh</code> – Chinese (Simplified)</li> - `vi` – Vietnamese
<li><code>zh-Hant</code> – Chinese (Traditional)</li> - `zh` – Chinese (Simplified)
<li><code>zh-TW</code> – Chinese (Taiwanese)</li> - `zh-Hant` – Chinese (Traditional)
<li> - `zh-TW` – Chinese (Taiwanese)
<a href="https://bit.ly/38F5RCa"> - [Add language](https://bit.ly/38F5RCa)
Add language
</a> </div>
</li>
</ul>
_Note that some languages will produce unreadable anchor links, due to the way _Note that some languages will produce unreadable anchor links, due to the way
the default slug function works. Consider using a Unicode-aware slug function, the default slug function works. Consider using a Unicode-aware slug function,
@ -97,40 +95,30 @@ can be added to the header next to the search bar. Languages can be defined via
``` yaml ``` yaml
extra: extra:
alternate: alternate:
# Switch to English
- name: English - name: English
link: https://squidfunk.github.io/mkdocs-material-insiders/en/ link: <your-site>/en/
lang: en lang: en
# Switch to German
- name: Deutsch - name: Deutsch
link: https://squidfunk.github.io/mkdocs-material-insiders/de/ link: <your-site>/de/
lang: de lang: de
# Switch to Japanese
- name: 日本語 - name: 日本語
link: https://squidfunk.github.io/mkdocs-material-insiders/jp/ link: <your-site>/ja/
lang: jp lang: ja
``` ```
This will render a language selector in the header next to the search bar: This will render a language selector in the header next to the search bar:
[![Language selection][4]][4] [![Language selection][4]][4]
[3]: ../insiders.md [3]: ../insiders.md
[4]: ../assets/screenshots/language-selection.png [4]: ../assets/screenshots/language-selection.png
This assumes that your project is structured into multiple subfolders, each of
which contain the entire documentation for a given language, e.g.:
``` sh
.
├─ en/
│ ├─ docs/
│ └─ mkdocs.yml
├─ de/
│ ├─ docs/
│ └─ mkdocs.yml
└─ jp/
├─ docs/
└─ mkdocs.yml
```
### Site search language ### Site search language
[:octicons-file-code-24: Source][5] · [:octicons-file-code-24: Source][5] ·
@ -141,7 +129,7 @@ work properly. Material for MkDocs relies on [lunr-languages][6] to provide this
functionality. See the guide detailing how to [set up site search][7] for functionality. See the guide detailing how to [set up site search][7] for
more information. more information.
[5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/main/index.ts#L77-L108 [5]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/search/worker/main/index.ts
[6]: https://github.com/MihaiValentin/lunr-languages [6]: https://github.com/MihaiValentin/lunr-languages
[7]: setting-up-site-search.md [7]: setting-up-site-search.md
@ -159,8 +147,7 @@ theme:
direction: ltr direction: ltr
``` ```
:material-cursor-default-click-outline: Click on a tile to change the Click on a tile to change the directionality:
directionality:
<div class="tx-switch"> <div class="tx-switch">
<button data-md-dir="ltr"><code>ltr</code></button> <button data-md-dir="ltr"><code>ltr</code></button>
@ -179,7 +166,7 @@ directionality:
}) })
</script> </script>
[8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L185 [8]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
## Customization ## Customization

2
docs/setup/changing-the-logo-and-icons.md
View File

@ -53,7 +53,7 @@ theme:
favicon: images/favicon.png favicon: images/favicon.png
``` ```
[4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L60-L61 [4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
### Icons ### Icons

148
docs/setup/setting-up-navigation.md
View File

@ -63,60 +63,16 @@ theme:
[![Without tabs][8]][8] [![Without tabs][8]][8]
Note that all __top-level pages__ (i.e. all top-level entries that directly
refer to an `*.md` file) defined inside the [`nav`][9] entry of `mkdocs.yml`
will be grouped under the first tab which will receive the title of the first
page.
This means that there will effectively be no collapsible subsections for the
first tab, because each subsection is rendered as another tab. If you want more
fine-grained control, _i.e. collapsible subsections for the first tab_, you can
use __top-level sections__, so that the top-level is entirely made up of
sections. This is illustrated in the following example:
=== "Top-level pages"
``` yaml
nav:
- Tab 1 + Page 1.1
- Page 1.2
- Tab 2:
- Page 2.1
- Page 2.2
- Page 2.3
- Page 1.3
```
=== "Top-level sections"
``` yaml
nav:
- Tab 1:
- Page 1.1
- Page 1.2
- Page 1.3
- Tab 2:
- Page 2.1
- Page 2.2
- Page 2.3
```
Also note that tabs are only shown for larger screens, so make sure that
navigation is plausible on mobile devices. As another example, see the
[`mkdocs.yml`][10] used to render these pages.
[6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/tabs.html [6]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/tabs.html
[7]: ../assets/screenshots/navigation-tabs.png [7]: ../assets/screenshots/navigation-tabs.png
[8]: ../assets/screenshots/navigation.png [8]: ../assets/screenshots/navigation.png
[9]: https://www.mkdocs.org/user-guide/configuration/#nav
[10]: https://github.com/squidfunk/mkdocs-material/blob/master/mkdocs.yml
#### Sticky navigation tabs #### Sticky navigation tabs
[:octicons-file-code-24: Source][11] · [:octicons-file-code-24: Source][9] ·
:octicons-unlock-24: Feature flag · :octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental · :octicons-beaker-24: Experimental ·
[:octicons-heart-fill-24:{: .tx-heart } Insiders only][11]{: .tx-insiders } [:octicons-heart-fill-24:{: .tx-heart } Insiders only][9]{: .tx-insiders }
When _sticky tabs_ are enabled, navigation tabs will lock below the header and When _sticky tabs_ are enabled, navigation tabs will lock below the header and
always remain visible when scrolling down. Just add the following two feature always remain visible when scrolling down. Just add the following two feature
@ -131,21 +87,20 @@ theme:
=== "With sticky tabs" === "With sticky tabs"
[![With sticky tabs][12]][12] [![With sticky tabs][10]][10]
=== "Without sticky tabs" === "Without sticky tabs"
[![Without sticky tabs][13]][13] [![Without sticky tabs][11]][11]
[11]: ../insiders.md [9]: ../insiders.md
[12]: ../assets/screenshots/navigation-tabs-sticky.png [10]: ../assets/screenshots/navigation-tabs-sticky.png
[13]: ../assets/screenshots/navigation-tabs-collapsed.png [11]: ../assets/screenshots/navigation-tabs-collapsed.png
### Navigation sections ### Navigation sections
[:octicons-file-code-24: Source][11] · [:octicons-file-code-24: Source][12] ·
:octicons-unlock-24: Feature flag · :octicons-unlock-24: Feature flag
[:octicons-heart-fill-24:{: .tx-heart } Insiders only][11]{: .tx-insiders }
When _sections_ are enabled, top-level sections are rendered as groups in the When _sections_ are enabled, top-level sections are rendered as groups in the
sidebar for viewports above `1220px`, but remain as-is on mobile. They can also sidebar for viewports above `1220px`, but remain as-is on mobile. They can also
@ -159,23 +114,23 @@ theme:
=== "With sections" === "With sections"
[![With sections][14]][14] [![With sections][13]][13]
=== "Without sections" === "Without sections"
[![Without sections][8]][8] [![Without sections][8]][8]
[14]: ../assets/screenshots/navigation-sections.png [12]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/nav-item.html
[13]: ../assets/screenshots/navigation-sections.png
Both feature flags, _tabs_ and _sections_, can be combined with each other. If Both feature flags, _tabs_ and _sections_, can be combined with each other. If
both feature flags are enabled, sections are rendered for 2nd level navigation both feature flags are enabled, sections are rendered for level 2 navigation
items. items.
### Navigation expansion ### Navigation expansion
[:octicons-file-code-24: Source][11] · [:octicons-file-code-24: Source][12] ·
:octicons-unlock-24: Feature flag · :octicons-unlock-24: Feature flag
[:octicons-heart-fill-24:{: .tx-heart } Insiders only][11]{: .tx-insiders }
When _expansion_ is enabled, the left sidebar will expand all collapsible When _expansion_ is enabled, the left sidebar will expand all collapsible
subsections by default, so the user doesn't have to open subsections manually. subsections by default, so the user doesn't have to open subsections manually.
@ -189,19 +144,19 @@ theme:
=== "With expansion" === "With expansion"
[![With expansion][15]][15] [![With expansion][14]][14]
=== "Without expansion" === "Without expansion"
[![Without expansion][8]][8] [![Without expansion][8]][8]
[15]: ../assets/screenshots/navigation-expand.png [14]: ../assets/screenshots/navigation-expand.png
### Table of contents ### Table of contents
[:octicons-file-code-24: Source][16] · [:octicons-workflow-24: Extension][17] [:octicons-file-code-24: Source][15] · [:octicons-workflow-24: Extension][16]
The [Table of contents][18] extension, which is part of the standard Markdown The [Table of contents][17] extension, which is part of the standard Markdown
library, provides some options that are supported by Material for MkDocs to library, provides some options that are supported by Material for MkDocs to
customize its appearance: customize its appearance:
@ -232,8 +187,8 @@ customize its appearance:
: :octicons-milestone-24: Default: `headerid.slugify` – This option allows for : :octicons-milestone-24: Default: `headerid.slugify` – This option allows for
customization of the slug function. For some languages, the default may not customization of the slug function. For some languages, the default may not
produce good and readable identifiers. Consider using another slug function produce good and readable identifiers – consider using another slug function
like for example those from [Python Markdown Extensions][19]: like for example those from [Python Markdown Extensions][18]:
=== "Unicode" === "Unicode"
@ -274,30 +229,29 @@ customize its appearance:
toc_depth: 0 toc_depth: 0
``` ```
Note that MkDocs will not generate [anchor links][20] for levels outside Note that MkDocs will not generate [anchor links][19] for levels outside
the range defined with `toc_depth`. However, Material for MkDocs also allows the range defined with `toc_depth`. However, Material for MkDocs also allows
to [hide the table of contents][21] on a specific page while keeping to [hide the table of contents][20] on a specific page while keeping
permalinks. permalinks.
_Material for MkDocs doesn't provide official support for the other options of _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 this extension, so they may be supported but can also yield weird results. Use
them at your own risk._ them at your own risk._
[16]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html [15]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/toc.html
[17]: https://python-markdown.github.io/extensions/toc/ [16]: https://python-markdown.github.io/extensions/toc/
[18]: https://python-markdown.github.io/extensions/toc/#usage [17]: https://python-markdown.github.io/extensions/toc/#usage
[19]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/ [18]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
[20]: #permalink [19]: #permalink
[21]: #hide-the-sidebars [20]: #hide-the-sidebars
#### Navigation integration #### Navigation integration
[:octicons-file-code-24: Source][11] · [:octicons-file-code-24: Source][21] ·
:octicons-unlock-24: Feature flag · :octicons-unlock-24: Feature flag
[:octicons-heart-fill-24:{: .tx-heart } Insiders only][11]{: .tx-insiders }
When _integration_ is enabled, the table of contents is rendered as part of When _integration_ is enabled, the table of contents is rendered as part of
the navigation for viewports above `1220px`, but remain as-is on mobile. This the navigation for viewports above `1220px`, but remains as-is on mobile. This
can be enabled via `mkdocs.yml`: can be enabled via `mkdocs.yml`:
``` yaml ``` yaml
@ -314,6 +268,7 @@ theme:
[![Separate table of contents][8]][8] [![Separate table of contents][8]][8]
[21]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_nav.scss
[22]: ../assets/screenshots/toc-integrate.png [22]: ../assets/screenshots/toc-integrate.png
The content section will now always stretch to the right side, resulting in The content section will now always stretch to the right side, resulting in
@ -322,12 +277,12 @@ feature flags, e.g. [tabs][1] and [sections][2].
### Hide the sidebars ### Hide the sidebars
[:octicons-file-code-24: Source][11] · [:octicons-file-code-24: Source][23] ·
[:octicons-heart-fill-24:{: .tx-heart } Insiders only][11]{: .tx-insiders } :octicons-note-24: Metadata
Sometimes it's desirable to hide the navigation and/or table of contents Sometimes it's desirable to hide the navigation and/or table of contents
sidebar, especially when there's a single navigation item. This can be done for sidebar, especially when there's a single navigation item. This can be done for
any page using the [Metadata][23] extension: any page using the [Metadata][24] extension:
``` yaml ``` yaml
--- ---
@ -341,26 +296,27 @@ hide:
=== "Hide navigation" === "Hide navigation"
[![Hide navigation][24]][24] [![Hide navigation][25]][25]
=== "Hide table of contents" === "Hide table of contents"
[![Hide table of contents][25]][25] [![Hide table of contents][26]][26]
=== "Hide both" === "Hide both"
[![Hide navigation and table of contents][26]][26] [![Hide navigation and table of contents][27]][27]
[23]: ../../reference/meta-tags/#metadata [23]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
[24]: ../assets/screenshots/hide-navigation.png [24]: ../../reference/meta-tags/#metadata
[25]: ../assets/screenshots/hide-toc.png [25]: ../assets/screenshots/hide-navigation.png
[26]: ../assets/screenshots/hide-navigation-toc.png [26]: ../assets/screenshots/hide-toc.png
[27]: ../assets/screenshots/hide-navigation-toc.png
## Customization ## Customization
### Keyboard shortcuts ### Keyboard shortcuts
[:octicons-file-code-24: Source][27] · [:octicons-file-code-24: Source][28] ·
:octicons-mortar-board-24: Difficulty: _easy_ :octicons-mortar-board-24: Difficulty: _easy_
Material for MkDocs includes several keyboard shortcuts that make it possible Material for MkDocs includes several keyboard shortcuts that make it possible
@ -386,7 +342,7 @@ to navigate your project documentation via keyboard. There're two modes:
* ++n++ , ++period++ : go to next page * ++n++ , ++period++ : go to next page
Let's say you want to bind some action to the ++x++ key. By using [additional Let's say you want to bind some action to the ++x++ key. By using [additional
JavaScript][28], you can subscribe to the `keyboard$` observable and attach JavaScript][29], you can subscribe to the `keyboard$` observable and attach
your custom event listener: your custom event listener:
``` js ``` js
@ -402,12 +358,12 @@ The call to `#!js key.claim()` will essentially execute `#!js preventDefault()`
on the underlying event, so the keypress will not propagate further and touch on the underlying event, so the keypress will not propagate further and touch
other event listeners. other event listeners.
[27]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts [28]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/integrations/keyboard/index.ts
[28]: ../customization.md#additional-javascript [29]: ../customization.md#additional-javascript
### Content area width ### Content area width
[:octicons-file-code-24: Source][29] · [:octicons-file-code-24: Source][30] ·
:octicons-mortar-board-24: Difficulty: _easy_ :octicons-mortar-board-24: Difficulty: _easy_
The width of the content area is set so the length of each line doesn't exceed The width of the content area is set so the length of each line doesn't exceed
@ -416,7 +372,7 @@ is a reasonable default, as longer lines tend to be harder to read, it may be
desirable to increase the overall width of the content area, or even make it desirable to increase the overall width of the content area, or even make it
stretch to the entire available space. stretch to the entire available space.
This can easily be achieved with an [additional stylesheet][30] and a few lines This can easily be achieved with an [additional stylesheet][31] and a few lines
of CSS: of CSS:
=== "Increase width" === "Increase width"
@ -435,5 +391,5 @@ of CSS:
} }
``` ```
[29]: https://github.com/squidfunk/mkdocs-material/blob/aeaa00a625abf952f355164de02c539b061e6127/src/assets/stylesheets/main/layout/_base.scss#L99-L104 [30]: https://github.com/squidfunk/mkdocs-material/blob/aeaa00a625abf952f355164de02c539b061e6127/src/assets/stylesheets/main/layout/_base.scss
[30]: ../customization.md#additional-css [31]: ../customization.md#additional-css

83
docs/setup/setting-up-site-search.md
View File

@ -6,8 +6,8 @@ template: overrides/main.html
Material for MkDocs provides an excellent, client-side search implementation, Material for MkDocs provides an excellent, client-side search implementation,
omitting the need for the integration of third-party services, which might omitting the need for the integration of third-party services, which might
violate data privacy regulations. Moreover, with some effort, search can be be tricky to integrate to be compliant with data privacy regulations. Moreover,
made available [offline][1]. with some effort, search can be made available [offline][1].
[1]: #offline-search [1]: #offline-search
@ -58,27 +58,29 @@ The following options are supported:
The following languages are supported: The following languages are supported:
<ul class="tx-columns"> <div class="tx-columns" markdown="1">
<li><code>ar</code> – Arabic</li>
<li><code>da</code> – Danish</li> - `ar` – Arabic
<li><code>du</code> – Dutch</li> - `da` – Danish
<li><code>en</code> – English</li> - `du` – Dutch
<li><code>fi</code> – Finnish</li> - `en` – English
<li><code>fr</code> – French</li> - `fi` – Finnish
<li><code>de</code> – German</li> - `fr` – French
<li><code>hu</code> – Hungarian</li> - `de` – German
<li><code>it</code> – Italian</li> - `hu` – Hungarian
<li><code>ja</code> – Japanese</li> - `it` – Italian
<li><code>no</code> – Norwegian</li> - `ja` – Japanese
<li><code>pt</code> – Portuguese</li> - `no` – Norwegian
<li><code>ro</code> – Romanian</li> - `pt` – Portuguese
<li><code>ru</code> – Russian</li> - `ro` – Romanian
<li><code>es</code> – Spanish</li> - `ru` – Russian
<li><code>sv</code> – Swedish</li> - `es` – Spanish
<li><code>th</code> – Thai</li> - `sv` – Swedish
<li><code>tr</code> – Turkish</li> - `th` – Thai
<li><code>vi</code> – Vietnamese</li> - `tr` – Turkish
</ul> - `vi` – Vietnamese
</div>
_Material for MkDocs also tries to support languages that are not part of _Material for MkDocs also tries to support languages that are not part of
this list by choosing the stemmer yielding the best result automatically_. this list by choosing the stemmer yielding the best result automatically_.
@ -149,19 +151,19 @@ theme:
- search.suggest - search.suggest
``` ```
Searching for [ :material-magnify: ^^code high^^ ] yields [ :material-magnify: Searching for ^^code high^^ yields ^^code highlighting^^ as a suggestion:
^^code highlighting^^ ] as a suggestion:
[![Search suggestions][9]][9] <figure markdown="1">
[![Search suggestions][9]][9]
[Try this feature][10]{: .md-button .md-button--primary } <figcaption markdown="1">
A demo is worth a thousand words — check it out at
_This feature is enabled on the [official documentation][10] built with [squidfunk.github.io/mkdocs-material-insiders][10]
Insiders._ </figcaption>
</figure>
[8]: ../insiders.md [8]: ../insiders.md
[9]: ../assets/screenshots/search-suggestions.png [9]: ../assets/screenshots/search-suggestions.png
[10]: https://squidfunk.github.io/mkdocs-material-insiders/setup/setting-up-site-search [10]: https://squidfunk.github.io/mkdocs-material-insiders/reference/code-blocks/?q=code+high
### Search highlighting ### Search highlighting
@ -180,14 +182,15 @@ theme:
- search.highlight - search.highlight
``` ```
Searching for [ :material-magnify: ^^code blocks^^ ] yields: Searching for ^^code blocks^^ yields:
[![Search highlighting][11]][11] <figure markdown="1">
[![Search highlighting][11]][11]
[Try this feature][12]{: .md-button .md-button--primary } <figcaption markdown="1">
A demo is worth a thousand words — check it out at
_This feature is enabled on the [official documentation][12] built with [squidfunk.github.io/mkdocs-material-insiders][12]
Insiders._ </figcaption>
</figure>
[11]: ../assets/screenshots/search-highlighting.png [11]: ../assets/screenshots/search-highlighting.png
[12]: https://squidfunk.github.io/mkdocs-material-insiders/reference/code-blocks/?h=code+blocks [12]: https://squidfunk.github.io/mkdocs-material-insiders/reference/code-blocks/?h=code+blocks
@ -204,7 +207,7 @@ combination with @squidfunk's [iframe-worker][15] polyfill.
For setup instructions, refer to the [official documentation][16]. For setup instructions, refer to the [official documentation][16].
[13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L368-L369 [13]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html
[14]: https://github.com/wilhelmer/mkdocs-localsearch/ [14]: https://github.com/wilhelmer/mkdocs-localsearch/
[15]: https://github.com/squidfunk/iframe-worker [15]: https://github.com/squidfunk/iframe-worker
[16]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5 [16]: https://github.com/wilhelmer/mkdocs-localsearch#installation-material-v5

2
docs/setup/setting-up-the-footer.md
View File

@ -101,7 +101,7 @@ displayed next to the social links. It can be defined as part of `mkdocs.yml`:
copyright: Copyright &copy; 2016 - 2020 Martin Donath copyright: Copyright &copy; 2016 - 2020 Martin Donath
``` ```
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/footer.html#L85-L99 [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/footer.html
### Remove generator ### Remove generator

5
docs/setup/setting-up-the-header.md
View File

@ -18,8 +18,7 @@ It also includes the [search bar][1] and a place to display your project's
[:octicons-file-code-24: Source][3] · [:octicons-file-code-24: Source][3] ·
:octicons-unlock-24: Feature flag · :octicons-unlock-24: Feature flag ·
:octicons-beaker-24: Experimental · :octicons-beaker-24: Experimental
[:octicons-heart-fill-24:{: .tx-heart } Insiders only][3]{: .tx-insiders }
When _autohiding_ is enabled, the header is automatically hidden when the When _autohiding_ is enabled, the header is automatically hidden when the
user scrolls past a certain threshold, leaving more space for content. It can user scrolls past a certain threshold, leaving more space for content. It can
@ -31,7 +30,7 @@ theme:
- header.autohide - header.autohide
``` ```
[3]: ../insiders.md [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/layout/_header.scss
## Customization ## Customization

14
docs/setup/setting-up-versioning.md
View File

@ -33,11 +33,13 @@ extra:
This will render a version selector in the header next to the title of your This will render a version selector in the header next to the title of your
project: project:
[![Version selection][3]][3] <figure markdown="1">
[![Version selection][3]][3]
[Try this feature][4]{: .md-button .md-button--primary } <figcaption markdown="1">
A demo is worth a thousand words — check it out at
_This feature is enabled in the [versioning example][4] built with Insiders._ [squidfunk.github.io/mkdocs-material-example-versioning][4]
</figcaption>
</figure>
!!! quote "[Why use mike?][5]" !!! quote "[Why use mike?][5]"
@ -52,7 +54,7 @@ _This feature is enabled in the [versioning example][4] built with Insiders._
to particularly notable versions. This makes it easy to make permalinks to to particularly notable versions. This makes it easy to make permalinks to
whatever version of the documentation you want to direct people to. whatever version of the documentation you want to direct people to.
_Note that you don't need to run `mike install-extras` as noted in the _Note that you don't need to run_ `mike install-extras` _as noted in the
[official documentation][6], as [mike][1] is now natively integrated with [official documentation][6], as [mike][1] is now natively integrated with
Material for MkDocs._ Material for MkDocs._

8
material/assets/manifest.json
View File

@ -5,10 +5,10 @@
"assets/javascripts/vendor.js.map": "assets/javascripts/vendor.0ac82a11.min.js.map", "assets/javascripts/vendor.js.map": "assets/javascripts/vendor.0ac82a11.min.js.map",
"assets/javascripts/worker/search.js": "assets/javascripts/worker/search.4ac00218.min.js", "assets/javascripts/worker/search.js": "assets/javascripts/worker/search.4ac00218.min.js",
"assets/javascripts/worker/search.js.map": "assets/javascripts/worker/search.4ac00218.min.js.map", "assets/javascripts/worker/search.js.map": "assets/javascripts/worker/search.4ac00218.min.js.map",
"assets/stylesheets/main.css": "assets/stylesheets/main.68792d00.min.css", "assets/stylesheets/main.css": "assets/stylesheets/main.e86bb7d5.min.css",
"assets/stylesheets/main.css.map": "assets/stylesheets/main.68792d00.min.css.map", "assets/stylesheets/main.css.map": "assets/stylesheets/main.e86bb7d5.min.css.map",
"assets/stylesheets/overrides.css": "assets/stylesheets/overrides.cff55ccf.min.css", "assets/stylesheets/overrides.css": "assets/stylesheets/overrides.1a64f041.min.css",
"assets/stylesheets/overrides.css.map": "assets/stylesheets/overrides.cff55ccf.min.css.map", "assets/stylesheets/overrides.css.map": "assets/stylesheets/overrides.1a64f041.min.css.map",
"assets/stylesheets/palette.css": "assets/stylesheets/palette.7cb87594.min.css", "assets/stylesheets/palette.css": "assets/stylesheets/palette.7cb87594.min.css",
"assets/stylesheets/palette.css.map": "assets/stylesheets/palette.7cb87594.min.css.map" "assets/stylesheets/palette.css.map": "assets/stylesheets/palette.7cb87594.min.css.map"
} }

3
material/assets/stylesheets/main.68792d00.min.css vendored
View File

File diff suppressed because one or more lines are too long

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

File diff suppressed because one or more lines are too long

3
material/assets/stylesheets/main.e86bb7d5.min.css vendored Normal file
View File

File diff suppressed because one or more lines are too long

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

File diff suppressed because one or more lines are too long

3
material/assets/stylesheets/overrides.1a64f041.min.css vendored Normal file
View File

@ -0,0 +1,3 @@
@-webkit-keyframes tx-heart{0%,40%,80%,100%{transform:scale(1)}20%,60%{transform:scale(1.15)}}@keyframes tx-heart{0%,40%,80%,100%{transform:scale(1)}20%,60%{transform:scale(1.15)}}.md-typeset figure>p+figcaption{margin-top:-1.2rem}.md-typeset .twitter{color:#00acee}.md-typeset .tx-video{width:auto}.md-typeset .tx-video__inner{position:relative;width:100%;height:0;padding-bottom:56.138%}.md-typeset .tx-video iframe{position:absolute;top:0;left:0;width:100%;height:100%;overflow:hidden;border:none}.md-typeset .tx-heart{-webkit-animation:tx-heart 1000ms infinite;animation:tx-heart 1000ms infinite}.md-typeset .tx-insiders{color:#e91e63}.md-typeset .tx-insiders-button{font-weight:400}.md-typeset .tx-insiders-count{font-weight:700}.md-typeset .tx-insiders-list{margin:2em 0;overflow:auto}.md-typeset .tx-insiders-list__item{display:block;float:left;width:3rem;height:3rem;margin:.2rem;overflow:hidden;border-radius:100%;transform:scale(1);transition:color 125ms,transform 125ms}.md-typeset .tx-insiders-list__item img{display:block;width:100%;height:auto;-webkit-filter:grayscale(100%);filter:grayscale(100%);transition:-webkit-filter 125ms;transition:filter 125ms;transition:filter 125ms, -webkit-filter 125ms}.md-typeset .tx-insiders-list__item:focus,.md-typeset .tx-insiders-list__item:hover{transform:scale(1.1)}.md-typeset .tx-insiders-list__item:focus img,.md-typeset .tx-insiders-list__item:hover img{-webkit-filter:grayscale(0%);filter:grayscale(0%)}.md-typeset .tx-insiders-list__item--private{color:var(--md-default-fg-color--lighter);font-weight:700;font-size:1.2rem;line-height:3rem;text-align:center;background:var(--md-default-fg-color--lightest)}.md-typeset .tx-switch button{cursor:pointer;transition:opacity 250ms}.md-typeset .tx-switch button:focus,.md-typeset .tx-switch button:hover{opacity:.75}.md-typeset .tx-switch button>code{display:block;color:var(--md-primary-bg-color);background-color:var(--md-primary-fg-color)}.md-typeset .tx-columns ol,.md-typeset .tx-columns ul{-moz-columns:2;columns:2}@media screen and (max-width: 29.9375em){.md-typeset .tx-columns ol,.md-typeset .tx-columns ul{-moz-columns:initial;columns:initial}}.md-typeset .tx-columns li{-moz-column-break-inside:avoid;break-inside:avoid}.md-announce a,.md-announce a:focus,.md-announce a:hover{color:currentColor}.md-announce strong{white-space:nowrap}.md-announce .twitter{margin-left:.2em}.tx-content__footer{margin-top:1rem;text-align:center}.tx-content__footer a{display:inline-block;color:#e91e63;transition:transform 250ms cubic-bezier(0.1, 0.7, 0.1, 1),color 125ms}.tx-content__footer a:focus,.tx-content__footer a:hover{transform:scale(1.2)}.tx-content__footer hr{display:inline-block;width:2rem;margin:1em;vertical-align:middle;background-color:currentColor;border:none}.tx-container{padding-top:1rem;background:url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 1123 258'><path d='M1124,2c0,0 0,256 0,256l-1125,0l0,-48c0,0 16,5 55,5c116,0 197,-92 325,-92c121,0 114,46 254,46c140,0 214,-167 572,-166Z' style='fill: hsla(0, 0%, 100%, 1)' /></svg>") no-repeat bottom,linear-gradient(to bottom, var(--md-primary-fg-color), #a63fd9 99%, var(--md-default-bg-color) 99%)}[data-md-color-scheme=slate] .tx-container{background:url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 1123 258'><path d='M1124,2c0,0 0,256 0,256l-1125,0l0,-48c0,0 16,5 55,5c116,0 197,-92 325,-92c121,0 114,46 254,46c140,0 214,-167 572,-166Z' style='fill: hsla(232, 15%, 21%, 1)' /></svg>") no-repeat bottom,linear-gradient(to bottom, var(--md-primary-fg-color), #a63fd9 99%, var(--md-default-bg-color) 99%)}.tx-hero{margin:0 .8rem;color:var(--md-primary-bg-color)}.tx-hero h1{margin-bottom:1rem;color:currentColor;font-weight:700}@media screen and (max-width: 29.9375em){.tx-hero h1{font-size:1.4rem}}.tx-hero__content{padding-bottom:6rem}@media screen and (min-width: 60em){.tx-hero{display:flex;align-items:stretch}.tx-hero__content{max-width:19rem;margin-top:3.5rem;padding-bottom:14vw}.tx-hero__image{order:1;width:38rem;transform:translateX(4rem)}}@media screen and (min-width: 76.25em){.tx-hero__image{transform:translateX(8rem)}}.tx-hero .md-button{margin-top:.5rem;margin-right:.5rem;color:var(--md-primary-bg-color)}.tx-hero .md-button:focus,.tx-hero .md-button:hover{color:var(--md-default-bg-color);background-color:var(--md-accent-fg-color);border-color:var(--md-accent-fg-color)}.tx-hero .md-button--primary{color:#894da8;background-color:var(--md-primary-bg-color);border-color:var(--md-primary-bg-color)}
/*# sourceMappingURL=overrides.1a64f041.min.css.map*/

1
material/assets/stylesheets/overrides.1a64f041.min.css.map Normal file
View File

File diff suppressed because one or more lines are too long

3
material/assets/stylesheets/overrides.cff55ccf.min.css vendored
View File

@ -1,3 +0,0 @@
.md-typeset .tx-insiders{color:#e91e63}.md-typeset .tx-switch button{cursor:pointer;transition:opacity 250ms}.md-typeset .tx-switch button:focus,.md-typeset .tx-switch button:hover{opacity:.75}.md-typeset .tx-switch button>code{display:block;color:var(--md-primary-bg-color);background-color:var(--md-primary-fg-color)}.md-typeset .tx-columns{-moz-columns:2;columns:2}.md-typeset .tx-columns>*{-moz-column-break-inside:avoid;break-inside:avoid}@media screen and (max-width: 29.9375em){.md-typeset .tx-columns{-moz-columns:initial;columns:initial}}.md-announce a,.md-announce a:focus,.md-announce a:hover{color:currentColor}.md-announce strong{white-space:nowrap}.md-announce .twitter{margin-left:.2em;color:#00acee}.tx-container{padding-top:1rem;background:url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 1123 258'><path d='M1124,2c0,0 0,256 0,256l-1125,0l0,-48c0,0 16,5 55,5c116,0 197,-92 325,-92c121,0 114,46 254,46c140,0 214,-167 572,-166Z' style='fill: hsla(0, 0%, 100%, 1)' /></svg>") no-repeat bottom,linear-gradient(to bottom, var(--md-primary-fg-color), #a63fd9 99%, var(--md-default-bg-color) 99%)}[data-md-color-scheme=slate] .tx-container{background:url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 1123 258'><path d='M1124,2c0,0 0,256 0,256l-1125,0l0,-48c0,0 16,5 55,5c116,0 197,-92 325,-92c121,0 114,46 254,46c140,0 214,-167 572,-166Z' style='fill: hsla(232, 15%, 21%, 1)' /></svg>") no-repeat bottom,linear-gradient(to bottom, var(--md-primary-fg-color), #a63fd9 99%, var(--md-default-bg-color) 99%)}@-webkit-keyframes tx-heart{0%,40%,80%,100%{transform:scale(1)}20%,60%{transform:scale(1.15)}}@keyframes tx-heart{0%,40%,80%,100%{transform:scale(1)}20%,60%{transform:scale(1.15)}}.tx-content__footer{margin-top:1rem;text-align:center}.tx-content__footer a{display:inline-block;color:#e91e63;transition:transform 250ms cubic-bezier(0.1, 0.7, 0.1, 1),color 125ms}.tx-content__footer a:focus,.tx-content__footer a:hover{transform:scale(1.2)}.tx-content__footer hr{display:inline-block;width:2rem;margin:1em;vertical-align:middle;background-color:currentColor;border:none}.tx-heart{-webkit-animation:tx-heart 1000ms infinite;animation:tx-heart 1000ms infinite}.tx-hero{margin:0 .8rem;color:var(--md-primary-bg-color)}.tx-hero h1{margin-bottom:1rem;color:currentColor;font-weight:700}@media screen and (max-width: 29.9375em){.tx-hero h1{font-size:1.4rem}}.tx-hero__content{padding-bottom:6rem}@media screen and (min-width: 60em){.tx-hero{display:flex;align-items:stretch}.tx-hero__content{max-width:19rem;margin-top:3.5rem;padding-bottom:14vw}.tx-hero__image{order:1;width:38rem;transform:translateX(4rem)}}@media screen and (min-width: 76.25em){.tx-hero__image{transform:translateX(8rem)}}.tx-hero .md-button{margin-top:.5rem;margin-right:.5rem;color:var(--md-primary-bg-color)}.tx-hero .md-button:hover,.tx-hero .md-button:focus{color:var(--md-default-bg-color);background-color:var(--md-accent-fg-color);border-color:var(--md-accent-fg-color)}.tx-hero .md-button--primary{color:#894da8;background-color:var(--md-primary-bg-color);border-color:var(--md-primary-bg-color)}
/*# sourceMappingURL=overrides.cff55ccf.min.css.map*/

1
material/assets/stylesheets/overrides.cff55ccf.min.css.map
View File

File diff suppressed because one or more lines are too long

2
material/base.html
View File

@ -39,7 +39,7 @@
{% endif %} {% endif %}
{% endblock %} {% endblock %}
{% block styles %} {% block styles %}
<link rel="stylesheet" href="{{ 'assets/stylesheets/main.68792d00.min.css' | url }}"> <link rel="stylesheet" href="{{ 'assets/stylesheets/main.e86bb7d5.min.css' | url }}">
{% if config.theme.palette %} {% if config.theme.palette %}
{% set palette = config.theme.palette %} {% set palette = config.theme.palette %}
<link rel="stylesheet" href="{{ 'assets/stylesheets/palette.7cb87594.min.css' | url }}"> <link rel="stylesheet" href="{{ 'assets/stylesheets/palette.7cb87594.min.css' | url }}">

2
material/overrides/main.html
View File

@ -22,7 +22,7 @@
<meta name="twitter:title" content="{{ title }}"> <meta name="twitter:title" content="{{ title }}">
<meta name="twitter:description" content="{{ config.site_description }}"> <meta name="twitter:description" content="{{ config.site_description }}">
<meta name="twitter:image" content="{{ image }}"> <meta name="twitter:image" content="{{ image }}">
<link rel="stylesheet" href="{{ 'assets/stylesheets/overrides.cff55ccf.min.css' | url }}"> <link rel="stylesheet" href="{{ 'assets/stylesheets/overrides.1a64f041.min.css' | url }}">
{% endblock %} {% endblock %}
{% block announce %} {% block announce %}
<a href="https://twitter.com/squidfunk"> <a href="https://twitter.com/squidfunk">

10
mkdocs.yml
View File

@ -53,7 +53,6 @@ theme:
features: features:
- navigation.sections - navigation.sections
- navigation.tabs - navigation.tabs
#- navigation.instant
palette: palette:
scheme: default scheme: default
primary: indigo primary: indigo
@ -110,6 +109,7 @@ markdown_extensions:
- def_list - def_list
- footnotes - footnotes
- meta - meta
- md_in_html
- toc: - toc:
permalink: true permalink: true
- pymdownx.arithmatex: - pymdownx.arithmatex:
@ -184,9 +184,11 @@ nav:
- Meta tags: reference/meta-tags.md - Meta tags: reference/meta-tags.md
- Variables: reference/variables.md - Variables: reference/variables.md
- Changelog: - Changelog:
- Release notes: changelog.md - Material for MkDocs: changelog.md
- Upgrading: upgrading.md - Material for MkDocs Insiders: changelog/insiders.md
- Deprecations: deprecations.md - Guides:
- Upgrading: upgrading.md
- Deprecations: deprecations.md
# Google Analytics # Google Analytics
google_analytics: google_analytics:

7
src/assets/stylesheets/main/_typeset.scss
View File

@ -456,12 +456,17 @@ kbd {
max-width: 100%; max-width: 100%;
margin: 0 auto; margin: 0 auto;
text-align: center; text-align: center;
// Figure images
img {
display: block;
}
} }
// Figure caption // Figure caption
figcaption { figcaption {
max-width: px2rem(480px); max-width: px2rem(480px);
margin: 0.5em auto 2em; margin: 1em auto 2em;
font-style: italic; font-style: italic;
} }

3
src/assets/stylesheets/main/extensions/markdown/_footnotes.scss
View File

@ -35,8 +35,9 @@
.md-typeset { .md-typeset {
// Footnote reference container - improve alignment // Footnote reference container - improve alignment
[id^="fnref:"] { html & [id^="fnref:"] {
display: inline-block; display: inline-block;
scroll-margin-top: px2rem(48px + 24px - 3px);
} }
// Footnote container // Footnote container

1
src/assets/stylesheets/overrides.scss
View File

@ -38,6 +38,5 @@
@import "overrides/typeset"; @import "overrides/typeset";
@import "overrides/layout/announce"; @import "overrides/layout/announce";
@import "overrides/layout/base";
@import "overrides/layout/content"; @import "overrides/layout/content";
@import "overrides/layout/hero"; @import "overrides/layout/hero";

133
src/assets/stylesheets/overrides/_typeset.scss
View File

@ -20,6 +20,20 @@
/// DEALINGS /// DEALINGS
//// ////
// ----------------------------------------------------------------------------
// Keyframes
// ----------------------------------------------------------------------------
// Pumping heart animation
@keyframes tx-heart {
0%, 40%, 80%, 100% {
transform: scale(1);
}
20%, 60% {
transform: scale(1.15);
}
}
// ---------------------------------------------------------------------------- // ----------------------------------------------------------------------------
// Rules // Rules
// ---------------------------------------------------------------------------- // ----------------------------------------------------------------------------
@ -27,17 +41,117 @@
// Scoped in typesetted content to match specificity of regular content // Scoped in typesetted content to match specificity of regular content
.md-typeset { .md-typeset {
// Screenshot caption
figure > p + figcaption {
margin-top: px2rem(-24px);
}
// Twitter icon
.twitter {
color: #00ACEE;
}
// Insiders video
.tx-video {
width: auto;
// Insiders video container
&__inner {
position: relative;
width: 100%;
height: 0;
padding-bottom: 56.138%;
}
// Insiders video iframe
iframe {
position: absolute;
top: 0;
left: 0;
width: 100%;
height: 100%;
overflow: hidden;
border: none;
}
}
// Pumping heart
.tx-heart {
animation: tx-heart 1000ms infinite;
}
// Insiders color (for links, etc.) // Insiders color (for links, etc.)
.tx-insiders { .tx-insiders {
color: $clr-pink-500; color: $clr-pink-500;
} }
// Insiders button
.tx-insiders-button {
font-weight: 400;
}
// Insiders count
.tx-insiders-count {
font-weight: 700;
}
// Insiders list
.tx-insiders-list {
margin: 2em 0;
overflow: auto;
// Insiders list item
&__item {
display: block;
float: left;
width: px2rem(60px);
height: px2rem(60px);
margin: px2rem(4px);
overflow: hidden;
border-radius: 100%;
transform: scale(1);
transition:
color 125ms,
transform 125ms;
// Sponsor avatar
img {
display: block;
width: 100%;
height: auto;
filter: grayscale(100%);
transition: filter 125ms;
}
// Sponsor item on focus/hover
&:focus,
&:hover {
transform: scale(1.1);
// Sponsor avatar
img {
filter: grayscale(0%);
}
}
// Private sponsor
&--private {
color: var(--md-default-fg-color--lighter);
font-weight: 700;
font-size: px2rem(24px);
line-height: px2rem(60px);
text-align: center;
background: var(--md-default-fg-color--lightest);
}
}
}
// Switch buttons // Switch buttons
.tx-switch button { .tx-switch button {
cursor: pointer; cursor: pointer;
transition: opacity 250ms; transition: opacity 250ms;
// Button on hover // Button on focus/hover
&:focus, &:focus,
&:hover { &:hover {
opacity: 0.75; opacity: 0.75;
@ -53,16 +167,21 @@
// Two-column layout // Two-column layout
.tx-columns { .tx-columns {
columns: 2;
// Column // Column
> * { ol,
break-inside: avoid; ul {
columns: 2;
// [mobile portrait -]: Reset columns on mobile
@include break-to-device(mobile portrait) {
columns: initial;
}
} }
// [mobile portrait -]: Reset columns on mobile // Column item
@include break-to-device(mobile portrait) { li {
columns: initial; break-inside: avoid;
} }
} }
} }

1
src/assets/stylesheets/overrides/layout/_announce.scss
View File

@ -42,6 +42,5 @@
// Twitter icon // Twitter icon
.twitter { .twitter {
margin-left: .2em; margin-left: .2em;
color: #00ACEE;
} }
} }

50
src/assets/stylesheets/overrides/layout/_base.scss
View File

@ -1,50 +0,0 @@
////
/// Copyright (c) 2016-2020 Martin Donath <martin.donath@squidfunk.com>
///
/// Permission is hereby granted, free of charge, to any person obtaining a
/// copy of this software and associated documentation files (the "Software"),
/// to deal in the Software without restriction, including without limitation
/// the rights to use, copy, modify, merge, publish, distribute, sublicense,
/// and/or sell copies of the Software, and to permit persons to whom the
/// Software is furnished to do so, subject to the following conditions:
///
/// The above copyright notice and this permission notice shall be included in
/// all copies or substantial portions of the Software.
///
/// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
/// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
/// FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL
/// THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
/// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
/// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
/// DEALINGS
////
// ----------------------------------------------------------------------------
// Rules
// ----------------------------------------------------------------------------
// Landing page container
.tx-container {
padding-top: px2rem(20px);
background:
url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 1123 258'><path d='M1124,2c0,0 0,256 0,256l-1125,0l0,-48c0,0 16,5 55,5c116,0 197,-92 325,-92c121,0 114,46 254,46c140,0 214,-167 572,-166Z' style='fill: hsla(0, 0%, 100%, 1)' /></svg>") no-repeat bottom,
linear-gradient(
to bottom,
var(--md-primary-fg-color),
hsla(280, 67%, 55%, 1) 99%,
var(--md-default-bg-color) 99%
);
// Adjust background for slate theme
[data-md-color-scheme="slate"] & {
background:
url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 1123 258'><path d='M1124,2c0,0 0,256 0,256l-1125,0l0,-48c0,0 16,5 55,5c116,0 197,-92 325,-92c121,0 114,46 254,46c140,0 214,-167 572,-166Z' style='fill: hsla(232, 15%, 21%, 1)' /></svg>") no-repeat bottom,
linear-gradient(
to bottom,
var(--md-primary-fg-color),
hsla(280, 67%, 55%, 1) 99%,
var(--md-default-bg-color) 99%
);
}
}

19
src/assets/stylesheets/overrides/layout/_content.scss
View File

@ -20,20 +20,6 @@
/// DEALINGS /// DEALINGS
//// ////
// ----------------------------------------------------------------------------
// Keyframes
// ----------------------------------------------------------------------------
// Pumping heart animation
@keyframes tx-heart {
0%, 40%, 80%, 100% {
transform: scale(1);
}
20%, 60% {
transform: scale(1.15);
}
}
// ---------------------------------------------------------------------------- // ----------------------------------------------------------------------------
// Rules // Rules
// ---------------------------------------------------------------------------- // ----------------------------------------------------------------------------
@ -68,8 +54,3 @@
border: none; border: none;
} }
} }
// Pumping heart
.tx-heart {
animation: tx-heart 1000ms infinite;
}

49
src/assets/stylesheets/overrides/layout/_hero.scss
View File

@ -24,29 +24,54 @@
// Rules // Rules
// ---------------------------------------------------------------------------- // ----------------------------------------------------------------------------
// Landing page container
.tx-container {
padding-top: px2rem(20px);
background:
url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 1123 258'><path d='M1124,2c0,0 0,256 0,256l-1125,0l0,-48c0,0 16,5 55,5c116,0 197,-92 325,-92c121,0 114,46 254,46c140,0 214,-167 572,-166Z' style='fill: hsla(0, 0%, 100%, 1)' /></svg>") no-repeat bottom,
linear-gradient(
to bottom,
var(--md-primary-fg-color),
hsla(280, 67%, 55%, 1) 99%,
var(--md-default-bg-color) 99%
);
// Adjust background for slate theme
[data-md-color-scheme="slate"] & {
background:
url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 1123 258'><path d='M1124,2c0,0 0,256 0,256l-1125,0l0,-48c0,0 16,5 55,5c116,0 197,-92 325,-92c121,0 114,46 254,46c140,0 214,-167 572,-166Z' style='fill: hsla(232, 15%, 21%, 1)' /></svg>") no-repeat bottom,
linear-gradient(
to bottom,
var(--md-primary-fg-color),
hsla(280, 67%, 55%, 1) 99%,
var(--md-default-bg-color) 99%
);
}
}
// Landing page hero // Landing page hero
.tx-hero { .tx-hero {
margin: 0 px2rem(16px); margin: 0 px2rem(16px);
color: var(--md-primary-bg-color); color: var(--md-primary-bg-color);
// Main headline // Hero headline
h1 { h1 {
margin-bottom: px2rem(20px); margin-bottom: px2rem(20px);
color: currentColor; color: currentColor;
font-weight: 700; font-weight: 700;
// [mobile portrait -]: Adjust headline // [mobile portrait -]: Larger hero headline
@include break-to-device(mobile portrait) { @include break-to-device(mobile portrait) {
font-size: px2rem(28px); font-size: px2rem(28px);
} }
} }
// Ensure that blob doesn't overlap buttons // Hero content
&__content { &__content {
padding-bottom: px2rem(120px); padding-bottom: px2rem(120px);
} }
// [tablet landscape +]: Display content and image next to each other // [tablet landscape +]: Columnar display
@include break-from-device(tablet landscape) { @include break-from-device(tablet landscape) {
display: flex; display: flex;
align-items: stretch; align-items: stretch;
@ -58,7 +83,7 @@
padding-bottom: 14vw; padding-bottom: 14vw;
} }
// Adjust order and set dimensions // Hero image
&__image { &__image {
order: 1; order: 1;
width: px2rem(760px); width: px2rem(760px);
@ -66,30 +91,30 @@
} }
} }
// [screen +]: Adjust spacing // [screen +]: Columnar display and adjusted spacing
@include break-from-device(screen) { @include break-from-device(screen) {
// Ensure the image aligns with the repository information // Hero image
&__image { &__image {
transform: translateX(#{px2rem(160px)}); transform: translateX(#{px2rem(160px)});
} }
} }
// Adjust spacing of buttons and invert them // Button
.md-button { .md-button {
margin-top: px2rem(10px); margin-top: px2rem(10px);
margin-right: px2rem(10px); margin-right: px2rem(10px);
color: var(--md-primary-bg-color); color: var(--md-primary-bg-color);
// Invert hover and focus button states // Button on focus/hover
&:hover, &:focus,
&:focus { &:hover {
color: var(--md-default-bg-color); color: var(--md-default-bg-color);
background-color: var(--md-accent-fg-color); background-color: var(--md-accent-fg-color);
border-color: var(--md-accent-fg-color); border-color: var(--md-accent-fg-color);
} }
// Invert primary button // Primary button
&--primary { &--primary {
color: hsla(280deg, 37%, 48%, 1); color: hsla(280deg, 37%, 48%, 1);
background-color: var(--md-primary-bg-color); background-color: var(--md-primary-bg-color);