diff --git a/CHANGELOG b/CHANGELOG index b57582135..56bd8b713 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,13 +1,13 @@ 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) 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 arbitrary links in navigation tabs + * Refactored navigation tabs to simplify grouping behavior * Fixed #2098: Subsequent active subsection not highlighted correctly mkdocs-material-6.1.7+insiders-1.12.1 (2020-12-08) diff --git a/docs/assets/screenshots/color-palette-toggle.png b/docs/assets/screenshots/color-palette-toggle.png new file mode 100644 index 000000000..7915deeb9 Binary files /dev/null and b/docs/assets/screenshots/color-palette-toggle.png differ diff --git a/docs/changelog.md b/docs/changelog.md index 579cbb2b2..9630ec223 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -4,100 +4,6 @@ template: overrides/main.html # Changelog -## Material for MkDocs Insiders - -### 1.13.1 _ December 13, 2020 - -- Removed horizontal scrollbars on language and version selector -- Fixed type conversion in JavaScript config - -### 1.13.0 _ December 13, 2020 - -- 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 _ December 8, 2020 - -- Fixed empty language selector being shown - -### 1.12.0 _ December 6, 2020 - -- Added support for adding a language selector - -### 1.11.2 _ November 29, 2020 - -- Fixed #2068: Search highlight interprets code blocks as JavaScript - -### 1.11.1 _ November 29, 2020 - -- Refactored styling to be more stable and easier to adjust -- Fixed some styling regressions from latest features - -### 1.11.0 _ November 22, 2020 - -- Added support for rendering admonitions as inline blocks - -### 1.10.0 _ November 15, 2020 - -- Added support for integrating table of contents into navigation - -### 1.9.0 _ November 7, 2020 - -- Added support for hiding navigation and table of contents on any page -- Removed autohiding table of contents when empty - -### 1.8.0 _ November 1, 2020 - -- Added support for navigation sections -- Fixed appearance of inactive search suggestions - -### 1.7.0 _ October 25, 2020 - -- Added support for deploying multiple versions -- Fixed alignment of sidebar when content area is too small - -### 1.6.0 _ October 11, 2020 - -- 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 _ September 21, 2020 - -- Fixed content area stretching to whole width for long code blocks - -### 1.5.0 _ September 19, 2020 - -- Added support for autohiding table of contents when empty - -### 1.4.1 _ September 6, 2020 - -- Improved typeahead and search result relevance and scoring - -### 1.4.0 _ August 30, 2020 - -- Added support for autohiding header on scroll - -### 1.3.0 _ August 26, 2020 - -- Added support for user-selectable color palettes - -### 1.2.0 _ August 11, 2020 - -- Added feature to expand navigation by default - -### 1.1.0 _ August 3, 2020 - -- Added highlighting of search results - -### 1.0.0 _ July 14, 2020 - -- Added grouping of search results -- Added missing query terms to search result -- Improved search result relevance and scoring - ## Material for MkDocs ### 6.1.7 _ December 6, 2020 diff --git a/docs/changelog/insiders.md b/docs/changelog/insiders.md new file mode 100644 index 000000000..160c3e1b0 --- /dev/null +++ b/docs/changelog/insiders.md @@ -0,0 +1,99 @@ +--- +template: overrides/main.html +--- + +# Changelog + +## Material for MkDocs Insiders + +### 1.13.1 _ December 20, 2020 + +- Removed horizontal scrollbars on language and version selector +- Fixed type conversion in JavaScript config + +### 1.13.0 _ December 13, 2020 + +- 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 _ December 8, 2020 + +- Fixed empty language selector being shown + +### 1.12.0 _ December 6, 2020 + +- Added support for adding a language selector + +### 1.11.2 _ November 29, 2020 + +- Fixed #2068: Search highlight interprets code blocks as JavaScript + +### 1.11.1 _ November 29, 2020 + +- Refactored styling to be more stable and easier to adjust +- Fixed some styling regressions from latest features + +### 1.11.0 _ November 22, 2020 + +- Added support for rendering admonitions as inline blocks + +### 1.10.0 _ November 15, 2020 + +- Added support for integrating table of contents into navigation + +### 1.9.0 _ November 7, 2020 + +- Added support for hiding navigation and table of contents on any page +- Removed autohiding table of contents when empty + +### 1.8.0 _ November 1, 2020 + +- Added support for navigation sections +- Fixed appearance of inactive search suggestions + +### 1.7.0 _ October 25, 2020 + +- Added support for deploying multiple versions +- Fixed alignment of sidebar when content area is too small + +### 1.6.0 _ October 11, 2020 + +- 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 _ September 21, 2020 + +- Fixed content area stretching to whole width for long code blocks + +### 1.5.0 _ September 19, 2020 + +- Added support for autohiding table of contents when empty + +### 1.4.1 _ September 6, 2020 + +- Improved typeahead and search result relevance and scoring + +### 1.4.0 _ August 30, 2020 + +- Added support for autohiding header on scroll + +### 1.3.0 _ August 26, 2020 + +- Added support for user-selectable color palettes + +### 1.2.0 _ August 11, 2020 + +- Added feature to expand navigation by default + +### 1.1.0 _ August 3, 2020 + +- Added highlighting of search results + +### 1.0.0 _ July 14, 2020 + +- Added grouping of search results +- Added missing query terms to search result +- Improved search result relevance and scoring diff --git a/docs/creating-your-site.md b/docs/creating-your-site.md index 1c4c56c9e..eb6a72e38 100644 --- a/docs/creating-your-site.md +++ b/docs/creating-your-site.md @@ -87,9 +87,11 @@ defaults, because_ [`mkdocs_theme.yml`][3] _is not loaded automatically as ### Advanced configuration -Material for MkDocs comes with a lot of configuration options. The _setup_ -section explains in great detail how to configure and customize colors, fonts, -icons and much more: +Material for MkDocs comes with many configuration options. The _setup_ section +explains in great detail how to configure and customize colors, fonts, icons +and much more: + +
- [Changing the colors][5] - [Changing the fonts][6] @@ -104,6 +106,8 @@ icons and much more: - [Adding a git repository][15] - [Adding a comment system][16] +
+ [5]: setup/changing-the-colors.md [6]: setup/changing-the-fonts.md [7]: setup/changing-the-language.md diff --git a/docs/getting-started.md b/docs/getting-started.md index dfa0a2eae..4fc8a704b 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -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 no need to install those packages separately. -_Note that in order to install [Material for MkDocs Insiders][8], you'll -need to [become a sponsor][9], create a personal access token[^1], and -set the_ `GH_TOKEN` _environment variable to the token's value._ +_Note that in order to install [Insiders][8], you'll need to [become a +sponsor][9], create a personal access token[^1], and set the_ `GH_TOKEN` +_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/ [6]: https://pygments.org/ @@ -78,15 +85,22 @@ The following plugins are bundled with the Docker image: - [mkdocs-minify-plugin][11] - [mkdocs-redirects][12] -_Note that in order to install [Material for MkDocs Insiders][8], you'll -need to [become a sponsor][9], create a personal access token[^2], and -set the_ `GH_TOKEN` _environment variable to the token's value._ +_Note that in order to install [Insiders][8], you'll need to [become a +sponsor][9], create a personal access token[^2], and set the_ `GH_TOKEN` +_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/ [11]: https://github.com/byrnereese/mkdocs-minify-plugin [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 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 ``` -_Note that in order to install [Material for MkDocs Insiders][8], you'll -need to [become a sponsor][9]._ +_Note that in order to install [Insiders][8], you'll need to [become a +sponsor][9]._ [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 [15]: https://docs.github.com/en/developers/apps/scopes-for-oauth-apps#available-scopes [16]: publishing-your-site.md#github-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 - [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 diff --git a/docs/insiders.md b/docs/insiders.md index 4f6ead9f0..84a0fd5ee 100644 --- a/docs/insiders.md +++ b/docs/insiders.md @@ -4,267 +4,230 @@ template: overrides/main.html # :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 -__Material for MkDocs Insiders__. Read on to learn [how sponsorship works][2], -and how you can [become a sponsor][3]. +__Insiders__. Read on to learn [how sponsorship works][1], and how easy it is +to [get access to Insiders][2]. - [1]: https://github.com/sponsorware/docs - [2]: #how-sponsorship-works - [3]: #how-to-become-a-sponsor +
+
+ +
+
+ A demo is worth a thousand words — check it out at + [squidfunk.github.io/mkdocs-material-insiders][3] +
+
-
- -
-

- A demo is worth a thousand words — check it out at
- - squidfunk.github.io/mkdocs-material-insiders - -

+ [1]: #how-sponsorship-works + [2]: #how-to-become-a-sponsor + [3]: https://squidfunk.github.io/mkdocs-material-insiders/ ## How sponsorship works -New features will first land in Material for MkDocs Insiders, which means that -_sponsors will have access immediately_. Every feature is tied to a funding -goal in monthly subscriptions. If a funding goal is hit, the features that are -tied to it are merged back into Material for MkDocs and released for general -availability. Bugfixes will always be released simultaneously in both editions. +New features first land in Insiders, which means that _sponsors will have access +immediately_. Every feature is tied to a funding goal in monthly subscriptions. +When a funding goal is hit, the features that are tied to it are merged back +into Material for MkDocs and released for general availability. Bugfixes are +always released simultaneously in both editions. -See the [roadmap][4] for a list of already available and upcoming features, and -for demonstration purposes, [the official documentation][5] built with Material -for MkDocs Insiders. +_Don't want to sponsor? No problem, Material for MkDocs already has tons of +features available, so chances are that most of your requirements are already +satisfied. See the [list of exclusive features][4] to learn which features are +currently only available to sponsors._ - [4]: #roadmap - [5]: https://squidfunk.github.io/mkdocs-material-insiders/ - - - - + [4]: #exclusive-features ## How to become a sponsor -So you've decided to become a sponsor? Great! You're just __three easy steps__ -away from enjoying the latest features of Material for MkDocs Insiders. -Complete the following steps and you're in: +You can become a sponsor using your individual or organization's GitHub account. +Just visit __[squidfunk's sponsor profile][5]__, pick any tier __from +$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 - access to squidfunk's sponsorware, which is _any tier from $10/month_. Select - the tier and complete the checkout. -- Within 24 hours, you will become a collaborator of the private Material for - MkDocs Insiders GitHub repository, a fork of Material for MkDocs with - [brand new and exclusive features][7]. -- Create a [personal access token][8], which allows installing Material for - MkDocs Insiders from any destination, including other CI providers like - [GitLab][9] or [Bitbucket][10]. +__Important__: If you're sponsoring @squidfunk through a GitHub organization, +please send a short email to sponsors@squidfunk.com with the name of your +organization and the account that should be added as a collaborator.[^1] -__Congratulations! :partying_face: You're now officially a sponsor and will -get updates for Material for MkDocs Insiders, until you decide to cancel your -monthly subscription, which you can do at any time.__ - -??? info "Sponsoring via a GitHub organization?" - - If you sponsor @squidfunk through a GitHub organization (which is currently - 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 + [^1]: + It's currently not possible to grant access to each member of an + organization, as GitHub only allows for adding users. Thus, after + sponsoring, please send an email to sponsors@squidfunk.com, stating which + account should become a collaborator of the Insiders repository. We're + working on a solution which will make access to organizations much simpler. + To ensure that access is not tied to a particular individual GitHub account, 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 - of collaborators, the bot account can create a private fork of the private - Insiders GitHub repository, effectively granting access to all members. + individual), and use this account for the sponsoring. After being added to + the list of collaborators, the bot account can create a private fork of the + private Insiders GitHub repository, and grant access to all members of the + organizations. - [6]: https://github.com/sponsors/squidfunk - [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 +You can cancel your sponsorship anytime.[^2] -## 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 -for MkDocs Insiders. You can click on each feature to learn more about it: +[:octicons-heart-fill-24:{: .tx-heart }   Join our awesome sponsors][5]{: .md-button .md-button--primary .tx-insiders-button } -- [x] [Remove _Made with Material for MkDocs_ from footer][11] -- [x] [Support for user-toggleable themes (light/dark mode switch)][12] -- [x] [Support for deploying multiple versions][13] -- [x] [Support for deploying multiple languages][22] -- [x] [Search suggestions help to save keystrokes][14] -- [x] [Highlighting of matched search terms in content area][15] -- [x] Search goes to first result on ++enter++ (I'm feeling lucky) -- [x] [Navigation tabs can be made sticky][23] -- [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 - [12]: setup/changing-the-colors.md#color-palette-toggle - [13]: setup/setting-up-versioning.md#versioning - [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 -[I'm growing on my balcony][24] – shows which features are already available -in Material for MkDocs Insiders. +## Exclusive features - [24]: https://www.instagram.com/squidfunk/ +The following features are currently exclusively available to sponsors: -### Madame Jeanette +
-[:octicons-flame-24: Funding goal: __$500__][6] · -:octicons-unlock-24: Status: _Generally available_ +- [x] [Color palette toggle][15] +- [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) -- [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] · -:octicons-lock-24: Status: _Insiders only_ + [6]: https://twitter.com/squidfunk -- [x] [Navigation can be grouped into sections][16] -- [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] +## Funding -### Bhut Jolokia +### Goals -[:octicons-flame-24: Funding goal: __$1,500__][6] · -:octicons-lock-24: Status: _Insiders only_ +Following is a list of funding goals. When a funding goal is hit, the features +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] -- [x] [Support for deploying multiple versions][13] -- [x] [Support for deploying multiple languages][22] +#### $ 1,500 – Bhut Jolokia -### Black Pearl +- [x] [Admonition inline blocks][12] +- [x] [Site language selection][13] +- [x] [Versioning][14] -[:octicons-flame-24: Funding goal: __$2,000__][6] · -:octicons-lock-24: Status: _Insiders only_ + [12]: reference/admonitions.md#inline-blocks + [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] -- [ ] Support for user-toggleable code-block styles (light/dark mode switch) -- [ ] Table of contents auto-collapses and expands only the active section +#### $ 2,000 – Black Pearl -### 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] · -:octicons-lock-24: Status: _Insiders only_ + [15]: setup/changing-the-colors.md#color-palette-toggle -- [x] [Search suggestions help to save keystrokes][14] -- [x] [Highlighting of matched search terms in content area][15] -- [x] Search goes to first result on ++enter++ (I'm feeling lucky) -- [ ] Table of contents shows which sections have search results -- [ ] Support for displaying a user's last searches +#### $ 2,500 – Biquinho Vermelho + +- [x] [Search suggestions][16] +- [x] [Search highlighting][17] +- [ ] 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 +- [ ] 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] · -:octicons-lock-24: Status: _Insiders only_ +### Goals completed -- [x] [Navigation tabs can be made sticky][23] -- [x] [Remove _Made with Material for MkDocs_ from footer][11] -- [ ] Brand-new and exclusive vertical layout +#### $ 500 – Madame Jeanette + +- [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 ### Compatibility _We're running an open source project and want to make sure that users can build -the documentation without having access to Insiders. Is that still possible?_ +the documentation without having access to Insiders. Is this still possible?_ -Yes. Material for MkDocs Insiders strives to be compatible with Material for -MkDocs, so all new features are implemented as feature flags and all -improvements (e.g. search) do not require any changes to existing configuration. -This means that your users will be able to build the docs locally with the -regular version and when they push their changes to CI/CD, they will be built -with Material for MkDocs Insiders. For this reason, it's recommended to -[install Insiders][25] only in CI, as you don't want to expose your `GH_TOKEN` -to users. +Yes. Insiders is compatible with Material for MkDocs. All new features are +implemented behind feature flags; all configuration changes are +backward-compatible. This means that your users will be able to build the +documentation locally with Material for MkDocs and when they push their changes, +it can be built with Insiders (e.g. as part of GitHub Actions). Thus, it's +recommended to [install Insiders][21] only in CI, as you don't want to expose +your `GH_TOKEN` to users. - [25]: publishing-your-site.md#github-pages + [21]: publishing-your-site.md#github-pages ### Terms _We're using Material for MkDocs to build the developer documentation of a -commercial project. Can we use Material for MkDocs Insiders under the same -terms?_ +commercial project. Can we use Insiders under the same terms and conditions?_ Yes. Whether you're an individual or a company, you may use _Material for MkDocs Insiders_ precisely under the same terms as Material for MkDocs, which are given -by the [MIT license][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: -- Please __don't distribute the source code__ from Material for MkDocs Insiders. - You may freely use it for public, private or commercial projects, fork it, - mirror it, do whatever you want with it, but please don't release the source - code, as it would cannibalize the sponsorware strategy. +- Please __don't distribute the source code__ of Insiders. You may freely use + it for public, private or commercial projects, fork it, mirror it, do whatever + you want with it, but please don't release the source code, as it would + counteract the sponsorware strategy. - If you cancel your subscription, you're removed as a collaborator and will - miss out on future updates of Material for MkDocs Insiders. However, you may - __use the latest version__ that's available to you __as long as you like__. - Just remember that __[GitHub deletes private forks][27]__. + miss out on future updates of Insiders. However, you may __use the latest + version__ that's available to you __as long as you like__. Just remember that + [GitHub deletes private forks][23]. - [26]: license.md - [27]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository + [22]: license.md + [23]: https://docs.github.com/en/github/setting-up-and-managing-your-github-user-account/removing-a-collaborator-from-a-personal-repository diff --git a/docs/publishing-your-site.md b/docs/publishing-your-site.md index 08aacd039..c5681ed12 100644 --- a/docs/publishing-your-site.md +++ b/docs/publishing-your-site.md @@ -75,8 +75,8 @@ to your repository to see the workflow in action. Your documentation should shortly appear at `.github.io/`. _Remember to set the_ `GH_TOKEN` _environment variable to the value of your -[personal access token][3] when using [Material for MkDocs Insiders][4], which -can be done using [secrets][5]._ +[personal access token][3] when deploying [Insiders][4], which can be done +using [secrets][5]._ [2]: https://github.com/features/actions [3]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token @@ -119,7 +119,7 @@ following contents: ``` yaml image: python:latest - deploy: + pages: stage: deploy only: - master @@ -138,8 +138,8 @@ workflow in action. Your documentation should shortly appear at `.gitlab.io/`. _Remember to set the_ `GH_TOKEN` _environment variable to the value of your -[personal access token][3] when using [Material for MkDocs Insiders][4], which -can be done using [masked custom variables][8]._ +[personal access token][3] when deploying [Insiders][4], which can be done +using [masked custom variables][8]._ [6]: https://gitlab.com/pages [7]: https://docs.gitlab.com/ee/ci/ diff --git a/docs/reference/abbreviations.md b/docs/reference/abbreviations.md index 9398c3b10..7f3531210 100644 --- a/docs/reference/abbreviations.md +++ b/docs/reference/abbreviations.md @@ -13,7 +13,9 @@ enable site-wide glossaries. ### 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 shown on hover__, e.g. for glossaries: @@ -22,11 +24,12 @@ markdown_extensions: - 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 -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 be enabled via `mkdocs.yml`: @@ -35,15 +38,15 @@ markdown_extensions: - pymdownx.snippets ``` - [2]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/ - [3]: https://facelessuser.github.io/pymdown-extensions/ + [3]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/ + [4]: https://facelessuser.github.io/pymdown-extensions/ ## Usage ### Adding abbreviations -When the [Abbreviations][4] extension is enabled, abbreviations can be defined -with a special syntax similar to URLs and [footnotes][5] at any point in the +When the [Abbreviations][5] extension is enabled, abbreviations can be defined +with a special syntax similar to URLs and [footnotes][6] at any point in the Markdown document. _Example_: @@ -62,12 +65,12 @@ The HTML specification is maintained by the W3C. *[HTML]: Hyper Text Markup Language *[W3C]: World Wide Web Consortium - [4]: #abbreviations_1 - [5]: footnotes.md + [5]: #abbreviations_1 + [6]: footnotes.md ### 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 – 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 unreferenced file._ - [6]: #snippets + [7]: #snippets diff --git a/docs/reference/code-blocks.md b/docs/reference/code-blocks.md index ae086c009..9878dd490 100644 --- a/docs/reference/code-blocks.md +++ b/docs/reference/code-blocks.md @@ -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 [24]: ../setup/changing-the-colors.md#color-scheme [25]: https://pygments.org/docs/tokens/#literals - [26]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_codehilite.scss#L42 + [26]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_codehilite.scss diff --git a/docs/reference/icons-emojis.md b/docs/reference/icons-emojis.md index b92fe4e03..520cff052 100644 --- a/docs/reference/icons-emojis.md +++ b/docs/reference/icons-emojis.md @@ -91,19 +91,19 @@ _Example_: ``` - :material-account-circle: – `.icons/material/account-circle.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_: - :material-account-circle: – [`.icons/material/account-circle.svg`][14] - :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 [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 - [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 @@ -178,20 +178,6 @@ and adding the dedicated CSS class to the icon: Then, simply add the CSS class to the icon. - - _Example_: ``` markdown @@ -200,7 +186,7 @@ _Example_: _Result_: -:octicons-heart-fill-24:{: .heart } +:octicons-heart-fill-24:{: .tx-heart } [20]: #with-colors [21]: https://developer.mozilla.org/en-US/docs/Web/CSS/animation diff --git a/docs/setup/adding-a-comment-system.md b/docs/setup/adding-a-comment-system.md index 4fe264459..a66dd0c60 100644 --- a/docs/setup/adding-a-comment-system.md +++ b/docs/setup/adding-a-comment-system.md @@ -55,6 +55,7 @@ Markdown document, delimited by a blank line which ends the YAML context. ### Selective integration [:octicons-file-code-24: Source][2] · +:octicons-note-24: Metadata · :octicons-mortar-board-24: Difficulty: _easy_ 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 %} ``` - [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 [10]: ../customization.md#overriding-blocks diff --git a/docs/setup/adding-a-git-repository.md b/docs/setup/adding-a-git-repository.md index e7ab67a40..4a9804629 100644 --- a/docs/setup/adding-a-git-repository.md +++ b/docs/setup/adding-a-git-repository.md @@ -93,7 +93,7 @@ behavior can be changed by setting [`edit_uri`][9] in `mkdocs.yml`: 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/ [7]: https://about.gitlab.com/ [8]: https://bitbucket.org/ diff --git a/docs/setup/changing-the-colors.md b/docs/setup/changing-the-colors.md index a849e0238..5f5dc17a1 100644 --- a/docs/setup/changing-the-colors.md +++ b/docs/setup/changing-the-colors.md @@ -30,8 +30,7 @@ theme: scheme: default ``` -:material-cursor-default-click-outline: Click on a tile to change the color -scheme: +_Click on a tile to change the color scheme_:
@@ -76,8 +75,7 @@ theme: primary: indigo ``` -:material-cursor-default-click-outline: Click on a tile to change the primary -color: +_Click on a tile to change the primary color_:
@@ -131,8 +129,7 @@ theme: accent: indigo ``` -:material-cursor-default-click-outline: Click on a tile to change the accent -color: +_Click on a tile to change the accent color_: