-
Notifications
You must be signed in to change notification settings - Fork 1
Advanced Static Website Generation
Advanced workshop video recording: link
If you don't like to work with the theme we provide, but rather completely start from scratch, then we'll try to guide and help you as good as possible.
The Jekyll docs provide a solid basis to get started, and the majority of this guide will redirect to their website.
You don't need to go over everything in this guide, however at some point you'll most likely have to use or understand it (you can then always look back to the documentation on how to do it).
Recommendations for this advanced workshop:
- Pre-requisites / Requirements
- Install Jekyll
- Site Structure
- Variables
- Partial-Templating
- Permalinks
- Layouts
- Content
- Pages
- Posts
- Data files (and/or collections)
- Static Files (images)
Additional Recommendations when wanting to create your own theme:
- Theme
- Gem-based Theme (if you want to create and release your own theme to the web).
- Assets
Jekyll has some pre-requisites, so please check the JJekyll Requirements Page and click on the Guide for your operating system (MacOS, Ubuntu, Windows or "Other Linux"), and go through those steps.
During the "Requirements" phase, you should have finished by installing the jekyll bundler, and running jekyll -v, if this command gave you a version output, then you are ready to go and follow the Quickstart Guide.
If you did not get any output or something similar to `Jekyll could not be found` then restart your terminal (and potentially even restart your pc).
At this point you should be able to access your local website on localhost:4000 or incremented by 1 if 4000 is already taken.
Additionally you could use the --livereload option when doing jekyll serve such that jekyll serve --livereload, which would live reload the browser when you make changes to your code.
The default theme that Jekyll currently provides and installs is the minima theme.
For our convenience, we'll overwrite the theme defaults, so we can create our own styling.
Follow Overriding theme defaults or Converting gem-based themes to regular themes from the Themes page in the documentation.
If you still want to keep the minima theme installed but overwrite its styling, then use the first guide, however if you want to not be on the gem-based themes and thus completely change the theme manually, use the second guide.
It is also possible to create your own gem-based theme, which is explained in Creating a gem-based theme, you can look at our Jekyll Bootstrap Resume to give you an indication on how to structure it and how to test it. If you created a gem-based theme, then you might also want to publish it for everybody else to use as a theme. Follow Publishing your theme to publish it on rubygem as a gem-based theme.
We recommend to check out Directory Structure to get an understanding of the structure in which Jekyll expects the structure. (You are however, free to structure it differently).
Jekyll uses the Liquid Templating language, if you are interested into learning more about this you can checkout Liquid.
Jekyll supports global, site and page variables. To get a better understanding on how to use them or create custom variables check out Variables.
Jekyll supports Partial Templating, this means that you can split up your template and seperate them into multiple files. This makes you able to recycle code-portions while following DRY-type of principles. e.g decoupling your head (title, meta data, styling) such that you can re-use it in different layouts while only having to code it once.
Information about partial templating can be find in Includes.
Permalinks are the output paths for your pages, posts or collections. They allow to structure your URL, and having easy and understandable URL structures can be very important (especially when dynamic).
Check out Permalinks to learn more about this.
When working with blogs, collections or data files you might want to have some pagination, to avoid your website being immensely long, and limiting the amount of results you get to see per page.
Checkout Pagination on how to add this.
You probably want to have some uniform layouts, that pages or posts would adhere to (so that you only write the code once, and then use use and append your content in there when needed).
Information can be found in Layouts.
The creation of pages can be found in Pages, which works using either markdown (md) and html.
For Pages it's recommended to use markdown as it's easier to maintain and understand.
The creation of posts can be found in Posts, in which you can also use tags and categories in your blog posts. (such that you can filter) This is explained in Tags and Categories.
You are also able to make draft posts.
Prepend your markdown files with some Front matter heading, which gives meta data to the Jekyll compiler such as the layout file that should be used (Creation of layout files is explained later), the page/post title, and more. More information about the Front Matter can be found on the Front matter page.
This would look something like this: about.md:
---
layout: post
title: Blogging Like a Hacker
---
YOUR CONTENT HERECollections are generally used to group related content, think about members of a team.
More information about collections can be found in Collections.
Data files are YAML, JSON, CSV or TSV files, which contain structured data which you can read in through Jekyll and use on your website. The use of data files can be read in Data files.
The main difference between Collections and Data Files is that Collections are not done through data files, but rather using markdown files.
This means that data files are easier to manage but are less flexible and must adhere to a structure. Where as Collections has some flexibility, but you'd have to register each new collection file you created.
Tip: Look at the workshop repository on how you could use data files. (We decided on data file structures instead of collections due to making it look more uniform throughout the whole website.
Information on Things like styling, images, fonts and javascript you can check Assets and Static Files.
Jekyll has a plugin system, so you are able to add plugins or make your own plugins. We won't go into this in great detail, but information on plugins can be found in Plugins.
If you already have a website, but think Jekyll could be easier and better, than you can easily migrate your posts from your website to Jekyll.
Check the Jekyll Importer page if your current platform is supported (A lot of major platforms such as Wordpress is already supported).
There are a couple of ways to deploy your website, manually, automatically (CI/CD) or using a third-party. Check out Deployment.