Additional Markdown Tips #

In this reading, we show you a few more tips for working with Markdown. You can also find a more comprehensive reference for Markdown in GitHub’s Basic writing and formatting syntax page (this is optional). Note that this page lists some GitHub-specific behavior that may not work on in all Markdown applications.

Below, we list a few things about Markdown that are not sufficiently explained (or not explained at all) in the required readings.

Headings #

In this course and in the linked pages, headings are formatted using the ATX style - that is, using one to six # characters to denote a heading level. There is also the setext style which formats headings like this:

Heading level 1 (equivalent to `# Heading level 1`)
===================================================

Heading level 2 (equivalent to `## Heading level 2`)
----------------------------------------------------

However, this style only supports the above two heading levels - further levels are not supported.

In general, you should think of these headings as providing structure rather than formatting. If you want a smaller font size for your header, you should not just use a higher heading level - there are other ways of controlling the font size of headings. For example, if you are currently writing under a level 3 heading (as this text is) and want to include a subheading, you should use a level 4 heading, and if you find that the font size for level 4 headings is not to your liking, you can adjust that elsewhere.

Some Markdown style guides will encourage you to only use the level 1 heading once, in the title of the document. While this is not a strict rule, it does make it easier to translate Markdown to other formats, so we encourage you to try and follow this rule where possible.

Line Breaks #

The smallest unit of text that Markdown groups together is the paragraph. Thus even if you start a sentence on a new line, the formatted text will come out as part of the same paragraph:

The smallest unit of text that Markdown groups together is the paragraph.
Thus even if you start a sentence on a new line, the formatted text will come out as part of the same paragraph:

To start a new paragraph, enter one or more blank lines after the previous paragraph. It does not matter how many blank lines you use, but you should only use one.

Occasionally, you may need to break a line at a certain place. For example, if you are writing a haiku, you need to make sure that each line has the appropriate number of syllables. You can make sure to start a new line by ending a line with two spaces:

Three things are certain:  
Death, taxes, and lost data.  
Guess which has occurred.

Which yields the following:

Three things are certain:
Death, taxes, and lost data.
Guess which has occurred.

In the Optional Exercise below, you have the chance to practice this and other types of formatting.

Alt Text #

Because Markdown was originally intended as a convenient shorthand for HTML, the language has some features that were influenced by HTML. Alt text (sometimes also called alternative text) is one of those features. In Markdown, this refers to the text that is shown if an image cannot be displayed for some reason (for example, if the URL pointing to the image is broken). On the Web, you can also see the alt text for images by hovering your mouse cursor over them.

If the image displays successfully, the alt text is not shown at all, but you should still write alt text for every image you include. Beyond being a failsafe for broken images, alt text is heavily used in Web accessibility, such as in screen readers used by visually impaired people.

Unfortunately, a great deal of sites on the Web do not include sufficiently helpful alt text for their visitors, creating a poor experience for users who rely on this feature. As new programmers, you should make a habit of including descriptive alt text with images in Markdown.

If you are interested in learning more about how to write good alt text, the nonprofit WebAIM (Web Accessibility in Mind) has put together an excellent guide for doing so. (This is optional reading. The guide is focused on HTML, but the principles are largely the same.)