Skip to content

Latest commit

 

History

History
94 lines (58 loc) · 7.46 KB

README.md

File metadata and controls

94 lines (58 loc) · 7.46 KB
Raw

TakeOnRules Hugo Theme

This Hugo began as a fork of the Hugo Tufte theme.

Since that time, I've made extensive changes, and consider this to be it's own theme.

You can see this template at Take on Rules. Note: To someone adopting this theme whole-cloth, there's a few pieces in my private repo that I also leverage. If you are interested, contact me and I can help.

For colors, I've adopted the palette from Protesilaos Stavrou's Modus themes; The colors are WCAG compliant and bring me a bit of joy.

ExampleSite

No care has been taken to update the exampleSite; I have, however, uploaded a re-dacted copy of my config.yml; Hopefully that helps with working through the site.

Semantic Markup and Linked Data

I strive for semantic markup; My goal is that I create an accessible site. Also, as a benefit, if you disable the stylesheet the page will continue to render in a meaningful way. In fact, I encourage you to disable the stylesheet on most sites and see how they look.

I also include inline Linked Data, using the RDFa format. I'm looking to provide machine-readable context which others can query; This also means that when I say "I'm writing about Stars without Number", I link to a disambiguator (e.g. Wikidata) to confirm "This is the Stars without Number" I'm writing about.

I had previously tried JSON+LD which may be more machine readable, but I found that this meant the Linked Data was separate from the associated HTML nodes that it represented. I didn't like that.

Partials

There are several partials that help build; Some rely on data files in my private repository. Others help manage paragraph structures for content passed as markdown.

Paragraph Management

The three primary paragraph management partials are:

  • unparagraphy.html :: ensures that the partial does not return wrap the content in a P-tag. In otherwords, useful for ensuring inline content (see display CSS Flow Layout).
  • paragraphy.html :: sibling to unparagraphy.html, this partial ensures that the returned content'a top-level DOM nodes are P-tags. Useful for ensuring block content.
  • smallParagraphy.html :: sibling to paragraphy.html, this partial ensures that the top-level DOM nodes are block display elements, and the children of those elements are wrapped in small tags. This is useful for marginalia (e.g. side comments).

Dates and Tags

  • dates-and-tags.html :: Each post has a published date and a last modified date. I also tag each post I write with a variety of tags. This partial helps create a uniform date and tag inline HTML. This partial also helps add RDFa metadata to the tags.

Shortcodes

Similar to partials, I leverage several shortcodes to help manage my content.

Marginalia

  • sidenote.html :: this shortcode creates an inline numbered sidenote in the margins; It uses the unparagraphy.html.
  • marginnote.html :: this shortcode creates a block margin note. It uses the smallParagraphy.html.
  • marginfigure.html :: a shortcode to ensure well formed images in the marginalia.

Semantically, I don't treat these as an ASIDE; Though I do add the dom attribute role="note". I have found that reader plugins don't render an aside, and I consider the marginalia important to the document.

Two other shortcodes (table.html and update.html) provide marginalia options. See below for more on these two shortcodes.

Cite Page

  • citePage.html :: A shortcode to conditionally generate a cite a or a tag to the page at the given filename (relative to the Hugo content directory). Note: I use tor-page-relative-pathname-list to generate a list of all the filenames.

Glossary

Throughout TakeOnRules.com, I make extensive use of a glossary. I use this markup to improve the accessibility of my site.

  • glossary.html :: Creates consistent markup for referencing a glossary entry.

The glossary.html shortcode uses the data/glossary.yml file as a database. I wrote about the Glossary in Many Small Tools Make Light Work (in Emacs).

Data Dictionary

Each glossary entry must have two keys:

  • key: This is how you look them up; this is human understandable
  • title: This is how you will most often refer to the thing; this is human readable and how you'd write it out in a sentence

There additional optional keys are as follows:

  • verbose_title: This is the lengthier title; you know, if there's a colon/subtitle in play use that.
  • plural_title: The pluralized title.
  • mention_as: If for some reason we don't always want to use the title, the mention_as is a replacement.
  • tag: If this entry represents a tag, this will be the tags name.
  • itemid: If this entry has a "sameAs" itemprop value, that will be the itemid (e.g. how to disambiguate)
  • abbr: When we provide an abbreviation, use this for the innerHTML of the abbr tag.
  • plural_abbr: The pluralized abbreviation.
  • offer: The URL where the thing is on offer (e.g. where you can buy it or borrow it).
  • game: Indicates that this thing is a game, useful for the linkToGame yasnippet.
  • content_disclaimers: (Array) Indicates that this entry has some associated content disclaimer.
  • itemtype: The schema.org itemtype for this entry.
  • description: Similar to note, treat as ohitemprop="description".
  • described: A boolean. When true the given glossary entry has already been described; don't attempt to fetch the description from Wikidata.

Other Stuff

  • table.html :: Helps ensure a well-formed table; one parameter allows for table rendering in the margins.
  • ogc.html :: I sometimes write Open Game Content (OGC), released under the Open Game License (OGL). This shortcode helps wrap that content.
  • blockquote.html :: I quote sources, and this shortcode helps create well-formed quotes; I also repurpose it for epigraphs.g One of my favorite books is Dune by Frank Herbert. Dune introduces each chapter with an epigraph. I like that style, and on occassion use that.
  • update.html :: a shortcode that helps create consistent document updates, via the INS-tag. One parameter allows for updates rendered in the margins.
  • maincolumn.html :: a shortcode to help render an image in the maincolumn.