Markdown guide

[mike-j-thomas]

Goal

Have a simple guide for Fleet-flavoured Markdown that lives in the handbook.

How

• [ ] Create a separate file, markdown.md, in the Digital Experience folder of the handbook (awaiting successful merge of https://github.com/fleetdm/fleet/pull/6524 before this can be created).
• [ ] Compile a list of all Markdown syntax that is supported by fleetdm.com and document it in the handbook. Ask @eashaw if you are unsure about any of the syntax:

Suggested structure for the guide:

• Headers
  • h1
  • h2
  • h3
  • h4
• Emphasis
  • Bold
  • Italic
  • Bold italic
  • Strikethrough
• Lists
  • Ordered
  • Unordered
  • Sub-list items
• Links
  • Inline links
  • Relative links
  • mailto links (good to have, but have a note saying that we NEVER use it. We don't want our email getting spammed.)
• Image
  • Image syntax
  • Image caption (* in the line directly under the image. See this example)
• Code and syntax highlighting
  • Inline code
  • Code block
  • Code block with syntax highlighting
• Tables
• Notes & Tips (we use blockquote ">" syntax for this)
• An actual blockquote (ask @eashaw if we support this)
• Horizontal rule (---)
• YouTube videos
• Podcast (Check our podcast posts. It's just a code snippet in an iframe, copy/pasted from Apple's podcast page).

Examples

https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet https://about.gitlab.com/handbook/markdown-guide/ https://www.markdownguide.org/basic-syntax/

[mike-j-thomas]

@Desmi-Dizney here's an example of how to add a video https://github.com/fleetdm/fleet/blob/main/articles/ebpf-the-future-of-osquery-on-linux.md

[Desmi-Dizney]

This is a work in progress but I'm saving the tables here until https://github.com/fleetdm/fleet/pull/6524 is complete.

Markdown option one	Rendered heading
# Heading 1	Heading 1
## Heading 2	Heading 2
### Heading 3	Heading 3
#### Heading 4	Heading 4

Markdown option one	HTML	Rendered Text
**Bold**	<strong>Bold</strong>	Bold
*Italic*	<em>Italic</em>	Italic
***Bold italic***	<em><strong>Bold italic</strong></em>	Bold italic
~~Strikethrough~~	<s>Strikethrough</s>	Strikethrough
	<ins>Underline</ins>	Underline

[Desmi-Dizney]

Markdown	HTML	Rendered List
1. Line one 2. Line two 3. Line three 4. Line four	<ol>      <li>Line one</li>      <li>Line two</li>      <li>Line three</li>      <li>Line four</li> </ol>	1. Line one 2. Line two 3. Line three 4. Line four
1. Line one 4. Line two 2. Line three 5. Line four	<ol>      <li>Line one</li>      <li>Line two</li>      <li>Line three</li>      <li>Line four</li> </ol>	1. Line one 2. Line two 3. Line three 4. Line four
1. Line one      1. Indent one 2. Line two 3. Line three       1. Indent one       2. Indent two 4. Line four	<ol>      <li>Line one</li>           <ol>                <li>Indent one</li>      <li>Line two</li>      <li>Line three</li>           <ol>                <li>Indent one </li>                 <li>Indent two</li>      <li>Line four</li> </ol>	1. Line one      1. Indent one 2. Line two 3. Line three       1. Indent one       2. Indent two 4. Line four

[Desmi-Dizney]

See the Markdown examples of unordered lists below.

Markdown option one	Rendered List
- Line one - Line two - Line three - Line four	Line one iLine two iLine three iLine four
- 7\. What a lucky number. - It's nothing like 13.	7. What a lucky number. It's nothing like 13.
- Line one     Your paragraph goes here. - Line two	Line one      Your paragraph goes here Line two.

To nest lists inside of other unordered lists using Markdown by including four spaces before each item you desire to indent.

- Line one      - Indent one - Line two - Line three      - Indent one      - Indent two - Line four

This is how it will render

• Line one
  • Indent one
• Line two
• Line three
  • Indent one
  • Indent two
• Line four

[Desmi-Dizney]

This is how you create a term with [a tooltip and no link ](## "add information to a term when someone hovers")

This is how you create a term with a tooltip and no link .

This is how you create a term with [a tooltip and a link ](https://fleetdm.com/handbook/brand#commonly-used-terms "add information to a term when someone hovers")

This is how you create a term with a tooltip and a link .

This is how you make a tooltip with the link separated, at the bottom of the page.

[1]: <https://en.wikipedia.org/wiki/Hobbit#Lifestyle> "Hobbit lifestyles"

[Desmi-Dizney]

To create malito link out of a URL, incase it in angle brackets like so:

<https://fleetdm.com>

This will render as: https://fleetdm.com

The same concept works with email addresses.

<fake@fleetdm.com>

This will render as:fake@fleetdm.com

Important To avoid spam, we NEVER user mailto links in the handbook or docs.

[Desmi-Dizney]

Everyone's favorite device management company is **[Fleet](https://fleetdm.com/)**.

Everyone's favorite device management company is Fleet.

Everyone's favorite device management company is *[Fleet](https://fleetdm.com/)*.

Everyone's favorite device management company is Fleet.

[mike-j-thomas]

@Desmi-Dizney this also exists. Let's consolidate it with the Markdown guide that you're creating. https://fleetdm.com/handbook/community#markdown

[Desmi-Dizney]

Markdown	Rendered output
`` Sometimes you need to talk about `code` in your Markdown. ``| Sometimes you need to talk about code in your Markdown.

[Desmi-Dizney]

I've started to add all of this to:

• https://github.com/fleetdm/fleet/pull/6813

It's a work in progress.

[Desmi-Dizney]

Ask @eashaw about:

• Relative links
• Code and syntax highlighting
  • Inline code
  • Code block
  • Code block with syntax highlighting
• Tables
• Notes & Tips (we use blockquote ">" syntax for this)
  • An actual blockquote (ask @eashaw if we support this)
  • Horizontal rule (---)
• YouTube videos
• Podcast (Check our podcast posts. It's just a code snippet in an iframe, copy/pasted from Apple's podcast page).

[eashaw]

Relative links: use ../ and ./ to link to other files Link from a handbook page to another handbook page: [Product DRI](./product.md#product-dris) Link to a docs page from a handbook page: [Contributing FAQ](../docs/Contributing/FAQ.md) link from a docs page to a handbook page: [Community](../../../community.md) « Eric TODO: make sure this is correct

`inline codeblock`

codeblock

codeblock with syntax highlighting:

```js
let foo = 0;
let bar = 'hi';

Tables:
| table header | table header|
|-|-|
|table cell | another table cell

Horizontal rule
---

Youtube videos:
https://about.gitlab.com/handbook/markdown-guide/#display-videos-from-youtube

Apple podcasts: use embeded code from apple podcast's website
ex: 
<iframe allow="autoplay *; encrypted-media *; fullscreen *; clipboard-write" frameborder="0" height="175" style="width:100%;max-width:660px;overflow:hidden;background:transparent;" sandbox="allow-forms allow-popups allow-same-origin allow-scripts allow-storage-access-by-user-activation allow-top-navigation-by-user-activation" src="https://embed.podcasts.apple.com/gb/podcast/ep-2-prima-virani-improving-endpoint-monitoring-and/id1627079895?i=1000568032620"></iframe>

[Desmi-Dizney]

Constructing a table

You'll want to begin by creating a header. Separate each column with a pipe "|" and separate rows by beginning a new line in markdown. Your header should look something like this:

| Category one | Category two | Category three |

The next line in Markdown contains no text. In between the pipes, add three or more dashes "---" to form a break. On either the left, right, or both sides you can add a colon ":" to specify left, right, or center alignment.

| Category one | Category two | Category three |
|:---|---:|:---:|
| Left alignment | Right alignment | Center Alignment 

Category one	Category two	Category three
Left alignment	Right alignment	Center Alignment

[Desmi-Dizney]

New PR:

• https://github.com/fleetdm/fleet/pull/6864

[mike-j-thomas]

@Desmi-Dizney, I moved this back to "Ready." There's a review comment to action in the PR https://github.com/fleetdm/fleet/pull/6864#pullrequestreview-1053545929