N-archive/hacks-guide-minimal-mistakes-theme
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Fix notices

Browse source
This commit is contained in:
Michael Rose 2017-11-27 12:06:42 -05:00
parent da72581be3
commit 02c109d24f
1 changed files with 138 additions and 358 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

496
docs/_docs/05-configuration.md
View file

@ -6,27 +6,18 @@ last_modified_at: 2017-11-27T11:28:31-05:00
toc: true toc: true
--- ---
Settings that affect your entire site can be changed in Settings that affect your entire site can be changed in [Jekyll's configuration file](https://jekyllrb.com/docs/configuration/): `_config.yml`, found in the root of your project. If you don't have this file you'll need to copy or create one using the theme's [default `_config.yml`](https://github.com/mmistakes/minimal-mistakes/blob/master/_config.yml) as a base.
[Jekyll's configuration file](https://jekyllrb.com/docs/configuration/):
`_config.yml`, found in the root of your project. If you don't have this file
you'll need to copy or create one using the theme's
[default `_config.yml`](https://github.com/mmistakes/minimal-mistakes/blob/master/_config.yml)
as a base.
**Note:** for technical reasons, `_config.yml` is NOT reloaded automatically **Note:** for technical reasons, `_config.yml` is NOT reloaded automatically when used with `jekyll serve`. If you make any changes to this file, please restart the server process for them to be applied.
when used with `jekyll serve`. If you make any changes to this file, please {: .notice--warning}
restart the server process for them to be applied. {: .notice--warning}
Take a moment to look over the configuration file included with the theme. Take a moment to look over the configuration file included with the theme. Comments have been added to provide examples and default values for most settings. Detailed explanations of each can be found below.
Comments have been added to provide examples and default values for most
settings. Detailed explanations of each can be found below.
## Site Settings ## Site Settings
### Theme ### Theme
If you're using the Ruby gem version of the theme you'll need this line to If you're using the Ruby gem version of the theme you'll need this line to activate it:
activate it:
```yaml ```yaml
theme: minimal-mistakes-jekyll theme: minimal-mistakes-jekyll
@ -40,14 +31,10 @@ Easily change the color scheme of the theme using one of the provided "skins":
minimal_mistakes_skin: "default" # "air", "aqua", "contrast", "dark", "dirt", "neon", "mint", "plum" "sunrise" minimal_mistakes_skin: "default" # "air", "aqua", "contrast", "dark", "dirt", "neon", "mint", "plum" "sunrise"
``` ```
**Note:** If you have made edits to the theme's CSS files be sure to update **Note:** If you have made edits to the theme's CSS files be sure to update [`/assets/css/main.scss`](https://github.com/mmistakes/minimal-mistakes/blob/master/assets/css/main.scss) to include `@import "minimal-mistakes/skins/{{ site.minimal_mistakes_skin | default: 'default' }}"; // skin` before the `minimal-mistakes` import.
[`/assets/css/main.scss`](https://github.com/mmistakes/minimal-mistakes/blob/master/assets/css/main.scss) {: .notice--warning}
to include `@import "minimal-mistakes/skins/{{ site.minimal_mistakes_skin |
default: 'default' }}"; // skin` before the `minimal-mistakes` import. {:
.notice--warning}
#### Air skin: `air` #### Air skin: `air`
{:.no_toc} {:.no_toc}
<figure class="half"> <figure class="half">
@ -57,7 +44,6 @@ default: 'default' }}"; // skin` before the `minimal-mistakes` import. {:
</figure> </figure>
#### Aqua skin: `aqua` #### Aqua skin: `aqua`
{:.no_toc} {:.no_toc}
<figure class="half"> <figure class="half">
@ -67,7 +53,6 @@ default: 'default' }}"; // skin` before the `minimal-mistakes` import. {:
</figure> </figure>
#### Contrast skin: `contrast` #### Contrast skin: `contrast`
{:.no_toc} {:.no_toc}
<figure class="half"> <figure class="half">
@ -77,7 +62,6 @@ default: 'default' }}"; // skin` before the `minimal-mistakes` import. {:
</figure> </figure>
#### Dark skin: `dark` #### Dark skin: `dark`
{:.no_toc} {:.no_toc}
<figure class="half"> <figure class="half">
@ -87,7 +71,6 @@ default: 'default' }}"; // skin` before the `minimal-mistakes` import. {:
</figure> </figure>
#### Dirt skin: `dirt` #### Dirt skin: `dirt`
{:.no_toc} {:.no_toc}
<figure class="half"> <figure class="half">
@ -97,7 +80,6 @@ default: 'default' }}"; // skin` before the `minimal-mistakes` import. {:
</figure> </figure>
#### Mint skin: `mint` #### Mint skin: `mint`
{:.no_toc} {:.no_toc}
<figure class="half"> <figure class="half">
@ -107,7 +89,6 @@ default: 'default' }}"; // skin` before the `minimal-mistakes` import. {:
</figure> </figure>
#### Neon skin: `neon` #### Neon skin: `neon`
{:.no_toc} {:.no_toc}
<figure class="half"> <figure class="half">
@ -117,7 +98,6 @@ default: 'default' }}"; // skin` before the `minimal-mistakes` import. {:
</figure> </figure>
#### Neon skin: `plum` #### Neon skin: `plum`
{:.no_toc} {:.no_toc}
<figure class="half"> <figure class="half">
@ -127,7 +107,6 @@ default: 'default' }}"; // skin` before the `minimal-mistakes` import. {:
</figure> </figure>
#### Sunrise skin: `sunrise` #### Sunrise skin: `sunrise`
{:.no_toc} {:.no_toc}
<figure class="half"> <figure class="half">
@ -138,133 +117,87 @@ default: 'default' }}"; // skin` before the `minimal-mistakes` import. {:
### Site Locale ### Site Locale
`site.locale` is used to declare the primary language for each web page within `site.locale` is used to declare the primary language for each web page within the site.
the site.
_Example:_ `locale: "en-US"` sets the `lang` attribute for the site to the _Example:_ `locale: "en-US"` sets the `lang` attribute for the site to the _United States_ flavor of English, while `en-GB` would be for the `United Kingdom` style of English. Country codes are optional and the shorter variation `locale: "en"` is also acceptable. To find your language and country codes check this [reference table](<https://msdn.microsoft.com/en-us/library/ee825488(v=cs.20).aspx>).
_United States_ flavor of English, while `en-GB` would be for the `United
Kingdom` style of English. Country codes are optional and the shorter variation
`locale: "en"` is also acceptable. To find your language and country codes check
this
[reference table](<https://msdn.microsoft.com/en-us/library/ee825488(v=cs.20).aspx>).
Properly setting the locale is important for associating localized text found in Properly setting the locale is important for associating localized text found in the [**UI Text**]({{ "/docs/ui-text/" | absolute_url }}) data file. An improper match will cause parts of the UI to disappear (eg. button labels, section headings, etc).
the [**UI Text**]({{ "/docs/ui-text/" | absolute_url }}) data file. An improper
match will cause parts of the UI to disappear (eg. button labels, section
headings, etc).
**Note:** The theme comes with localized text in English (`en`, `en-US`, **Note:** The theme comes with localized text in English (`en`, `en-US`, `en-GB`). If you change `locale` in `_config.yml` to something else, most of the UI text will go blank. Be sure to add the corresponding locale key and translated text to `_data/ui-text.yml` to avoid this.
`en-GB`). If you change `locale` in `_config.yml` to something else, most of the {: .notice--warning}
UI text will go blank. Be sure to add the corresponding locale key and
translated text to `_data/ui-text.yml` to avoid this. {: .notice--warning}
### Site Title ### Site Title
The name of your site. Is used throughout the theme in places like the site The name of your site. Is used throughout the theme in places like the site masthead and `<title>` tags.
masthead and `<title>` tags.
_Example:_ `title: "My Awesome Site"` _Example:_ `title: "My Awesome Site"`
You also have the option of customizing the separation character used in You also have the option of customizing the separation character used in SEO-friendly page titles.
SEO-friendly page titles.
_Example:_ `title_separator: "|"` would produce page titles like `Sample Page | _Example:_ `title_separator: "|"` would produce page titles like `Sample Page | My Awesome Site`.
My Awesome Site`.
**Note:** Long site titles have been known to break the masthead layout. Avoid **Note:** Long site titles have been known to break the masthead layout. Avoid adding a long "tagline" to the title prevent this from happening eg. `My Awesome Site is the Best Because I Say So".
adding a long "tagline" to the title prevent this from happening eg. `My Awesome {: .notice--warning}
Site is the Best Because I Say So". {: .notice--warning}
### Site Name ### Site Name
Used to assign a site author. Don't worry, you can override the site author with Used to assign a site author. Don't worry, you can override the site author with different ones on specific posts, pages, or collection documents.
different ones on specific posts, pages, or collection documents.
_Example:_ `name: "Michael Rose"`. _Example:_ `name: "Michael Rose"`.
**ProTip:** If you want to get crafty with your YAML you can use **ProTip:** If you want to get crafty with your YAML you can use [anchors](http://www.yaml.org/spec/1.2/spec.html#id2785586) to reuse values. For example `foo: &var "My String"` allows you to reuse `"My String"` elsewhere in `_config.yml` like so... `bar: *var`. You'll see a few examples of this in the provided Jekyll config.
[anchors](http://www.yaml.org/spec/1.2/spec.html#id2785586) to reuse values. For {: .notice--info}
example `foo: &var "My String"` allows you to reuse `"My String"` elsewhere in
`_config.yml` like so... `bar: *var`. You'll see a few examples of this in the
provided Jekyll config. {: .notice--info}
### Site Description ### Site Description
Fairly obvious. `site.description` describes the site. Used predominantly in Fairly obvious. `site.description` describes the site. Used predominantly in meta descriptions for improving SEO.
meta descriptions for improving SEO.
_Example:_ `description: "A flexible Jekyll theme for your blog or site with a _Example:_ `description: "A flexible Jekyll theme for your blog or site with a minimalist aesthetic."`
minimalist aesthetic."`
### Site URL ### Site URL
The base hostname and protocol for your site. If you're hosting with GitHub The base hostname and protocol for your site. If you're hosting with GitHub Pages this will be something like `url: "https://github.io.mmistakes"` or `url: "https://mademistakes.com"` if you have a custom domain name.
Pages this will be something like `url: "https://github.io.mmistakes"` or `url:
"https://mademistakes.com"` if you have a custom domain name.
GitHub Pages now GitHub Pages now [forces `https://` for new sites](https://help.github.com/articles/securing-your-github-pages-site-with-https/) so be mindful of that when setting your URL to avoid mixed-content warnings.
[forces `https://` for new sites](https://help.github.com/articles/securing-your-github-pages-site-with-https/)
so be mindful of that when setting your URL to avoid mixed-content warnings.
**Note:** Jekyll 3.3 overrides this value with `url: http://localhost:4000` when **Note:** Jekyll 3.3 overrides this value with `url: http://localhost:4000` when running `jekyll serve` locally in development. If you want to avoid this behavior set `JEKYLL_ENV=production` to [force the environment](http://jekyllrb.com/docs/configuration/#specifying-a-jekyll-environment-at-build-time) to production.
running `jekyll serve` locally in development. If you want to avoid this {: .notice--warning}
behavior set `JEKYLL_ENV=production` to
[force the environment](http://jekyllrb.com/docs/configuration/#specifying-a-jekyll-environment-at-build-time)
to production. {: .notice--warning}
### Site Base URL ### Site Base URL
This little option causes all kinds of confusion in the Jekyll community. If This little option causes all kinds of confusion in the Jekyll community. If you're not hosting your site as a GitHub Pages Project or in a subfolder (eg: `/blog`), then don't mess with it.
you're not hosting your site as a GitHub Pages Project or in a subfolder (eg:
`/blog`), then don't mess with it.
In the case of the Minimal Mistakes demo site it's hosted on GitHub at In the case of the Minimal Mistakes demo site it's hosted on GitHub at <https://mmistakes.github.io/minimal-mistakes>. To correctly set this base path I'd use `url: "https://mmistakes.github.io"` and `baseurl: "/minimal-mistakes"`.
<https://mmistakes.github.io/minimal-mistakes>. To correctly set this base path
I'd use `url: "https://mmistakes.github.io"` and `baseurl: "/minimal-mistakes"`.
For more information on how to properly use `site.url` and `site.baseurl` as For more information on how to properly use `site.url` and `site.baseurl` as intended by the Jekyll maintainers, check [Parker Moore's post on the subject](https://byparker.com/blog/2014/clearing-up-confusion-around-baseurl/).
intended by the Jekyll maintainers, check
[Parker Moore's post on the subject](https://byparker.com/blog/2014/clearing-up-confusion-around-baseurl/).
**Note:** When using `baseurl` remember to include it as part of your path when **Note:** When using `baseurl` remember to include it as part of your path when testing your site locally. Values of `url:` and `baseurl: "/blog"` would make your local site visible at `http://localhost:4000/blog` and not `http://localhost:4000`.
testing your site locally. Values of `url:` and `baseurl: "/blog"` would make {: .notice--warning}
your local site visible at `http://localhost:4000/blog` and not
`http://localhost:4000`. {: .notice--warning}
### Site Repository ### Site Repository
Add your repository name with organization to your site's configuration file, Add your repository name with organization to your site's configuration file, `_config.yml`.
`_config.yml`.
```yaml ```yaml
repository: "username/repo-name" repository: "username/repo-name"
``` ```
"NWO" stands for "name with owner." It is GitHub lingo for the username of the "NWO" stands for "name with owner." It is GitHub lingo for the username of the owner of the repository plus a forward slash plus the name of the repository, e.g. `mmistakes/minimal-mistakes`, where **mmistakes** is the owner and **minimal-mistakes** is the repository name.
owner of the repository plus a forward slash plus the name of the repository,
e.g. `mmistakes/minimal-mistakes`, where **mmistakes** is the owner and
**minimal-mistakes** is the repository name.
Your `site.github.*` fields should fill in like normal. If you run Jekyll with Your `site.github.*` fields should fill in like normal. If you run Jekyll with the --verbose flag, you should be able to see all the API calls made.
the --verbose flag, you should be able to see all the API calls made.
If you don't set `repository` correctly you may see the following error when If you don't set `repository` correctly you may see the following error when trying to `serve` or `build` your Jekyll site:
trying to `serve` or `build` your Jekyll site:
**Liquid Exceptions:** No repo name found. Specify using `PAGES_REPO_NWO` **Liquid Exceptions:** No repo name found. Specify using `PAGES_REPO_NWO` environment variables, `repository` in your configuration, or set up `origin` git remote pointing to your github.com repository.
environment variables, `repository` in your configuration, or set up `origin` {: .notice--danger}
git remote pointing to your github.com repository. {: .notice--danger}
For more information on how `site.github` data can be used with Jekyll check out For more information on how `site.github` data can be used with Jekyll check out [`github-metadata`'s documentation](https://github.com/jekyll/github-metadata).
[`github-metadata`'s documentation](https://github.com/jekyll/github-metadata).
### Site Scripts ### Site Scripts
Add scripts to the `<head>` or closing `</body>` elements by assigning paths to Add scripts to the `<head>` or closing `</body>` elements by assigning paths to either `head_scripts` and/or `footer_scripts`.
either `head_scripts` and/or `footer_scripts`.
For example, to add a CDN version of jQuery to page's head along with a custom For example, to add a CDN version of jQuery to page's head along with a custom script you'd do the following:
script you'd do the following:
```yaml ```yaml
head_scripts: head_scripts:
@ -272,22 +205,18 @@ head_scripts:
- /assets/js/your-custom-head-script.js - /assets/js/your-custom-head-script.js
``` ```
Consult the [JavaScript documentation]({{ site.baseurl }}{% link Consult the [JavaScript documentation]({{ site.baseurl }}{% link _docs/17-javascript.md %}) for more information on working with theme scripts.
_docs/17-javascript.md %}) for more information on working with theme scripts.
{: .notice--info} {: .notice--info}
### Site Default Teaser Image ### Site Default Teaser Image
To assign a fallback teaser image used in the "**Related Posts**" module, place To assign a fallback teaser image used in the "**Related Posts**" module, place a graphic in the `/assets/images/` directory and add the filename to `_config.yml` like so:
a graphic in the `/assets/images/` directory and add the filename to
`_config.yml` like so:
```yaml ```yaml
teaser: /assets/images/500x300.png teaser: /assets/images/500x300.png
``` ```
This image can be overridden at anytime by applying the following to a This image can be overridden at anytime by applying the following to a document's YAML Front Matter.
document's YAML Front Matter.
```yaml ```yaml
header: header:
@ -301,37 +230,26 @@ header:
### Breadcrumb Navigation (Beta) ### Breadcrumb Navigation (Beta)
Enable breadcrumb links to help visitors better navigate deep sites. Because of Enable breadcrumb links to help visitors better navigate deep sites. Because of the fragile method of implementing them they don't always produce accurate links reliably. For best results:
the fragile method of implementing them they don't always produce accurate links
reliably. For best results:
1. Use a category based permalink structure e.g. `permalink: 1. Use a category based permalink structure e.g. `permalink: /:categories/:title/`
/:categories/:title/` 2. Manually create pages for each category or use a plugin like [jekyll-archives][jekyll-archives] to auto-generate them. If these pages don't exist breadcrumb links to them will be broken.
2. Manually create pages for each category or use a plugin like
[jekyll-archives][jekyll-archives] to auto-generate them. If these pages
don't exist breadcrumb links to them will be broken.
![breadcrumb navigation example]({{ "/assets/images/mm-breadcrumbs-example.jpg" ![breadcrumb navigation example]({{ "/assets/images/mm-breadcrumbs-example.jpg" | absolute_url }})
| absolute_url }})
```yaml ```yaml
breadcrumbs: true # disabled by default breadcrumbs: true # disabled by default
``` ```
Breadcrumb start link text and separator character can both be changed in the Breadcrumb start link text and separator character can both be changed in the [UI Text data file]({{ "/docs/ui-text/" | absolute_url }}).
[UI Text data file]({{ "/docs/ui-text/" | absolute_url }}).
### Reading Time ### Reading Time
Enable estimated reading time snippets with `read_time: true` in YAML Front Enable estimated reading time snippets with `read_time: true` in YAML Front Matter. `200` has been set as the default words per minute value --- which can be changed by adjusting `words_per_minute:` in `_config.yml`.
Matter. `200` has been set as the default words per minute value --- which can
be changed by adjusting `words_per_minute:` in `_config.yml`.
![reading time example]({{ "/assets/images/mm-read-time-example.jpg" | ![reading time example]({{ "/assets/images/mm-read-time-example.jpg" | absolute_url }})
absolute_url }})
Instead of adding `read_time: true` to each post, apply as a default in Instead of adding `read_time: true` to each post, apply as a default in `_config.yml` like so:
`_config.yml` like so:
```yaml ```yaml
defaults: defaults:
@ -343,16 +261,11 @@ defaults:
read_time: true read_time: true
``` ```
To disable reading time for a post, add `read_time: false` its YAML Front Matter To disable reading time for a post, add `read_time: false` its YAML Front Matter to override what was set in `_config.yml`.
to override what was set in `_config.yml`.
### Comments ### Comments
[**Disqus**](https://disqus.com/), [**Discourse**](https://www.discourse.org/), [**Disqus**](https://disqus.com/), [**Discourse**](https://www.discourse.org/), [**Facebook**](https://developers.facebook.com/docs/plugins/comments), **Google+**, and static-based commenting via [**Staticman**](https://staticman.net/) are built into the theme. First set the comment provider you'd like to use:
[**Facebook**](https://developers.facebook.com/docs/plugins/comments),
**Google+**, and static-based commenting via
[**Staticman**](https://staticman.net/) are built into the theme. First set the
comment provider you'd like to use:
| Name | Comment Provider | | Name | Comment Provider |
| ---------------- | ------------------------- | | ---------------- | ------------------------- |
@ -366,8 +279,7 @@ comment provider you'd like to use:
Then add `comments: true` to each document you want comments visible on. Then add `comments: true` to each document you want comments visible on.
Instead of adding YAML Front Matter to each document, apply as a default in Instead of adding YAML Front Matter to each document, apply as a default in `_config.yml`. To enable comments for all posts:
`_config.yml`. To enable comments for all posts:
```yaml ```yaml
defaults: defaults:
@ -379,14 +291,11 @@ defaults:
comments: true comments: true
``` ```
If you add `comments: false` to a post's YAML Front Matter it will override the If you add `comments: false` to a post's YAML Front Matter it will override the default and disable comments for just that post.
default and disable comments for just that post.
##### Disqus ##### Disqus
To use Disqus you'll need to create an account and To use Disqus you'll need to create an account and [shortname](https://help.disqus.com/customer/portal/articles/466208-what-s-a-shortname-). Once you have both update `_config.yml` to:
[shortname](https://help.disqus.com/customer/portal/articles/466208-what-s-a-shortname-).
Once you have both update `_config.yml` to:
```yaml ```yaml
comments: comments:
@ -397,9 +306,7 @@ comments:
##### Discourse ##### Discourse
For guidance on how to set up Discourse for embedding comments from a topic on a For guidance on how to set up Discourse for embedding comments from a topic on a post page, [consult this guide](https://meta.discourse.org/t/embedding-discourse-comments-via-javascript/31963).
post page,
[consult this guide](https://meta.discourse.org/t/embedding-discourse-comments-via-javascript/31963).
```yaml ```yaml
comments: comments:
@ -408,14 +315,12 @@ comments:
server : # meta.discourse.org server : # meta.discourse.org
``` ```
**Note:** Do not include `http://` or `https://` when setting your Discourse **Note:** Do not include `http://` or `https://` when setting your Discourse `server`. The theme automatically prepends the URL `//`, following a scheme-less pattern.
`server`. The theme automatically prepends the URL `//`, following a scheme-less {: .notice--info}
pattern. {: .notice--info}
##### Facebook Comments ##### Facebook Comments
To enable Facebook Comments choose how many comments you'd like visible per post To enable Facebook Comments choose how many comments you'd like visible per post and the color scheme of the widget.
and the color scheme of the widget.
```yaml ```yaml
comments: comments:
@ -428,31 +333,21 @@ comments:
##### Static-Based Comments via Staticman ##### Static-Based Comments via Staticman
Transform user comments into `_data` files that live inside of your GitHub Transform user comments into `_data` files that live inside of your GitHub repository by enabling Staticman.
repository by enabling Staticman.
**Note:** Looking to migrate comments from a Wordpress based site? Give **Note:** Looking to migrate comments from a Wordpress based site? Give [this tool](https://github.com/arthurlacoste/wordpress-comments-jekyll-staticman) a try.
[this tool](https://github.com/arthurlacoste/wordpress-comments-jekyll-staticman) {: .notice--info}
a try. {: .notice--info}
###### Add Staticman as a Collaborator ###### Add Staticman as a Collaborator
1. Allow Staticman push access to your GitHub repository by clicking on 1. Allow Staticman push access to your GitHub repository by clicking on **Settings**, then the **Collaborators** tab and adding `staticmanapp` as a collaborator.
**Settings**, then the **Collaborators** tab and adding `staticmanapp` as a 2. To accept the pending invitation visit: `https://api.staticman.net/v2/connect/{your GitHub username}/{your repository name}`. Consult the Staticman "[Get Started](https://staticman.net/get-started)" guide for more info.
collaborator.
2. To accept the pending invitation visit:
`https://api.staticman.net/v2/connect/{your GitHub username}/{your repository
name}`. Consult the Staticman
"[Get Started](https://staticman.net/get-started)" guide for more info.
###### Configure Staticman ###### Configure Staticman
**Staticman v2** **Staticman v2**
Default settings have been provided in Default settings have been provided in [`staticman.yml`](https://github.com/mmistakes/minimal-mistakes/blob/master/staticman.yml) and are commented to guide you through setup. View the [full list of configurations](https://staticman.net/docs/configuration).
[`staticman.yml`](https://github.com/mmistakes/minimal-mistakes/blob/master/staticman.yml)
and are commented to guide you through setup. View the
[full list of configurations](https://staticman.net/docs/configuration).
```yaml ```yaml
# staticman.yml (defaults) # staticman.yml (defaults)
@ -485,20 +380,15 @@ staticman:
branch : "master" branch : "master"
``` ```
**Branch setting:** This is the branch comment files will be sent to via pull **Branch setting:** This is the branch comment files will be sent to via pull requests. If you host your site on GitHub Pages it will likely be `master` unless your repo is setup as a project --- use `gh-pages` in that case.
requests. If you host your site on GitHub Pages it will likely be `master` {: .notice--info}
unless your repo is setup as a project --- use `gh-pages` in that case. {:
.notice--info}
**Note:** Staticman is currently only compatible with GitHub based repositories. **Note:** Staticman is currently only compatible with GitHub based repositories. [Support for GitLab Pages](https://github.com/eduardoboucas/staticman/issues/22) is planned but not available yet.
[Support for GitLab Pages](https://github.com/eduardoboucas/staticman/issues/22) {: .notice--warning}
is planned but not available yet. {: .notice--warning}
**Staticman v1 (deprecated)** **Staticman v1 (deprecated)**
Default settings have been provided in `_config.yml`. The important ones to set Default settings have been provided in `_config.yml`. The important ones to set are `provider: "staticman"`, `branch`, and `path`. View the [full list of configurations](https://staticman.net/docs/configuration).
are `provider: "staticman"`, `branch`, and `path`. View the
[full list of configurations](https://staticman.net/docs/configuration).
```yaml ```yaml
# _config.yml (defaults) # _config.yml (defaults)
@ -524,29 +414,21 @@ staticman:
###### Comment Moderation ###### Comment Moderation
By default comment moderation is enabled in `staticman.yml`. As new comments are By default comment moderation is enabled in `staticman.yml`. As new comments are submitted Staticman will send a pull request. Merging these in will approve the comment, close the issue, and automatically rebuild your site (if hosted on GitHub Pages).
submitted Staticman will send a pull request. Merging these in will approve the
comment, close the issue, and automatically rebuild your site (if hosted on
GitHub Pages).
To skip this moderation step simply set `moderation: false`. To skip this moderation step simply set `moderation: false`.
**ProTip:** Create a GitHub webhook that sends a `POST` request to the following **ProTip:** Create a GitHub webhook that sends a `POST` request to the following payload URL `https://api.staticman.net/v2/webhook` and triggers a "Pull request" event to delete Staticman branches on merge.
payload URL `https://api.staticman.net/v2/webhook` and triggers a "Pull request" {: .notice--info}
event to delete Staticman branches on merge. {: .notice--info}
![pull-request webhook]({{ "/assets/images/mm-staticman-pr-webhook.jpg" | ![pull-request webhook]({{ "/assets/images/mm-staticman-pr-webhook.jpg" | absolute_url }})
absolute_url }})
###### reCAPTCHA Support (v2 only) ###### reCAPTCHA Support (v2 only)
To enable Google's reCAPTCHA to aid in spam detection you'll need to: To enable Google's reCAPTCHA to aid in spam detection you'll need to:
1. Apply for [reCAPTCHA API](https://www.google.com/recaptcha) keys and register 1. Apply for [reCAPTCHA API](https://www.google.com/recaptcha) keys and register your site using the reCAPTCHA V2 type.
your site using the reCAPTCHA V2 type. 2. Add your site and secret keys to `staticman.yml` and `_config.yml`. Be sure to properly encrypt your secret key using [Staticman's encrypt endpoint](https://staticman.net/docs/encryption).
2. Add your site and secret keys to `staticman.yml` and `_config.yml`. Be sure
to properly encrypt your secret key using
[Staticman's encrypt endpoint](https://staticman.net/docs/encryption).
```yaml ```yaml
reCaptcha: reCaptcha:
@ -557,46 +439,34 @@ reCaptcha:
##### Other Comment Providers ##### Other Comment Providers
To use another provider not included with the theme set `provider: "custom"` To use another provider not included with the theme set `provider: "custom"` then add their embed code to `_includes/comments-providers/custom.html`.
then add their embed code to `_includes/comments-providers/custom.html`.
### Custom Feed URL ### Custom Feed URL
By default the theme links to `feed.xml` generated in the root of your site by By default the theme links to `feed.xml` generated in the root of your site by the **jekyll-feed** plugin. To link to an externally hosted feed update `atom_feed` in `_config.yml` like so:
the **jekyll-feed** plugin. To link to an externally hosted feed update
`atom_feed` in `_config.yml` like so:
```yaml ```yaml
atom_feed: atom_feed:
path: "http://feeds.feedburner.com/youFeedname" path: "http://feeds.feedburner.com/youFeedname"
``` ```
**Note:** By default the site feed is linked in two locations: inside the **Note:** By default the site feed is linked in two locations: inside the [`<head>` element](https://github.com/mmistakes/minimal-mistakes/blob/master/_includes/head.html) and at the bottom of every page in the [site footer](https://github.com/mmistakes/minimal-mistakes/blob/master/_includes/footer.html).
[`<head>` element](https://github.com/mmistakes/minimal-mistakes/blob/master/_includes/head.html)
and at the bottom of every page in the
[site footer](https://github.com/mmistakes/minimal-mistakes/blob/master/_includes/footer.html).
{: .notice--info} {: .notice--info}
### SEO, Social Sharing, and Analytics Settings ### SEO, Social Sharing, and Analytics Settings
All optional, but a good idea to take the time setting up to improve SEO and All optional, but a good idea to take the time setting up to improve SEO and links shared from the site.
links shared from the site.
#### Google Search Console #### Google Search Console
Formerly known as Formerly known as [Google Webmaster Tools](https://www.google.com/webmasters/tools/), add your [verification code](https://support.google.com/analytics/answer/1142414?hl=en) like so: `google_site_verification: "yourVerificationCode"`.
[Google Webmaster Tools](https://www.google.com/webmasters/tools/), add your
[verification code](https://support.google.com/analytics/answer/1142414?hl=en)
like so: `google_site_verification: "yourVerificationCode"`.
**Note:** You likely won't have to do this if you verify site ownership through **Note:** You likely won't have to do this if you verify site ownership through **Google Analytics** instead.
**Google Analytics** instead. {: .notice--warning} {: .notice--warning}
#### Bing Webmaster Tools #### Bing Webmaster Tools
There are several ways to There are several ways to [verify site ownership](https://www.bing.com/webmaster/help/how-to-verify-ownership-of-your-site-afcfefc6) --- the easiest adding an authentication code to your config file.
[verify site ownership](https://www.bing.com/webmaster/help/how-to-verify-ownership-of-your-site-afcfefc6)
--- the easiest adding an authentication code to your config file.
Copy and paste the string inside of `content`: Copy and paste the string inside of `content`:
@ -612,10 +482,7 @@ bing_site_verification: "0FC3FD70512616B052E755A56F8952D"
#### Naver Webmaster Tools #### Naver Webmaster Tools
To verify site ownership you will need to To verify site ownership you will need to [create a Naver account](https://nid.naver.com/user2/joinGlobal.nhn?lang=en_US&m=init) and then **Add your site** via [Naver Webmaster Tools](http://webmastertool.naver.com/).
[create a Naver account](https://nid.naver.com/user2/joinGlobal.nhn?lang=en_US&m=init)
and then **Add your site** via
[Naver Webmaster Tools](http://webmastertool.naver.com/).
Much like Google and Bing you'll be provided with a meta description: Much like Google and Bing you'll be provided with a meta description:
@ -645,31 +512,23 @@ yandex_site_verification: "2132801JL"
#### Twitter Cards and Facebook Open Graph #### Twitter Cards and Facebook Open Graph
To improve the appearance of links shared from your site to social networks like To improve the appearance of links shared from your site to social networks like Twitter and Facebook be sure to configure the following.
Twitter and Facebook be sure to configure the following.
##### Site Twitter Username ##### Site Twitter Username
Twitter username for the site. For pages that have custom author Twitter Twitter username for the site. For pages that have custom author Twitter accounts assigned in their YAML Front Matter or data file, they will be attributed as a **creator** in the Twitter Card.
accounts assigned in their YAML Front Matter or data file, they will be
attributed as a **creator** in the Twitter Card.
For example if my site's Twitter account is `@mmistakes-theme` I would add the For example if my site's Twitter account is `@mmistakes-theme` I would add the following to `_config.yml`
following to `_config.yml`
```yaml ```yaml
twitter: twitter:
username: "mmistakes-theme" username: "mmistakes-theme"
``` ```
And if I assign `@mmistakes` as an author account it will appear in the Twitter And if I assign `@mmistakes` as an author account it will appear in the Twitter Card along with `@mmistakes-theme`, attributed as a creator of the page being shared.
Card along with `@mmistakes-theme`, attributed as a creator of the page being
shared.
**Note**: You need to **Note**: You need to [apply for Twitter Cards](https://dev.twitter.com/docs/cards) and validate they're working on your site before they will begin showing up.
[apply for Twitter Cards](https://dev.twitter.com/docs/cards) and validate {: .notice--warning}
they're working on your site before they will begin showing up. {:
.notice--warning}
##### Facebook Open Graph ##### Facebook Open Graph
@ -681,26 +540,19 @@ facebook:
publisher: # A Facebook page URL or ID of the publishing entity publisher: # A Facebook page URL or ID of the publishing entity
``` ```
While not part a part of Open Graph, you can also add your Facebook username for While not part a part of Open Graph, you can also add your Facebook username for use in the sidebar and footer.
use in the sidebar and footer.
```yaml ```yaml
facebook: facebook:
username: "michaelrose" # https://www.facebook.com/michaelrose username: "michaelrose" # https://www.facebook.com/michaelrose
``` ```
**ProTip:** To debug Open Graph data use **ProTip:** To debug Open Graph data use [this tool](https://developers.facebook.com/tools/debug/og/object?q=https%3A%2F%2Fmademistakes.com) to test your pages. If content changes aren't reflected you will probably have to hit the **Fetch new scrape information** button to refresh.
[this tool](https://developers.facebook.com/tools/debug/og/object?q=https%3A%2F%2Fmademistakes.com) {: .notice--info}
to test your pages. If content changes aren't reflected you will probably have
to hit the **Fetch new scrape information** button to refresh. {: .notice--info}
##### Open Graph Default Image ##### Open Graph Default Image
For pages that don't have a `header.image` assigned in their YAML Front Matter, For pages that don't have a `header.image` assigned in their YAML Front Matter, `site.og_image` will be used as a fallback. Use your logo, icon, avatar or something else that is meaningful. Just make sure it is place in the `/assets/images/` folder, a minimum size of 120px by 120px, and less than 1MB in file size.
`site.og_image` will be used as a fallback. Use your logo, icon, avatar or
something else that is meaningful. Just make sure it is place in the
`/assets/images/` folder, a minimum size of 120px by 120px, and less than 1MB in
file size.
```yaml ```yaml
og_image: /assets/images/site-logo.png og_image: /assets/images/site-logo.png
@ -711,8 +563,7 @@ og_image: /assets/images/site-logo.png
<figcaption>Example of a image placed in a Summary Card.</figcaption> <figcaption>Example of a image placed in a Summary Card.</figcaption>
</figure> </figure>
Documents who have a `header.image` assigned in their YAML Front Matter will Documents who have a `header.image` assigned in their YAML Front Matter will appear like this when shared on Twitter and Facebook.
appear like this when shared on Twitter and Facebook.
<figure> <figure>
<img src="{{ '/assets/images/mm-twitter-card-summary-large.jpg' | absolute_url }}" alt="page shared on Twitter"> <img src="{{ '/assets/images/mm-twitter-card-summary-large.jpg' | absolute_url }}" alt="page shared on Twitter">
@ -726,10 +577,7 @@ appear like this when shared on Twitter and Facebook.
##### Include your social profile in search results ##### Include your social profile in search results
Use markup on your official website to add your Use markup on your official website to add your [social profile information](https://developers.google.com/structured-data/customize/social-profiles#adding_structured_markup_to_your_site) to the Google Knowledge panel in some searches. Knowledge panels can prominently display your social profile information.
[social profile information](https://developers.google.com/structured-data/customize/social-profiles#adding_structured_markup_to_your_site)
to the Google Knowledge panel in some searches. Knowledge panels can prominently
display your social profile information.
```yaml ```yaml
social: social:
@ -745,8 +593,7 @@ social:
#### Analytics #### Analytics
Analytics is disabled by default. To enable globally select one of the Analytics is disabled by default. To enable globally select one of the following:
following:
| Name | Analytics Provider | | Name | Analytics Provider |
| -------------------- | --------------------------------------------------------------- | | -------------------- | --------------------------------------------------------------- |
@ -763,19 +610,16 @@ analytics:
tracking_id: "UA-1234567-8" tracking_id: "UA-1234567-8"
``` ```
To use another provider not included with the theme set `provider: "custom"` To use another provider not included with the theme set `provider: "custom"` then add their embed code to `_includes/analytics-providers/custom.html`.
then add their embed code to `_includes/analytics-providers/custom.html`.
## Site Author ## Site Author
Used as the defaults for defining what appears in the author sidebar. Used as the defaults for defining what appears in the author sidebar.
![author sidebar example]({{ "/assets/images/mm-author-sidebar-example.jpg" | ![author sidebar example]({{ "/assets/images/mm-author-sidebar-example.jpg" | absolute_url }})
absolute_url }})
**Note:** For sites with multiple authors these values can be overridden post by **Note:** For sites with multiple authors these values can be overridden post by post with custom YAML Front Matter and a data file. For more information on how that works see below.
post with custom YAML Front Matter and a data file. For more information on how {: .notice--info}
that works see below. {: .notice--info}
```yaml ```yaml
author: author:
@ -786,37 +630,23 @@ author:
uri : "http://your-site.com" uri : "http://your-site.com"
``` ```
Social media links are all optional, include the ones you want visible. In most Social media links are all optional, include the ones you want visible. In most cases you just need to add the username. If you're unsure double check `_includes/author-profile.html` to see how the URL is constructed.
cases you just need to add the username. If you're unsure double check
`_includes/author-profile.html` to see how the URL is constructed.
To add social media links not included with the theme or customize the author To add social media links not included with the theme or customize the author sidebar further, read the full [layout documentation]({{ "/docs/layouts/#author-profile" | absolute_url }}).
sidebar further, read the full [layout documentation]({{
"/docs/layouts/#author-profile" | absolute_url }}).
## Reading Files ## Reading Files
Nothing out of the ordinary here. `include` and `exclude` may be the only things Nothing out of the ordinary here. `include` and `exclude` may be the only things you need to alter.
you need to alter.
## Conversion and Markdown Processing ## Conversion and Markdown Processing
Again nothing out of the ordinary here as the theme adheres to the defaults used Again nothing out of the ordinary here as the theme adheres to the defaults used by GitHub Pages. [**Kramdown**](http://kramdown.gettalong.org/) for Markdown conversion, [**Rouge**](http://rouge.jneen.net/) syntax highlighting, and incremental building disabled. Change them if you need to.
by GitHub Pages. [**Kramdown**](http://kramdown.gettalong.org/) for Markdown
conversion, [**Rouge**](http://rouge.jneen.net/) syntax highlighting, and
incremental building disabled. Change them if you need to.
## Front Matter Defaults ## Front Matter Defaults
To save yourself time setting To save yourself time setting [Front Matter Defaults](https://jekyllrb.com/docs/configuration/#front-matter-defaults) for posts, pages, and collections is the way to go. Sure you can assign layouts and toggle settings like **reading time**, **comments**, and **social sharing** in each file, but that's not ideal.
[Front Matter Defaults](https://jekyllrb.com/docs/configuration/#front-matter-defaults)
for posts, pages, and collections is the way to go. Sure you can assign layouts
and toggle settings like **reading time**, **comments**, and **social sharing**
in each file, but that's not ideal.
Using the `default` key in `_config.yml` you could set the layout and enable Using the `default` key in `_config.yml` you could set the layout and enable author profiles, reading time, comments, social sharing, and related posts for all posts --- in one shot.
author profiles, reading time, comments, social sharing, and related posts for
all posts --- in one shot.
```yaml ```yaml
defaults: defaults:
@ -857,55 +687,37 @@ defaults:
layout: single layout: single
``` ```
And of course any default value can be overridden by settings in a post, page, And of course any default value can be overridden by settings in a post, page, or collection file. All you need to do is specify the settings in the YAML Front Matter. For more examples be sure to check out the demo site's [`_config.yml`](https://github.com/mmistakes/minimal-mistakes/blob/master/_config.yml).
or collection file. All you need to do is specify the settings in the YAML Front
Matter. For more examples be sure to check out the demo site's
[`_config.yml`](https://github.com/mmistakes/minimal-mistakes/blob/master/_config.yml).
## Outputting ## Outputting
The default permalink style used by the theme is `permalink: The default permalink style used by the theme is `permalink: /:categories/:title/`. If you have a post named `2016-01-01-my-post.md` with `categories: foo` in the YAML Front Matter, Jekyll will generate `_site/foo/my-post/index.html`.
/:categories/:title/`. If you have a post named `2016-01-01-my-post.md` with
`categories: foo` in the YAML Front Matter, Jekyll will generate
`_site/foo/my-post/index.html`.
**Note:** If you plan on enabling breadcrumb links --- including category names **Note:** If you plan on enabling breadcrumb links --- including category names in permalinks is a big part of how those are created.
in permalinks is a big part of how those are created. {: .notice--warning} {: .notice--warning}
### Paginate ### Paginate
If [using pagination](https://github.com/jekyll/jekyll-paginate) on the homepage If [using pagination](https://github.com/jekyll/jekyll-paginate) on the homepage you can change the amount of posts shown with:
you can change the amount of posts shown with:
```yaml ```yaml
paginate: 5 paginate: 5
``` ```
You'll also need to include some Liquid and HTML to properly use the paginator, You'll also need to include some Liquid and HTML to properly use the paginator, which you can find in the **Layouts** section under [Home Page]({{ "/docs/layouts/#home-page" | absolute_url }}).
which you can find in the **Layouts** section under [Home Page]({{
"/docs/layouts/#home-page" | absolute_url }}).
The paginator only works on files with name `index.html`. To use pagination in a The paginator only works on files with name `index.html`. To use pagination in a subfolder --- for example `/recent/`, create `/recent/index.html` and set the `paginate_path` in `_config.yml` to this:
subfolder --- for example `/recent/`, create `/recent/index.html` and set the
`paginate_path` in `_config.yml` to this:
```yaml ```yaml
paginate_path: /recent/page:num/ paginate_path: /recent/page:num/
``` ```
**Please note:** When using Jekyll's default **Please note:** When using Jekyll's default [pagination plugin](http://jekyllrb.com/docs/pagination/) `paginator.posts` can only be called once. If you're looking for something more powerful that can paginate category, tag, and collection pages I suggest [**jekyll-paginate-v2**](https://github.com/sverrirs/jekyll-paginate-v2).
[pagination plugin](http://jekyllrb.com/docs/pagination/) `paginator.posts` can {: .notice--info}
only be called once. If you're looking for something more powerful that can
paginate category, tag, and collection pages I suggest
[**jekyll-paginate-v2**](https://github.com/sverrirs/jekyll-paginate-v2). {:
.notice--info}
### Timezone ### Timezone
This sets the timezone environment variable, which Ruby uses to handle time and This sets the timezone environment variable, which Ruby uses to handle time and date creation and manipulation. Any entry from the [IANA Time Zone Database](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones) is valid. The default is the local time zone, as set by your operating system.
date creation and manipulation. Any entry from the
[IANA Time Zone Database](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
is valid. The default is the local time zone, as set by your operating system.
```yaml ```yaml
timezone: America/New_York timezone: America/New_York
@ -913,10 +725,7 @@ timezone: America/New_York
## Plugins ## Plugins
When hosting with GitHub Pages a small When hosting with GitHub Pages a small [set of gems](https://pages.github.com/versions/) have been whitelisted for use. The theme uses a few of them which can be found under `gems`. Additional settings and configurations are documented in the links below.
[set of gems](https://pages.github.com/versions/) have been whitelisted for use.
The theme uses a few of them which can be found under `gems`. Additional
settings and configurations are documented in the links below.
| Plugin | Description | | Plugin | Description |
| ---------------------------------- | ----------------------------------------------------------------------------------------- | | ---------------------------------- | ----------------------------------------------------------------------------------------- |
@ -932,24 +741,18 @@ settings and configurations are documented in the links below.
[jekyll-feed]: https://github.com/jekyll/jekyll-feed [jekyll-feed]: https://github.com/jekyll/jekyll-feed
[jemoji]: https://github.com/jekyll/jemoji [jemoji]: https://github.com/jekyll/jemoji
If you're hosting elsewhere then you don't really have to worry about what is If you're hosting elsewhere then you don't really have to worry about what is whitelisted as you are free to include whatever [Jekyll plugins](https://jekyllrb.com/docs/plugins/) you desire.
whitelisted as you are free to include whatever
[Jekyll plugins](https://jekyllrb.com/docs/plugins/) you desire.
## Archive Settings ## Archive Settings
The theme ships with support for taxonomy (category and tag) pages. GitHub Pages The theme ships with support for taxonomy (category and tag) pages. GitHub Pages hosted sites need to use a _Liquid only_ approach while those hosted elsewhere can use plugins like [**jekyll-archives**][jekyll-archives] to generate these pages automatically.
hosted sites need to use a _Liquid only_ approach while those hosted elsewhere
can use plugins like [**jekyll-archives**][jekyll-archives] to generate these
pages automatically.
[jekyll-archives]: https://github.com/jekyll/jekyll-archives [jekyll-archives]: https://github.com/jekyll/jekyll-archives
The default `type` is set to use Liquid. The default `type` is set to use Liquid.
**Note:** `category_archive` and `tag_archive` were previously named **Note:** `category_archive` and `tag_archive` were previously named `categories` and `tags`. Names were changed to avoid possible conflicts with `site.categories` and `site.tags`.
`categories` and `tags`. Names were changed to avoid possible conflicts with {: .notice--danger}
`site.categories` and `site.tags`. {: .notice--danger}
```yaml ```yaml
category_archive: category_archive:
@ -960,27 +763,14 @@ tag_archive:
path: /tags/ path: /tags/
``` ```
Which would create category and tag links in the breadcrumbs and page meta like: Which would create category and tag links in the breadcrumbs and page meta like: `/categories/#foo` and `/tags/#foo`.
`/categories/#foo` and `/tags/#foo`.
**Note:** these are simply hash (fragment) links into the full taxonomy index **Note:** these are simply hash (fragment) links into the full taxonomy index pages. For them to resolve properly, the category and tag index pages need to exist at [`/categories/index.html`](https://github.com/{{ site.repository }}/blob/master/docs/_pages/category-archive.html) (copy to `_pages/category-archive.html`) and [`/tags/index.html`](https://github.com/{{ site.repository }}/blob/master/docs/_pages/tag-archive.html) (copy to `_pages/tag-archive.html`).
pages. For them to resolve properly, the category and tag index pages need to {: .notice--warning}
exist at [`/categories/index.html`](https://github.com/{{ site.repository
}}/blob/master/docs/_pages/category-archive.html) (copy to
`_pages/category-archive.html`) and [`/tags/index.html`](https://github.com/{{
site.repository }}/blob/master/docs/_pages/tag-archive.html) (copy to
`_pages/tag-archive.html`). {: .notice--warning}
If you have the luxury of using Jekyll Plugins, then If you have the luxury of using Jekyll Plugins, then [**jekyll-archives**][jekyll-archives] will create a better experience as discrete taxonomy pages would be generated, and their corresponding links would be "real" (not just hash/fragment links into a larger index). However, the plugin will not generate the taxonomy index pages (`category-archive.html` and `_pages/tag-archive.html`) so you'd still need to manually create them if you'd like to have them (see note above).
[**jekyll-archives**][jekyll-archives] will create a better experience as
discrete taxonomy pages would be generated, and their corresponding links would
be "real" (not just hash/fragment links into a larger index). However, the
plugin will not generate the taxonomy index pages (`category-archive.html` and
`_pages/tag-archive.html`) so you'd still need to manually create them if you'd
like to have them (see note above).
First, you'll need to make sure that the `jekyll-archives` plugin is installed. First, you'll need to make sure that the `jekyll-archives` plugin is installed. Either run `gem install jekyll-archives` or add the following to your `Gemfile`:
Either run `gem install jekyll-archives` or add the following to your `Gemfile`:
``` ```
group :jekyll_plugins do group :jekyll_plugins do
@ -990,9 +780,7 @@ end
Then run `bundle install`. Then run `bundle install`.
Now that the plugin is installed, change `type` to `jekyll-archives` and apply Now that the plugin is installed, change `type` to `jekyll-archives` and apply the following [configurations](https://github.com/jekyll/jekyll-archives/blob/master/docs/configuration.md):
the following
[configurations](https://github.com/jekyll/jekyll-archives/blob/master/docs/configuration.md):
```yaml ```yaml
category_archive: category_archive:
@ -1013,21 +801,16 @@ jekyll-archives:
tag: /tags/:name/ tag: /tags/:name/
``` ```
**Note:** The `archive-taxonomy` layout used by jekyll-archives is provided with **Note:** The `archive-taxonomy` layout used by jekyll-archives is provided with the theme and can be found in the `_layouts` folder.
the theme and can be found in the `_layouts` folder. {: .notice--info} {: .notice--info}
## HTML Compression ## HTML Compression
If you care at all about performance (and really who doesn't) compressing the If you care at all about performance (and really who doesn't) compressing the HTML files generated by Jekyll is a good thing to do.
HTML files generated by Jekyll is a good thing to do.
If you're hosting with GitHub Pages there aren't many options afforded to you If you're hosting with GitHub Pages there aren't many options afforded to you for optimizing the HTML Jekyll generates. Thankfully there is some Liquid wizardry you can use to strip whitespace and comments to reduce file size.
for optimizing the HTML Jekyll generates. Thankfully there is some Liquid
wizardry you can use to strip whitespace and comments to reduce file size.
There's a variety of configurations and caveats to using the `compress` layout, There's a variety of configurations and caveats to using the `compress` layout, so be sure to read through the [documentation](http://jch.penibelst.de/) if you decide to make change the defaults set in the theme's `_config.yml`.
so be sure to read through the [documentation](http://jch.penibelst.de/) if you
decide to make change the defaults set in the theme's `_config.yml`.
```yaml ```yaml
compress_html: compress_html:
@ -1036,11 +819,8 @@ compress_html:
envs: development # disable compression in dev environment envs: development # disable compression in dev environment
``` ```
**Caution:** Inline JavaScript comments can cause problems with `compress.html`, **Caution:** Inline JavaScript comments can cause problems with `compress.html`, so be sure to `/* comment this way */` and avoid `// these sorts of comments`.
so be sure to `/* comment this way */` and avoid `// these sorts of comments`.
{: .notice--warning} {: .notice--warning}
**Note:** CDN services such as CloudFlare provide optional automatic **Note:** CDN services such as CloudFlare provide optional automatic minification for HTML, CSS, and JavaScript. If you are serving your site via such a service and have minification enabled, this configuration might be redundant.
minification for HTML, CSS, and JavaScript. If you are serving your site via {: .notice--info}
such a service and have minification enabled, this configuration might be
redundant. {: .notice--info}