Basic structure
| Content | HTML | Markdown | |
|---|---|---|---|
| Heading 1 | <h1> | # | This is the main heading of the page. It tells users what the page is about. There should normally only be one <h1> on a page. Some content management systems (CMS) have a separate field for the page heading. |
| Headings 2 to 4 | <h2> to <h4> | ## ### #### | These are the next level headings. They tell the story of the page. If the user just reads the headings, they will understand what the page is about, and find the section they want easily. Headings must be used in sequence, for example <h2> <h3> <h3> <h2> <h3> <h4> Some content management systems (CMS) only allow <h2> and below in the text field. |
| paragraph | <p> | The basic paragraph block. There is a space between paragraphs. | |
| Unordered list | <ul> | - First item - Second item - Third item - Fourth item | Unordered lists - have bullet points - don’t need a specific order to make sense - are useful for breaking up longer sentences |
| Ordered lists | <ol> | 1. First item 2. Second item 3. Third item 4. Fourth item | Ordered lists - Are numbered - Need to be in a specific sequence - Are useful for step by step instructions |
| Bold and italics | <strong> <em> NOT <bold> <i> | **bold** *italic* | If you use bold and italics (and you must test with users if you do) then take care that the HTML used is semantic. Semantic code says something about the content. So when a screen reader speaks the previous paragraph, the word “semantic” will be emphasised. This will only happen if the HTML is written with the HTML <strong> or <em>. <bold> and <i> look identical, but are not semantic, they do not say anything about the content, and will not be announced by a screen reader. |
| Quotes | <blockquote> | > Blockquote | The quotation at the top of this doc from Tim Berner-Lee should be marked up as <blockquote>. It’s not possible to create a real blockquote in Google Docs. |
| Link (hypertext reference) | <a href=”https://www.example.com (opens in a new tab)”> Website </a> | [website](https://example.com) | The World Wide Web would be nothing without links (opens in a new tab). It would be nice if the HTML was <link>, but that’s another thing (opens in a new tab). <a> means anchor, and href is a hypertext reference. So <a href> means “go to the place where this thing is anchored”. If you have any control over the design of links, please make sure they are blue and underlined. You users will thank you. |
| Button | <button> | CTAs and buttons are different in Markdown software. | Buttons are different to links. Buttons do something. Links go somewhere. When you log in to a page, that’s a button. When you click a menu item, that takes you to another page, so that’s a link. Call-to-action (CTA) elements can be either a button or a link, depending what happens. It might look similar to a button, but if it takes you to a sign-up page, then it should be an <a href>. If it’s a “download” CTA then it must be a button. |
| Alternative text | <img src=”goose.jpg” alt=”An elegant china goose, about 1 metre tall.”> |  | Images must have a description in words in case the image does not load. It helps bots and screen readers to know what the image is. To write alt text, imagine what you would say when reading the page to someone over the phone, without mentioning that there's an image on the page. If the image is purely decorative, use Alt = “” and the bots will ignore the image. As a content editor, you’d have to ask why it’s there! |
| Tables, with rows, headers, and data | <table> <tr> <th> <td> | Use | to separate columns. Use 3 or more dashes - below the header. | A simple table will have a header row, maybe a header column and the data. Don’t worry about the code too much, just make sure that it’s clear in your table what is what. | Team | Win | Lose | Draw | Barcelona | 13 | 3 | 5 | Liverpool | 12 | 4 | 6 | Ajax | 9 | 6 | 3 |
Next: Take care in Google Docs →
Discussion
Log in to join the discussion. Your comment will be checked before it appears publicly.