# Markup

HTML, Markdown, and semantic tagging in documentation source. From the Google
developer documentation style guide; each section names its source page.

Guide content © Google, used under CC BY 4.0
(https://creativecommons.org/licenses/by/4.0/).

## Contents

- [Markdown versus HTML](#markdown-versus-html)
- [Semantic tagging](#semantic-tagging)
- [HTML formatting](#html-formatting)

## Markdown versus HTML

Source: https://developers.google.com/style/markdown

Markdown is the default; it takes less effort to write and to read in source. Use HTML when you need semantic elements Markdown can't
express, a specific rendering it can't produce, or literal control over special
characters such as nonbreaking spaces inside code.

Where a team or a template has already settled on one, consistency wins over
preference.

## Semantic tagging

Source: https://developers.google.com/style/semantic-tagging

Use each element for the job it was designed for. `cite` for the title of a
standalone work, `code` for code, `kbd` for keyboard input, `var` for variables
and placeholders, `abbr` for abbreviations.

Emphasis is meaning, not styling:

- `em` marks emphasis. For italics that carry no emphasis, use `i`.
- `strong` marks importance. To bold something that isn't important, use `b`.

Headings (`h1`, `h2`, ...) express hierarchy, never appearance. Don't use frames or tables for layout. `br` belongs only where the line break is
part of the content, such as an address or a line of verse; for spacing, use `p`
and CSS.

When no element carries the meaning you want, use CSS or a presentational
element rather than misusing a semantic one.

## HTML formatting

Source: https://developers.google.com/style/html-formatting

Follow the [Google HTML/CSS style guide](https://google.github.io/styleguide/htmlcssguide.html),
with one exception: don't omit optional elements.

- Spaces, never tabs. Editors disagree about tab width, and some Markdown
  constructs require spaces.
- Two spaces per indent level.
- Lowercase element and attribute names.
- No trailing whitespace, except where Markdown requires it.
- 80-character lines. Exceptions: `meta` elements at the top of a file. A
  long URL also goes on its own line with its `href`.

Inside `<pre>`, break at 80 characters only where the break can't change what the
code means. In a file that already uses a different line length, match the file
rather than reformatting it.