Markdown Formatting

The way a blog styles content can have a direct impact on its success. Text needs to be legible, pleasing to the eye, and—if possible—it should match the subject matter in a way that feels natural to the reader. This post examines the way this site’s theme processes and renders the basic markdown files that contain its content to (hopefully) meet those needs.

Headings organize content (h2)

The various heading levels will be used in this document to display how they interact with content. Only heading levels 2–6 are formatted, as the site automatically displays the title of a page (set in the YAML frontmatter) as a H1 element and only one H1 should be present on any page. Having more than one can cause issues for some accessibility software.

Table of Contents (H3)

On screens large enough to display sidebars, the right side normally displays a collection of off-site links. This can optionally be replaced with a table of contents with links to each heading on the page. If the browser supports it, the ToC will slide down to remain on screen as you scroll as well. The ToC is optional on posts (set through YAML frontmatter) and is turned on for Projects by default.

Note that the ToC only includes H1–H4 items. While H5–H6 are available, they are left out of the ToC to keep it from becoming unwieldy.

Example H5

This is just an example as this heading level wasn’t otherwise required for this document. You would not normally want to use headings out of order like this.

Example H6

This is just an example as this heading level wasn’t otherwise required for this document.

Styling Markdown

The most basic level of styling at play here is the differences in heading sizes and font styling and the spacing around the various page elements. Paragraph spacing might be easily disregarded, but it is possibly the most critical concern when prsenting a body of text.

Spacing & Line Breaks

As you can see, some space is left between paragraphs automatically. This can be overriden however, so that one body of text immediately follows the last, by way of a line break. A line break is created in markdown by including two spaces directly after the last sentence of a paragrap and then starting the next paragraph on the next line.
This is a second paragraph following a line break.
This is a third.

Simply go back to leaving no spaces at the end of text, and including a new-line between paragraphs, to return to normal spacing when you are done using line breaks.

Text Variety

In addition to block items, markdown includes support for styling individual words, or collections of words, to cause them to stand out or to impart semantic importance. on them. Bold Text is supported, as is Emphasized Text and Monospaced Text. Kramdown extends this to indlude Struckthrough Text as well.

Links

Markdown supports hyperlinking, and the liquid templating of the site includes some features that make it easier to target specific local pages regardless of their url on the production site.

Reference Links (H4)

You can define a link in one place (see below) and then reference that link anywhere else using the correct markdown.

Footnotes

You can also include footnotes¹. This allows for further explanation of things to appear at the bottom of pages.

Abbreviations

Similar to footnotes, abbreviations allow you to create a tooltip to further define a thing. The additional text appears when hovering the cursor over the abbreviation. You get the information without having to scroll for a footnote but without the option to format it with additional markdown.

Block Elements

There are a number of ways you might want to style a block of text. Markdown and Kramdown provide automatic support for quotes and code.

Horizontal Rules

You can use three dashes into insert an HR to further divide content.

These are colored differently than the lines that appear around structural elements like the Recommendations or under some headings. Do consider using this sparingly, however.

Block Quotes

Having a way to identify something as a quote is important. The site theme also makes use of this same stylying on the category pages.

You can include a block quote by proceeding the line with an arrow. Kramdown extends this by allowing you to include a title after the quote that will display when the cursor hovers over the block.

Block quotes can be nested. This one is nested, but the theme doesn’t currently treat a nested quote any differently than a regular one. This may be something that I want to address later.

Code Blocks

This site won’t have much use for traditional code blocks, but formatting a block of text in a monospaced font might be useful someday.

You can do this by placing four spaces before the start of a paragraph, or by "fencing" the block.

CSS Classed Blocks

Kramdown also makes it possible to assign a CSS class to a block of text. This site may use some specialized classes to identify text as a sidenote or important information, but in this example the text color is being changed simply by applying a class from the Tailwind CSS framework that the site uses for styling.

Lists

Formatting lists is important, as having several kinds of lists available will make it easier to idenitfy information. Markdown supports orders and unordered lists. Kramdown provides access to “Github style” task lists as well.

Ordered Lists

1. ordered..
2. lists..
3. are..
4. supported.

Unordered Lists

• unordered..
• lists..
• are..
• too.

Task Lists

• checked item.
• checked item.
• checked item.
• unchecked item.
• unchecked item.

List items with multiple lines.

You can also put another element in a list item, like a second paragraph, by proceeding it with 4 spaces.

• List item.
• List item.
  This is a paragraph inserted into a list item.
• List item.
• List item.
• List item.

Tables

So here we are, looking at a table. I’m adding this text just to show how it interacts with a proceeding paragraph.

This shows how a pragraph following a table is formatted in relationsip to it.

Images

You can also place images in a document. Here is the default way an image is included.