Preface
Goal: What Jekyll can do in this article series
Repositories
This tutorial consist of two stage, but in three parts. The second stage is a choice between Bulma and Bootstrap.
-
Stage 1: Jekyll Plain
- Layout, Content, Managing Code, Feature: Pagination, Plugin, Theme.
-
Stage 2: Jekyll + Bootstrap
- CSS, SASS, Layout, Widget, Pagination, Blog Post, Content.
-
Stage 2: Jekyll + Bulma
- CSS, SASS, Layout, Widget, Pagination, Blog Post, Content.
Table of Content
-
Preface: Table of Content
-
1: Jekyll in General
-
Jekyll Plain
-
2: Jekyll Layout
-
3: Jekyll Content
-
4: Managing Code
-
5: Feature: Pagination
-
6: Ruby Plugins
-
7: Theme Bundling
-
-
Jekyll with Bootstrap or Bulma
-
8: Apply CSS
-
9: Apply SASS
-
10: Layout
-
11: Widget
-
12: Pagination
-
13: Blog Post
-
14: Content
-
-
15: Deploy
-
Conclusion
1: Jekyll in General
Topics Covered
-
Foreword
-
Install
-
Deploy
Why Jekyll?
But why?
- This is just an example project. Most you can do with one SSG can be done with other SSG as well.
- You are free to use your SSG choice: Jekyl, Hugo, Eleventy, 11ty, Pelican, Gatsby.
- Here is the Concept SSG Presentation.
Any Expectation?
- Case can be applied somewhere else. Most stuff applied in other SSG. Just don’t be a fanatic.
- An example case for beginner. Just another humble example.
- Starting point for a serious writer. After all, making a blog site is easy and fun.
Theme Making Cycle
Making theme consist of these steps:
-
Start From the Layout
- Preparing layout with templating engine.
-
Custom Pages:
- Liquid loop for custom pages and layout.
-
Adding Stylesheet:
- Give wearable clothes to above loop, for nice looks.
-
Additional Feature:
- Such as static data, widget and pagination.
-
Page Content:
- Meta SEO, TOC, markdown, shortcode, syntax highlighting, stylesheet adjustment, MathJax.
Theming Skill
Adjustment is a reccuring issue that arise regularly.
Even when you are using a ready to use theme, you might still need customization to suit your needs.
Install Jekyll
-
Default Package from distro:
- Easy for beginner.
-
Bundle:
- Bundle can handle multiple Jekyll installment.
-
RVM:
- RVM can handle multiple Ruby installment.
Article: Jekyll - Install using RVM
Simple Deployment
-
Git skill is a must.
-
Multiple configuration:
- Such as using
_config_dev.yml.
- Such as using
Article: Jekyll - Deploy - Simple
CI/CD Deployment
Flexible for intermediate user:
-
Github Actions
-
Gitlab CI
-
Netlify
-
Vercel (Zeit Now)
-
Travis
-
CircleCI
-
Manual
Article: Jekyll - Deploy - CI/CD
2: Jekyll Layout
Topics Covered
-
Plain Tutor 01: Minimal Layout
-
Plain Tutor 02: Partial Layout
-
Plain Tutor 03: Custom Pages
-
Plain Tutor 03: Custom Output
Minimal Layout
The easiest thing to do this is to make a minimal layout, and modified later.
Article: Jekyll Plain - Minimal
Partial Layout
Just a bit of refactoring.
With a very humble result as figure below
Article: Jekyll Plain - Layout
Custom Pages
With Jekyll layout, you can add custom pages, such as: archives, tags, categories, blog list.
Article: Jekyll Plain - Custom Pages
Custom Output
Jekyll can generate custom output, without adding any plugin.
Article: Jekyll Plain - Custom Output
3: Jekyll Content
Topics Covered
-
Plain Tutor 04: Markdown
-
Plain Tutor 04: Shortcode
-
Plain Tutor 05: Custom Code: Meta SEO
Markdown
Markdown is simply, just a text format.
Which will be processed to markup.
Article: Jekyll Plain - Markdown
Shortcode
We can utilize shortcodes like code in Jekyll. To provide link, or to provide image.
Which will also be processed to HTML.
This shortcode is just an include statement.
Custom Code: Meta SEO
Opengraph is a must nowadays.
Article: Jekyll Plain - Meta SEO
4: Managing Code
Topics Covered
-
Plain Tutor 04: Part One
- Liquid Code Placement, Layout Enhancement.
-
Plain Tutor 04: Part Two
- Category and Tag, Archive by Year, then by Month.
-
Plain Tutor 05: Part Three
- Clean up pages from code, prepare theme for use in Gemfile.
Liquid Code Placement
So far we have three places to put liquid code:
-
pagesas content, or -
_layouts, or -
_includes.
Guidance:
- Avoid liquid codes in
pagesexcept for content such as shortcodes. - Logic and reusable should be moved to
_includes. - HTML layout view to parent template in
_layouts. - Child template in
_layoutscontain only frontmatter and include calls.
Layout Enhancement
More Layout based on Default
Template Inheritance: Page
First, you need to understand template inheritance.
With the result as below figure
Template Inheritance: Blog List
And apply this to other layout kind.
With the result as below figure
Template Inheritance: Tags Tree
Go further
With the result as below figure
Template Inheritance: Archive By Month
And go further again:
With the result as below figure
5: Feature: Pagination
Topics Covered
-
Plain Tutor 05: Intro
-
Plain Tutor 05: Simple
-
Plain Tutor 05: Number
-
Plain Tutor 05: Adjacent
-
Plain Tutor 05: Indicator
Intro
Example Pagination URL
-
Page 1: http://localhost:4000/pages/
-
Page 2: http://localhost:4000/pages/blog-2/
-
Page 3: http://localhost:4000/pages/blog-3/
-
And so on.
Article: Jekyll Plain - Pagination - Intro
Simple
Article: Jekyll Plain - Pagination - Simple
Number
Article: Jekyll Plain - Pagination - Number
Adjacent
Prepare pagination with indicator, by only showing what necessary, and hide the rest.
Article: Jekyll Plain - Pagination - Adjacent
Offset calculation require logic, and math.
Article: Jekyll Plain - Pagination - Logic
Indicator
And the result is as figure below:
6: Ruby Plugins
-
Plain Tutor 06: Simple
-
Plain Tutor 06: Pagination
-
Plain Tutor 06: Tag Names
Simple
Liquid limitation make code complex.
This can be simplified by plugin.
Article: Jekyll Plain - Plugin - Simple
Pagination
Simplified Adjacent Calculation with Ruby Plugin.
Dramatically reduce liquid code.
And also avoid buggy code.
Article: Jekyll Plain - Plugin - Pagination
Tag Names
Extending official examples, now each tag name URLs can show list of post.
Article: Jekyll Plain - Plugin - Tag Names
7: Theme Bundling
-
Plain Tutor 07: Build Gemfile
-
Plain Tutor 07: Using Gemfile
Build Gemfile
Bundling theme with Gemspec, for use with other people.
Article: Jekyll Plain - Theme Bundling
Using Theme in Gemfile
8: Apply CSS
Mobile First Page Design
Adding Assets
You can add any necessary assets such as: images, css frameworks, and javascript frameworks.
Using CSS Frameworks
Using CSS framework such as Bulma or Bootstrap or Custom, can make your life easier.
Article: Jekyll - Bootstrap - CSS - Part One
Article: Jekyll - Bulma - CSS - Part One
Parent and Child Layouts
Both are using Bootstrap now.
All Layouts
Article: Jekyll - Bootstrap - CSS - Part Two
Article: Jekyll - Bulma - CSS - Part Two
9: Apply SASS
Using Custom SASS
-
You desire for a better design
- Further, you can utilize stylesheet to control your responsive space, or custom component
-
Long code tends to get messy.
- You need to get organized.
Enhance theme looks: Small thing, might have great impact.
Article: Jekyll - Bootstrap - SASS - Part One
Article: Jekyll - Bulma - SASS - Part One
Adding SASS Assets
Jekyll utilize SASS/SCSS as default CSS preprocessor.
Import SASS from any directory.
Apply to All Layouts
Again, we can apply to other layouts as well.
Article: Jekyll - Bootstrap - SASS - Part Two
10: Layout
Variables
Managing Default Color Between Layout.
Color property propagate, from pages frontmatter to child layout to parent layout.
Article: Jekyll - Bulma - Layout - Variables
Responsive Content
Mobile First Content Design
Mobile First Index Columns
Article: Jekyll - Bulma - Layout - Index List
11: Widget
Template
Prepare the default looks.
Simple
Start from simple, such as plain HTML list.
Liquid Loop
You can also put anything in your widget as creative as you are.
Static Data
To generate content, such as backlink, internal link, or other stuff.
Now consider link the data, from this content below.
With previous frontmatter, we can see one or more links in a widget.
12: Pagination
Bootstrap Stylesheet
Using Liquid and Bootstrap stylesheet, a common pagination could be achieved.
Bootstrap Responsive
Using Liquid and custom stylesheet, a responsive pagination also could be achieved.
Or alternatively
Bulma Stylesheet
Using Liquid and Bulma stylesheet, a common pagination could be achieved.
Or alternatively
Bulma Responsive
Again, using Liquid and custom stylesheet, a responsive pagination also could be achieved.
13: Blog Post
Parent Layout
Your generic columns-double.html
should contain header, and optionally footer.
Child Layout
May contain additional stuff such as: table of content, navigation, and maybe license.
Preview
A typical post can be seen in preview below.
Article: Jekyll - Bulma - Content - Blog Post
Additional
You can add any stuff such as Table of Content.
14: Content
Markdown
The same as previous plain tutorial.
Shortcode
The same as previous plain tutorial.
Syntax Highlighting
This require additional stylesheets.
Article: Jekyll - Bootstrap - Content
Article: Jekyll - Bulma - Content
Miscellanous: MathJax
15: Deploy!
To Github or Gitlab or Bitbucket or Netlify or else.
Article: CI/CD - Deploy Overview
Conclusion
There in nothing more after summary, except this presentation slide.
Consider continue watching [ Eleventy - Presentation Slide ].
Thank you for reading.