The Hypothesis editor supports formatting your annotations using Markdown — this help article serves as a “cheat sheet” for using Markdown syntax in the annotation editor.
Also see our articles on adding links and images, embedding videos, and formatting annotations using LaTeX.
| Style | Syntax | Example | Result |
|---|---|---|---|
| Headings | # H1
## H2 ### H3 |
# Largest heading ## Smaller heading ### Even smaller |
Largest headingSmaller headingEven smaller |
| Bold | **text** or __text__ |
**This text is bold** |
This text is bold |
| Italic | *text* or _text_ |
*This text is italicized* |
This text is italicized |
| Strikethrough | ~~text~~ |
~~This text has been struck through~~ |
|
| Blockquote | > quoted text |
Here’s a quote: > quoted text |
Here’s a quote:
|
| Ordered list | 1. First item 2. Second item 3. Third item |
Favorite colors: 1. Blue 2. Purple 3. Green |
Favorite colors:
|
| Unordered list | – First item
– Second item – Third item |
Grocery list: - Coffee - Tea - Milk |
Grocery list:
|
| Inline code | `code` |
Run `make dev` to start the server |
Run make dev to start the server |
| Horizontal rule |
--- |
Starting a new section --- (notice the empty line between the text and horizontal rule) |
Starting a new section
|
Text in another language
If part of your annotation is in a different language, you can mark it so screen readers switch to the right pronunciation. On screen it looks the same; the difference is in how it’s read aloud.
Wrap a phrase in a span tag with a lang attribute and a language code:
<p lang="fr">Bonjour tout le monde.</p>
For a whole paragraph, use a p tag:
<p lang="fr">Bonjour tout le monde.</p>
Hypothesis automatically displays annotations written in right-to-left languages from right to left. If your annotation mixes directions (for example, an English sentence followed by an Arabic paragraph), wrap the right-to-left part in <p dir="rtl"> so it lines up correctly.
Tables
The annotation editor doesn’t support Markdown tables (rows separated by | pipes). To add a table, use HTML instead. Put column headings in th tags so screen readers can tell readers which column each cell belongs to. A caption gives the table a title.
Here’s the HTML:
| Week | Chapter |
|---|---|
| 1 | Introduction |
| 2 | Chapter 1 |
Here’s the resulting table in an annotation card.
Tip: don’t leave blank lines inside the table code.
Previewing your annotation
You can click “Preview” in the annotation editor toolbar to see what your formatted annotation will look like:
…and you can click “Write” to continue editing your annotation:
Troubleshooting annotation formatting
- If you are copying annotation text from another source (Microsoft Word, Google Docs, etc), paste the text without formatting. You can do this with Option+Shift+Command+V for Macs or Ctrl+Shift+V for PCs.
- Ensure there is an empty line between paragraph text and horizontal rules.
- Experiment with hitting Enter or Return once vs. twice if you encounter line break issues.
- Consult the GitHub Flavored Markdown spec or create a ticket to get help from the Hypothesis team.