diff --git a/docs/assets/screenshots/social-cards-accent.png b/docs/assets/screenshots/social-cards-accent.png new file mode 100644 index 000000000..8531f694e Binary files /dev/null and b/docs/assets/screenshots/social-cards-accent.png differ diff --git a/docs/assets/screenshots/social-cards-invert.png b/docs/assets/screenshots/social-cards-invert.png new file mode 100644 index 000000000..156a4e968 Binary files /dev/null and b/docs/assets/screenshots/social-cards-invert.png differ diff --git a/docs/assets/screenshots/social-cards-variant.png b/docs/assets/screenshots/social-cards-variant.png new file mode 100644 index 000000000..7bdaae397 Binary files /dev/null and b/docs/assets/screenshots/social-cards-variant.png differ diff --git a/docs/assets/screenshots/social-cards.png b/docs/assets/screenshots/social-cards.png index 3b348db34..40c51d7bd 100644 Binary files a/docs/assets/screenshots/social-cards.png and b/docs/assets/screenshots/social-cards.png differ diff --git a/docs/getting-started.md b/docs/getting-started.md index 34a49fcdb..c5a2b5d94 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -61,8 +61,8 @@ install those packages separately. :fontawesome-brands-youtube:{ style="color: #EE0F0F" } __[How to set up Material for MkDocs]__ by @james-willett – :octicons-clock-24: -15m – Learn how to create and host a documentation site using Material for Docs -on GitHub Pages in a step-by-step guide. +15m – Learn how to create and host a documentation site using Material for +MkDocs on GitHub Pages in a step-by-step guide. [How to set up Material for MkDocs]: https://www.youtube.com/watch?v=Q-YA_dA8C20 diff --git a/docs/insiders/changelog.md b/docs/insiders/changelog.md index 6d623e585..8eaf5f090 100644 --- a/docs/insiders/changelog.md +++ b/docs/insiders/changelog.md @@ -2,6 +2,11 @@ ## Material for MkDocs Insiders +### 4.33.0 April 22, 2023 { id="4.33.0" } + +- Added support for custom layouts for social plugin +- Added support for background images for social cards + ### 4.32.6 April 22, 2023 { id="4.32.6" } - Fixed #5336: Interplay of blog plugin with git-revision-date-localized diff --git a/docs/insiders/index.md b/docs/insiders/index.md index 0a6368dea..3d43da911 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -88,14 +88,16 @@ a handful of them, [thanks to our awesome sponsors]! ## What's in it for me? The moment you [become a sponsor][how to become a sponsor], you'll get __immediate -access to 25 additional features__ that you can start using right away, and +access to 27 additional features__ that you can start using right away, and which are currently exclusively available to sponsors:
+- [x] [Social plugin: custom layouts] :material-alert-decagram:{ .mdx-pulse title="Added on May 8, 2023" } +- [x] [Social plugin: background images] :material-alert-decagram:{ .mdx-pulse title="Added on May 8, 2023" } - [x] [Code range selection] :material-alert-decagram:{ .mdx-pulse title="Added on February 19, 2023" } -- [x] [Code annotations: custom selectors] :material-alert-decagram:{ .mdx-pulse title="Added on February 19, 2023" } -- [x] [Privacy plugin: optimization support] :material-alert-decagram:{ .mdx-pulse title="Added on February 6, 2023" } +- [x] [Code annotations: custom selectors] +- [x] [Privacy plugin: optimization support] - [x] [Optimize plugin] - [x] [Navigation path] (Breadcrumbs) - [x] [Typeset plugin] @@ -256,10 +258,6 @@ features prefixed with a checkmark symbol, denoting whether a feature is :octicons-check-circle-fill-24:{ style="color: var(--md-default-fg-color--lightest)" } planned, but not yet implemented. When the funding goal is hit, the features are released for general availability. -> [In February, we lost $1,3k in monthly funding because GitHub removed PayPal support][Twitter] - - [Twitter]: https://twitter.com/squidfunk/status/1643539228574269443 - #### $ 12,000 – Piri Piri - [x] [Blog plugin] @@ -327,10 +325,14 @@ are released for general availability. #### $ 24,000 – Blockpaprika +- [x] [Social plugin: custom layouts] +- [x] [Social plugin: background images] - [x] [Code range selection] - [x] [Code annotations: custom selectors] - [ ] Code line wrap button + [Social plugin: custom layouts]: ../setup/setting-up-social-cards.md#custom-layouts + [Social plugin: background images]: ../setup/setting-up-social-cards.md#+social.cards_layout_params.background_image [Code range selection]: ../reference/code-blocks.md#code-selection-button [Code annotations: custom selectors]: ../reference/code-blocks.md#custom-selectors diff --git a/docs/setup/building-an-optimized-site.md b/docs/setup/building-an-optimized-site.md index 1110dfc98..1486530de 100644 --- a/docs/setup/building-an-optimized-site.md +++ b/docs/setup/building-an-optimized-site.md @@ -1,7 +1,3 @@ ---- -status: new ---- - # Building an optimized site Material for MkDocs, by default, allows to build optimized sites that rank great @@ -196,7 +192,7 @@ The following configuration options are available for caching: ``` yaml plugins: - optimize: - cache_dir: path/to/folder + cache_dir: .cache/plugins/optimize ``` By default, all built-in plugins that implement caching will create a diff --git a/docs/setup/setting-up-a-blog.md b/docs/setup/setting-up-a-blog.md index 1470cf79d..454fef4d3 100644 --- a/docs/setup/setting-up-a-blog.md +++ b/docs/setup/setting-up-a-blog.md @@ -93,7 +93,7 @@ The following configuration options are available: ``` yaml plugins: - blog: - blog_dir: path/to/folder + blog_dir: blog ``` === "Standalone" diff --git a/docs/setup/setting-up-social-cards.md b/docs/setup/setting-up-social-cards.md index 0ef032a7c..7e220d89d 100644 --- a/docs/setup/setting-up-social-cards.md +++ b/docs/setup/setting-up-social-cards.md @@ -1,36 +1,27 @@ +--- +status: new +--- + # Setting up social cards -Social cards, also known as social previews, are images that are displayed when -a link to your project documentation is shared on social media. Material for -MkDocs can generate beautiful social cards automatically, using the [colors], -[fonts] and [logo][^1] defined in `mkdocs.yml`, -e.g.: +Material for MkDocs can automatically create beautiful social cards for your +documentation, which appear as link previews on social media platforms. You +can select from a variety of [pre-designed layouts][default layouts] or create +[custom layouts] to match your unique style and branding.
-[![Social cards preview]][Social cards preview] +[![Layout default variant]][Layout default variant]
-The social preview image for the page on [setting up site analytics]. -[Twitter's Card validator] shows how it will look when shared. +Social card of [formatting] reference.
- [^1]: - Both types of logos, images ([`theme.logo`](changing-the-logo-and-icons.md#image)) - and icons ([`theme.icon.logo`](changing-the-logo-and-icons.md#icon-bundled)) - are supported. While an image logo is used as-is, icons are filled with the - ([`social.cards_color.text`](#+social.cards_color)) color. Valid file paths - inside the [`custom_dir`](../customization.md#setup-and-theme-structure) will take priority. - - [colors]: changing-the-colors.md#primary-color - [fonts]: changing-the-fonts.md#regular-font - [logo]: changing-the-logo-and-icons.md#logo - [Social cards preview]: ../assets/screenshots/social-cards.png - [setting up site analytics]: setting-up-site-analytics.md - [Twitter's Card validator]: https://cards-dev.twitter.com/validator + [custom layouts]: #custom-layouts + [formatting]: ../reference/formatting.md ## Configuration @@ -40,17 +31,72 @@ The social preview image for the page on [setting up site analytics]. :octicons-cpu-24: Plugin · :octicons-beaker-24: Experimental -First, ensure you've installed all [dependencies] and have a valid [`site_url`] -[site_url], as social preview images must be referenced via absolute URLs. -Then, add the following lines to `mkdocs.yml`: +The built-in social plugin automatically generate a custom preview image for +each page. Install all [dependencies for image processing][^1] and add the +following lines to `mkdocs.yml`: + + [^1]: + The awesome thing about social cards is that they are generated during + build time and directly distributed with your documentation, no external + services involved. While it would technically be simpler to generate + social cards using a web browser and an automation framework like + [Puppeteer], it would add further liabilities to the toolchain, with the + potential to make build pipelines more complex and resource intense. + + For this reason, Material for MkDocs again follows its core principle of + making it as simple and powerful as possible, providing an easy-to-use + framework for building [custom layouts] using Python image processing + libraries. Additionally, this means that there's no necessity for internet + access in CI environments. ``` yaml plugins: - social ``` +> Note that [Insiders] contains a ground up rewrite of the social plugin that +> generates images much more efficiently in parallel and allows to build +> entirely [custom layouts]. + The following configuration options are available: +[`enabled`](#+social.enabled){ #+social.enabled } + +: :octicons-milestone-24: Default: `true` – This option specifies whether + the plugin is enabled when building your project. If you want to speed up + local builds, you can use an [environment variable]: + + ``` yaml + plugins: + - social: + enabled: !ENV [CI, false] + ``` + +[`concurrency`](#+social.concurrency){ #+social.concurrency } + +: [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24: + Default: _number of CPUs_ – How many CPUs the plugin is allowed to use when + generating social cards. With more CPUs, the plugin can do more work in the + same time, thus complete generation faster. Concurrent processing can be + disabled with: + + ``` yaml + plugins: + - social: + concurrency: 1 + ``` + + [Social cards support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0 + [built-in plugins]: ../insiders/getting-started.md#built-in-plugins + [dependencies for image processing]: dependencies/image-processing.md + [Puppeteer]: https://github.com/puppeteer/puppeteer + [Insiders]: ../insiders/index.md + [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables + +#### Social cards + +The following configuration options are available for social card generation: + [`cards`](#+social.cards){ #+social.cards } : :octicons-milestone-24: Default: `true` – This option specifies whether @@ -60,256 +106,250 @@ The following configuration options are available: ``` yaml plugins: - social: - cards: !ENV [CARDS, false] + cards: !ENV [CI, false] + ``` + +[`cards_dir`](#+social.cards_dir){ #+social.cards_dir } + +: :octicons-milestone-24: Default: `assets/images/social` – This option + specifies where the generated social cards will be stored. While it's + usually not necessary to change this option, change it with: + + ``` yaml + plugins: + - social: + cards_dir: assets/images/social ``` [`cards_color`](#+social.cards_color){ #+social.cards_color } -: :octicons-milestone-24: Default: [`theme.palette.primary`][palette.primary] - – This option specifies the colors for the background `fill` and foreground +: :octicons-milestone-24: Default: [`theme.palette.primary`][primary color] – + This option specifies the colors for the background `fill` and foreground `text` when generating the social card: ``` yaml plugins: - social: cards_color: - fill: "#0FF1CE" # (1)! + fill: "#0FF1CE" text: "#FFFFFF" ``` - 1. Colors can either be defined as HEX colors, or as [CSS color keywords]. - Note that HEX colors must be enclosed in quotes. + !!! warning "If you're using [Insiders], use [`cards_layout_params`](#+social.cards_layout_params)" [`cards_font`](#+social.cards_font){ #+social.cards_font } -: :octicons-milestone-24: Default: [`theme.font.text`][font.text] – This - option specifies which font to use for rendering the social card, which can - be any font hosted on [Google Fonts]: +: :octicons-milestone-24: Default: [`theme.font.text`][font] – This option + specifies which font to use for rendering the social card, which can be + any font hosted on [Google Fonts]: ``` yaml plugins: - social: - cards_font: Roboto + cards_font: Ubuntu ``` - !!! question "Why do social cards render boxes for CJK languages?" + !!! warning "If you're using [Insiders], use [`cards_layout_params`](#+social.cards_layout_params)" - Some fonts do not contain CJK characters, like for example the - [default font, `Roboto`][font.text]. In case your `site_name`, - `site_description`, or [page title] contain CJK characters, choose - another font from [Google Fonts] which comes with CJK characters, e.g. - one from the `Noto Sans` font family: +[`cards_layout_dir`](#+social.cards_layout_dir){ #+social.cards_layout_dir } - === "Chinese (Simplified)" - - ``` yaml - plugins: - - social: - cards_font: Noto Sans SC - ``` - - === "Chinese (Traditional)" - - ``` yaml - plugins: - - social: - cards_font: Noto Sans TC - ``` - - === "Japanese" - - ``` yaml - plugins: - - social: - cards_font: Noto Sans JP - ``` - - === "Korean" - - ``` yaml - plugins: - - social: - cards_font: Noto Sans KR - ``` - -[`cards_dir`](#+social.cards_dir){ #+social.cards_dir } - -: :octicons-milestone-24: Default: `assets/images/social` – This option - specifies where the generated social card images will be written to. It's - normally not necessary to change this option: +: [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24: + Default: _project root_ – This option specifies where the social plugin + should try to resolve [custom layouts] from, taking precedence over the + included layouts: ``` yaml plugins: - social: - cards_dir: path/to/folder + cards_layout_dir: .overrides/social/layouts ``` - [Social cards support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0 - [dependencies]: #dependencies - [site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url - [palette.primary]: changing-the-colors.md#primary-color - [font.text]: changing-the-fonts.md#regular-font - [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables - [CSS color keywords]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords - [Google Fonts]: https://fonts.google.com - [page title]: ../reference/index.md#setting-the-page-title +[`cards_layout`](#+social.cards_layout){ #+social.cards_layout } :material-alert-decagram:{ .mdx-pulse title="Added on May 8, 2023" } -#### Dependencies +: [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24: + Default: `default` – Layout specification the social card should use. The + plugin includes the following layouts which make use of the [color palette] + and [font]: -Two Python libraries must be installed alongside Material for MkDocs to generate -the social preview images, both of which are based on [Cairo Graphics] – -[Pillow] and [CairoSVG]: + === "`default`" -``` -pip install pillow cairosvg -``` + ``` yaml + plugins: + - social: + cards_layout: default + ``` -Both libraries are built with native extensions which need to be installed as -well. The [Docker image] comes with all dependencies pre-installed. If you don't -want to use Docker, see the following section which explains how to install all -dependencies on your system: + This layout uses the configured [primary color] as a background: -=== ":material-apple: macOS" + [![Layout default]][Layout default] - Make sure [Homebrew] is installed, which is a modern package manager for - macOS. Next, use the following command to install all necessary - dependencies: + === "`default/variant`" - ``` - brew install cairo freetype libffi libjpeg libpng zlib + ``` yaml + plugins: + - social: + cards_layout: default/variant + ``` + + This layout includes the [page icon] as a watermark, if defined: + + [![Layout default variant]][Layout default variant] + + === "`default/accent`" + + ``` yaml + plugins: + - social: + cards_layout: default/accent + ``` + + This layout uses the configured [accent color] as a background: + + [![Layout default accent]][Layout default accent] + + === "`default/invert`" + + ``` yaml + plugins: + - social: + cards_layout: default/invert + ``` + + This layout inverts the background and foreground colors: + + [![Layout default invert]][Layout default invert] + + All of the `default` layouts use the following variables: + + - :material-page-layout-header: – `config.site_name` + - :material-page-layout-body: – `page.meta.title` or `page.title` + - :material-page-layout-footer: – `page.meta.description` or `config.site_description` + - :material-page-layout-sidebar-right: – `theme.logo` or `theme.icon.logo` + +[`cards_layout_params`](#+social.cards_layout_params){ #+social.cards_layout_params } + +: [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24: + Default: _none_ – This option allows to set [parameters] as provided by + the layout specification. For [custom layouts], this key can be used to + provide layout-specific options, making layouts entirels configurable. + + --- + + All [`default`][default layouts] layouts specify the following parameters: + + [`background_color`](#+social.cards_layout_params.background_color){ #+social.cards_layout_params.background_color } + + : Set a background color, which can be a [CSS color keyword], a 3, 4, 6 + or 8 letter HEX color code. Alpha channels are supported as well: + + ``` yaml + plugins: + - social: + cards_layout_params: + background_color: "#0FF1CE" + ``` + + [`background_image`](#+social.cards_layout_params.background_image){ #+social.cards_layout_params.background_image } + + : Set a background image. If a `background_color` is set, like for the + [`default`][default layouts] layouts, the image is tinted (overlayed) + with the color. Thus, the background color must be (partially) + transparent for the image to become visible: + + ``` yaml + plugins: + - social: + cards_layout_params: + background_color: "#00000000" + background_image: .overrides/social/background.png + ``` + + The path of the image must be defined relative to the project root. + + [`color`](#+social.cards_layout_params.color){ #+social.cards_layout_params.color } + + : Set a foreground color, which can be a [CSS color keyword], a 3, 4, 6 + or 8 letter HEX color code. The color is primarily used to tint text and + icons: + + ``` yaml + plugins: + - social: + cards_layout_params: + color: "#0FF1CE" + ``` + + [`font_family`](#+social.cards_layout_params.font_family){ #+social.cards_layout_params.font_family } + + : Set a font family. This overrides the [font] that is set as part of the + theme configuration. The [built-in social plugin] will automatically + download the font from [Google Fonts]: + + ``` yaml + plugins: + - social: + cards_layout_params: + font_family: Ubuntu + ``` + + [color palette]: ./changing-the-colors.md#color-palette + [primary color]: ./changing-the-colors.md#primary-color + [accent color]: ./changing-the-colors.md#accent-color + [font]: ./changing-the-fonts.md#regular-font + [Google Fonts]: https://fonts.google.com/ + [page icon]: ../reference/index.md#setting-the-page-icon + [Layout default]: ../assets/screenshots/social-cards.png + [Layout default variant]: ../assets/screenshots/social-cards-variant.png + [Layout default accent]: ../assets/screenshots/social-cards-accent.png + [Layout default invert]: ../assets/screenshots/social-cards-invert.png + [parameters]: #parameters + [default layouts]: #+social.cards_layout + [CSS color keyword]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords + +#### Caching + +The [built-in social plugin] implements an intelligent caching mechanism, +ensuring that social cards are only re-generated when they're not contained in +the cache or their contents change. If any of the variables used in a layout +changes, the plugin will detect it and re-generate the card. + +The following configuration options are available for caching: + +[`cache`](#+social.cache){ #+social.cache } + +: [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24: + Default: `true` – Whether the plugin queries its cache for an existing + artifact before starting a generation job. It's normally not necessary to + change this setting, except for when debugging the plugin itself. Caching + can be disabled with: + + ``` yaml + plugins: + - social: + cache: false ``` -=== ":fontawesome-brands-windows: Windows" +[`cache_dir`](#+social.cache_dir){ #+social.cache_dir } - As stated in the [installation guide], the easiest way to get up and running - with the [Cairo Graphics] library on Windows is by installing [GTK+], since - it has Cairo as a dependency. You can also download and install a - precompiled [GTK runtime]. +: :octicons-milestone-24: Default: `.cache/plugins/social` – This option + specifies the file system location of the plugin's cache. It's normally not + necessary to change this setting, except for when debugging the plugin + itself. The cache directory can be changed with: -=== ":material-linux: Linux" - - There are several package managers for Linux with varying availability per - distribution. The [installation guide] explains how to install the [Cairo - Graphics] library for your distribution: - - === ":material-ubuntu: Ubuntu" - - ``` - apt-get install libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev - ``` - - === ":material-fedora: Fedora" - - ``` - yum install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel - ``` - - === ":fontawesome-brands-suse: openSUSE" - - ``` - zypper install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel - ``` - - [Cairo Graphics]: https://www.cairographics.org/ - [Pillow]: https://pillow.readthedocs.io/ - [CairoSVG]: https://cairosvg.org/ - [Docker image]: https://hub.docker.com/r/squidfunk/mkdocs-material/ - [Homebrew]: https://brew.sh/ - [installation guide]: https://www.cairographics.org/download/ - [GTK+]: https://www.gtk.org/docs/installations/windows/ - [GTK runtime]: https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases - -#### Caching recommended { #caching data-toc-label="Caching" } - -The [built-in social plugin] automatically fetches the fonts you define in -`mkdocs.yml` from Google Fonts, and uses them to render the text that is -displayed on the social card. The font files and generated cards are both -written to the `.cache` directory, which is used in subsequent builds to detect -whether the social cards need to be regenerated. You might want to: - -1. Ignore the `.cache` directory in your project, by adding it to `.gitignore`. -2. When building your site for publishing, use a build cache to save the - `.cache` directory in between builds. Taking the example from the - [publishing guide], add the following lines: - - ``` yaml hl_lines="15-20" - name: ci - on: - push: - branches: - - master - - main - jobs: - deploy: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - uses: actions/setup-python@v4 - with: - python-version: 3.x - - uses: actions/cache@v3 - with: - key: mkdocs-material-${{ github.sha }} - path: .cache - restore-keys: | - mkdocs-material- - - run: pip install mkdocs-material - - run: mkdocs gh-deploy --force + ``` yaml + plugins: + - social: + cache_dir: .cache/plugins/social ``` + By default, all built-in plugins that implement caching will create a + `.cache` directory in the same folder your `mkdocs.yml` resides, and create + subfolders to not interfere with each other. If you use multiple instances + of this plugin, it could be necessary to change this setting. + [built-in social plugin]: #built-in-social-plugin [publishing guide]: ../publishing-your-site.md#with-github-actions -#### Meta tags - -The [built-in social plugin] automatically sets all necessary `meta` tags, -equivalent to the following two customizations, which you can set manually when -you don't want to use it: - -=== ":material-graph: Open Graph" - - ``` html - {% extends "base.html" %} - - {% block extrahead %} - {% set title = config.site_name %} - {% if page and page.meta and page.meta.title %} - {% set title = title ~ " - " ~ page.meta.title %} - {% elif page and page.title and not page.is_homepage %} - {% set title = title ~ " - " ~ page.title %} - {% endif %} - - - - - - - - - {% endblock %} - ``` - -=== ":fontawesome-brands-twitter: Twitter Cards" - - ``` html - {% extends "base.html" %} - - {% block extrahead %} - {% set title = config.site_name %} - {% if page and page.meta and page.meta.title %} - {% set title = title ~ " - " ~ page.meta.title %} - {% elif page and page.title and not page.is_homepage %} - {% set title = title ~ " - " ~ page.title %} - {% endif %} - - - - - {% endblock %} - ``` - - [Twitter Cards]: https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards - ## Usage If you want to adjust the title or set a custom description for the social card, @@ -321,3 +361,60 @@ precedence over the default values. [Changing the title]: ../reference/index.md#setting-the-page-title [Changing the description]: ../reference/index.md#setting-the-page-description + + +### Choosing a font + +Some fonts do not contain CJK characters, like for example the +[default font, `Roboto`][font]. In case your `site_name`, `site_description`, or +page title contain CJK characters, choose another font from [Google Fonts] which +comes with CJK characters, e.g. one from the `Noto Sans` font family: + +=== "Chinese (Simplified)" + + ``` yaml + plugins: + - social: + cards_font: Noto Sans SC + ``` + +=== "Chinese (Traditional)" + + ``` yaml + plugins: + - social: + cards_font: Noto Sans TC + ``` + +=== "Japanese" + + ``` yaml + plugins: + - social: + cards_font: Noto Sans JP + ``` + +=== "Korean" + + ``` yaml + plugins: + - social: + cards_font: Noto Sans KR + ``` + +## Customization + +### Custom layouts + +[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } · +[:octicons-tag-24: insiders-4.33.0][Insiders] · +:octicons-beaker-24: Experimental + +!!! info "Custom layout guide coming shortly" + + We're working hard to explain in detail how to build custom layouts. If you + want to start to build a custom layout right away before we finish the guide, + check out the [source code of the `default` layout](https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/plugins/social/layouts/default.yml) + and watch the [demo on Twitter](https://twitter.com/squidfunk/status/1654832324272431104). + +#### Parameters