A free and open-source Jekyll theme. Based on Rohan Chandra type-theme packed with extra features and easily customizable:
- Responsive design on all devices (π₯, π», π±, ...)
- Portfolio π, Gallery πΌ pages for your projects
- Multi comments π¬ options
- Tags compatibility π·
- Handle Bootstrap'ed pages: Get Bootstrap
- π Search feature: Simple-Jekyll-Search
- Math Rendering : KateX
- Diagram Rendering: Mermaid-js
- π Nice fonts: Font Awesome, Source Sans Pro, Pacifico
- Seo Tags: Jekyll-seo-tag
- π Syntax Highlighting: Easily customisable Base16
- π‘ Light and dark theme supported
- Find free of rights images on pexels
- Fork and clone the Type on Strap repo:
git clone https://github.com/Sylhare/Type-on-Strap.git
- Install Jekyll:
gem install jekyll
, check #1 if you have a problem. - Install the theme's dependencies:
bundle install
- Customize the theme
- GitHub Page: update
_config.yml
- GitHub Page: update
- Run the Jekyll server:
bundle exec jekyll serve
Check out this tutorial: Use as Ruby Gem
Here are the main files of the template
./Type-on-Strap
βββ _includes # Theme includes
βββ _layouts # Theme layouts (see below for details)
βββ _portfolio # Collection of articles for the portfolio page
βββ _posts # Blog posts
βββ _sass # Sass partials (compiled into css at runtime)
βββ assets
| βββ js # JS compiled for distribution + raw sources
| βββ css # CSS compiled for distribution
| βββ fonts # Font-Awesome, and other fonts
| βββ img # Images used for the template
βββ pages
| βββ 404.md # To be displayed when url is wrong
| βββ about.md # About example page
| βββ gallery.md # Gallery page for your photos
| βββ portfolio.md # Portfolio page for your projects
| βββ search.md # Search page
| βββ tags.md # The tag page
βββ _config.yml # sample configuration
βββ _data
| βββ authors.yml # Update the post authors configurations
| βββ language.yml # Localization configuration
| βββ biblio.yml # To create a reference bibliography
| βββ social.yml # Social configurations to share posts (RSS, shares, ...)
| βββ icons.yml # Footer icons (Twitter, Github, Stackoverflow, ...)
βββ index.html # sample home page (blog page paginated)
Open _config.yml
in a text editor to change most of the blog's settings.
If a variable in this document is marked as "optional", disable the feature by removing all text from the variable.
Configure Jekyll as your own blog or with a "baseurl" in _config.yml
:
Jekyll website without a "baseurl" (such as a GitHub Pages website with your username as the repository name):
baseurl: ""
url: "https://username.github.io"
Jekyll website with "baseurl" (like the Type on Strap demo page):
baseurl: "/sub-directory"
url: "https://username.github.io"
And here is the basic information you will need in your _config.yml
for it to work properly:
# BLOG CONFIGURATION
post_navigation: true
paginate: 10
paginate_path: "blog/page:num"
plugins: [jekyll-paginate, jekyll-seo-tag, jekyll-feed]
To configure the blog part and default plugins. Those plugins are validated by GitHub page.
Meta variables hold basic information about your Jekyll site, which will be used throughout the site and as meta properties that are used for search engines, browsers, and the site's RSS feed.
Change these variables in _config.yml
:
title: My Jekyll Blog # Name of website
avatar: assets/img/avatar.png # Path of avatar image, to be displayed in the theme's header
description: My blog posts # Short description, primarily used by search engines
favicon: assets/favicon.ico # Icon displayed in the tab
color_theme: auto # color theme auto, dark or light
You can also customize the seo tags default option following the jekyll-seo-tag plugin documentation. The color theme can be set to dark or light (customize it in variables.scss). Using auto you'll have a tiny icon in the navbar allowing the use to manually switch from dark to light theme.
Customize your site header/footer with these variables in _config.yml
:
header_text: Welcome to my Jekyll blog
footer_text: Copyright 2017
If you don't want anything, replace the value by " "
.
The header's image (tested with 2480x1280) can be set as one image with header_feature_image
but can also be responsive:
header_feature_image: assets/img/header/my-header-image.png
header_feature_image_responsive: true
By setting header_feature_image_responsive
to true, it will look for images
with suffix -small
(620x320) and -medium
(1240x640) to display on smaller screen.
Localization string is a way to quickly change the template language for text like Next Post or Follow on, ...
You can find all the properties in _data/language.yml
.
By default, it is in English, but you can add your own language.
Here you also can set the date format, e.g., set str_date_format: '%B %-d, %Y'
for "January, 13, 2024",
str_date_format: '%Y-%m-%d'
for 2024-01-13, or str_date_format: '%d.%m.%Y'
for 13.01.2024.
To enable Google Analytics (GA4), add your Measurement ID
to _config.yml
like so:
google_analytics: G-XXXXXXXXXX
It will use the Google Tag Manager
If you have a Disqus account, you can show a comments section below each post.
To enable Disqus comments, add your Disqus shortname
to your project's _config.yml
file:
comments:
disqus_shortname: my_disqus_shortname
Cusdis is an open-source alternative to Disqus. You can read more about it in the documentation
To enable it, set your Cusdis name in _config.yml
:
comments:
cusdis_app_id: my_data-app-id
Utterances is another open source alternative linked to one's GitHub account. It stores the comments as GitHub issues on a repository for each page.
Install the utterance app to your repo.
After installing, add your info in the _config.yml
:
comments:
utterances: # Enable by filling below information. For more info, go to https://utteranc.es
repo: # your public comments repository (e.g. owner/repo)
issue-term: # Issue term (e.g. "comment" consider issues with this word in the title as comments)
theme: # OPTIONAL: Take the `color_theme` by default, or set a custom one like github-dark-orange
label: # OPTIONAL: Adds an issue label in the issue
When KateX is set in _config.yml
:
katex: true # to enable it
You can then wrap math expressions with $$
signs in your posts and make sure you have set the katex
variable
in _config.yml
to true
for math typesetting.
For inline math typesetting, type your math expression on the same line as your content. For example:
Type math within a sentence $$2x^2 + x + c$$ to display inline
For display math typesetting, type your math expression on a new line. For example:
$$
\bar{y} = {1 \over n} \sum_{i = 1}^{n}y_i
$$
You can find a cheat sheet of the compatible LaTex symbols online.
Enable the mermaid-js diagram rendering by setting mermaid to true in the _config.yml
.
This will load and init the mermaid.min.js.
mermaid: default # Enable mermaid-js for diagrams, use theme: base, forest, dark, default, neutral
Find all the help you need on the official mermaid documentation.
Use mermaid
as color highlighter language to render the diagram or with the class="mermaid"
inside the <div>
:
```mermaid
sequenceDiagram
Alice->>John: Hello John, how are you?
John-->>Alice: Great!
In _data/social.yml
you can customize the social icons that will be displayed in the post to share your post.
You can also enable RSS.
The site icons come from Font Awesome.
In _data/icons.yml
you can set the footer icon that will appear at the bottom of the page.
They will redirect the user on your profile on to other platforms like Twitter, GitHub and so many more!
You can add a cookie consent with a disclaimer if you use Google Analytics while respecting the GDPR. Set to true, there will be a banner at the bottom of the page with the disclaimer, and an approve button. Once the user clicks on "Approve" the cookies will be created for Google Analytics.
The share icons are the one at the bottom of the blog page if enabled. They will on click redirect you to the logo's platform to share the article.
Display icons in the footer.
All icon variables should be your username enclosed in quotes (e.g. "username") in _data/icons.yml
.
You can update the RSS settings in _data/social
to change the default feed path (generated by jekyll-feel).
To enable the share icons at the bottom of each article,
set to true the one you'd like under share
in the _data/social.yml
file.
When writing a post, be sure in jekyll to:
- Put it in the
_posts
folder - Name it with the date first like
2019-08-21-This-is-my-blog-post.md
Please refer to the Jekyll docs for writing posts.
These are the basic features you can use with the post
layout, in the comment the Opt
means that
it is optional.
---
layout: post
title: Hello World # Title of the page
hide_title: true # [Opt] Hide the title when displaying the post, but shown in lists of posts
feature-img: "assets/img/sample.png" # [Opt] Add a feature-image to the post
thumbnail: "assets/img/thumbnails/sample-th.png" # [Opt] Add a thumbnail image on blog view
color: rgb(80,140,22) # [Opt] Add the specified color as feature image and links in post
position: 1 # [Opt] Set position on the menu navigation bar
tags: [sample, markdown, html] # [Opt] Add tags to the page
---
With thumbnail
, you can add a smaller image than the feature-img
.
If you don't have a thumbnail, you can still use the same image as the feature one. Or use the gulp task to create it.
If you don't use a feature image, but color
, the transparent background is set comes from lineart.png
.
You can edit it in the config file (_config.yml > color_image
). If you want another one, put it in /assets/img
as well.
For position, if not set on all pages, it will be by alphabetical order without position
then by position
order.
If two pages have the same position number, the order is decided by alphabetical order on the page title.
There's also bootstrap: true
which is not mandatory and only useful if you want to add HTML content in your page that
requires bootstrap.
It will respect the page and theme layout, mind the padding on the sides.
The excerpt is the head of the article rendered in the blog page.
The length of the excerpt has a default of around 250
characters or can be manually set in the post using:
in conflig.yml
:
excerpt: true
Then in your post, add the excerpt separator
:
---
layout: post
title: Sample Page
excerpt_separator: <!--more-->
---
some text in the excerpt
<!--more-->
... rest of the text not shown in the excerpt ...
The html is stripped out of the excerpt, so it only displays text.
To easily add align images side by side in your article using the aligner.html
include:
{% include aligner.html
images="path/to/img1.png,path/to/img2.png,path/to/img3.png"
column=3
caption="some description"
%}
Use it in any markdown file. There are two fields in the include you need to look into:
- images: Takes a string separated with
,
of all the images' path.- It by default look into
assets/img/
so give the path from there.
- It by default look into
- column: (OPTIONAL) Set the number of column you want your imaged displayed in.
- default is 2 columns
column=3
set 3 columnscolumn="auto"
makes as many columns as images
- caption: (OPTIONAL) Add a caption to the images
Like all CSS variables in the theme, you can edit the color of the code highlight in _sass > base > _variables.scss
.
The code highlighting works with base16 you can find existing example
of your favourite highlight color scheme on this format.
All feature pages besides the "home" one are stored in the page
folder,
they will appear in the navigation bar unless you set Hide: true
in the front matter.
Here are the documentation for the other feature pages that can be added through _config.yml
.
Non-standard features are documented below.
This layout includes the head, navigation bar and footer around your content. Unless you are making a custom layout you won't need it.
This page is used as the home page of the template (in the index.html
). It displays the list of articles in _posts
.
You can use this layout in another page (adding a title to it will make it appear in the navigation bar).
The recommended width and height for the home picture is width:2484px;
and height:1280px
which are the dimensions of the actual picture for it to be rolling down as you scroll the page.
If your posts are not displaying ensure that you have added the line paginate: 5
to _config.yml
.
The page layout has a bit more features explained here.
---
layout: page
title: "About"
subtitle: "This is a subtitle"
feature-img: "assets/img/sample.png"
permalink: /about/ # Set a permalink your your page
hide: true # Prevent the page title to appear in the navbar
icon: "fa-search" # Will Display only the fontawesome icon (here: fa-search) and not the title
tags: [sample, markdown, html]
---
The hide only hides your page from the navigation bar, it is, however, still generated and can be accessed through its link.
Portfolio is a feature page that will take all the markdown/html files in the _portfolio
folder to create a 3-columns image portfolio matrix.
To use the portfolio, simply create a portfolio.md
with this information inside:
---
layout: page
title : Portfolio
---
{% include default/portfolio.html %}
You can format the portfolio posts in the _portfolio
folder using the post layout
.
Here is a little explanation on some of the possible features you can use.
If you decide to use a date, please be sure to use one that can be parsed such as yyyy-mm-dd
.
You can see more format examples in the demo posts that are available for the theme:
---
layout: post
title: Circus # Title of the portfolio post
feature-img: "assets/img/portfolio/cake.png" # Will display the image in the post
img: "assets/img/portfolio/cake.png" # Will display the image in the portfolio page
date: 2019-07-25 # Not mandatory, however needs to be in date format to display the date
---
Make sure your _config.yml
contains the following if you are using the theme as a gem:
# PORTFOLIO
collections:
portfolio:
output: true
permalink: /:collection/:name
This creates the collection for Jekyll, so it can find and display your portfolio posts.
You can create a gallery using Masonry JS which will placing the pictures at the optimal position
based on available vertical space.
You need to specify the gallery_path
which will be used to find the pictures to render.
It will take all the pictures under that directory. Then use the include
to add it in your page.
---
layout: page
title: Gallery
gallery: "assets/img/pexels"
---
{% include default/gallery.html gallery_path=page.gallery %}
The search feature is based on Simple-Jekyll-search
there is a search.liquid
file that will create a list of all the site posts, pages and portfolios.
Then there's a script displaying the formatted results in the search page.
To exclude contents from the search add the exclude: true
option in the markdown header.
By default, all posts, pages, and collections are available in the search.
Hide the search page from the navigation bar with the hide: true
option.
You can remove the icon by removing icon
:
---
layout: search
title: Search
icon: "search"
---
Tags should be placed between []
in your post metadata. Separate each tag with a comma.
Tags are recommended for posts and portfolio items.
For example:
---
layout: post
title: Markdown and HTML
tags: [sample, markdown, html]
---
Tags are case-sensitive
Tag_nAme
βtag_name
All the tags will be listed on the "tags" page with a link toward the pages or posts.
The Tag page can be hidden with the hide
option. You can remove the icon by removing icon
(like for the search page).
Jekyll works with liquid tags usually represented by:
{{ liquid.tag | filter }}
These are useful to render your jekyll files. You can learn more about them on shopify's doc
Before you need to have node and npm
installed:
- Windows: https://nodejs.org/
- Ubuntu/Debian:
apt-get install nodejs npm libgl1 libxi6
- Fedora (dnf) / RHEL/CentOS (yum):
dnf install node npm libglvnd-glx libXi
Then you need to install gulp-cli
and its dependencies:
cd assets/
sudo npm install gulp-cli -g
npm install
You can run the default task that will compress the js, css and images and create the thumbnails for the supported image formats:
cd assets/
gulp default
gulp thumbnails-all # to create all of the images thumbnails
gulp thumbnails # to create thumbnails for the feature-img/ only
# tip: run a git status to see the changes
git status
You can find more about the gulp tasks in the gulpfile.js.
To create a .md
file in the _posts/ section with the jekyll format of today's date.
Use this command with the title you'd like to create the very basic post.
gulp post -n 'title of the post'
A file will be created following the format yyyy-mm-dd-title-of-the-post.md
with default post attributes inside.
Nothing will happen if the file exists already.
You can use Type-on-strap as a gem.
Using the Ruby Gem Method. Add this line to your Jekyll site's Gemfile (or create one):
gem "type-on-strap"
Add this line to your Jekyll site's _config.yml
file:
theme: type-on-strap
Then run Bundler to install the theme gem and dependencies:
bundle install
Then you can start adding content like:
- Add a
index.html
file - Add the feature page you want. (ex: as it is already in
pages
) - Add posts in
_posts
and_portfolio
to be displayed
Now you can use any theme gem with GitHub pages with 29/11/2017 GitHub Pages Broadcast.
For that remove all theme:
attributes from _config.yml
and add instead:
remote_theme: sylhare/Type-on-Strap
This theme is licensed under the MIT License (MIT)
- Pictures from Pexels are under Creative Commons Zero (CC0) license
- Fonts are licensed under the SIL Open Font License (OFL)