Document user custom element hooks (mmistakes#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 <tsmanner@us.ibm.com> Co-authored-by: Michael Rose <mmistakes@users.noreply.github.com>
mjt91 · Jun 23, 2021 · 2afe645 · 2afe645
1 parent 86cee40
commit 2afe645
Show file tree

Hide file tree

Showing 3 changed files with 66 additions and 18 deletions.
diff --git 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
@@ -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) <i class="fas fa-file-alt"></i> **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 `<a>` 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 `<head>` 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 %}
+    <link rel="stylesheet" href="{{ stylesheet | relative_url }}">
+  {% 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 `<footer>` tag. An example use of this include is to add custom JavaScript per page:
+
+Add some Liquid tags for the new configuration to `_includes/footer/custom.html`.
+{% raw %}```html
+{% if page.page_js %}
+  {% for script in page.page_js %}
+    <script src="{{ script | relative_url }}"></script>
+  {% endfor %}
+{% endif %}
+```{% endraw %}
+
+Next, add `page_js` to any page's YAML Front Matter to have your CSS loaded for that page.
+```yaml
+page_js:
+  - /path/to/your/custom.css
+```
+
+---
diff --git a/docs/_docs/16-stylesheets.md b/docs/_docs/16-stylesheets.md
@@ -40,29 +40,29 @@ minimal-mistakes
 
 ## Customizing
 
-To override the default [Sass](http://sass-lang.com/guide) (located in theme's 
+To override the default [Sass](http://sass-lang.com/guide) (located in theme's
 `_sass` directory), do one of the following:
 
 1. Copy directly from the Minimal Mistakes theme gem
 
-   - Go to your local Minimal Mistakes gem installation directory (run 
+   - Go to your local Minimal Mistakes gem installation directory (run
      `bundle show minimal-mistakes-jekyll` to get the path to it).
-   - Copy the contents of `/assets/css/main.scss` from there to 
+   - Copy the contents of `/assets/css/main.scss` from there to
      `<your_project>`.
    - Customize what you want inside `<your_project>/assets/css/main.scss`.
 
 2. Copy from this repo.
 
-   - Copy the contents of [assets/css/main.scss](https://github.com/mmistakes/minimal-mistakes/blob/master/assets/css/main.scss) 
+   - Copy the contents of [assets/css/main.scss](https://github.com/mmistakes/minimal-mistakes/blob/master/assets/css/main.scss)
      to `<your_project>`.
    - Customize what you want inside `<your_project/assets/css/main.scss`.
 
-**Note:** To make more extensive changes and customize the Sass partials bundled 
-in the gem. You will need to copy the complete contents of the `_sass` directory 
+**Note:** To make more extensive changes and customize the Sass partials bundled
+in the gem. You will need to copy the complete contents of the `_sass` directory
 to `<your_project>` due to the way Jekyll currently reads those files.
 
-To make basic tweaks to theme's style Sass variables can be overridden by adding 
-to `<your_project>/assets/css/main.scss`. For instance, to change the 
+To make basic tweaks to theme's style Sass variables can be overridden by adding
+to `<your_project>/assets/css/main.scss`. For instance, to change the
 link color used throughout the theme add:
 
 ```scss
@@ -71,7 +71,7 @@ $link-color: red;
 
 Before any `@import` lines.
 
-### Paragraph indention 
+### Paragraph indention
 
 To mimic the look of type set in a printed book or manuscript you may want to enable paragraph indention. When `$paragraph-indent` is set to `true` indents are added to each sibling and the margin below each paragraph is removed.
 
@@ -120,7 +120,7 @@ $header-font-family : $sans-serif-narrow;
 
 ### Type scale
 
-Wherever possible type scale variables have been used instead of writing out fixed sizes. This makes updating much easier by changing values in one file. 
+Wherever possible type scale variables have been used instead of writing out fixed sizes. This makes updating much easier by changing values in one file.
 
 Example:
 
@@ -370,7 +370,7 @@ $base0c: #8abeb7;
 $base0d: #81a2be;
 $base0e: #b294bb;
 $base0f: #a3685a;
-```  
+```
 
 ### Breakpoints and grid stuff