jekyll-wren 0.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 880063b3f3f71125016ffc145ad9c1928d83a3b101de7ce4b8331f1a37080d71
+  data.tar.gz: 79f38b62a4c74603e458b7a5c385a084c91b8add5aa9ec1fa13f8f96c6229791
+SHA512:
+  metadata.gz: 555cfb22eea2cde9883d0fea0fdf78da7a435771b37623d3d229f858f238e130d7db845ad44b2e8293200acbdcf40bbdbe76d3ac7a22c12e828f87f3a44a9af0
+  data.tar.gz: 61aabed58c5665fe218f7397de35d00e89c914b4a34404b9b33fecbe02e46b27181c83770753e0ff1667a1ea8eea6e5e012f2dc76469b82ac5b125b1476fd04e

data/LICENSE.md

@@ -0,0 +1,9 @@
+# MIT License
+
+Copyright (c) 2021 Josh Fogg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,177 @@
+# Wren
+
+[![Jekyll CI Status]][jekyll-ci-link]
+[![CodeFactor Rating]][codefactor-link]
+[![MIT Licensed]][license-link]
+
+[Jekyll CI Status]: https://img.shields.io/github/workflow/status/Foggalong/Wren/Jekyll%20CI?label=Jekyll%20CI
+[jekyll-ci-link]: https://github.com/Foggalong/Wren/actions/workflows/codeql-analysis.yml
+[CodeFactor Rating]: https://img.shields.io/codefactor/grade/github/foggalong/wren/main?color&label=CodeFactor
+[codefactor-link]: https://www.codefactor.io/repository/github/foggalong/wren
+[MIT Licensed]: https://img.shields.io/badge/License-MIT-brightgreen.svg
+[license-link]: #licenses
+
+A paper-style theme for [Jekyll]. Check out the GitHub pages [deployment] to see what the default looks like and read on for information on usage and customisation. Be aware that this **beta** software so will contain bugs; use it at your own risk.
+
+[Jekyll]: https://jekyllrb.com
+[deployment]: https://foggalong.github.io/Wren
+[wiki]: https://github.com/Foggalong/Wren/wiki
+
+## Features
+
+- 🎨 Responsive, [customisable] design
+- 🕔 See post reading time
+- 🗄️ 'First published on' icons
+- 🏷️ Browse posts by tags
+- 🧑 Browse posts by author
+- 📺 Embedded [YouTube, Twitch, etc][videos]
+- 🦶🏼 [Extendable] head, foot, and post meta
+- 📃 Optional [pagination]
+- 📰 Atom/RSS feed of posts
+- 📈 In-built search engine optimization
+
+[customisable]: #custom-styling
+[videos]: https://foggalong.github.io/Wren/video-embed-demo
+[extendable]: #custom-templates
+[pagination]: #pagination
+
+## Installing
+
+Whether you fork this repo or start from scratch there are two supported options for using Wren as your theme. Which works better for you will depend on your personal priorities.
+
+### Theme Gem
+
+Use the `jekyll-wren` gem, fetched automatically from [RubyGems] or downloaded from the [releases page] and installed locally. Either way you'll need to add
+
+```yaml
+theme: jekyll-wren
+```
+
+to your [config] and
+
+```ruby
+gem "jekyll-wren", "~> 0.4"
+```
+
+to your [Gemfile] plugins list.
+
+The upsides are that builds will be quicker and you'll have more control over the version through the Gemfile. The downside is that it will prevent building with GitHub Pages' builder since Wren isn't on the [whitelist] (though you'll still be able to build locally and push to a GitHub pages branch/repo).
+
+[RubyGems]: https://rubygems.org
+[releases page]: https://github.com/Foggalong/Wren/releases/latest
+[config]: https://github.com/Foggalong/Wren/blob/main/_config.yml#L22-L23
+[Gemfile]: https://github.com/Foggalong/Wren/blob/main/Gemfile#L22-L28
+
+### Remote Theme
+
+It's possible to use the theme directly from this repo. You'll need to add
+
+```yaml
+plugins:
+  - jekyll-remote-theme
+
+remote_theme: foggalong/wren@0.4
+```
+
+to your [config] and then
+
+```ruby
+gem "jekyll-remote-theme", "~> 0.4"
+```
+
+to your [Gemfile] plugins list.
+
+The upside is that this will work with GitHub Pages' builder ([Jekyll Remote Theme] is on the [whitelist]). The downsides are that builds will be slower and your [version control] is slightly weaker; you're tied to `HEAD` or a specific version.
+
+[Jekyll Remote Theme]: https://github.com/benbalter/jekyll-remote-theme
+[version control]: https://github.com/benbalter/jekyll-remote-theme#declaring-your-theme
+
+## Config Options
+
+The [config.yml] in this repo can be used as a template for your own Wren instance. The file is thoroughly commented so it's worth having a read to know all the options available.
+
+[config.yml]: https://github.com/Foggalong/Wren/blob/main/_config.yml
+
+## Custom Templates
+
+[Minima] has a feature which allows users to create a [_includes/custom-head.html] file which is then [included] with the rest of the head. This is a useful feature if, for example, you want your website to cover favicons for more browsers than the default setup does.
+
+[_includes/custom-head.html]: https://github.com/jekyll/minima/blob/master/_includes/custom-head.html
+[included]: https://github.com/jekyll/minima/blob/master/_includes/head.html#L12
+
+Wren keeps this feature and extends it so that `custom-foot.html` (displayed above the copyright notice) and `custom-meta.html` (displayed at the end of a post's meta line) can also be specified.
+
+## Custom Styling
+
+Like [Minima] (on which Wren's [SASS] is built) there are a whole bunch of variables which you can change to personalise the theme. To do this you just add lines such as
+
+```scss
+$background-color: #3d9da3;
+```
+
+to [`assets/style.scss`] and you're good to go. The list of what's customisable is slightly different (and longer!) than Minima so have a look at the full list of [style variables].
+
+[Minima]: https://github.com/jekyll/minima
+[`assets/style.scss`]: https://github.com/Foggalong/Wren/blob/main/assets/style.scss
+[style variables]: https://github.com/Foggalong/Wren/blob/main/_sass/wren/initialize.scss#L10-L87
+
+## Pagination
+
+If the following two [config.yml] lines aren't commented, Wren will use [Jekyll Paginate][Paginate] to split the posts page into multiple pages of `paginate` many posts with url `paginate_path`.
+
+```yaml
+paginate: 5
+paginate_path: "/blog/:num"
+```
+
+Note that due to [Paginate]'s technical limitations this will only happen on the main posts page, not other post lists such as the tags page. It's generally quite limited in how it works compared to [Paginate v2], but the latter isn't on the [whitelist].
+
+Another caveat is that, if you're using Paginate, the main post list page **must** have filename `index.html`; that's why in this repo it's `blog/index.html`. If you're not using Paginate though, Wren allows you to put that file anywhere and called whatever you like without problems.
+
+[Paginate v2]: https://github.com/sverrirs/jekyll-paginate-v2
+
+## Error Pages
+
+Wren includes [`error.html`], a layout for formatting error pages; they're centered, have different spacing, and slightly different `<h1>` formatting. In [`errors/`] there are some examples; those aren't in the theme-gem (see [#25]) but to use them just copy to your website's repo. See this [tutorial] for configuring error pages on GitHub pages, Apache, and Nginx.
+
+[`error.html`]: https://github.com/Foggalong/Wren/blob/main/_layouts/error.html
+[`errors/`]: https://github.com/Foggalong/Wren/tree/main/errors
+[#25]: https://github.com/Foggalong/Wren/issues/25
+[tutorial]: https://jekyllrb.com/tutorials/custom-404-page
+
+## Philosophy
+
+I ❤️ [Wrens]. They're smol, quick, and rotund. When I was little we had a family of them come nest in our garden and they sang the most brilliant songs. Oh wait? You're saying this was supposed to be the project's philosophy? Let's just just say it's to be small, fast, and round.
+
+[Wrens]: https://en.wikipedia.org/wiki/Wren
+
+## Licenses
+
+Wren is released under the [MIT License] and is built with [Jekyll] and a whole host of other MIT licensed projects.
+
+[MIT License]: https://choosealicense.com/licenses/mit
+
+In order to remain compatible with GitHub Pages Wren only uses plugins from the [whitelist]. Massive props to [Remote Theme], [Feed], [Paginate], and [SEO] for doing their thing in the background without me needing to worry about it. Further features are achieved through [Liquid] templates, some of which are based on existing Ruby plugins. These include [Reading Time], [Embed Video], [Tag Cloud].
+
+[whitelist]: https://pages.github.com/versions
+[Remote Theme]: https://github.com/benbalter/jekyll-remote-theme
+[Feed]: https://github.com/jekyll/jekyll-feed
+[Paginate]: https://github.com/jekyll/jekyll-paginate
+[SEO]:  https://github.com/jekyll/jekyll-seo-tag
+[Liquid]: https://github.com/Shopify/liquid
+[Reading Time]: https://github.com/risan/jekyll-reading-time
+[Embed Video]: https://github.com/nathancy/jekyll-embed-video
+[Tag Cloud]: https://superdevresources.com/tag-cloud-jekyll
+
+Style wise, Wren's [SASS] is forked from [Minima] which proved crucial in knowing what did and didn't need to be covered by Jekyll themes. The icons (apart from are based on designs from [Font Awesome], redrawn for the smaller form factor. Credit also to Antoine Boulanger's guide on [SVG Favicons].
+
+[SASS]: https://sass-lang.com
+[Font Awesome]: https://github.com/Rush/Font-Awesome-SVG-PNG
+[SVG Favicons]: https://link.medium.com/oDf4MMhiqjb
+
+The only part of Wren _not_ MIT licensed is the [default profile image], a [CC-BY-NC] licensed [photo] of a Bewick Wren taken by [Minette Layne].
+
+[default profile image]: images/profile-hq.jpg
+[photo]: https://flic.kr/p/4E9FY2
+[Minette Layne]: https://www.flickr.com/people/minette_layne
+[CC-BY-NC]: https://creativecommons.org/licenses/by-nc/2.0

data/_includes/custom-foot.html

@@ -0,0 +1,4 @@
+{% comment %}
+  Placeholder to allow defining custom footer content.
+  In principle, you can add anything here.
+{% endcomment %}

data/_includes/custom-head.html

@@ -0,0 +1,13 @@
+{% comment %}
+  Placeholder to allow defining custom head. In principle, you can add
+  anything here, e.g. favicons.
+
+  If you have a website that you anticipate people using as a webapp on
+  iOS, Android, or Windows 8 or Windows 10 then it would be worth head
+  over to https://realfavicongenerator.net/ to add your own favicons and
+  insetting the code snippets they give into _includes/custom-head.html
+  in your source directory.
+
+  The favicons Wren provides are the absolute minimum to cover modern
+  browsers. See here for more info: https://link.medium.com/oDf4MMhiqjb
+{% endcomment %}

data/_includes/custom-meta.html

@@ -0,0 +1,5 @@
+{% comment %}
+  Placeholder to allow defining custom meta content. In principle, you can add
+  anything here. To keep style consistent with the rest of Wren's meta you
+  should use '•' to separate different attributes.
+{% endcomment %}

data/_includes/footer.html

@@ -0,0 +1,23 @@
+<footer class="site-footer h-card">
+  <data class="u-url" href="{{ "/" | relative_url }}"></data>
+  {%comment%} add user's custom footer; anything can go here! {%endcomment%}
+  {%- include custom-foot.html -%}
+  {%comment%} keeps copyright notice to current year {%endcomment%}
+  Copyright © {{ site.time | date: '%Y' }}
+  {%- if site.author %}
+    {% if site.author.name -%}
+      {% if site.author.email -%}
+        <a href="mailto:{{ site.author.email }}">{{ site.author.name }}</a>
+      {% else -%}
+        {{ site.author.name }}
+      {%- endif %}
+    {%- endif %}
+  {%- endif -%}
+  {%comment%} remove line below if you don't want to attribute Jekyll/Wren {%endcomment%}
+  · Made using <a href="https://jekyllrb.com">Jekyll</a> with <a href="https://github.com/Foggalong/Wren">Wren</a>
+
+  {%comment%} social-list.html quite big so in a separate file {%endcomment%}
+  <div class="social-list">
+    {%- include social-list.html -%}
+  </div>
+</footer>

data/_includes/head.html

@@ -0,0 +1,21 @@
+<head>
+  <meta charset="utf-8">
+  <meta http-equiv="X-UA-Compatible" content="IE=edge">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  {%comment%} jekyll-seo-tag doing its thing {%endcomment%}
+  {%- seo -%}
+  {%comment%}
+    using SVG favicons, see link below for documentation. In theory the flav.svg will
+    cover all modern browsers except iOS Safari which the apple-touch-icon.png covers
+    https://medium.com/swlh/are-you-using-svg-favicons-yet-a-guide-for-modern-browsers
+  {%endcomment%}
+  <link rel="icon" href="{{ '/assets/flav.svg' | relative_url }}">
+  <link rel="shortcut icon" href="{{ '/assets/flav.svg' | relative_url }}">
+  <link rel="apple-touch-icon" href="{{ '/assets/apple-touch-icon.png' | relative_url }}">
+  {%comment%} assets/style.css isn't a typo, is where SASS will compile to {%endcomment%}
+  <link rel="stylesheet" href="{{ '/assets/style.css' | relative_url }}">
+  {%comment%} jekyll-feed doing its thing {%endcomment%}
+  {%- feed_meta -%}
+  {%comment%} add user's custom header; anything can go here! {%endcomment%}
+  {%- include custom-head.html -%}
+</head>

data/_includes/meta.html

@@ -0,0 +1,82 @@
+{%comment%} ensures this file works with posts and pages {%endcomment%}
+{%- if page.date -%}
+  {%- assign p = page -%}
+  {%- assign align = 'center' -%}
+{%- else -%}
+  {%- assign p = post -%}
+  {%- assign align = 'left' -%}
+{% endif %}
+
+{%comment%} Sets the default date format as ISO 8601 {%endcomment%}
+{% assign date_format = site.wren.date_format | default: "%Y-%m-%d" %}
+
+<p class="post-meta" {{ align | prepend: 'style= "text-align: ' | append: ';"'}}>
+  {%comment%} assign variables prevents overflow between entries {%endcomment%}
+  {%- assign original_date = p.date | date: date_format -%}
+  {%- assign modified_date = p.modified_date -%}
+  {%comment%} if post was modified, add * and add that date as hover text {%endcomment%}
+  {%- if modified_date -%}
+    {%- assign modified_date = modified_date | date: date_format | prepend: 'Updated on ' -%}
+    {%- assign original_date = original_date | append: '*' -%}
+  {%- endif -%}
+  <time title="{{ modified_date }}" class="dt-published" datetime="{{ original_date | date_to_xmlschema }}" itemprop="datePublished">
+    {{ original_date }}
+  </time>
+
+  {%comment%} passing content to be analysed by reading-time explicitly {%endcomment%}
+  • {%- include reading-time.html text=p.content -%}
+
+  {%comment%} if tag given, give as comma-separated list with links to tag page {%endcomment%}
+  {%- if p.tags -%}
+    {%- for tag in p.tags -%}
+      {%- if forloop.first == true %}• {% endif %}
+      <a href={{ 'blog/tags#' | append: tag | relative_url }}>{{ tag }}</a>
+      {%- if forloop.last == false %}, {% endif %}
+    {%- endfor -%}
+  {%- endif %}
+
+  {%comment%} if authors given, give as comma-separated list {%endcomment%}
+  {%- if p.author -%}
+    {%- for author in p.author -%}
+      {%- if forloop.first == true -%}• {% endif -%}
+        {%- assign author_id = author | replace: ' ', '_' -%}
+        <span itemprop="author" itemscope itemtype="http://schema.org/Person">
+          <span class="p-author h-card" itemprop="name">
+            <a href={{ 'blog/authors#' | append: author_id | relative_url }}>{{author}}</a>
+            {%- if forloop.last == false -%}, {%- endif -%}
+          </span>
+        </span>
+    {% endfor %}
+  {%- endif -%}
+
+  {%comment%} indicate if the post was first published elsewhere first {%endcomment%}
+  {%- if p.first_published_on -%}
+    {%comment%} allow specifying a specific URL at which it was published {%endcomment%}
+    {%- if p.first_published_url -%}
+      {%- assign fpo_string = "First published on " | append: p.first_published_url -%}
+    {%- else -%}
+      {%- assign fpo_string = "First published on " | append: p.first_published_on -%}
+    {%- endif -%}
+    {%comment%} construct expected icon path, then check if exists {%endcomment%}
+    {%- assign icon_path = p.first_published_on | prepend: 'assets/social-icons/' | append: '.svg' -%}
+    {%- assign found = false -%}
+    {%- for static_file in site.static_files -%}
+      {%- if static_file.path contains icon_path -%}
+        {%- assign found = true -%}
+      {%- endif -%}
+    {%- endfor -%}
+    {%comment%} if it doesn't, use the default source icon {%endcomment%}
+    {%- if found == false -%}
+      {%- assign icon_path = 'assets/social-icons/Default.svg' -%}
+    {%- endif -%}
+    {%comment%} put that all together with a.svg.use for the button {%endcomment%}
+    •
+    <a title="{{ fpo_string }}" alt="{{ fpo_string }}">
+      <svg style="vertical-align: sub; width: 16px; height: 16px;" =>
+        <use xlink:href="{{ icon_path | append: '#soc' | relative_url }}"/>
+      </svg>
+    </a>
+  {%- endif -%}
+  {%comment%} add user's custom meta; anything can go here! {%endcomment%}
+  {%- include custom-meta.html -%}
+</p>

data/_includes/navigation.html

@@ -0,0 +1,70 @@
+{%comment%}
+  In principle other content could be displayed in the <header> element (as in
+  Minima) but stock Wren only uses it for navigation links. Also shouldn't be
+  confused with head.html which provides HTML <head> meta information. 
+{%endcomment%}
+
+<header class="site-header">
+  {%comment%} <nav> notifies browser there are navigation links {%endcomment%}
+  <nav class="site-nav">
+    {%comment%} always include link to home in navbar {%endcomment%}
+    <a class="page-link" href="{{ site.baseurl }}/" title="Home" alt="Home">
+      <svg>
+        {%comment%} #nav acts as an anchor for the import {%endcomment%}
+        <use xlink:href="{{ 'assets/nav-icons/home.svg#nav' | relative_url }}"/>
+      </svg>
+    </a>
+
+    {%comment%} display any pages listed in _config.yml in order {%endcomment%}
+    {%- for path in site.wren.header_pages -%}
+      {%comment%} shortcuts for basic page info {%endcomment%}
+      {%- assign my_page = site.pages | where: "path", path | first -%}
+      {%- assign title = my_page.title | escape -%}
+
+      {%comment%} prepend '/' so split works even if file in root {%endcomment%}
+      {%- assign clean_path = path | prepend: '/' | split: '/' -%}
+      {%comment%} need an ID by which to look for navigation icons {%endcomment%}
+      {%- if clean_path[-1] == 'index.html' -%}
+        {%comment%} ID is containing directory if link an index file {%endcomment%}
+        {%- assign id  = clean_path[-2] -%}
+      {%- else -%}
+        {%comment%} ID is filename if not an index file {%endcomment%}
+        {%- assign id = clean_path[-1] | remove: '.md' | remove: '.html' -%}
+      {%- endif -%}
+
+      {%comment%} construct expected icon path, then check if exists {%endcomment%}
+      {%- assign icon_path = id | prepend: 'assets/nav-icons/' | append: '.svg' -%}
+      {%- assign found = false -%}
+      {%- for static_file in site.static_files -%}
+        {%- if static_file.path contains icon_path -%}
+          {%- assign found = true -%}
+        {%- endif -%}
+      {%- endfor -%}
+      {%comment%} if it doesn't, use the default navigation icon {%endcomment%}
+      {%- if found == false -%}
+        {%- assign icon_path = 'assets/nav-icons/default.svg' -%}
+      {%- endif -%}
+
+      {%comment%} put that all together with a.svg.use for the button {%endcomment%}
+      <a class="page-link" href="{{ my_page.url | relative_url }}" title="{{ title }}" alt="{{ title }}">
+        <svg>
+          <use xlink:href="{{ icon_path | append: '#nav' | relative_url }}"/>
+        </svg>
+      </a>
+    {%- endfor -%}
+
+    {%comment%} always include link to RSS in navbar {%endcomment%}
+    <a class="page-link" href="{{ 'feed.xml' | relative_url }}" title="Feed">
+      <svg>
+        <use xlink:href="{{ 'assets/nav-icons/rss.svg#nav' | relative_url }}"/>
+      </svg>
+    </a>
+
+    {%comment%} always include shortcut to top of page in navbar {%endcomment%}
+    <a class="page-link" href="#" title="Top" alt="Top">
+      <svg>
+        <use xlink:href="{{ 'assets/nav-icons/top.svg#nav' | relative_url }}"/>
+      </svg>
+    </a>
+  </nav>
+</header>

data/_includes/reading-time.html

@@ -0,0 +1,41 @@
+{% comment %}
+  This is an amazing example of how Liquid templates can behave exactly
+  like functions. Used as {% include reading-time.html text=content %},
+  this template takes an optional variable `text` as input and returns
+  how long it takes to read the content of that variable as output. If
+  no text given it just analyses the page its included in instead.
+{% endcomment %}
+
+{%comment%} check which provides fallback for `text` {%endcomment%} 
+{%- if include.text -%}
+  {%- assign text = include.text -%}
+{%- else -%}
+  {%- assign text = content -%}
+{%- endif -%}
+
+{%comment%} set the default reading speed {%endcomment%} 
+{%- assign wpm = site.wren.wpm | default: 180 -%}
+
+{%comment%}
+  Liquid can't do arithmetic within conditional expressions. We'll
+  need wpm/2 to check if the post is less than 30 seconds so have
+  to assign it a variable before the check happens.
+{%endcomment%}  
+{%- assign wp30s = wpm | divided_by: 2 -%}
+
+{%comment%}
+  This is a simple reading time calculation is based entirely on the
+  number of words; Medium is more complex and counts images as well.
+{%endcomment%} 
+{%- assign words = text | number_of_words -%}
+
+{%- if words > 0 and words < wp30s -%}
+  {%comment%} if takes less than 30 secs, just say 30 secs {%endcomment%} 
+  {%- assign time = '30 sec' -%}
+{%- else -%}
+  {%comment%} otherwise, give reading time to nearest minute {%endcomment%} 
+  {%- assign time = words | plus: wp30s | divided_by: wpm | append: ' min' -%}
+{%- endif -%}
+
+{%comment%} give Medium-style output {%endcomment%} 
+{{ time | append: ' read' }}