A work in progress…
A Jekyll site based on the minima theme (version 2.5.1). (The dependence on the gem theme has been overridden, so updates to minima will have no effect on Minimag.)
This repo is designed for development within a Docker container.
The initial construction of this site follows Bill Raymond’s YouTube video “Draft training - Run GitHub Pages in a Docker container,” which was a draft and unlisted as of April 2, 2023.
One departure of Minimag from minima is the implementation of a “card” presentation, including an illustration, for each post’s entry on posts-listing pages. A card has the following elements:
-
An image component
-
A text component, made up of subcomponents
- Post title
- Post excerpt
- Post date (The last-updated date)
- Post author
-
A “featured post” will have a horizontal card format such that the image will occupy the top of the card, and the text elements will appear below the image
- All featured-post cards will be the same width, and narrow enough so that on a desktop display, multiple cards will typically span a row of cards for featured posts.
-
The posts in a list of not necessarily featured posts will have a vertical card format such that the image will occupy the left part of the card, and the text elements will appear in the right side of the card.
- Each vertical-format card will span the full width of the display.
In its out-of-the-box configuration, the URL for a post 2023-04-02-welcome-to-jekyll.markdown
is simply /welcome-to-jekyll
.
This is in contrast to the default behavior of, the built-in theme minima, where the URL for a post encodes the post’s date and categories. E.g., when the categories are “jekyll” and “update”: /jekyll/update/2023/04/02/welcome-to-jekyll.html
.
This decision for Minimag was made primarily to allow the date of a post to be updated without changing its URL.
Note: This decision implies that posts now share the same namespace as pages, so there is the possibility of collisions. Names of posts and pages must be chosen to avoid such a collision.
Related to this: The _posts
directory is now flat: there are not spearate folders by date and/or category.
More flexibility in defining header structures and allowing for different header structures for different pages/posts
The original default layout assumed:
- that all posts and pages would have the same header/navbar structure
- that the navbar element was always the topmost element of the page, preventing a banner graphic appearing above the navbar.
In Minimag, the default layout is less opininated about the header. The structure of the header is now not defined by the default layout but rather by each other layout that inherit from default. This gives greater flexibility, for example, in placing the navbar either above or below a header banner and/or having a different header structure for, for example, the home page than a post page.
├── _includes
├── _layouts
├── _pages
├── _posts
│ └── 2023-04-02-welcome-to-jekyll.markdown
├── _sass
├── about.md
├── assets
│ ├── images
│ │ └── posts
│ │ ├── 2023-04-02-Oakland-Bay-Bridge-east-span-photo-1575649212494-720dd18f9c35.avif
│ ├── main.scss
│ └── minima-social-icons.svg
└── index.md
By default (due to a setting in _config.yml
), every post will inherit the layout post.html
.
Thus it is not necessary to include layout: post
in the front matter of a post.
There are three types of images for posts: (a) card-image
, (b) top-image
, and (c) interior images. Types (a) and (b) require special attention in the post’s front matter; type (c) does not.
card-image
- An image associated with a particular post to be displayed in the card for that post on a posts-listing page, such as the home page, a category listing page, or an archive page.
- To assure uniformity across posts’ cards, there will be a fixed aspect ratio that applies to all posts’ cards and their images.
- The displayed image will be displayed with
object-fit: cover
, because this (a) does not distort/skew the image’s native aspect ratio and (b) completely fills the alloted space without letterboxing. (See Jim Ratliff, “How the object-fit CSS property works: Comparing the various values,” CodePen.)
- The displayed image will be displayed with
- To assure uniformity across posts’ cards, an image will be displayed in each post’s card, even if the post does not specify a
card-image
. - The post-card image displayed depends at least on the value of
card-image
. Ifcard-image
is- specified, the specified image will be displayed
default
, the default post-card image will be displayed- Note: Although this is the default behavior even when
card-image
is unspecified, specifyingdefault
can have an effect when the post does have a specification fortop-image
. In this case, specifyingcard-image
asdefault
prevents the specifiedtop-image
from being displayed in the post’s card.
- Note: Although this is the default behavior even when
- unspecified:
- If a
top-image
for the post is specified,- that image is used in the post’s card
- Otherwise:
- the default post-card image will be displayed
- If a
top-image
- An image displayed at the top of a post.
- An image in this location requires special attention in the front matter of the post because this image will appear prior to the content in the post file. This requires the file name of the image to be passed to
_layouts/post.html
so that the image can be rendered in the header portion of that layout.
- An image in this location requires special attention in the front matter of the post because this image will appear prior to the content in the post file. This requires the file name of the image to be passed to
- There is no aspect-ratio constraint for a
top-image
. Its full height will be displayed at the top of a post, and the remaining content of the post will begin immediately below the bottom of thetop-image
. - A
top-image
is not mandatory. Thus,- If a
top-image
is specified, it is used at the top of the post. - If a
top-image
is not specified, an image is not displayed at the top of the post.
- If a
- The top image also has an associated, optional,
top-image-caption
.
- An image displayed at the top of a post.
- Interior images
- These are images displayed in the body of a post.
- These don’t require special attention in the front matter, because the image is rendered within the content of the post’s file.
Usage notes:
- Ideally, whatever image plays the role of
card-image
should have a native aspect ratio close to that of the frame in the card into which it must fit. - If the same image should be used for both
card-image
andtop-image
, it is sufficient to specify that image fortop-image
, and leavecard-image
unspecified. In that case the image fortop-image
will be chosen forcard-image
.
It is intended that images used only in particular posts should be located here:
assets/images/posts
config.yml
now defines two related variables:
url_images: "/assets/images"
url_post_images: "/assets/images/posts"
See the post 2023-04-06-displaying-interior-images-with-markdown.markdown for ways that an image can be included in the interior of a post using Markdown syntax:
This site structure is available as open source under the terms of the MIT License.
- v0.0.1, April 2, 2023
- Essentially identical to the default, built-in minima theme, except that theme is frozen at version 2.5.1.
- Configured for development within a Docker container.
- v.0.0.2, April 4, 2023
- Sets the locale (and UTF-8) for Docker container
- v.0.0.3, April 4, 2023
post.html
is now the default layout for posts. (No need to specify in front matter of a post.)- URL of a post is now simply the sluggified title; URL doesn’t encode the data or any categories. Ditto for the
_posts
directory: it’s flat.
- v.0.0.4, April 6, 2023
- Refactored default layout to be less opinionated. Original default layout assumed that all posts and pages would have the same header/navbar structure. This decision has been moved out of the default layout, into the hands of the other layouts that inherit from default. This gives greater flexibility (a) in placing the navbar either above or below a header banner and (b) to having a more-expansive branding banner image on a home and/or listing page but a smaller branding image on a post page (so as not to distrct from the post-specific featured image).
- Created
site.description_for_display
inconfig.yml
to leavesite.description
exclusively for the jekyll-seo-tag plugin. - Created assets/images/posts directory to be used for storing all images that are specific to particular posts.
- Added an
updated
datetime for posts (though it still needs to be implemented on each post) and it not yet connected to any sorting functionality. - Added an example post that shows ways to display an interior image (i.e., within a post’s content) using Markdown syntax.
- v.0.0.5, April 9, 2023
- Moved the
<nav>
landmark role, which had been nested within the banner landmark role,<header>
, to an independent top-level role.- There’s an accessibility argument for this.
- The navbar has been removed from
_includes/header.html
and into its own_includes/nav-role.html
.- This gives greater flexibility is placing the navbar either above or below a header banner.
- The navbar no longer automatically populates with all pages.
- Instead, you manually populate, in
_includes/nav-role.html
, the list items you want to be represented on the navbar.
- There is no longer a logo or site title reference in the navbar.
- See
_includes/header_A.html
for how (a) a standalone strip for the site title and/or a logo and (b) the navbar can be separately included in either order.
- See
- Moved the
- v.0.0.6, April 10, 2023
- Add ability to specify an image in the front matter (
top-image
) to be displayed at the top of each post (above the post’s title). You can specify alt text withtop-image-alt
.- Optionally, specify text (
top-image-caption
), which can be multi-line, to appear directly below the top-image as a caption.
- Optionally, specify text (
- Add ability to specify an image in the front matter (
- v.0.0.7, April 10, 2023
- Add CSS custom property (--nav-toggle-label-vertical-offset-fudge-term) to adjust the vertical position of the “hamburger” navicon.
- v.0.0.8, April 11, 2023
- Style .table-of-contents
- Pending
I should probably use either Google or DuckDuckGo. See “The easiest search option for Jekyll,” WebJeda, July 18, 2016.
Minimag inherits from minima the jekyll-seo-tag plugin. From README_minima.md:
Minima comes with
jekyll-seo-tag
plugin preinstalled to make sure your website gets the most useful meta tags. See usage to know how to set it up.
The usage docs for jekyll-seo-tag identify a large number of site-wide variables that this plugin will exploit when they’re present, including title
, tagline
, description
, url
, author
, twitter
(including twitter:card
and twitter:username
), facebook
(and associated properties), logo
, social
(and associated properties), google_site_verification
, and locale
.
At the page/post level, tThe SEO tag will respect the following YAML front matter if included in a post, page, or document:
title
- The title of the post, page, or documentdescription
- A short description of the page's contentimage
- URL to an image associated with the post, page, or document (e.g.,/assets/page-pic.jpg
)author
- Page-, post-, or document-specific author information (see Advanced usage)locale
- Page-, post-, or document-specific locale information. Takes priority over existing front matter attributelang
.
Note: Front matter defaults can be used for any of the above values as described in advanced usage with an image example.
Questions:
- Since one of my personal use cases is to use this blog as a complement to a main site (i.e., being accessed by visitors at TLD/blog, via Cloudflare workers after being served directly at blog.TLD subdomain), I have to consider how much of this plugin’s site-wide function conflicts with what I’m already (or should be) doing on the main site.
- Is the post-specific SEO stuff worthwhile? Doesn’t Google do a good-enough job on this?