Skip to content
Monica Powell's Workshop Site for Technical Blogging with Jekyll @ CodelandConf 2018.
HTML CSS JavaScript Ruby
Branch: master
Clone or download
Pull request Compare This branch is 42 commits ahead, 2 commits behind melangue:master.
Latest commit 57e716f May 18, 2018

README.md

Technical Blogging with Jekyll

Today we are going to learn the basics of publishing and maintaining a blog to host your technical writing. You will create a static blog and learn how to host it for free on Github Pages. You can expect to walk away being confident modifying and customizing your blog to better fit your needs.

Slides for the workshop are viewable here: http://aboutmonica.com/codeland/jekyll.pdf

Installation instructions are viewable here: https://m0nica.github.io/dactl/posts/welcome


This workshop was built using dactl which is a fast, modern and configurable Jekyll theme with some tricks up it's sleeve. Its main blog layout display prominent hero images for posts with colored overlays and nice animations. workshop homepage

Installation

Running locally

Assuming you've got Jekyll installed, clone or download this repo, cd to wherever you've put dactl folder, bundle install dependencies and then run bundle exec jekyll serve

Hosting on GitHub

Fork this repo and rename it to yourusername.github.io... and that's it!
Your new dactl-themed Jekyll blog should be up and running at yourusername.github.io.

Features

Though minimalistic-looking by nature, dactl is easily configurable and includes quite a lot of niceties:

Main features:

  • Customizable blog layout - choose how your posts will be displayed * Light/Dark live theme switcher
  • Inline footnotes using Barefoot
  • IcoMoon custom icon set (~4kb)
  • Typography and components size set in rem and em which makes them easily scalable
  • Responsive design

Jekyll-specific features:

  • Pagination (default: 5 posts per page)
  • Fully compatible with Jekyll 3.x and GitHub Pages
  • SEO optimized
  • Google Analytics support
  • Disqus comments support
  • Syntax highlighter using Rouge with numbered code lines

Other features:

  • Archive page
  • About page
  • Tags functionality and tags pages
  • Link posts functionality

Some of the features listed above can be easily configured or disabled by you.

Information about dactl

At it's core, dactl is a forked version of daktilo but it has been almost entirely rewritten from scratch.
I have just started my journey in the world of web development, learning new things on the way.
Looking for a way to put my newly acquired skills to test I found Jekyll and I quickly realized that it's going to be a good learning experience since I don't like building 'dummy' projects.
I've built this theme as a way to develop my skills further.

You can find credits at the bottom of this Readme file.
All feedback is welcome, both positive and negative.

Usage

Slight warning

dactl relies heavily on modern CSS properties such as mix-blend-mode, -webkit-filter and css variables so it may not work properly on older browsers.
It was tested with and works fully on webkit-powered browsers - Safari, Chrome, Vivald.

Layout configurations

By default dactl uses blog layout which you can see below or check for yourself in the live version.

Main blog layout displays 5 posts. Each post has a heading contained in a medium-sized tile - with an color overlay over the background image. You need to set the image and color of the overlay in post's YAML front matter.

If you don't want to use images for post headings you can easily configure the layout to you needs by changing settings located in configure.yml file, both post and blog layout will adapt accordingly.

Options include:

  • Use or don't use post heading images (Blog & Post)
  • Show full post content or post excerpts (Blog)
  • Show post titles only (Blog)

Additional information about some features

Hero images and blog layout

Liquid 'script' which is used to append correct hero image and overlay color as set in post YAML Front matter was written by me and while it's really basic it functions properly.
You can read more about it and see the code in include/utils/hero.html.

Theme switcher

For this fork I have disabled the Theme switcher. By default light theme css is in the _variables.scss file and the dark theme css is below (commented out). If you would like to switch to the dark theme css then comment out the above light theme css and uncomment the dark theme css.

// light theme

$bg-color: #eee;
$text-color: #000;
$text-color-light: #828282;
$link-color: #8BC34A;
$metadata-color: #999;
$post-title: #313131;
$code-border: #f5f5f5;
$code-bg-color: #fff;
$table-border-color: #e5e5e5;
$table-header-color: #fefefe;
$shadow-color: rgba(0, 0, 0, 0.1);
$invert-logo-color: 'invert(0)';

// night theme

//un-comment for night theme
  //
  //
  // $bg-color: #1c1c1c;
  // $text-color: #c4c4c4;
  // $text-color-light: #777;
  // $link-color: #f1f1f1;
  // $metadata-color: #666;
  // $post-title: #fff;
  // $code-bg-color: #252525;
  // $code-border: #222;
  // $table-border-color: #292929;
  // $table-header-color: #505050;
  // $shadow-color: rgba(255, 255, 255, 0.1);
  // $invert-logo-color: invert(1);
  

Inline Barefoot footnotes

dactl uses Barefoot plugin to create nice looking inline footnotes from those generated by kramdown, daktl's markdown processor.

Barefoot description (from project's page):

Barefoot is a lightweight Bigfoot.js alternative written in vanilla Javascript to create beautiful inline footnotes.
Barefoot grabs the common markup used for footnotes on the web, mostly generated by Markdown processors, and transform it into beautiful and meaningful footnotes.

CSS

CSS is built by via Jekyll's SASS compiler. Source partial SASS files are located in _sass folder, included into main.scss, and compile to main.css.

Additional pages

Archive page

Archive page displays all of your posts grouped by month. Under this page's title you'll find a Searchbox which is hooked up to DuckDuckGo's :site search and will open the results in a new tab.
You need to provide your blog's web address in search_path field found in _config.yml for it to work.

About page

About page displays your photo under the title (set in config.yml) and the content of about.md.

Tags & Tags Pages

Tags and tag pages are supported by using Jekyll's native collections functionality.

Even more info

Rems, font-size and scaling

dactl is built almost entirely with rems (instead of pixels). rems are like ems, but instead of building on the immediate parent's font-size, they build on the root element, <html>.

By default, dactl uses the following:

html {
  font-size: 20px;
  line-height: 1.6;
}
@media (max-width: 48rem) {
  html {
    font-size: 18px;
  }
}

To easily scale your site's typography and components, simply customize the base font-sizes found in _sass/variables.scss file.

(Lifted from here)

Credits

Resources used

Inspiration and thoughtful code-jacking

Inspiration and bits of things listed below are present inside dactl's code:

  • Daktilo - dactl is based on Daktilo and inherits it's one-column layout.
  • Hydejack - I've learned a lot about Jekyll when I took apart @qwtel's excellent fork of Hyde theme. I embraced his more partials = everything is easier to edit policy. Hydejack theme gave me an idea on how to create hero images liquid scripting, loading google fonts and using rem's/em's and more.
  • Minimal Mistakes - This guy makes awesome themes and writes a lot about Jekyll and it's more obscure use cases on his blog, Made Mistakes. Looking through his theme's code - Minimal Mistakes in particular - gave me lot of information about how to build a robust theme and how to make it configurable within _config.yml
  • Trophy - Link border slide animation SASS mixin which I slightly modified to be able to easily change the direction of the animation.
  • Various blog posts about Jekyll and Stackoverflow posts with useful Liquid snippets.

License

All parts of dactl Jekyll theme are free to use and abuse under the open-source MIT license.

TO DO

  • Inline critical .css in <head> for faster load times
  • Fix theme-switcher - sometimes it does not inject all of the colors properly on first page load and a refresh, fixes itself after switching the theme back and forth. (fixed via removal for this demo application)
You can’t perform that action at this time.