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 <tsmanner@us.ibm.com>
Co-authored-by: Michael Rose <mmistakes@users.noreply.github.com>
This commit is contained in:
Tom Manner 2021-04-13 16:10:08 -04:00 committed by GitHub
parent 99cd379c61
commit de6870743d
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 66 additions and 18 deletions

View file

@ -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. 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} {: .notice--info}
```bash ```bash
@ -18,8 +18,10 @@ minimal-mistakes
├── _includes ├── _includes
| ├── analytics-providers # snippets for analytics (Google and custom) | ├── analytics-providers # snippets for analytics (Google and custom)
| ├── comments-providers # snippets for comments | ├── comments-providers # snippets for comments
| ├── footer # custom snippets to add to site footer | ├── footer
| ├── head # custom snippets to add to site head | | └── custom.html # custom snippets to add to site footer
| ├── head
| | └── custom.html # custom snippets to add to site head
| ├── feature_row # feature row helper | ├── feature_row # feature row helper
| ├── gallery # image gallery helper | ├── gallery # image gallery helper
| ├── group-by-array # group by array helper for archives | ├── group-by-array # group by array helper for archives

View file

@ -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** | Optional | Show table of contents. (boolean) | `false` |
| **toc_label** | Optional | Table of contents title. (string) | `toc_label` in UI Text data file. | | **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_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** **TOC example with custom title and icon**
@ -363,7 +363,7 @@ Then adjust the `paginate_path` in **_config.yml** to match.
```yaml ```yaml
paginate_path: /blog/page:num 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. **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} {: .notice--info}
@ -627,7 +627,7 @@ For example, to color a Reddit icon, simply add a `color` declaration and the co
color: #ff4500; color: #ff4500;
} }
} }
``` ```
![Reddit link in author profile with color]({{ "/assets/images/mm-author-profile-reddit-color.png" | relative_url }}) ![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:** **Sample sidebar menu links:**
```yaml ```yaml
docs: docs:
- title: Getting Started - title: Getting Started
children: 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 }}) ![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
```
---

View file

@ -40,29 +40,29 @@ minimal-mistakes
## Customizing ## 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: `_sass` directory), do one of the following:
1. Copy directly from the Minimal Mistakes theme gem 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). `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>`. `<your_project>`.
- Customize what you want inside `<your_project>/assets/css/main.scss`. - Customize what you want inside `<your_project>/assets/css/main.scss`.
2. Copy from this repo. 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>`. to `<your_project>`.
- Customize what you want inside `<your_project/assets/css/main.scss`. - Customize what you want inside `<your_project/assets/css/main.scss`.
**Note:** To make more extensive changes and customize the Sass partials bundled **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 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 `<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 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 `<your_project>/assets/css/main.scss`. For instance, to change the
link color used throughout the theme add: link color used throughout the theme add:
```scss ```scss
@ -71,7 +71,7 @@ $link-color: red;
Before any `@import` lines. 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. 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 ### 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: Example:
@ -370,7 +370,7 @@ $base0c: #8abeb7;
$base0d: #81a2be; $base0d: #81a2be;
$base0e: #b294bb; $base0e: #b294bb;
$base0f: #a3685a; $base0f: #a3685a;
``` ```
### Breakpoints and grid stuff ### Breakpoints and grid stuff