Bold or italics? Single quotes or double? When should you use <mark>? Should code snippets have captions? Here I lay down some ground rules.

Guidelines

For lack of a better place, I've decided to put the style guide of my website here. I use the term not in reference to CSS "styling," but in the old-fashioned sense of a style guide—as you'd find at a publishing house or a newspaper. Here we're talking about what is called typography.

Note that these guidelines are for myself and reflect my own preferences (if not biases). But they may give you a good starting point for your own website. (For hints from others, see Notes & Resources.) The most important thing is that you be consistent and not stray so far from convention that you confuse or throw off your readers.

As I said, the kind of style I'm talking about here concerns typography--the appearance or presentation of text, as opposed to writing style (which gives advice on level of formality, the use of active or passive voice, etc.). Typography concerns the use of high-level textual tools such as italics, boldface and indentation. I do not mean the specific way in which these tools are implemented with font, font size and so on.

There are three different ways I could have arranged the material on this page: (1) according to the intention behind the textual tool (for example, "How to Indicate an Extended Quotation"); (2) according to the implementation of the intention ("Use of <blockquote>"); or (3) a hodge-podge of the first two, letting the topic and my own whimsy decide. I have chosen the third option.

Standard Print Conventions

Use standard book and magazine print conventions, except as contradicted elsewhere in these guidelines.

Italics & Quotes

This means that you use italics to refer to:

  • book, magazine and journal titles
  • names of movies and television shows
  • using a word as the name for that word (for example: "French has two verbs for the English verb to know—savoir and connaître.")

Use double quotes to refer to:

  • chapter and section names of books
  • titles of magazine and newspaper articles
  • titles of poems and songs

Use double quotes when quoting text from another source or what someone says.

For example:

"Stopping by Woods on a Snowy Evening" was first published in Robert Frost's New Hampshire collection of poems. He once described it as "my best bid for remembrance."

Capitalization

Use title case for:

  • web page titles

  • section titles (i.e., headers) (This is going against the modern trend, which is to capitalize only the first word.)

Bulleted Lists

For bulleted lists, follow standard convention regarding capitalization and the use of punctuation. That is, if the list item is a sentence, capitalize the first letter and put a period at the end. Otherwise, list elements should be all in lowercase and not end in a period (nor in a semi-colon).

Letters and Characters

Typographic convention surrounds letters in double quotes; for example, often in English first names, the boys' version ends in a "y" while the girls' ends with an "i". My suggestion is to follow this rule, except in a computer or programming context, where you should feel free to use single quotes (following the C++ and Java distinction between strings and chars).

Other Notes

Use &mdash; instead of one or two hyphens.

My friends—and I think of you all as friends—it is time we come to a decision.

Use <bold> for terms that are being introduced or explained for the first time. If the term falls into some other category that requires special formatting, use that other category’s formatting. For example, Unix-style commands should be enclosed in the <code> tag (see Code Snippets below), so if you are introducing the make command, it should be surrounded with the <code> tag and not be put into boldface.

Referring to Websites and Web Pages

Italics and Double Quotes

Use italics to refer to:

  • website names
  • website sections that contain multiple web pages (for example, the Miscellaneous section of Close to the Machine)
  • blogs (Compare this to "blog post titles" in the next bulleted list.)

Use double quotes to refer to:

  • titles of web pages
  • section names of web pages (i.e. headers)
  • blog post titles

In general, when referring to a web page you should provide a link. But feel free not to link to the web page under special circumstances. For example, if you're discussing a web page in a paragraph of text, and you provided a link when you first mentioned the web page--to put a link on every mention of the web page in the same paragraph would be unsightly.

Links to particular sections of other pages should link to bookmarks on the pages if at all possible. If it's not possible, use the form The "References" section of <link to page>.

If an item is a link and gets special typographic treatment for that reason, adding additional typographic styling is optional. Just be consistent. For example, on the issue of whether or not to put double quotes around the title of the newspaper article in this reference, either of these is correct.

Rachel Nuwer, "A Forgotten Step in Saving African Wildlife: Protecting the Rangers," New York Times, November 28, 2016

Rachel Nuwer, A Forgotten Step in Saving African Wildlife: Protecting the Rangers, New York Times, November 28, 2016

This rule applies to all typographic styling, not just double quotes. In other words, it also applies to italicizing book titles and newspaper names.

Whether you decide to add typographic styling to links will probably depend on at least these factors:

  • Whether or not you are going to print the page, and how the link will appear on the print out. If the link text won't appear any different from the text around it, you should add the typographic styling.

  • How dramatically different your links appear compared to the text around them in a browser. If your CSS is presenting the link text in a different color, you probably don't need additional styling. On the other hand, if the link appears in the same color, just underlined, you may decide to add the typographic styling as well. Again, just be consistent.

Machine Instructions: Computer Code, etc.

These guidelines apply to normal text, not section titles. In titles some of these guidelines result in HTML which is not pleasing to the eye. For exampe, using the <code> tag (the backtick in markdown) in a title results in text in which the spacing within the <code> tag is dramatically different from the spacing outside of it. In this case, I think, single quotes ought to be used instead of the <code> tag.

Code Snippets

Code snippets should be enclosed in either a <code> tag or in a <pre> block.

  • Use the <code> tag for short snippets. In markdown, you do this by surrounding the snippet in backticks.

  • Use <pre> for longer, multi-line snippets. In markdown, you do this by "fencing" the lines of code in with three backticks, one set at the start of the code snippet, and one set at the end.

The following markdown shows how these guidelines play out.

```
month = 'August'
day = '9'
date = month + ' ' + day
```
Or, in a single line of code: `date = 'August 9'`.

This markdown is generated into the following HTML:

<pre>
month = 'August'
day = '9'
date = month + ' ' + day
</pre>
<p>Or, in a single line of code: <code>date = 'August 9'</code>.</p>

Writing about Programming or Computers

Here we are not talking about code snippets. Here we're talking about text that is trying to describe how code and other software-related aspects of computers work. (Code in text)

Use the <code> tag for:

  • very short snippets of code (See Code Snippets above.)
  • variable names and variable contents (Or, optionally, you can use <var>. See <var> below.)
  • class names
  • HTML and XMl tag names
  • HTML entities like &mdash; etc.
  • UNIX-style shell command names as well as complete shell commands
  • file and directory names
  • the names of repository (e.g. Subversion and Git) projects and branches
  • sofware project names, Python and Java package names, etc.

The exception to these rules occurs when these elements are used inside a title or headline, where <code>-tagged words appear ungainly, in my opinion. In these cases I prefer single quotes.

Use ordinary type (that is, do not use the <code> tag) for:

  • names of software projects
  • programming language libraries
  • computer hardware
  • user-interface elements (See the next topic, below.)
  • method and function names (But do mark them up with an empty space inside parentheses after the name, as in the getId( ) method.)

For example:

One of the most useful commands is cut. This command will get you the third word for every line in a file: cut -d ' ' -f 3.

Use the <bold> tag for user-interface elements. (UI elements and interaction)

To view Firefox licensing details on a Mac, go to Firefox > About and click on Licensing Information.

Special HTML tags: <kbd>, <samp>, <var>

<kbd> is meant for user input; <samp> for computer-generated output. Use these HTML tags with discretion. On a web page that is technical in nature you might want to use them, but on non-technical web pages you may find that the use of double quotes is more appropriate. For example

Eliza is a famous early example of a chatbot. It had no real understanding of human input, and employed a strategy of repeating back to the user segments of the input to create the illusion of understanding. For example, if the user typed in I'm feeling down today, Eliza might respond with Why are you feeling down today?

The above example employs <kbd> for user input, and <samp> for Eliza's output. This is correct if the topic is Eliza's internal implementation, but if the focus of the topic is concerned exclusively with Eliza's external behavior, then double quotes may be better..

The <var> tag should be used for the names of variables. So far, I have not been able to find guidelines on the contents of variables. For the time being, at least, I've decided to signify variable content with the <code> tag, and to differentiate strings from other primitive types with double quotes.

For example:

month = 'August'


dayStr = '9'
date1 = month + ' ' + dayStr


dayInt = 9
date2 = month + ' ' + str(dayInt)
dayStr is set to "9". dayInt is set to 9. After this code is run, date1 and date2 have the same contents—"August 9".

When using these tags, feel free to style them yourself with CSS. Start with my own styling or that of any of the resources, and make modifications as you wish.

The <mark> Tag

It took me a while to find good advice on when to use the <mark> tag. (See below.) Generally, this tag can be used when you want to highlight part of a longer piece of text. This means that you'll most often use this tag within a block quote.

Use <mark> to indicate search results. For example, suppose you want to show what searching on luctus will return in the following Lorem Ipsum passage.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur malesuada arcu justo, nec luctus massa bibendum pretium. Integer cursus rhoncus nulla, vel imperdiet eros aliquam ut.

Similarly, use <mark> to highlight related words in a longer passage. Suppose you want to highlight all the words that end in -us in a Lorem Ipsum passage.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur malesuada arcu justo, nec luctus massa bibendum pretium. Integer cursus rhoncus nulla, vel imperdiet eros aliquam ut.

Use <mark> with discretion. To my eye, it looks rather garish on the page, and I would only use it in a technical, "computer-ese" context. In other contexts it may be more attractive to use the old-fashioned way of highlighting a portion of a longer passage—with italics and a parenthetical.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur malesuada arcu justo, nec luctus massa bibendum pretium. Integer cursus rhoncus nulla [emphasis added], vel imperdiet eros aliquam ut.

Another way of accomplishing the same thing:

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Curabitur malesuada arcu justo, nec luctus massa bibendum pretium. Integer cursus rhoncus nulla, vel imperdiet eros aliquam ut. (Emphasis mine.)

Indenting and <blockquote>

In print, indentation tends to be used for two purposes:

  • For extended quotations, or to highlight short quotations.
  • To separate an example from the text that describes or explains it.

On the Web, these purposes are usually served by the <blockquote> tag, which in markdown tends to be rendered by starting the line with the right angled bracket >.

Text enclosed in <blockquote> tags usually appears with a vertical bar running down the lefthand side of the paragraph. It is, however, permitted to use CSS styling to use traditional indentation for the purposes of extended quotation or separating examples from normal text, as long as you are consistent.

Notes & Resources

Google's "Code in text": https://developers.google.com/style/code-in-text

  • Offers a thorough list of computer-related items to put into <code> tags.

Bootstrap's "Code": https://v4-alpha.getbootstrap.com/content/code/

  • Offers advice on special tags like <kbd>.

Google's "UI elements and interaction": https://developers.google.com/style/ui-elements

  • UI elements to put into boldface.

Google's "Markdown syntax": https://developers.google.com/web/resources/markdown-syntax

  • While telling you how to do certain things in markdown, sometimes this page implicitly gives advice on presentation style.

Google's Developer Documentation Style Guide: https://developers.google.com/style/highlights

  • More of a writing style guide than on visual style.

AP vs. Chicago Manual of Style: https://apvschicago.com/2011/04/titles-quote-marks-italics-underlining.html

  • Most discussions of AP, MLA and the Chicago Manual of Style concern citation, which is not what what we're talking about here. But this page is talking about copyediting, and so it is relevant.

On the Use of the <mark> Tag

I did not know about this tag until I read that my website generator, Urubu, supports it. To understand the tag's purpose, Jan recommends a Stack Overflow page. However, I do not find this explanation at all helpful, especially since it provides no examples. (What does the contributer mean by "due to its relevance in another context"?)

After a frustrating search, I finally found a Mozilla page with good explanations and plenty of examples. But it led me to question Jan's use of the tag on the Start page of Urubu Quickstart. Personally, I think boldface would have been the better choice there.