Configuration

Example website

If you want to learn by example, this website uses Petridish. Browse the Petridish repository to see how things are configured.

Site-wide configuration

Your site’s configuration is controlled by _config.yml. Set at least a title and maybe some social profiles.

Pages

Create pages as Markdown files in your repository (e.g. about.md for this page).

Pages can have the following front matter (only title is required):

---
title: Title for the page
description: Description that will appear below the title in the banner
background: /assets/images/banner_background_image.jpg
permalink: /about/
toc: false
comments: false # See posts
---

Our project ...

Pages will use layout: default by default.

title will appear on the page itself, but you can use a different (e.g. shorter) name in navigation.

background can be a local or remote image. It will be cropped vertically. For faster page loads, reduce image sizes to less than 1MB (e.g. by reducing resolution to 72dpi and/or width to 2000px).

To add a table of content based on the h2 and h3 headers of your page (like on this configuration page), add toc: true. The width of the page is unaffected by the table of content. The table of content is disabled by default.

For easier maintenance, organize your pages in a pages/ directory and set their permalink.

Home page

To enable options for your home page (source home.md), add the following front matter:

layout: home

In _config.yml you can now define:

posts_on_home: 3                        # Show x number of latest posts on homepage, can be 0
tweets_on_home: true                    # Show Twitter feed of twitter_username on homepage

For easier maintenance, move/rename your index.md to pages/home.md and set its permalink to /.

Team page

To enable your team page (source team.md), add the following front matter:

layout: team

Then create a _data/team.yml file to list team members.

Archive page

To enable your news / blog / archive page (source archive.md) - i.e. the page listing all posts - add the following front matter:

layout: archive

And enable post categories by repeating the permalink for your archive page in _config.yml:

archive_permalink: /blog/               # Permalink of page using archive.html layout, required when using post categories

To see blog posts, you’ll have to create some. ☺️

Blog posts

Create posts as yyyy-mm-dd-title.md Markdown files in the _posts/ directory (e.g. 2019-07-08-dmp.md for this post).

Posts can have the following front matter (only title is required):

---
title: "Title for the post: wrap in quotes if it contains special characters"
description: Description that will appear below the title in the banner
background: /assets/images/banner_background_image.jpg
author: [Author 1, Author 2]
categories: [Category 1, Category 2]
toc: false # See pages
comments: false
---

We are happy to announce ...

Posts can be shown on an archive page and on the home page.

Posts will use layout: default by default.

To enable post comments, add your site to Disqus and add comments: true to each post where you want comments. Comments are disabled by default.

To change the permalink of all posts from the default yyyy/mm/dd/title.html to e.g. blog/{filename}/ without having to add a permalink to each post, set a front matter default in _config.yml:

defaults:
  -
    scope:
      path: ""
      type: "posts"
    values:
      permalink: "/blog/:slug/"         # Use /blog/{filename}/ as permalink for all posts

Markdown options

See the Markdown guide for an overview of the Markdown syntax you can use in pages and posts.

Create a _data/navigation.yml file and add pages in the order you want to include them in your top site navigation. You can also include dropdown menus.

Colors & font

Customize colors, font type and corners in _config.yml:

colors:
  links: "#007bff"                      # Color for links: use a readable color that contrasts well with dark text
  banner: "#007bff"                     # Background color for page banners: use color that contrasts well with white
  footer: "#6c757d"                     # Background color for footer: use color that contrasts well with white
font_serif: true                        # Font type for page content: serif (default) or slightly smaller sans-serif
rounded_corners: true                   # Enable (default) rounded corners on boxes and buttons

Logo & favicon

Add a logo by uploading it to assets/ and referencing it in _config.yml:

logo: /assets/images/logo.png  # Logo in navbar, will be displayed with 30px height

Add a favicon by adding a favicon.ico file to the root of your repository.

Add social icons to the footer by adding your (project’s) social profiles in _config.yml:

email: your.email@example.com
twitter_username: your_twitter_username
github_username: your_github_username

Create a _data/footer.yml file to further customize your footer with text, links and/or a disclaimer.

Testing your site locally

All the above settings can be directly made in your GitHub repository in your browser, but especially during setup it is more convenient to make those changes locally, render your website locally and then push your changes to GitHub.

Clone your repository to your computer.
Place a Gemfile in your repository root, with the content:
```
 gem "github-pages", group: :jekyll_plugins
```

Place a .gitignore in your repository root, with the content:

 # Jekyll
 _site/
 .sass-cache/
 .jekyll-cache/
 .jekyll-metadata

Install Jekyll. Skip the step to make a new site.
Serve your site with bundle exec jekyll serve.
Make changes and see the effect at http://localhost:4000/.
Push your changes to GitHub.

On this page