Markdown and HTML

The goal of this page is to help us track best practices for using HTML tags and Markdown.

HTML Tags

<a>- Links

Links have a notable role in how our ranking in search results. While Markdown is great for writing, it can be tricky to get the right attributes into our <a> tags. Here is how our <a> tags should look.

<a href="http://www.link.com/" title="link anchor text">Link Anchor Text</a> 

Things to avoid:

• Using the words "click here" for the anchor link text - use a phase that describes where the link goes.
• Having a long (more than 9 words) anchor link text

Things to think about for screen readers:

• Most screen readers say "link" before the link, so there's not need to add that language in the link itself.
• Linking to non-HTML content - like PDFs - should include that description in the link like <a href="our_plan.pdf" title="Our Plan">Our Plan (PDF)</a>

For more information checkout the WebAIM article on links and accessibility.

<img> - Images

<div> - Special divisions

Markdown

Most of our content should be written in Markdown. While Markdown is easy to write with once it is learned, there is a learning curve. In addition to the guides that GitHub has built into it, here are a few additional resources:

• Adam Pritchard's Markdown Cheatsheet
• GitHub Guides - Mastering Markdown
• About writing and formatting on GitHub

Headers

Paragraphs

Lists