MoAlaa How to Jekyll!

12 minute read

A variety of common markup showing how the theme styles them.

Header two

Header three

Header four

Header five

Header six

Blockquotes

Single line blockquote:

Stay hungry. Stay foolish.

Multi line blockquote with a cite reference:

People think focus means saying yes to the thing you’ve got to focus on. But that’s not what it means at all. It means saying no to the hundred other good ideas that there are. You have to pick carefully. I’m actually as proud of the things we haven’t done as the things I have done. Innovation is saying no to 1,000 things.

Steve Jobs — Apple Worldwide Developers’ Conference, 1997

Tables

Employee	Salary
John Doe	$1	Because that’s all Steve Jobs needed for a salary.
Jane Doe	$100K	For all the blogging she does.
Fred Bloggs	$100M	Pictures are worth a thousand words, right? So Jane × 1,000.
Jane Bloggs	$100B	With hair like that?! Enough said.

Header1	Header2	Header3
cell1	cell2	cell3
cell4	cell5	cell6
cell1	cell2	cell3
cell4	cell5	cell6
Foot1	Foot2	Foot3

Definition Lists

Definition List Title: Definition list division.
Startup: A startup company or startup is a company or temporary organization designed to search for a repeatable and scalable business model.
#dowork: Coined by Rob Dyrdek and his personal body guard Christopher “Big Black” Boykins, “Do Work” works as a self motivator, to motivating your friends.
Do It Live: I’ll let Bill O’Reilly explain this one.

Unordered Lists (Nested)

List item one
- List item one
  - List item one
  - List item two
  - List item three
  - List item four
- List item two
- List item three
- List item four
List item two
List item three
List item four

Ordered List (Nested)

List item one
1. List item one
  1. List item one
  2. List item two
  3. List item three
  4. List item four
2. List item two
3. List item three
4. List item four
List item two
List item three
List item four

Forms

Buttons

Make any link standout more when applying the .btn class.

<a href="#" class="btn--success">Success Button</a>

Default Button Primary Button Success Button Warning Button Danger Button Info Button Inverse Button Light Outline Button

[Default Button Text](#link){: .btn}
[Primary Button Text](#link){: .btn .btn--primary}
[Success Button Text](#link){: .btn .btn--success}
[Warning Button Text](#link){: .btn .btn--warning}
[Danger Button Text](#link){: .btn .btn--danger}
[Info Button Text](#link){: .btn .btn--info}
[Inverse Button](#link){: .btn .btn--inverse}
[Light Outline Button](#link){: .btn .btn--light-outline}

X-Large Button Large Button Default Button Small Button

[X-Large Button](#link){: .btn .btn--primary .btn--x-large}
[Large Button](#link){: .btn .btn--primary .btn--large}
[Default Button](#link){: .btn .btn--primary }
[Small Button](#link){: .btn .btn--primary .btn--small}

Notices

Watch out! This paragraph of text has been emphasized with the {: .notice} class.

Watch out! This paragraph of text has been emphasized with the {: .notice--primary} class.

Watch out! This paragraph of text has been emphasized with the {: .notice--info} class.

Watch out! This paragraph of text has been emphasized with the {: .notice--warning} class.

Watch out! This paragraph of text has been emphasized with the {: .notice--success} class.

Watch out! This paragraph of text has been emphasized with the {: .notice--danger} class.

HTML Tags

Address Tag

1 Infinite Loop
Cupertino, CA 95014
United States

Anchor Tag (aka. Link)

This is an example of a link.

Abbreviation Tag

The abbreviation CSS stands for “Cascading Style Sheets”.

Cite Tag

“Code is poetry.” —Automattic

Code Tag

You will learn later on in these tests that word-wrap: break-word; will be your best friend.

Strike Tag

This tag will let you ~~strikeout text~~.

Emphasize Tag

The emphasize tag should italicize text.

Insert Tag

This tag should denote inserted text.

Keyboard Tag

This scarcely known tag emulates keyboard text, which is usually styled like the <code> tag.

Preformatted Tag

This tag styles large blocks of code.

.post-title {
	margin: 0 0 5px;
	font-weight: bold;
	font-size: 38px;
	line-height: 1.2;
	and here's a line of some really, really, really, really long text, just to see how the PRE tag handles it and to find out how it overflows;
}

Quote Tag

Developers, developers, developers… –Steve Ballmer

Strong Tag

This tag shows bold text.

Subscript Tag

Getting our science styling on with H₂O, which should push the “2” down.

Superscript Tag

Still sticking with science and Albert Einstein’s E = MC², which should lift the 2 up.

Variable Tag

This allows you to denote variables.

You’ll find this post in your _posts directory. Go ahead and edit it and re-build the site to see your changes. You can rebuild the site in many different ways, but the most common way is to run jekyll serve, which launches a web server and auto-regenerates your site when a file is updated.

To add new posts, simply add a file in the _posts directory that follows the convention YYYY-MM-DD-name-of-post.ext and includes the necessary front matter. Take a look at the source for this post to get an idea about how it works.

Jekyll also offers powerful support for code snippets:

def print_hi(name)
  puts "Hi, #{name}"
end
print_hi('Tom')
#=> prints 'Hi, Tom' to STDOUT.

Check out the Jekyll docs for more info on how to get the most out of Jekyll. File all bugs/feature requests at Jekyll’s GitHub repo. If you have questions, you can ask them on Jekyll Talk.

And this is how a quote looks.

Only one thing is impossible for God: To find any sense in any copyright law on the planet.

Mark Twain

A notice displays information that explains nearby content. Often used to call attention to a particular detail.

When using Kramdown {: .notice} can be added after a sentence to assign the .notice to the <p></p> element.

Changes in Service: We just updated our privacy policy here to better service our customers. We recommend reviewing the changes.

Primary Notice: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer nec odio. Praesent libero. Sed cursus ante dapibus diam. Sed nisi. Nulla quis sem at nibh elementum imperdiet.

Info Notice: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer nec odio. Praesent libero. Sed cursus ante dapibus diam. Sed nisi. Nulla quis sem at nibh elementum imperdiet.

Warning Notice: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer nec odio. Praesent libero. Sed cursus ante dapibus diam. Sed nisi. Nulla quis sem at nibh elementum imperdiet.

Danger Notice: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer nec odio. Praesent libero. Sed cursus ante dapibus diam. Sed nisi. Nulla quis sem at nibh elementum imperdiet.

Success Notice: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer nec odio. Praesent libero. Sed cursus ante dapibus diam. Sed nisi. Nulla quis sem at nibh elementum imperdiet.

Want to wrap several paragraphs or other elements in a notice? Using Liquid to capture the content and then filter it with markdownify is a good way to go.

{% capture notice-2 %}
#### New Site Features

* You can now have cover images on blog pages
* Drafts will now auto-save while writing
{% endcapture %}

<div class="notice">{{ notice-2 | markdownify }}</div>

New Site Features

You can now have cover images on blog pages
Drafts will now auto-save while writing

Or you could skip the capture and stick with straight HTML.

<div class="notice">
  <h4>Message</h4>
  <p>A basic message.</p>
</div>

Message

A basic message.

Minimal Mistakes has been developed as a Gem-based theme for easier use, and 100% compatible with GitHub Pages when used as a remote theme.

If you enjoy this theme, please consider sponsoring me to continue developing and maintaining it.

Installing the theme

If you’re running Jekyll v3.7+ and self-hosting you can quickly install the theme as a Ruby gem.

ProTip: Be sure to remove /docs and /test if you forked Minimal Mistakes. These folders contain documentation and test pages for the theme and you probably don’t want them littering up your repo.

Note: The theme uses the jekyll-include-cache plugin which will need to be installed in your Gemfile and added to the plugins array of _config.yml. Otherwise you’ll throw Unknown tag 'include_cached' errors at build.

Gem-based method

With Gem-based themes, directories such as the assets, _layouts, _includes, and _sass are stored in the theme’s gem, hidden from your immediate view. This allows for easier installation and updating as you don’t have to manage any of the theme files.

To install as a Gem-based theme:

Add the following to your Gemfile:
```
gem "minimal-mistakes-jekyll"
```
Fetch and update bundled gems by running the following Bundler command:
```
bundle
```
Set the theme in your project’s Jekyll _config.yml file:
```
theme: minimal-mistakes-jekyll
```

To update the theme run bundle update.

Remote theme method

Remote themes are similar to Gem-based themes, but do not require Gemfile changes or whitelisting making them ideal for sites hosted with GitHub Pages.

To install as a remote theme:

Create/replace the contents of your Gemfile with the following:

source "https://rubygems.org"

gem "github-pages", group: :jekyll_plugins
gem "jekyll-include-cache", group: :jekyll_plugins

Add jekyll-include-cache to the plugins array of your _config.yml.
Fetch and update bundled gems by running the following Bundler command:
```
bundle
```
Add remote_theme: "mmistakes/minimal-mistakes@" to your _config.yml file. Remove any other theme: or remote_theme: entry.

You may also optionally specify a branch, tag, or commit to use by appending an @ and the Git ref (e.g., mmistakes/minimal-mistakes@4.9.0 or mmistakes/minimal-mistakes@bbf3cbc5fd64a3e1885f3f99eb90ba92af84063d). This is useful when rolling back to older versions of the theme. If you don’t specify a Git ref, the latest on master will be used.

Looking for an example? Use the Minimal Mistakes remote theme starter for the quickest method of getting a GitHub Pages hosted site up and running. Generate a new repository from the starter, replace sample content with your own, and configure as needed.

Note: Your Jekyll site should be viewable immediately at http://USERNAME.github.io. If it’s not, you can force a rebuild by Customizing Your Site (see below for more details).

If you’re hosting several Jekyll based sites under the same GitHub username you will have to use Project Pages instead of User Pages. Essentially you rename the repo to something other than USERNAME.github.io and create a gh-pages branch off of master. For more details on how to set things up check GitHub’s documentation.

You can also install the theme by copying all of the theme files¹ into your project.

To do so fork the Minimal Mistakes theme, then rename the repo to USERNAME.github.io — replacing USERNAME with your GitHub username.

GitHub Pages Alternatives: Looking to host your site for free and install/update the theme painlessly? Netlify, GitLab Pages, and Continuous Integration (CI) services have you covered. In most cases all you need to do is connect your repository to them, create a simple configuration file, and install the theme following the Ruby Gem Method above.

Remove the Unnecessary

If you forked or downloaded the minimal-mistakes-jekyll repo you can safely remove the following folders and files:

.editorconfig
.gitattributes
.github
/docs
/test
CHANGELOG.md
minimal-mistakes-jekyll.gemspec
README.md
screenshot-layouts.png
screenshot.png

Note: If forking the theme be sure to update Gemfile as well. The one found at the root of the project is for building the theme’s Ruby gem and is missing dependencies. To properly setup a Gemfile with the theme, consult the “Install Dependencies” section.

Setup Your Site

Depending on the path you took installing Minimal Mistakes you’ll setup things a little differently.

ProTip: The source code and content files for this site can be found in the /docs folder if you want to copy or learn from them.

Starting Fresh

Starting with an empty folder and Gemfile you’ll need to copy or re-create this default _config.yml file. For a full explanation of every setting be sure to read the Configuration section.

From v4.5.0 onwards, Minimal Mistakes theme-gem comes bundled with the necessary data files for localization. They will be picked up automatically if you have the jekyll-data plugin installed. If you’re hosting on GitHub Pages, you can copy the _data/ui-text.yml file into your repository for the localization feature to work.

You’ll need to create and edit these data files to customize them:

_data/ui-text.yml - UI text documentation
_data/navigation.yml - navigation documentation

Starting from `jekyll new`

Scaffolding out a site with the jekyll new command requires you to modify a few files that it creates.

Edit _config.yml. Then:

Replace <site root>/index.md with a modified Minimal Mistakes index.html. Be sure to enable pagination if using the home layout by adding the necessary lines to _config.yml.
Change layout: post in _posts/0000-00-00-welcome-to-jekyll.markdown to layout: single.
Remove about.md, or at the very least change layout: page to layout: single and remove references to icon-github.html (or copy to your _includes if using it).

Migrating to Gem Version

If you’re migrating a site already using Minimal Mistakes and haven’t customized any of the theme files things upgrading will be easier for you.

Start by removing the following folders and any files within them:

├── _includes
├── _layouts
├── _sass
├── assets
|  ├── css
|  ├── fonts
|  └── js

You won’t need these anymore as they’re bundled with the theme gem — unless you intend to override them.

Note: When clearing out the assets folder be sure to leave any files you’ve added and need. This includes images, CSS, or JavaScript that aren’t already bundled in the theme.

From v4.5.0 onwards, the default language files are read-in automatically via the jekyll-data plugin if it’s installed. For sites hosted with GitHub Pages, you still need to copy the _data/ui-text.yml file because the jekyll-data plugin is unsupported on GitHub Pages.

If you customized any of these files leave them alone, and only remove the untouched ones. If done correctly your modified versions should override the versions bundled with the theme and be used by Jekyll instead.

Update Gemfile

Replace gem "github-pages or gem "jekyll" with gem "jekyll", "~> 3.5". You’ll need the latest version of Jekyll² for Minimal Mistakes to work and load all of the theme’s assets properly, this line forces Bundler to do that.

Add the Minimal Mistakes theme gem:

gem "minimal-mistakes-jekyll"

When finished your Gemfile should look something like this:

source "https://rubygems.org"

gem "jekyll", "~> 3.7"
gem "minimal-mistakes-jekyll"

Then run bundle update and add theme: minimal-mistakes-jekyll to your _config.yml.

v4 Breaking Change: Paths for image headers, overlays, teasers, galleries, and feature rows have changed and now require a full path. Instead of just image: filename.jpg you’ll need to use the full path eg: image: /assets/images/filename.jpg. The preferred location is now /assets/images/ but can be placed elsewhere or externally hosted. This applies to image references in _config.yml and author.yml as well.

That’s it! If all goes well running bundle exec jekyll serve should spin-up your site.

See Structure page for a list of theme files and what they do. ↩
You could also run bundle update jekyll to update Jekyll. ↩

Share on

Twitter Facebook LinkedIn