Markdown Editing Basics

Diode Collab renders Markdown in two places: Markdown files, and chat messages.

Markdown files are the Zone home page, secure notes, File Details, and Web Link previews. Open a .md file to edit it with the document editor. That editor has a formatting toolbar and a source view. The same file, when set as the Zone home page, is what teammates see when they open the Zone.

Chat uses a shorter formatting bar. The message is still Markdown, and the basics below work in both places. A few tools and the quote styling differ. Those differences are in Markdown in Chat vs. Markdown docs.

For the full language, see the Markdown Guide cheat sheet.

Markdown in Chat vs. Markdown docs

	Markdown docs	Chat
Where it appears	Home page, notes, File Details, Web Link preview, and a `.md` file attached in chat	The message itself
How you format	Document toolbar, or type the syntax	Chat formatting bar, or type the syntax
Headings, bold, italic, lists, links, inline code, fenced code	Yes	Yes
Blockquote	Quote button, or type `>`	Type `>` (there is no quote button)
How a blockquote looks	Muted text with a vertical bar on the left	Indented quotation, without that bar
Underline	Not available	Underline button. This is chat formatting, not standard Markdown
@mentions	Not available	Mention button, or type `@`
Images inside the text	Image button, or the image syntax below	Attach the image. A Zone image path inside the message does not preview the way it does in a Markdown file
Tables	Table button in the editor. The preview shows the table as text, not as a grid	No table button. A pasted table also shows as text
Diagrams	A Mermaid code block renders in the file preview, including when that file is attached in chat	A Mermaid block typed into the message stays as code
Emoji button and source view	Yes	No

The chat formatting bar is bold, italic, underline, link, mention, numbered list, bulleted list, and inline code. The document toolbar adds headings, the quote button, images, tables, emoji, indent, and source view.

Syntax

Headings

Description: A section title. The document toolbar's heading menu inserts these
Syntax: # Title through ###### Small heading
Example:

# Quarterly plan
## Risks

Bold and italic

Description: Emphasis
Syntax: **bold** and *italic*
Example: **Decision:** ship on *Friday*
Notes
In chat, use the B and I buttons, or type the markers

Underline

Description: Underline in a chat message
Syntax: the U button on the chat formatting bar
Notes
Underline is only in chat. A Markdown file has no underline control

Link

Description: Text that opens a web page, a diode:// address, or a file or folder in the Zone
Syntax: [Link text](target)
Examples
Web: [Diode](https://diode.io)
Zone root: [All files](/)
Folder: [Finance](/Finance)
File: [2022 model](/Finance/Forecast/2022/2022_financial_model-v3.xlsx)
Notes
A path inside the Zone starts with /. That path is from the Zone root, not from the folder that contains the Markdown file
Web links open in the browser. diode:// links open in the in-app browser
In chat, the link button wraps the selection. The shortcut is Cmd+K or Ctrl+K

Blockquote

Description: A quotation or callout, set off from the paragraph around it
Syntax: start each line with > and a space. A nested quote uses >>
Example:

> Ship on Friday.
>
> The notes are in /Finance.
>> Only if the review is done.

That source renders as:

Ship on Friday.

The notes are in /Finance.

Only if the review is done.

How to add one
In a Markdown doc, click the quote button on the toolbar (the quotation-mark icon, after the image button). Click it again to remove the quote. You can also type > and a space at the start of a line
In chat, type > and a space at the start of the line. The formatting bar does not have a quote button
How it looks
In a Markdown doc, the quote is muted and has a vertical bar on the left
In a sent chat message, the quote is indented and does not use that bar
Notes
A blank line ends the quote. Put > on the blank line too if the quotation continues
Bold, italic, and links work inside a quote

Lists

Description: A bulleted or numbered list
Syntax: - item or 1. item
Example:

- Owner
- Reviewer

1. Draft
2. Review

Notes
In chat, use the list buttons on the formatting bar

Code

Description: Inline code, or a fenced block
Syntax: `name` for inline code, and a fence for a block

```
mix test
```

Notes
The chat code button inserts inline code
A fence in a Markdown file can be marked mermaid. That diagram renders in the file preview and in a chat attachment of that file. The same fence typed into a chat message stays as code

Emoji

Description: Insert an emoji from the document toolbar
Notes
The emoji button is on the Markdown document toolbar, not the chat bar. You can still paste an emoji into chat

Display an image

Description: Show an image in a Markdown file
Syntax: ![Name of image](/Path/to/image.png)
Example: ![My Logo](/Brand/mylogo.png)
Notes
Use the image button to choose a file, or paste a PNG into the document
A path inside the Zone starts with /. A path next to the Markdown file can start with ./
https:// image addresses also work
The preview shows PNG, JPEG, GIF, and WebP
In chat, attach the image instead of using this syntax. A Zone path inside a message is not turned into a preview
If the Markdown file's name or any folder in its path contains ( or ), images in that file break. Rename the file or folder to remove the parentheses. See why images break in certain Markdown files

Display an image with a link

Description: An image that opens another Zone path or a website
Syntax: [![Name of image](/Path/to/image.png)](https://linkurl)
Example: [![My Logo](/Brand/mylogo.png)](https://diode.io)
Notes
The same path and format rules as Display an image apply

Tables

Description: The document toolbar can insert a table
Notes
The file stores a Markdown table. File Details, the home page, and Web Link previews show that table as text, not as a grid
Chat has no table button