From d16624fce84c33624af618adbd3203e5de0af345 Mon Sep 17 00:00:00 2001 From: Tom Manner Date: Tue, 13 Apr 2021 16:10:08 -0400 Subject: [PATCH] Document user custom element hooks (#2815) * Added documentation for including custom CSS on a site or page * Removed non-configuration related content from 05-configuration.md and cleaned up some style in new sections of 16-stylesheets.md * Moved small custom head documentation to a ProTip in _docs/06-overriding-theme-defaults.md * Cleaned up some documentation, and added some example uses of custom head and footer. * Replace double space with single * Replace double spaces with single Co-authored-by: Tom Manner Co-authored-by: Michael Rose --- docs/_docs/02-structure.md | 8 ++++-- docs/_docs/10-layouts.md | 54 +++++++++++++++++++++++++++++++++--- docs/_docs/16-stylesheets.md | 22 +++++++-------- 3 files changed, 66 insertions(+), 18 deletions(-) diff --git a/docs/_docs/02-structure.md b/docs/_docs/02-structure.md index 5c7016364d8d..18562ad34abf 100644 --- a/docs/_docs/02-structure.md +++ b/docs/_docs/02-structure.md @@ -7,7 +7,7 @@ last_modified_at: 2018-03-20T15:19:22-04:00 Nothing clever here :wink:. Layouts, data files, and includes are all placed in their default locations. Stylesheets and scripts in `assets`, and a few development related files in the project's root directory. -**Please note:** If you installed Minimal Mistakes via the Ruby Gem method, theme files like `_layouts`, `_includes`, `_sass`, and `/assets/` will be missing. This is normal as they are bundled with the [`minimal-mistakes-jekyll`](https://rubygems.org/gems/minimal-mistakes-jekyll) Ruby gem. +**Please note:** If you installed Minimal Mistakes via the Ruby Gem method, theme files like `_layouts`, `_includes`, `_sass`, and `/assets/` will be missing. This is normal as they are bundled with the [`minimal-mistakes-jekyll`](https://rubygems.org/gems/minimal-mistakes-jekyll) Ruby gem. If you would like to make changes, create the files and Jekyll will prefer your local copy. {: .notice--info} ```bash @@ -18,8 +18,10 @@ minimal-mistakes ├── _includes | ├── analytics-providers # snippets for analytics (Google and custom) | ├── comments-providers # snippets for comments -| ├── footer # custom snippets to add to site footer -| ├── head # custom snippets to add to site head +| ├── footer +| | └── custom.html # custom snippets to add to site footer +| ├── head +| | └── custom.html # custom snippets to add to site head | ├── feature_row # feature row helper | ├── gallery # image gallery helper | ├── group-by-array # group by array helper for archives diff --git a/docs/_docs/10-layouts.md b/docs/_docs/10-layouts.md index acb7e098b72f..0a6ef71f0b01 100644 --- a/docs/_docs/10-layouts.md +++ b/docs/_docs/10-layouts.md @@ -129,7 +129,7 @@ Auto-generated table of contents list for your posts and pages can be enabled by | **toc** | Optional | Show table of contents. (boolean) | `false` | | **toc_label** | Optional | Table of contents title. (string) | `toc_label` in UI Text data file. | | **toc_icon** | Optional | Table of contents icon, displays before the title. (string) | [Font Awesome](https://fontawesome.com/icons?d=gallery&s=solid&m=free) **file-alt** icon. Other FA icons can be used instead. | -| **toc_sticky** | Optional | Stick table of contents to top of screen. | `false` | +| **toc_sticky** | Optional | Stick table of contents to top of screen. | `false` | **TOC example with custom title and icon** @@ -363,7 +363,7 @@ Then adjust the `paginate_path` in **_config.yml** to match. ```yaml paginate_path: /blog/page:num -``` +``` **Note:** Jekyll can only paginate a single `index.html` file. If you'd like to paginate more pages (e.g. category indexes) you'll need the help of a custom plugin. For more pagination related settings check the [**Configuration**]({{ "/docs/configuration/#paginate" | relative_url }}) section. {: .notice--info} @@ -627,7 +627,7 @@ For example, to color a Reddit icon, simply add a `color` declaration and the co color: #ff4500; } } -``` +``` ![Reddit link in author profile with color]({{ "/assets/images/mm-author-profile-reddit-color.png" | relative_url }}) @@ -677,7 +677,7 @@ To start, add a new key to `_data/navigation.yml`. This will be referenced later **Sample sidebar menu links:** -```yaml +```yaml docs: - title: Getting Started children: @@ -798,3 +798,49 @@ Add the new `.btn--reddit` class to the `` element from earlier, [compile `ma ``` ![Reddit social share link button]({{ "/assets/images/mm-social-share-links-reddit-color.png" | relative_url }}) + +--- + +## Custom head and footer + +The `default` layout includes a number of custom templates, which provide ways for you to directly add content to all your pages. + +### Head + +`_includes/head/custom.html` is included at the end of the `` tag. An example use of this include is to add custom CSS per page: + +Add some Liquid tags for the new configuration to `_includes/head/custom.html`. +{% raw %}```html +{% if page.page_css %} + {% for stylesheet in page.page_css %} + + {% endfor %} +{% endif %} +```{% endraw %} + +Next, add `page_css` to any page's YAML Front Matter to have your CSS loaded for that page. +```yaml +page_css: + - /path/to/your/custom.css +``` + +### Footer + +`_includes/footer/custom.html` is included at the beginning of the `