You can think of these Jekyll helpers as little shortcuts. Since GitHub Pages doesn't allow most plugins --- [custom tags](https://jekyllrb.com/docs/plugins/#tags) are out. Instead the theme leverages [**includes**](https://jekyllrb.com/docs/templates/#includes) to do something similar.
## Base Path
**Deprecated**. Use `absolute_url` filter instead.
Instead of repeating `{% raw %}{{ site.url }}{{ site.baseurl }}{% endraw %}` over and over again to create absolute URLs, you can use `{% raw %}{{ base_path }}{% endraw %}` instead. Simply add `{% raw %}{% include base_path %}{% endraw %}` to layouts, posts, pages, collections, or other includes and you're good to go.
**ProTip:** It's a good practice to use absolute URL paths for assets (especially post images) so they correctly resolve in the site's XML feeds. Example: `{% raw %}{{ "/assets/images/filename.jpg" | absolute_url }}{% endraw %}` ~> `https://yourdoamin.com/assets/images/filename.jpg`
{: .notice--info}
## Group by Array
[Jekyll Group-By-Array](https://github.com/mushishi78/jekyll-group-by-array) by Max White.
A liquid include file for Jekyll that allows an object to be grouped by an array.
The Liquid based taxonomy archives found amongst the demo pages rely on this helper.
{% raw %}{% include figure image_path="/assets/images/unsplash-image-10.jpg" alt="this is a placeholder image" caption="This is a figure caption." %}{% endraw %}
```
Will output the following:
{% include figure image_path="/assets/images/unsplash-image-10.jpg" alt="this is a placeholder image" caption="This is a figure caption." %}
```html
<figure>
<imgsrc="/assets/images/unsplash-image-10.jpg"alt="this is a placeholder image">
<figcaption>This is a figure caption.</figcaption>
| **id** | Optional | To add multiple galleries to a document uniquely name them in the YAML Front Matter and reference in `{% raw %}{% include gallery id="gallery_id" %}{% endraw %}` | `gallery` |
| **class** | Optional | Use to add a `class` attribute to the surrounding `<figure>` element for additional styling needs. | |
{% raw %}{% include gallery caption="This is a sample gallery with **Markdown support**." %}{% endraw %}
```
**Gallery example with caption:**
{% include gallery caption="This is a sample gallery with **Markdown support**." %}
**More Gallery Goodness:** A few more examples and [source code](https://github.com/{{ site.repository }}/blob/master/docs/_posts/2010-09-09-post-gallery.md) can be seen in [this sample gallery post]({{ "" | absolute_url }}{% post_url 2010-09-09-post-gallery %}).
{: .notice--info}
## Feature Row
Designed to compliment the [`splash`]({{ "/docs/layouts/#splash-page-layout" | absolute_url }}) page layout as a way of arranging and aligning "feature blocks" containing text or image.
To add a feature row containing three content blocks with text and image, add the following YAML Front Matter
| **id** | Optional | To add multiple rows to a document uniquely name them in the YAML Front Matter and reference in `{% raw %}{% include feature_row id="row2" %}{% endraw %}` | `feature_row` |
| **type** | Optional | Alignment of the featured blocks in the row. Options include: `left`, `center`, or `right` aligned. | |
```liquid
{% raw %}{% include feature_row %}{% endraw %}
```
{% include feature_row %}
**More Feature Row Goodness:** A [few more examples]({{ "/splash-page/" | absolute_url }}) and [source code](https://github.com/{{ site.repository }}/blob/master/docs/_pages/splash-page.md) can be seen in the demo site.
Embed a video from YouTube or Vimeo that responsively sizes to fit the width of its parent.
| Parameter | Required | Description |
|---------- |--------- | ----------- |
| `id` | **Required** | ID of the video |
| `provider` | **Required** | Hosting provider of the video, either `youtube` or `vimeo` |
### YouTube
To embed the following YouTube video at url `https://www.youtube.com/watch?v=XsxDH4HcOWA` (long version) or `https://youtu.be/XsxDH4HcOWA` (short version) into a post or page's main content you'd use:
To include an [auto-generated table of contents](https://kramdown.gettalong.org/converter/html.html#toc) for posts and pages, add the following helper before any actual content in your post or page.
![table of contents example]({{ "/assets/images/mm-toc-helper-example.jpg" | absolute_url }})
| Parameter | Required | Description | Default |
| --------- | -------- | ----------- | ------- |
| **title** | Optional | Table of contents title. | `toc_label` in UI Text data file. |
| **icon** | Optional | Table of contents icon (shows before the title). | [Font Awesome](https://fortawesome.github.io/Font-Awesome/icons/) <iclass="fa fa-file-text"></i>**file-text** icon. Any other FA icon can be used instead. |
**TOC example with custom title and icon**
```liquid
{% raw %}{% include toc icon="gears" title="My Table of Contents" %}{% endraw %}
```
## Navigation List
Include an unordered list of links to be used as sidebar navigation with the `nav_list` helper.
**1.** Start by adding a set of titles and URLs to `_data/navigation.yml` in the same way the [`main` navigation]({{ "/docs/navigation/" | absolute_url }}) is built.
`foo` navigation example:
```yaml
# _data/navigation.yml
foo:
- title: "Link 1 Title"
url: /link-1-page-url/
- title: "Link 2 Title"
url: http://external-link.com
- title: "Link 3 Title"
url: /link-3-page-url/
- title: "Link 4 Title"
url: /link-4-page-url/
```
For a navigation list that has child pages you'd structure the YAML like this:
```yaml
# _data/navigation.yml
foo:
- title: "Parent Link 1"
url: /parent-1-page-url/
children:
- title: "Child Link 1"
url: /child-1-page-url/
- title: "Child Link 2"
url: /child-2-page-url/
- title: "Parent Link 2"
url: /parent-2-page-url/
children:
- title: "Child Link 1"
url: /child-1-page-url/
- title: "Child Link 2"
url: /child-2-page-url/
- title: "Child Link 3"
url: /child-3-page-url/
```
**2:** On the page(s) you'd like the `foo` sidebar nav add the following YAML Front Matter, referencing the same key name.
```yaml
sidebar:
nav: "foo"
```
**ProTip:** If you're applying the same navigation list to several pages setting it as a [Front Matter default](https://jekyllrb.com/docs/configuration/#front-matter-defaults) is the better option.
The theme's documentation is built with the `nav_list` helper so if you'd like an example to dissect take a look at `navigation.yml`, `_config.yml` and `_doc` collection in the [`/docs/` folder](https://github.com/{{ site.repository }}/tree/master/docs/) of this repo.
