Introducing Tufte for Micro.blog

My testing site will finally be able to take a well-deserved vacation…

I’m extremely excited and happy to announce Tufte for Micro.blog is complete and ready to share with the community. This is my first ever online software release of any kind, and with luck it won’t be the only theme I bring to the platform. Not only is it a great feeling to share this with fellow Micro.bloggers to enjoy, but I had so much fun learning and working on this project. There couldn’t be a more fitting inaugural release for me than this grail theme I’ve wanted to use for so long. So, without further ado it’s time for a walkthrough of Tufte.

What is Tufte?

A clean and beautiful theme based on the design and typography styles of Edward Tufte. Based heavily on the Tufte-CSS project by Dave Liepmann with my own tweaks and additions for Micro.blog, and ported from the Hugo-Tufte theme by SlashForMotion.

Features

• Well spaced main content with use of sidebar elements for figures, margin notes, and sidenotes instead of footnotes, and plenty of whitespace
• Dark mode version
• Hugo shortcodes for various elements:
  • blockquote
  • cite
  • div
  • epigraph
  • figure
  • marginnote
  • newthought
  • section
  • sidenote
  • summary
  • poetry
• Fully styled Micro.blog conversation elements
• Poetry styling!
  • “poetry” shortcode creates a <pre><code> block with the poem text
  • css styles the block with normal et-book text to look like a normal post but maintains indents and line returns
  • css also removes the horizontal scroll of long lines, instead word-wrapping normally at whitespace depending on screen width
• Added customizable site subtitle in config.json
• Added mailto: address in config.json, and auto includes “Reply by email” link at the bottom of each post
  • subject will automatically include the title if one is available, otherwise will include the permalink

Shortcode Usage

All of these shortcodes use the standard Hugo syntax of {{< name >}} to open and {{< /name >}} to close. Some of them use inner parameters in addition to text between the open and closing blocks.

Note for Ulysses: shortcodes need to be opened and closed by adding a tilde (~) on each end, which tells the software to keep it as raw source. - Credit to @moondeer on Micro.blog for this tip!

Blockquote & Epigraph

Blockquote is a shortcode version of the standard Markdown blockquote option, except it provides parameters to add attribution information to the quote:

• pre: name.
• cite: attribution source.
• link: creates a link to the website using the cite value as the URL label
  • Note: due to how Hugo handles external URLs, the link must be entered without the http(s): portion, instead only using //site-name/link/ (see example below)
• post: optional to add trailing attribution info after the cite, such as page number references

Epigraph uses the same parameters but these are used to highlight special passages or quotes either within or at the beginning of an article, or even a quote style post. They are formatted in slightly smaller and italic text as opposed to blockquotes which are only indented. Think of the epigraph as the Tufte equivalent of pullquotes.

Code example:

{{< blockquote pre="Person's Name" cite="Site Name" link="//example.com/link/" >}}blockquote text goes here{{< /blockquote >}}

Blockquote Result:

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Varius sit amet mattis vulputate enim nulla. Amet risus nullam eget felis eget nunc lobortis mattis. Et magnis dis parturient montes nascetur ridiculus mus mauris vitae. Sed ullamcorper morbi tincidunt ornare massa eget. Vitae ultricies leo integer malesuada. Nec dui nunc mattis enim ut tellus elementum. Varius duis at consectetur lorem donec. Mauris rhoncus aenean vel elit scelerisque mauris pellentesque pulvinar pellentesque. Dictum fusce ut placerat orci nulla pellentesque dignissim. Habitant morbi tristique senectus et. Non nisi est sit amet.

Epigraph Result:

Cite

This does the same thing as the parameter version, except it can be run as its own separate shortcode. It will format the text in smaller italics.

Code example:

{{< cite >}}cite name here{{< /cite >}}

Div & Section

These are shortcodes used to code <div> and <section> blocks, and can use the ‘class’ and ‘id’ parameters. To close the block, use {{< div "end" >}}.

Code example:

{{< div class="class_name" id="id_name" >}}
	/* block content */
{{< div "end" >}}

Figure

Allows the insertion of figures into your article, and uses three different formats:

• regular - same as the article text width
• full - takes up the full body width including the side margin
• margin - places the figure and image in the margin, and treats it as a marginnote

The full and margin options are specified using the ‘type’ parameter, otherwise it will use the regular width if the type parameter is not present.

Figure also uses the following paramaters:

• title: the figure title in bold
• caption: the figure caption text
• alt: the image description
• label: the unique figure label text (this is for the marginnote toggle to work properly)
• src: the url of the figure image
• attrlink: the attribution link URL
• attr: the link label for the attribution

Code example:

{{< figure src="https://example.com/link-to-image" alt="description" type="margin" title="Title text" caption="caption text goes here" label="unique label text" >}}

Result:

⊕ Margin Figure This is an example of a margin figure.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Varius sit amet mattis vulputate enim nulla. Amet risus nullam eget felis eget nunc lobortis mattis. Et magnis dis parturient montes nascetur ridiculus mus mauris vitae. Sed ullamcorper morbi tincidunt ornare massa eget. Vitae ultricies leo integer malesuada. Nec dui nunc mattis enim ut tellus elementum. Varius duis at consectetur lorem donec. Mauris rhoncus aenean vel elit scelerisque mauris pellentesque pulvinar pellentesque. Dictum fusce ut placerat orci nulla pellentesque dignissim. Habitant morbi tristique senectus et. Non nisi est sit amet.

Mauris rhoncus aenean vel elit scelerisque mauris pellentesque pulvinar pellentesque. Dictum fusce ut placerat orci nulla pellentesque dignissim. Habitant morbi tristique senectus et. Non nisi est sit amet.

Sidenote & Marginnote

These both place notes in the side margin, except in the case of sidenote it will add a sequential number to each one just like footnotes normally do. These both use an inner unique label to identify the note.

Code example:

{{< sidenote "label text" >}}sidenote text goes here{{< /sidenote >}}

Result:

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Varius sit amet mattis vulputate enim nulla. This is a numbered sidenote that is Tufte’s version of a footnote. Amet risus nullam eget felis eget nunc lobortis mattis. Et magnis dis parturient montes nascetur ridiculus mus mauris vitae. Sed ullamcorper morbi tincidunt ornare massa eget. Vitae ultricies leo integer malesuada. Nec dui nunc mattis enim ut tellus elementum. Varius duis at consectetur lorem donec. ⊕ This is a margin note that is a perfect way of highlighting asides or interesting thoughts… Mauris rhoncus aenean vel elit scelerisque mauris pellentesque pulvinar pellentesque. Dictum fusce ut placerat orci nulla pellentesque dignissim. Habitant morbi tristique senectus et. Non nisi est sit amet.

Newthought

This is a span of small cap styled text that can be used to highlight the start of sections.

Code example:

{{< newthought >}}Here is the start of a section{{< /newthought >}} that is using the newthought shortcode.

Result:

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Varius sit amet mattis vulputate enim nulla. Amet risus nullam eget felis eget nunc lobortis mattis. Et magnis dis parturient montes nascetur ridiculus mus mauris vitae. Sed ullamcorper morbi tincidunt ornare massa eget.

Summary

This shortcode is used to add a post synopsis or summary to longer, titled essay style articles. It’s used in conjunction with a ‘more’ divider that will display only the summary on the index page followed by a link to read the article in full.

Code example:

# Post title

{{< summary >}}This is the post summary text that will be displayed by itself on the index page.{{< /summary >}}<!--more-->
/* post content starts here */

Result:

See the top of this post for the summary style in action!

Poetry

The poetry shortcode is an optional coding shortcut that can be used for poetry writing that maintains line returns and tab spaces for unique poem formatting. It puts the text content into a code block, but then changes the styling to match the ET-book serif font that all articles use. It will also perform word wrapping at whitespaces between words (dependant on the screen width of the device). Note: This works in Drafts, but I haven’t been able to get it to work properly in Ulysses yet. If anyone knows how please feel free to open a pull request on GitHub.

Code example:

{{< poetry >}}
Now is the time
	for all good men
		to come to the aid of the party
{{< /poetry >}}

Result:

Now is the time
for all good men
to come to the aid of the party

URL Slug Control

Micro.blog is unique in how it handles URL slugs, normally capturing the first three words of the title or article text. However, when writing a title-less short-form post in Tufte that starts with a shortcode, such as epigraph or blockquote for a quote style post, or poetry, the shortcode text itself gets picked up as one of the URL slug words. To get around this, you can use a hidden paragraph html tag with the slug title you want to use. Note: M.b. will still use only the first three words.

Code example:

<p hidden>slug title here</p>
{{< epigraph pre="Charles E. Weller" >}}Now is the time for all good men to come to the aid of the party.{{< /epigraph >}}

Mobile Sidenote/Marginnote Expansion

On smaller mobile screens the sidenotes, marginnotes and margin figures will be replaced with a tappable button that toggles their display. For sidenotes, tapping the number will toggle it, while marginnotes and figures will be identified by a ⊕ symbol.

Credits

• Dave Liepmann - Tufte-CSS project
• SlashForMotion - Hugo-Tufte theme
• Leon Paternoster (@leonp on Micro.blog) for his numerous excellent posts on font spacing, typography, and legibility
• Jason Cardwell (@moondeer on Micro.blog) for his Ulysses tip for shortcode handling
• Manton Reece (@manton on Micro.blog) for creating the Micro.blog platform

How To Install Tufte & More Info

Tufte is now available in Micro.blog as a plug-in! Upon installing it, you also have to go into “Design” and select “Blank” instead of one of the built-in themes. Afterwards, be sure to edit the config.json file and change the “subtitle” and “mailto” variables for your blog and email address.

The official site for the theme is on GitHub, so feel free to check it out for screenshots and more information.

I sincerely hope you enjoy Tufte.

Cheers!
-Pete