Skip to content

Markdown style and conventions

Jump to bottom
gabry edited this page Feb 3, 2022 · 2 revisions

Filename

  • Use underscores dashes instead of spaces
  • Use the .md (markdown) file extension

Example: Arduino_101.md

Front matter

The article must begin with a front matter, that should be formatted exactly like below.

---
title: "<title>"
---
  • The title attribute will set the article title when deployed to the Help Center.
  • Do not use a heading for the title.
  • The title should be surrounded by double quotes.
  • The title should be written in TitleCase, i.e only the first word is capitalized, except for 'Arduino', product names, etc.

Note the quotation marks around the title. The first word, the Arduino name, and names of product/services should be capitalized.

Example:

---
title: "Calibration and debugging of MKR IoT Carrier capacitive buttons"
---

Headings

The deployed article will make the title a level 1 heading. So any headings in the article should start at level 2, 3, 4... i.e. ##, ### and so on.

They should be capitalised the same way as titles.

Lists

  • For step-by-step instructions, use numbered lists.
  • The elements in a step-by-step list should be fairly short, and not too many (typically not more than five). If the steps are many or long, use a different structure.

Notes

  • The quote syntax can be used for citations, but more commonly as a type of "note", used for clarifications or additional information.
  • If it's a required step of a tutorial etc. it should be included in the list of steps.

Buttons

There is no set standard. In some contexts simply capitalizing the button name can be enough, but formatting will help the button stand out:

Uppercase Uppercase
“Quotes” “Quotes”
Bold Bold
Cursive Cursive
Code Code

Buttons in the IDE

By using inline images you can make it clearer when referring to IDE buttons.

Click the ![Upload button](img/symbol_upload.png) **Upload** button.

Click the Upload button Upload button.

Click ![Verify button](img/symbol_verify) **Verify**.

Click Verify button Verify.

  • To use these, they must be added to the article's image folder.
  • They should be named symbol_upload.png and symbol_verify.png, respectively.

Drop-down menu navigation

  • Use '>' between each selection.
  • Surround with backticks ( ` ) or underscores ( _ )
    • Tools > Board > Board Manager...
    • Tools > Board > Board Manager...

Filenames

When referencing a filename, use inline code highlighting:

Open `settings.txt`

This renders as "Open settings.txt"

Clone this wiki locally