My Notes on Blogging with Jekyll

Generally

• https://jekyllrb.com/
• Jekyll tutorial, cloudcannon.
• Jekyll Cheat Sheet, cloudcannon.
• Michael Rose, Going static: Using Jekyll without a CMS, Made Mistakes, Aug. 2, 2021.
• Keir Whitaker, Rebuilding keirwhitaker.com with Jekyll, Jan. 5, 2017.
• Although Jekyll is free, you can make a finacial contribution.

_config.yml

• Configuration, Jekyll.

404 Page

• Custom 404 Page, Jekyll.
• Custom 404 Page, Vercel.
• Rachel Leist, 40 Clever 404 Error Pages From Real Websites.

Anchors

• AnchorJS

Collections

• Collections
• “I mentioned the permalink structure for the _posts collection earlier and it’s perhaps worth talking about the opposite of a collection which is a page. If you are familiar with WordPress the analogy holds true for Jekyll. A collection file is normally date relevant whereas a page file is a stand-alone piece of content.” Keir Whitaker, Rebuilding keirwhitaker.com with Jekyll.

Comments

• ghpages-ghcomments – For an example, see Joe Friedrichsen’s blog, Down to the Wire.

Excerpts

• Sean Buscay, How I Added Teaser and Read-more Functionality to My Jekyll Blog on GitHub Pages, Feb. 12, 2015.

Footnotes

• You can change 1 to [1] with two CSS rules:

a.footnote:before {   
 content: "[";
}

a.footnote:after {
    content: "]";
}

gemfile

• “A gem is a little bundle of code we can get included in our Ruby projects. The gemfile allows us to take someone else’s code and drop it straight into our own project. . . . Jekyll itself is a gem as well many Jekyll plugins including jekyll-paginate and jekyll-feed which get included in the base site.” Alan Reid, Jekyll File Structure, Sept. 25, 2018.
• Bundler – “Bundler provides a consistent environment for Ruby projects by tracking and installing the exact gems and versions that are needed.”
  • “A quick side note on Bundler. Whilst I had used Bundler before it was something I needed to re-familiarise myself with. Essentially Bundler provides a consistent environment for Ruby (which Jekyll is written in) projects by tracking and installing the exact Gems and versions that are needed. It works hand in glove with the Gemfile located in the root of the project folder. Using Bundler effectively allows you to use different Gem versions for individual projects.” Keir Whitaker, Rebuilding keirwhitaker.com with Jekyll .

Images

• See Michael Rose’s discussion, Responsive images revisited.
• Mat Maequis, Responsive Images: How they Almost Worked and What We Need, A List Apart, Jan. 31, 2012.

Layout

• Toshimaru’s Blog, How to disable layout in Jekyll, June 12, 2016.

Kramdown

• For notes on Kramdown, see the Markdown writeup.

Liquid

• Control flow tags - “Control flow tags create conditions that decide whether blocks of Liquid code get executed.”

Markdown

• Jekyll converts Markdown to HTML.
• You must specify the Markdown filter (such as Kramdown) in the _config.yml file.
• Files must have a Markdown extension (not txt) in order for Jekyll to convert them.
• Files must have front matter in order for Jekyll to convert them.

Pagination

• Pagination, Jekyll.
• Sean Buscay, How I Added Teaser and Read-more Functionality to My Jekyll Blog on GitHub Pages, Feb. 12, 2015.

Permalinks

• Permalinks, Jekyll.

Read More

• Sean Buscay, How I Added Teaser and Read-more Functionality to My Jekyll Blog on GitHub Pages, Feb. 12, 2015.

Reading Time

• Alan Reid, Jekyll tips & tricks, Oct. 27, 2015.
• Displaying an Accurate Reading Time Estimate in Jekyll, April 21, 2020.

Sass

• Sass/SCSS, Jekyll.
• Setting Per-Page Custom CSS in Jekyll, jreel.

Table of Contents

• Kramdown
  • Automatic “Table of Contents” Generation, Kramdown.
  • Toshimaru’s Blog, Create Table of Contents in kramdown, Oct. 20, 2020.
  • Sam Buscay, How I Add a Table of Contents to my Jekyll Blog Written in Markdown, Feb. 11, 2015.

  • N.B. Despite a suggestion on Stack Overflow, you can’t have Kramdown TOC in a separate includefile and create a YAML tag (such as toc: true because Markdown in include file is not processed. All of the layout files (in the _layouts directory) are HTML files (default.html, home.html, page.html, and post.html), and the include tag places the Markdown in the HTML file before the Markdown is processed. Because the Kramdown TOC instruction is in Markdown that isn’t processed, it appears literally. To summarize:

    • Markdown include files works correctly in Markdown files.
    • HTML include files works correctly in HTML files.
    • Markdown include files do not render correctly in HTML files.
• You can probably use a jQuery plugin:
  • Plugin: TOC Generator for Markdown, GitHub
  • docassemble uses this plugin.
  • N.B.:
    • The plugin allows you to use show/hide the toc amd save the status using a cookie.
    • The plugin does not number headings in the document.
• toshimaru/jekyll-toc - “Jekyll plugin which generates a table of contents.”

Themes

• Michael Rose, Jekyll themes, Made Mistakes.

YAML Front Matter

• Keir Whitaker, Rebuilding keirwhitaker.com with Jekyll: “Many of the front matter variables are predefined and have particular reference to Jekyll. You can also create your own variables using non-reserved words. These are known as custom variables. You simply access these using the following syntax:

{{ page.customvariable }}