Configuration

Getting Started

This theme is a Jekyll powered project. For more information on Jekyll and how it works, take a look at the official Jekyll documentation. If you plan on modifying the theme files directly it’s also worth browsing the liquid documentation which is Jekyll’s templating language.

Installation

First things first, you’ll need to have Jekyll installed and running. Jekyll has some great documentation explaining how to do this on multiple operating systems. Once Jekyll is installed, you can create a Jekyll site using:

~ $ jekyll new your-website-name

To install the Lost Woods theme simply unzip the package in your new site directory. Next you’ll want to configure your site by modifying _config.yml. Below is a full list of options and customizations you have available through your config file.

Updating

To update Lost Woods to a newer version, override the _includes/ and _layouts/ directories. Make sure not to delete or override any of your custom content or edits. For theme styles and scripts, you can either update the src/ directory and run the provided build scripts or override the dist/ directory.

Build scripts

This project uses Gulp for it’s processing of CSS, JavaScript and other asset files such as SVG icons. If you’d like to customize the styles, scripts or theme assets, make sure you install the required packages in your environment using node package manager:

~ $ npm install

To see all the available tasks, simply run:

~ $ gulp --tasks

Build scripts process files located in the src/ directory. Their output paths are shown below but can be changed by updating the paths variable in gulpfile.babel.js. Some tasks will processes all files in their directory (e.g. images and svg icons) while others have a specific entry and output file e.g. CSS and JavaScript.

Third Party Assets

Lost Woods uses a few third party open-source projects. Here’s a complete list of all of these projects and their project pages:

• Vrembem: A CSS component library built using the BEM methodology. Also included from this project are a few JavaScript plugins for modals and dismissible functionality.
• Feather Icons: Simply beautiful open source icons.
• svgxuse: A simple polyfill that fetches external SVGs referenced in use elements when the browser itself fails to do so.
• simple-jekyll-search: A JavaScript library to add search functionality to any Jekyll blog.
• smooth-scroll: A lightweight script to animate scrolling to anchor links.
• gumshoe: A simple, framework-agnostic scrollspy script.
• vanilla-lazyload: A fast, lightweight and flexible script that speeds up your web application by loading images as they enter the viewport.

Configuration

The _config.yml file is where the default configuration settings are set. The official Jekyll documentation has a full list of all the default configurations you can set in this file. The following site details are used by the theme:

_config.yml

# Used throughout theme and meta data
title: [string]
description: [string]

# These plugins are GitHub Pages friendly
plugins:
  - jekyll-feed
  - jekyll-paginate

# We exclude build related files
exclude:
  - Gemfile
  - Gemfile.lock
  - node_modules
  - src
  - gulpfile.babel.js
  - package-lock.json
  - package.json
  - readme.md

By default, you site title will be output in the header. To use a custom logo for your site, simply include a path for your logo file. You can include either a string or a list of strings with a condition for responsive images. If you have a logo to swap for when it’s on a dark background, you can use the optional logo_invert parameter.

_config.yml

# Set the path(s) to your logo file
logo: [string | list]

# Set the path(s) to your inverted logo file
logo_invert: [string | list]

# Set the width and height attributes for your image e.g. 120x80
logo_size: [string]

Input

logo:
  - assets/img/logo.png
  - assets/img/logo@2x.png 2x

Output

<img srcset="/assets/img/logo.png,
             /assets/img/logo@2x.png 2x"
     src="/assets/img/logo.png" alt="{{ site.title }}" role="logo">

You can also optionally set the width and height attribute of your logo by providing those values separated by an x character here:

_config.yml

logo_size: '[width] x [height]'

The class options are a way to hook into core layout elements and add class modifiers or custom hooks. This works together with the page class front matter and both are added to their respective elements.

_config.yml

class:
  html: [spaced list] # Classes to add to the html element
  body: [spaced list] # Classes to add to the body element
  parent: [spaced list] # Classes to add to the parent div
  container: [spaced list] # Classes to add to the container div
  section: [spaced list] # Classes to add to the section div

input

# Added to _config.yml
# This class will output on every page of your site
class:
  html: global_class

# Added to path/my_page.md
# This class will only appear on the post or page it's set on
---
class:
  html: context_class
---

output

<!-- When on path/my_page.html -->
<html class="global_class context_class">

<!-- Everywhere else -->
<html class="global_class">

The format template to use for displaying dates. Defaults to "%B %-d, %Y". Date template placeholders can be found here: Date formatting

_config.yml

date_format: [date template] # [default: "%B %-d, %Y"]

Output

October 20, 2018

This sets the path to your symbol definitions file. If one is provided it will be automatically included after the opening <body> tag and the icon.html helper include will switch to reference symbol definitions instead of injecting SVG icons directly.

_config.yml

symbols: svg/symbols.svg

Lost Woods comes with support for the jekyll-paginate plugin. These are the settings related to configuring pagination in your blog.

_config.yml

# Number of posts per page
paginate: [integer]

# Where the pagination pages should be output e.g. '/blog/page/:num/'
paginate_path: [string with :num]

Need taxonomy? Lost Woods handles this when you assign categories or tags to your posts and then create index pages for your taxonomies using the taxonomy layout. To set a custom categories or tags index page path, set the path here:

_config.yml

# The default categories path to look for
index_categories: [string] [default: categories.md]

# The default tags path to look for
index_tags: [string] [default: tags.md]

Search is provided by the simple-jekyll-search JavaScript library. It takes three options, the first enables search, the second decides which groups of collections are to be made searchable and third which groups of pages are to be made searchable.

_config.yml

# Whether search should be enabled or not
search: true

# All collections that should be made searchable
# Takes a string or list of collection names e.g. posts
search_posts: [string | list] [default: posts]

# All pages that should be made searchable
# Takes either a list of page paths or a menu key that contains page paths
search_pages: [string | list]

The search results are built using the search.json template. On building your site, this file will output the search.json file in your site directory.

You can enable Google Analytics on your site by providing your tacking ID:

_config.yml

google_analytics: [tracking-id]

Lost Woods supports the use of Disqus comments. To enable them comments on your site, you’ll need to provide your disqus shortname. Once that’s added you’ll need to add the comments: true front matter to your post or page.

_config.yml

disqus_shortname: [username]

There are a few places in this theme that you can add custom site wide content. To add some footer content, just add it via the footer.body setting:

_config.yml

footer:
  body: [string]

To add custom modal footers you have the following settings available:

_config.yml

modal_search:
  footer: [string]

modal_menu:
  footer: [string]

Menus

Lost Woods uses a simple but flexible and highly customizable menu system. Menus can be defined as easily as creating a list of page paths.

menu_custom:
  - index.md
  - blog.md
  - contact.md

You can also provide more details about your menu using the key list format. This lets you set custom text, icons, classes and attributes for your menu links:

menu_custom:
  - path: index.md
    text: 'Go Home'
  - path: blog.md
    text: 'My Blog'
    icon: 'book'

It’s possible to add separators in your menus. Simple create a menu item with --- as it’s value and the menu system will create a separator when it’s built.

menu_custom:
  - index.md
  - ---
  - blog.md
  - contact.md

Predefined Menus

Lost Woods has a few predefined menus that are used throughout the theme. These menus can contain a simple or detailed list but can also reference other menus by using their menu name.

_config.yml

# Menu that displays in the header
menu_header: [list | string]

# Menu that displays in the mobile menu modal
menu_modal: [list | string]

# Menu used to define relationships between pages
menu_siblings: [list | string]

# Menu used to find pages adjacent to one another
menu_adjacent: [list | string]

As an exmaple, you can define one list and then use that definition for some of the other predefined menus:

_config.yml

menu_header:
  - index.md
  - blog.md
  - contact.md

menu_modal: menu_header

It’s also important to know where predefined menus are used and how we can utilize and customize them. Check out the menu options documentation for details on how to toggle predefined menu options.

_config.yml

menu_header: [list | string]

Used for displaying primary menu links and optionally the search and more modal toggles. By default, this menu is referenced in the header.html include. The “view more” and search modal toggles are displayed by default but can be hidden from this menu using the menu options.

_config.yml

menu_modal: [list | string]

This menu is recommneded for more detailed or when you need a greater number of list items. It’s the main menu that mobile users use to navigate your site and can addiitonally be used to suppliment the limited space available for the header menu.

The mini menu is what replaces the header menu on smaller screens and the toolbar links that are revealed when you scroll past the header. It isn’t customizable in the same way other menus are, but you can optionally toggle certain tools. For information on how to customize the mini menu, check out the menu options documentation.

_config.yml

menu_siblings: [list | string]

The siblings menu is used to define relationships between pages. Sibling menus are enabled by a pages front matter and can be used to list any group of pages that are related to one another.

_config.yml

menu_adjacent: [list | string]

This menu is used to navigate between page and post siblings. In the context of posts the previous and next post links will be displayed while for pages you need to define a page order using this menu.

The social menu is used to display social links in the footer. It’s structured by social key and user handle pairs. These are associated with a unique social url and icon. Only the items that are provided a value will be rendered.

_config.yml

menu_social:
  twitter: [username]
  facebook: [username]
  google: [username]
  instagram: [username]
  github: [username]
  dribbble: [username]
  youtube: [username]
  pinterest: [username]
  linkedin: [username]
  yelp: [username]
  stackoverflow: [username]
  tumblr: [username]
  email: [email]
  rss: /feed.xml

The share menu is displayed after the page or post content. It allows users to share the current page on their social media accounts. Setting a social value to true will display the icon and default text for that social share link. You can also optionally disable icons or text, or even provide a custom text value for a link.

_config.yml

menu_share:
  twitter: [boolean | keyed list]
  facebook: [boolean | keyed list]
  google: [boolean | keyed list]
  pinterest: [boolean | keyed list]
  linkedin: [boolean | keyed list]
  tumblr: [boolean | keyed list]
  email: [boolean | keyed list]

Menu Options

Some pre-defined menus come with their own customization options. Below is all of the available pre-defined menu options.

_config.yml

menu:
  menu_header:
    # If we should hide the more modal toggle
    hide_more: [boolean]

    # If we should hide the search modal toggle
    hide_search: [boolean]

  menu_mini:
    # If we should hide the search modal toggle
    hide_search: [boolean]

    # If we should hide the back to parent button
    hide_back: [boolean]

    # If we should hide the back to top button
    hide_totop: [boolean]

  menu_adjacent:
    # If page adjacent items should repeat
    repeat: [boolean]

Front Matter

Here are some common values you can set in your page or post front matter. These are global settings and are not dependent on the layout you’re using. To get the most out of this theme it’s recommended that you include the following front matter for your pages, posts and collections (where applicable):

Front matter

---
layout: [string]
title: [string]
description: [string]
date: [yyyy-mm-dd]
---

Some listing layouts use images to link to your posts. This front matter allows you to set a thumbnail for your post. Remember to use the ./ prefix if you intend to link to an image relative to the root of your project. Otherwise it will be searched for using a context specific path.

---
thumbnail: [string] # Used for image based listing layouts
---

Whether or not you want your page to include a “table of contents”. If enabled, all the headings in your documnet will be compiled and a modal will be created to help navigate the page.

---
toc: [boolean]
---

If the table of contents is enaled a button will show to the right of the page title and in the toolbar that appears once you scroll down the page. Clicking these buttons will toggle the “table of contents” modal.

The class options give you a lot of control with modifying your sites content and allowing you to create hooks or apply modifiers at every level of the structural markup. This is added to the global classes settings in _config.yml.

Front matter

---
class:
  html: [spaced list] # Classes to add to the html element when on this page
  body: [spaced list] # Classes to add to the body element when on this page
  parent: [spaced list] # Classes to add to the parent div when on this page
  container: [spaced list] # Classes to add to the container div when on this page
  section: [spaced list] # Classes to add to the section div when on this page
---

The type component is what adds all the typographic styles to your document. It’s added by wrapping content with the .type class. This front matter allows you to disable the automattic application of the type component so that you can add it yourself manually.

Front matter

---
type: [boolean] # If the type component should be applied
---

Some components do not work well when nested within the type component. If you’d like to use components that aren’t compatible with the type component, use this paremeter to disable the type component and apply it where needed manually.

page.md

---
type: false
---

<div class="type">
  <h1>Styled Heading</h1>
  <p>This content will have typography styles applied to it.</p>
</div>

<ul class="menu">
  <li class="menu__item">
    <a class="menu__link" href="#">Not Effected</a>
  </li>
  <li class="menu__item">
    <a class="menu__link" href="#">By Type Component</a>
  </li>
</ul>

The parent front matter allows you to assign a parent to your page. This enables the “back to parent” button which gives users another tool to better navigate your site.

Front matter

---
parent: [string] # The path that this page is a parent to
---

You can set a parent page for all your posts or collections using default front matter. Here’s an example of setting the blog/index.html page as the parent of all blog posts:

_config.yml

defaults:
  - scope:
      path: ''
      type: posts
    values:
      parent: blog/index.html

Whether or not to include comments on this page or post. This requires that you have provided a disqus shortname in the config file. Comments must be explicitly set to output on each page otherwise you can set page or post defaults to automattically enable comments.

Front matter

---
comment: [boolean] # [default: false]
---

If you need to include context specific assets such as CSS or JavaScript, you can include them using this front matter. CSS gets injected in the head element and JavaScript is injected in the footer before the closing body tag.

Front matter

---
include:
  css: [string | list]
  js: [string | list]
---

Remember to use the ./ prefix if you intend to link to a file relative to the root of your project. Otherwise the assets will be searched for using a context specific path.

Input

---
include:
  css:
   - filename.css # Context specific file
   - ./assets/another.css # Relative to root path
  js: ./assets/example.js # Relative to root path
---

Output

<!-- Placed in <head> after the theme stylesheet -->
<link rel="stylesheet" href="/assets/pages/config/filename.css">
<link rel="stylesheet" href="/assets/another.css">

<!-- Placed in footer before the closing <body> tag -->
<script src="/assets/example.js"></script>

The Open Graph protocol enables any web page to become a rich object in a social graph. These values are built automatically for each page using your title and description values but if you’d like to create custom values for a page or post you can use this front matter:

Front matter

---
og:
  title: [string]
  description: [string]
  image: [filename]
---