Alternatives and detailed information of jekyll-theme-simplex

The source of the generic demo is available here: https://github.com/andreondra/simplex-demo

A simple yet neat blogging theme. Developed for the golas blog project.

👓 Preview

💎 Features

Responsive

Dark mode

Buttons

Lity Lightbox

Supports images, videos, iFrames and more. See below for syntax.

Open Graph tags

ℹ Installation

Add this line to your Jekyll site's Gemfile:

gem "jekyll-theme-simplex"

And add this line to your Jekyll site's _config.yml:

theme: jekyll-theme-simplex

And then execute:

$ bundle

Or install it yourself as:

$ gem install jekyll-theme-simplex

✔ Usage

⚙ Setting up the template

Add following to the _config.yml:

logo_img: /assets/img/icons/golasblog_logo.svg #Absolute path to the logo. If not specified, the title will be displayed instead.
copyright: © Golasowski 2020 #Your copyright.

collections:
    category:
        output: true
    authors:
        output: false

defaults:
  -
    scope:
      path: ""
      type: category
    values:
      layout: "category"

✨ Defining categories

Create a _category folder in the root directory of the blog. Create a .md file for every category with the contents:

---
category: [design] #Category ID.
hue: var(--c-themeHueOrange) #Category hue. See note [1].
title: Design #Category title.
description: Lorem ipsum dolor sit amet.
---

🤵 Defining authors

Create a _authors folder in the root directory. Create a .md file for every author with the contents:

---
nick: golas #Author's nick.
full_name: Andrew Golasowski #Author's full name.
photo_dir: assets/img/authors/golas.png #Path to the author's pic.
---

📰 Defining the menu

Create a _data folder in the root directory. In the folder, create a nav.yaml file. Here's an example:

- title: Programming #Menu item title.
  url: category/programming.html #Menu item url.
  icon: assets/img/icons/programming.svg #Menu item icon.
  hue: "var(--c-themeHueRed)" #Menu item hue - see note [1].
  subnav: #Subnav. See note [2].
      - title: C++ #Submenu item title.
        url: category/cpp.html #Submenu item url.
        hue: "var(--c-themeHueOrange)" #Submenu item hue.
        subnav: #Another subnav
            - title: Libraries
              url: libs.html
              hue: "var(--c-themeHueBlue)"
- title: Design
  url: category/design.html
  icon: assets/img/icons/design.svg
  hue: "var(--c-themeHueRed)"

Pro tip:

Use color icons with the same hue as the menu items. Icons will be black and on hover the color will be shown.

✒ Creating posts

Posts are created in the _posts directory. Following front matter attributes are supported:

---
layout: post #Do not change.
category: [programming, testing] #One, more categories or no at all.
title: "Lorem ipsum" #Article title.
author: andy #Author's nick.
nextPart: _posts/2021-01-30-example.md #Next part.
prevPart: _posts/2021-01-30-example.md #Previous part.
og_image: assets/example.png #Open Graph preview image.
og_description: "Example description." #Open Graph description.
fb_app_id: example
---
Your markdown content here.

⚡ Syntax highlighting

The theme uses Pygments CSS created by @richleland. If you want to modify the highlighting styles, just download different CSS or create your own - see Jekyll docs.

Note - @media is used to manage different styles for light and dark web browser mode. See _variables.scss file for details.

📷 Inserting pictures

Classic Markdown syntax is supported. However, to be able to use the lightbox feature, you have to use HTML syntax. Minimal example:

<a href="/assets/example.jpg" data-lity>
  <img src="/assets/example_thumbnail.jpg"/>
</a>

To provide image description use this syntax:

<div class="sx-picture">
  <a href="/assets/example.jpg" data-lity>
    <img src="/assets/example_thumbnail.jpg"/>
  </a>
  <span class="sx-subtitle">My picture description.</span>
</div>

Do not forget the data-lity attribute.

↔ Centering

To center pictures, put the code inside a div with sx-center class like this:

<div markdown=1 class="sx-center">
  ![My picture](/assets/example.jpg)
</div>

🔘 Buttons

Buttons can be inserted with the following syntax. Just replace theme with red, green, blue, orange, purple or brown, specify the target link in href attribute and the icon in src attribute.

<div class='sx-button'>
  <a href='https://your.link.here.example.com/' class='sx-button__content theme'>
    <img src='/assets/img/icons/example_icon.svg'/>#{text}
  </a>
</div>

Markdown attribute can be omitted if you don't use markdown inside the block (e.g. by using the lightbox syntax).

ℹ Notes

[1] Hue can be either one of the predefined colors or any of the CSS color attribute supported values (hex, rgb...).

[2] Submenus are generated recursively, so any menu (and submenu) can have its own submenu.

Predefined colors

You can use following predefined colors:

--c-themePrimaryLight: #EFEFEF;
--c-themePrimaryDark:  #101010;
--c-themeSecondaryLight: #DADADA;
--c-themeSecondaryDark: #252525;
--c-themeTerniaryLight: #AEAEAE;
--c-themeTerniaryDark: #515151;
--c-themeQuaternaryLight: #919191;
--c-themeQuaternaryDark: #888888;

--c-themeHueRed: #C02717;
--c-themeHueGreen: #8EA604;
--c-themeHueBlue: #2E86AB;
--c-themeHueOrange: #E59500;
--c-themeHuePurple: #9F00CE;
--c-themeHueBrown: #230007;

These colors are CSS variables, usage: var(--var-name)

Add-ons

Add-ons are distributed as Jekyll plugins. Just download any desired .rb file from the repository _plugin folder and put it in your _plugin folder.

Buttons (button.rb)

Adds a tag to simplify insertion of buttons:

{% button red|https://www.example.com/|/assets/img/icons/cog.svg %}
Download binary
{% endbutton %}

🤝 Contributing

Bug reports and pull requests are welcome on GitHub.

⚙ Development

To set up your environment to develop this theme, run bundle install.

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, documents, data, etc. like normal 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. If you recieve an error stating, "require': cannot load such file -- webrick (LoadError)' Simply run bundle add webrick and this will install the dependencies for running the Jekyll and then you may repeat Step 2!

When your theme is released, only the files in _layouts, _includes, _sass and assets tracked with Git will be bundled. To add a custom directory to your theme-gem, please edit the regexp in jekyll-theme-simplex.gemspec accordingly.

Credits

Includes icons by uxwing.

The lightbox feature is provided by Lity licensed under the MIT License.

Uses jQuery JavaScript plugin licensed under the MIT License.

Cheap and reliable Node.js hosting starts at $3/month, and $1/month static HTML hosting

andreondra / jekyll-theme-simplex

Programming Languages

Labels

Projects that are alternatives of or similar to jekyll-theme-simplex