My Web Post Style Guidelines

created May 26, 2019

I've been using Textile, since 2005 and Markdown/Multimarkdown since 2013, but over the past three years, I have used Markdown (not Multimarkdown) as my primary markup language.

For some formatting options, Markdown provides multiple methods to complete the tasks. I have settled on the following, which makes the description below my standard for formatting web pages here.

Headers


I use the pound sign method.

# Heading One Used Only for the Page's Title
## Heading two used rarely as a sub-title
### Heading three used often
#### Heading four used rarely

Links


[My Web Post Style Guidelines](http://sawv.org/2019/05/26/my-web-post-style-guidelines.html)

Or make the URL clickable:

<https://daringfireball.net/projects/markdown>

Images


![our dog Barney with his winter hairdo](https://c1.staticflickr.com/5/4343/37245534185_de744fcc17_q.jpg)

Horizontal rule


I use three hyphens.

---

Markdown, however, provides multiple ways to produce the horizontal rule, like it does with other formatting options. Three asterisks is an option. Since I prefer to use the asterisk option for unordered bullet point lists and for bolding and italicizing text, I should probably switch to using asterisks to create the horizontal rule too.

Lists


I use the unordered lists often, and I use the asterisk method.

* bullet point one
* bullet point two
    * bullet point two-A
    * bullet point two-B
* bullet point three

I rarely use numbered or ordered lists, but when I do, I use the numeral version in this manner.

1. Cleveland Browns
1. Baltimore Ravens
1. Pittsburgh Steelers
1. Cincinnati Bengals

Emphasis


For italicizing, I wrap single asterisks around the text.

This is a test sentence with *italicized text* in the middle.

For bolding, I wrap double asterisks around the text.

This is a test sentence with **bolded text** in the middle.

Blockquote


Markdown only provides one method.

> This is a blockquote paragraph.

> > This will be a blockquote within a blockquote

> And back to a normal blockquoted paragraph.

Code


For inline code, Markdown wraps the single backtick character around the text that is meant to be displayed as code.

For code blocks, I use Markdown's default behavior.

    I indent four spaces to make a code block.
    I created my own code block or fencing command,
    but that is custom to my CMS.
    I try to rely on the default Markdown behavior
    of the library that I'm using. 

Etc.


I should use Markdown's reference link feature more, especially when a lot of long URLs are used close together. The reference link option would make the markup text appear neater.

Here's an example of reference linking from Gruber's Markdown syntax page.

I get 10 times more traffic from [Google] [1] than from
[Yahoo] [2] or [MSN] [3].

[1]: http://google.com/        "Google"
[2]: http://search.yahoo.com/  "Yahoo Search"
[3]: http://search.msn.com/    "MSN Search"

The reference links can appear at the bottom of the markup page. The link title text at the end is optional. And the ID can be alphanumeric.

[foo]: http://example.com/  "Optional Title Here"

[id]: <http://example.com/>  "Optional Title Here"

[id]: http://example.com/longish/path/to/resource/here
    "Optional Title Here"

Another option called implicit linking that is similar to the above.

I get 10 times more traffic from [Google][] than from
[Yahoo][] or [MSN][].

[google]: http://google.com/        "Google"
[yahoo]:  http://search.yahoo.com/  "Yahoo Search"
[msn]:    http://search.msn.com/    "MSN Search"

Markdown permits escaping some chars via the backslash. I have not used this feature, but I should when I occasionally want to include a hashtag that starts a new line.

\#hashtag

From the Markdown syntax page:

Markdown allows you to use backslash escapes to generate literal characters which would otherwise have special meaning in Markdown’s formatting syntax.

\ backslash
` backtick
* asterisk
_ underscore
{} curly braces
[] square brackets
() parentheses
# hash mark
+ plus sign
- minus sign (hyphen)
. dot
! exclamation mark


On the very rare occasions that I need to display tabular data, I can either type the HTML table-related tags by hand, since I know how to use them, or I can use a code block if it's a small table.

I very rarely use footnotes, but I can either type the HTML <sup> tag by hand, or I could bold a number, contained within brackets and provide a section of numbered footnotes at the bottom of the page. Both options lack Textile's and MultiMarkdown's ability to link from the number to the bottom of the page where the footnotes would be located. MultiMarkdown provides the ability to link from the footnotes section up to where the footnote was mentioned.

But I agree with one thought about footnote linking within a web page. It can cause the reader to click the link, read the footnote, and possibly not make it back to where the reader left off. Instead of linking, make obvious notes within the text where footnotes occurred, and when the reader reached the bottom of the post, the reader can read the footnotes section.

It's thought that despite it being the web, which involves linking to URLs, if the body text of the web post contains too many links, readers can become distracted by clicking one of the links and getting lost in the web elsewhere.

I use a couple footnote options in this test page.

-30-