Style Guide
This page lays out the site-wide styles and how to use them. It’s a form of visual documentation and a reference for how to display visual elements. It also allows easier testing of styles and cross-browser compatibility checks. This page was partially inspired by pages like gRegor Morrill’s style guide and some CSS framework documentation sites.
See the source of main.css for the complete styles. Custom shortcodes and other build customizations are defined in .eleventy.js and the imported files. Includes are defined in the /_includes directory.
CSS Units
Use REM units where reasonable with a base-2 sizing structure based on 4, 8, 16 or
- Use css custom properties for colors (for theming) and base styles. The most significant styles would be widths and margins that my need to be referenced elsewhere.
Headers
TODO: Describe the primary header and define a secondary heading option for the
Typeography
Currently the site uses the Roboto font but the ultimate goal is to move to primarily system fonts. Headings each have their own size. To allow for flexibility while retaining semantic accuracy, there should be a class to override heading styles.
Heading Level 1
Heading Level 2
Heading Level 3
Heading Level 4
Heading Level 5
Body text example: Adventures of Huckleberry Finn
You don’t know about me without you have read a book by the name of The Adventures of Tom Sawyer; but that ain’t no matter. That book was made by Mr. Mark Twain, and he told the truth, mainly. There was things which he stretched, but mainly he told the truth. That is nothing. I never seen anybody but lied one time or another, without it was Aunt Polly, or the widow, or maybe Mary. Aunt Polly–Tom’s Aunt Polly, she is–and Mary, and the Widow Douglas is all told about in that book, which is mostly a true book, with some stretchers, as I said before.
Now the way that the book winds up is this: Tom and me found the money that the robbers hid in the cave, and it made us rich. We got six thousand dollars apiece–all gold. It was an awful sight of money when it was piled up. Well, Judge Thatcher he took it and put it out at interest, and it fetched us a dollar a day apiece all the year round–more than a body could tell what to do with. The Widow Douglas she took me for her son, and allowed she would sivilize me; but it was rough living in the house all the time, considering how dismal regular and decent the widow was in all her ways; and so when I couldn’t stand it no longer I lit out. I got into my old rags and my sugar-hogshead again, and was free and satisfied. But Tom Sawyer he hunted me up and said he was going to start a band of robbers, and I might join if I would go back to the widow and be respectable. So I went back.
Special Text
Text can be strengthened, emphasized, or even made smaller. In markdown quotes in “quoted text” are stylized to highlight the begining vs the end.
Links
Links in paragraph are styled to increase readability and make it clear they are links. This includes different colored text and underlining, though bold text has been considered. Links should ideally contain multiple word for increased readability.
In navigation sections, links aren’t blue, but their linkyness should probably be emphasized with underlining, at least on hover.
Images


There are several ways to display images. Above is shown the wide orientation which goes as wide as the text is allowed.
Floated content is also possible and it will wrap around the floated image. However this can lead to situations where later headings also begin to wrap.
To prevent further text from wraping around the image use a clearfix. Also note that images need an empty line above and below in markdown to be rendered correctly.
<div style="clear:both;"></div>

float: right
Captions support markdown syntax but be careful with quotes in alt text. You can use the “stylized” quotes to fixt that. Below is a default width image with a caption. It uses the .post-img--wide
class name.
{.post-img--float .post-img--float-right}

Lists
Unordered
- Item one
- Item two
- Subitem A
- Subitem B
- Item three
Ordered
- Fist item
- Second item
- Two point one
- Two point two
- Two point three
- Two point three one
- Third item
Quotes
Text in a <blockquote>
“Say, who is you? Whar is you? Dog my cats ef I didn’ hear sumf’n. Well, I know what I’s gwyne to do: I’s gwyne to set down here and listen tell I hears it agin.”
—Mark Twain, “Adventures of Huckleberry Finn”
Code Blocks
Currently using highlight.css to style code. Markdown’s inline code references <div>example</div>
are not syntax highlighted.
const trimTime = (dateInput) => {
const date = new Date(dateInput); // Parse date in case it is a string
return new Date(date.getFullYear(), date.getMonth(), date.getDate());
};
Sometimes HTML shows up unexpectedly as code blocks due to indenting, sometimes hidden by liquid pre-processing. This can be escaped using a custom removeindents
shortcode.
{% removeindents %}
<div>
<p>Accidentally indented</p>
</div>
{% endremoveindents %}
Horizontal Ruler
The following is an <hr>
tag which can also be defined in markdown with three dashes (---
) on their own line.
Embed links
These are inspired by Medium’s approach to linking to external content. It shows a preview of the title, text, and featured image which acts as a link.
{% include "embed-link.html"
title: "Blue-throated Motmot"
url: "https://ebird.org/species/bltmot1/"
description: "Scarce inhabitant of highland forests in Chiapas and south to Honduras. Found in humid pine and evergreen forest, perching at all levels. Like other motmots, rather inactive a…"
img: "/assets/img/embed-thumbnail-blue-throated-motmot.jpg"
alt: "green bird with bright blue throat and a long skinny tail"
%}
Aside
These need to be formalized but they are usefull for calling out the context of an article. So far I’ve added inline styles since I want them to appear in RSS readers.
<aside style="padding: 16px 0;font-size: 1.1em;border-top: medium double #333;border-bottom: medium double #333;margin: 32px;font-style: italic;">
This post is part of a series describing our trip to Italy. To read an overview of our trip and why we went, check out this <a href="/blog/2019/11/27/we-traveled-to-italy/">introductory post</a>.
</aside>
Forms
Forms are designed for one column. Buttons can be used outside of forms, but should ideally only be used for actions (not links).
Recipes
TODO: Example shortcodes
Post previews
Posts can be summarized and shown in feed pages or as suggestions below other posts.
Recent articles
{% include "post-card.html" post: nextPost %}
Different post types appear differently
Pagination
For paginated pages, you can show pagination links at the bottom.
{% include "pagination.html" %}
Footer
TODO: Describe the footer below.