harms-columns-front-page

This Jekyll theme was developed as part of a bachelor thesis.

Jekyll is a static site generator based on ruby. For more information visit https://jekyllrb.com/.

How to install Jekyll

On Windows

This guide is based on this article by David Burela.

Step 1: Install the chocolatey package manager by following these instructions on their site.

Step 2: Install Ruby by running the following command in the command prompt:

choco install ruby -y

Make sure you install all 3 MSYS2 components when a new command prompt window opens with the Ruby Installer. When finished, you have to close and reopen your command prompt.

Step 3: Install Bundler by running:

gem install bundler

Step 4: And finally you can install Jekyll by running:

gem install jekyll

And now you're ready to go with Jekyll!

On Linux

This guide is based on Step 1 of this tutorial by Melissa Anderson. I have not yet tested it myself.

Step 1: Update your package list by running the following command in the terminal:

sudo apt-get update

Step 2: Install Ruby, make and gcc by running:

sudo apt-get install ruby ruby-dev make gcc

Step 3: Install Jekyll and Bundler by running:

sudo gem install jekyll bundler

And now you're ready to go with Jekyll!

On Mac

If you're using a Mac, then Ruby should already be installed on your machine.

Step 1: Run the following command to install Jekyll and Bundler:

gem install jekyll bundler

And that's it, you're ready to go with Jekyll!

How to create a Jekyll site

Step 1: Open your terminal and navigate into a directory where your Jekyll site should be stored.

Step 2: Run the following command in the terminal to create a new Jekyll project:

jekyll new project-name

Step 3: Enter the project directory by running:

cd project-name

Step 4: Run the following command to build your Jekyll site and preview it locally at http://localhost:4000.

bundle exec jekyll serve

The files for your website are located in the _site folder inside of your project folder.

How to install the theme

Step 1: Add this line to the bottom of your Jekyll site's Gemfile:

gem "harms-columns-front-page"

Step 2: Install the theme by running this in the terminal:

bundle

Step 3: In your Jekyll site's _config.yml, find the line that starts with theme: and replace it with this line:

theme: harms-columns-front-page

Step 4 (OPTIONAL): Then find the section that starts with gems: and add the following entries to the list:

gems:
  - jekyll-autoprefixer
  - jekyll-minifier

You do not have to add them to your _config.yml to use the theme. These dependencies are not required, but they are used to minify and autoprefix the site's code for cross browser compatibility and faster loading times of your site and therefore they make your site better.

Step 5: Run the following command in the terminal (note that this command can take a while to be finished if you've decided to follow Step 4):

bundle exec jekyll serve

Now you can head over to http://localhost:4000 in your browser and view the new theme on your jekyll site.

If you're getting an error message like ERROR: Current ExecJS runtime doesn't support ES5. Please install node.js. while trying to accomplish Step 5, you can try the following:

1. Close your terminal
2. Install node.js by downloading the installer here
3. Reopen your terminal
4. Navigate into your Jekyll project's directory
5. Then run bundle update

Now you should be able to try again and complete Step 5.

Updating

If you've already installed this theme for your Jekyll site and want to update to a newer version of the theme, you can simply execute the following command in the terminal. This will update not only the theme but all of your dependencies in your Jekyll project:

bundle update

Usage

Global options

The following options are available to use in your Jekyll site's _config.yml.

Site Title

Appears in the header and as the title of your browser window.

title: Your title here

Site Description

This is the meta description of your site.

description: Your site description here.

Profile/Logo Image

This image will appear as a little profile or logo image in your header.

profile-image: path/to/your/image/here.jpg

Site Language

Sets the language attribute of the html element of your site. This is important for search engines and browsers.

lang: en

Color of the header

You can customize the background color of the header. The color code can be provided as rgb, rgba or hex. When using hex, please make sure to wrap the color code in single quotes like this:

header-color: '#2FEB8D'

Color of the front page columns

You can customize the background color of the columns on the front page. The color code can be provided as rgb, rgba or hex. When using hex, please make sure to wrap the color code in single quotes like this:

columns-color: '#FFFFFF'

Color of the front page columns text

You can customize the text color of the site's front page columns. The color code can be provided as rgb, rgba or hex. When using hex, please make sure to wrap the color code in single quotes like this:

columns-text-color: '#282828'

Color of the site's h1

You can customize the color of the site's h1 heading. The color code can be provided as rgb, rgba or hex. When using hex, please make sure to wrap the color code in single quotes like this:

h1-color: '#282828'

Color of the site's subtitle

You can customize the color of the site's subtitle in the header. The color code can be provided as rgb, rgba or hex. When using hex, please make sure to wrap the color code in single quotes like this:

subtitle-color: '#FFFFFF'

Color of the site's h2

You can customize the color of the site's h2 heading. The color code can be provided as rgb, rgba or hex. When using hex, please make sure to wrap the color code in single quotes like this:

h2-color: '#2FEB8D'

Color of the site's h3

You can customize the color of the site's h3 heading. The color code can be provided as rgb, rgba or hex. When using hex, please make sure to wrap the color code in single quotes like this:

h3-color: '#282828'

Color of the site's text

You can customize the color of the site's plain text. The color code can be provided as rgb, rgba or hex. When using hex, please make sure to wrap the color code in single quotes like this:

text-color: '#282828'

Color of the site's links and buttons

You can customize the color of the site's links and buttons. The color code can be provided as rgb, rgba or hex. When using hex, please make sure to wrap the color code in single quotes like this:

link-color: '#12ADFF'

Color of the site's navigation links

You can customize the color of the site's navigation links when they are not active or hovered. The color code can be provided as rgb, rgba or hex. When using hex, please make sure to wrap the color code in single quotes like this:

nav-inactive-color: '#282828'

Color of the site's footer

You can customize the background-color of the site's footer. The color code can be provided as rgb, rgba or hex. When using hex, please make sure to wrap the color code in single quotes like this:

footer-color: '#EEEEEE'

Color of the site's footer text

You can customize the text color of the site's footer. The color code can be provided as rgb, rgba or hex. When using hex, please make sure to wrap the color code in single quotes like this:

footer-text-color: '#95989A'

Maximum width of the site

You can customize the maximum width that your site should fill (in pixels). Please provide a number WITHOUT the 'px' like so:

site-max-width: 1200

Header padding

You can affect the height of the site's header by changing the value for it's top and bottom padding (in pixels). If the padding is set to '0', it will only be as high as it's content. Please provide a number WITHOUT the 'px' like so:

header-padding: 80

Footer padding

You can affect the height of the site's footer by changing the value for it's top and bottom padding (in pixels). If the padding is set to '0', it will only be as high as it's content. Please provide a number WITHOUT the 'px' like so:

footer-padding: 100

Custom CSS

If the configuration options for the site's styles are not enough to meet your needs, you can add custom css to style certain elements exactly the way you want to. Provide your CSS like so:

custom-css: "
  body {
    background-color: #FFFFFF;
  }
"

Favicon

The favicon will appear as the icon alongside the title of your site in the browser window. Please use a png-file.

favicon: path/to/your/favicon/here.png

Subtitle

The subtitle will appear in your header under the site title.

subtitle: Your subtitle here

Social Links

The links to your social profiles will appear in the footer of your site. You have to specify a title and the link url. Optionally you can specify the path to an icon that should be used for the link instead of the title.:

social:
  - title: Link 1
    url: http://www.your-first-link-here.com
    icon: path/to/social/icon/1.jpg
  - title: Link 2
    url: http://www.your-second-link-here.com
    icon: path/to/social/icon/1.jpg

Footer Copyright Text

You can add your name to the copyright section in the footer.

footer-copyright: Year and name here

Font size of plain post and page text

You can change the font size of the paragraphs in posts and on pages.

text-font-size: 15px

Font size of the text inside of the home columns

You can change the font size of the paragraphs in the home columns on the front page.

columns-font-size: 15px

Line height of plain post and page text

You can change the line height of the paragraphs in posts and on pages.

text-line-height: 2

Line height of the text inside of the home columns

You can change the line height of the paragraphs in the home columns on the front page.

columns-line-height: 15px

Home columns

Here you can add content for the column section on the home page. You have to specify a heading and the content. The button url and the button label are optional: if the url is not set, there will be no button for that column on your site.

home-columns:
  - heading: Your heading 1 here
    content: Your content 1 here
    button-url: http://www.your-link-1-here.com
    button-label: Your button 1 text here

  - heading: Your heading 2 here
    content: Your content 2 here
    button-url: http://www.your-link-2-here.com
    button-label: Your button 1 text here

  - heading: Your heading 3 here
    content: Your content 3 here
    button-url: http://www.your-link-3-here.com
    button-label: Your button 1 text here

Read more button text

In lists of your posts there's just an excerpt being shown for every post. You have to specify the text for the button that takes you to the whole post, when clicking on it.

post-button-label: Read more

Page options

The following options are available to use in each of your Jekyll site's pages front matter.

Accordion for saving space

If you're having a page that contains large amounts of contents, you can save space by displaying them as an accordion. The sections of the accordion can be opened and closed. No configuration in the front matter is needed. Simply use this syntax in your page's markdown:

<div id="accordion" markdown="block">

### Section 1 heading
<div markdown="block">
Section 1 content
</div>

### Section 2 heading
<div markdown="block">
Section 2 content
</div>

### Section 3 heading
<div markdown="block">
Section 3 content
</div>

</div>

Layout

You can specify a layout for a page like this:

layout: layout-name-here

The available layouts are:

• home - for the front page
• page - for pages
• post - for posts
• not-found - for 404-error-pages (with automatic redirection to front page after 5 seconds)

Title

This specifies the title of your page, which will appear on top of the page (except for the front page) and in the title of your browser window behind your site title.

title: Your page title here

Permalink

This specifies the permalink of your page and therefore the url your page will be avaialable at (www.your-site-name.com/your-page-permalink-here)

permalink: /your-page-permalink-here/

Display the page in the navigation menu

With this variable you can specify if this page should appear in one of the navigation menus. If you don't specify this variable, the page won't be accessible over any navigation menu. To place a page in the main navigation located on top of the screen, use this line:

nav: main

To place a page in the navigation links down in the footer, use this line:

nav: footer

Order of the navigation menus

If you want to have your pages in a navigation menu in a specific order you can archieve this by assigning positions to every one of them.

nav-position: 1

Show post list on a page

If you want to display a list of posts beneath the main content of a page, you can do this by setting a variable with the category of posts you want to show. If the variable is not set, the page will not have blog posts on it.

show-category: News

Simultaneously you can specify a maximum number of posts to display. When this variable is not set, all posts of the category are displayed.

post-limit: 3

Filter posts by tag

If you're displaying a post list on a page and you want to give your site's visitors the ability to filter that list by different tags, you can do this by setting this variable. A list of buttons with the different tags to choose from will appear:

tag-filter: true

Simultaneously you should specify the text that should be used for the button that shows all posts again after filtering, like so:

show-all-filter-label: Show all posts

Post options

The following options are available to use in each of your Jekyll site's posts front matter.

Accordion for saving space

If you're having a post that contains large amounts of contents, you can save space by displaying them as an accordion. The sections of the accordion can be opened and closed. No configuration in the front matter is needed. Simply use this syntax in your post's markdown:

<div id="accordion" markdown="block">

### Section 1 heading
<div markdown="block">
Section 1 content
</div>

### Section 2 heading
<div markdown="block">
Section 2 content
</div>

### Section 3 heading
<div markdown="block">
Section 3 content
</div>

</div>

Featured image

You can specify a path to a featured image for a post. It will then be used as a preview image in lists in which the post appears.

featured-image: /assets/img/your-image.jpg

Post excerpt

When listed in a list of blog posts, a small preview of the content of your post is shown. You can choose how long this post excerpt is. The following front matter variable defines a string, which you can use in your blog post markdown to determine where a post excerpt of that post should end.

excerpt_separator: <!--more-->

Layout

You can specify a layout for a post like this:

layout: layout-name-here

The available layouts are:

• home - for the front page
• page - for pages
• post - for posts

Title

This specifies the title of your post, which will appear on top of the page (except for the front page) and in the title of your browser window behind your site title. Also it appears as the post title in post listings.

title: Your post title here

Publishing date

If a publishing date is set for your post, it will be displayed alongside the content.

publishing-date: 27.10.2016

Category

You can specify a category to which a post belongs. You can then display all posts of a blog-category on a page for example.

category: Events

Tags

You can specify tags for posts as something like subcategories. They can be used to filter posts of the same category in a post list. Please note that a tag can only consist of one single word.

tags: Tournament

One post can have multiple tags. Please specify them as a list like so:

tags:
  - Tournament
  - Football

Editing the content and publishing your site online

If you're having a server on the internet and want to publish or refresh your Jekyll site on there, follow these steps:

Updating page or post content

If you want to update the content of a page or a post, then follow these steps:

Step 1: Open your terminal and navigate into your Jekyll project's directory on your local machine.

Step 2: Run the following command:

bundle exec jekyll serve

Step 3: Now you can open the file in your Jekyll project that you want to make changes to with a code editor, edit it and save it. You can get information on how the markdown syntax in your pages and posts works here.

Step 4: Now you can preview your changes locally in your browser at http://localhost:4000. As you make modifications to your content, your site will regenerate and you should see the changes in the browser after a refresh.

Step 5: If you're satisfied with your changes, open your favorite FTP-software, connect to your webserver and upload every file inside of your Jekyll project's directory _site to the public directory of your webserver.

Step 6: Open your website on the internet in your browser and check if everything went as planned.

Updating global configuration options

If you want to update something in your Jekyll site's _config.yml, you have to follow these steps:

Step 1: Edit the file with a code editor.

Step 2: Run the following command in the terminal:

bundle exec jekyll serve

Everytime you make changes to the _config.yml you have to stop the server (cmd + C on mac, CTRL + C on windows) and rebuild your site and restart the server by running the command from Step 2 again. Then you can preview your site locally in your browser at http://localhost:4000.

Step 3: If you're satisfied with your changes, open your favorite FTP-software, connect to your webserver and upload every file inside of your Jekyll project's directory _site to the public directory of your webserver.

Step 4: Open your website on the internet in your browser and check if everything went as planned.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/michael-harms/harms-columns-front-page.

Development

Overriding

If you just want to change some of the theme's default layouts, scripts, styles etc. for your own Jekyll project, you can just override them in your project directory. You can get more information on this here in the official Jekyll docs.

Develop your own version

If you want to use my theme as a starting point for your own theme devlopement, you can do this by accomplishing the following steps:

Step 1: Open the terminal and navigate into the directory where you want your theme to be stored.

Step 2: Create a new Jekyll theme, by running the following command in the terminal:

jekyll new-theme your-theme-name-here

Step 3: Enter the theme directory in the terminal by running:

cd your-theme-name-here

Step 3: Download my theme's files from https://github.com/michael-harms/harms-columns-front-page and copy them into the directory of the Jekyll theme that you've just created, overriding everything that already exists in the directory.

Step 4: Delete your theme's .gemspec, rename my harms-columns-front-page.gemspec-file to your-theme-name-here.gemspec and update it's contents.

Step 5: Develop your theme

Your theme is setup just like a normal Jekyll site! To test your theme, run bundle exec jekyll serve and open your browser at http://localhost:4000. This starts a Jekyll server using your theme. Add pages, a _config.yml, etc. like in a Jekyll project to test your theme's contents. As you make modifications to your theme and to your content, your site will regenerate and you should see the changes in the browser after a refresh, just like normal.

When your theme is released, only the files tracked with Git will be released.

Step 6: Publish your new theme

After you've finished developing your theme, update your .gemspec and README.md accordingly and then follow these instructions in the official Jekyll docs to publish your theme as a Ruby gem.

License

The theme is available as open source under the terms of the MIT License.