0 / 0

Markdown Guide

What is Markdown?

Markdown (.md) is a markup language, similar to a .txt file, but with basic in-text formating elements. Although it can produce similar outputs as a word processor, there are other benefits that Thoth Tech can leverage.

Thoth Tech and Markdown

Thoth Tech will use Markdown as it default documentation standard.

This decision is based on a number of factors:

  1. Widespread acceptance and support
  2. Readability
  3. Existing products have a md presence
  4. GitHub support (ensuring accountability and transparency)
  5. HTML and static site capability

Many tools are capable of working in Markdown (Dillinger and VS Code are good starting points)

Guide to using Markdown

How do I create a Markdown file?

It's simple to specify a file as Markdown. Simply name it with the extension .md.

How do I format a Markdown file?

The Markdown Guide is an excellent online resource providing at-a-glance formatting examples.

Commonly used formatting options include the following:

Markdown Result
# H1

H1
## H2

H2
### H3

H3
**bold text** bold text
*italicized text* italicized text
> blockquote
blockquote
1. First item 1. First item
1. Second item 2. Second item
1. Third item 3. Third item
- First item
  • First item
    		•
    - Second item
  • Second item
    		•
    - Third item
  • Third item
    		•
    `code` code
    ---
    [Link Name](https://www.markdownguide.org) Link Name

    Diagrams

    You can generate diagrams and flowcharts from text by using Mermaid.

    The Mermaid Live Editor helps you learn Mermaid and debug issues in your Mermaid code. Use it to identify and resolve issues in your diagrams.

    To generate a diagram or flowchart, write your text inside the mermaid block:

    ```mermaid
graph TD
  A[Dinner]-->B[Tacos]
  A-->C[Noodles]
  B-->D[Fulfillment]
  C-->D
```

    graph TD
  A[Dinner]-->B[Tacos]
  A-->C[Noodles]
  B-->D[Fulfillment]
  C-->D

    Collapse

    A collapsed content section is used to hide information until a user chooses to reveal it with a click or tap on the summary text. The hidden content is revealed inline. For example, this code:

    <details>
<summary>This is the summary text, click me to expand</summary>

This is the detailed text.

You can learn more about expected usage of this approach in the
[Thoth Tech markdown guide](https://github.com/thoth-tech/handbook/blob/main/docs/learning/training/markdown-guide.md).

</details>

    results in:

    This is the summary text, click me to expand

    This is the detailed text.

    You can learn more about expected usage of this approach in the Thoth Tech markdown guide.

    Using VS Code to preview Markdown

    VS Code has built in support for previewing Markdown files.

    Mac Users

    To open your current tab in Markdown preview, use shift + command + v.

    To create a split screen view (allowing you to edit your Markdown file in one screen while previewing in another, side-by-side), press command + k, release the keys, then press v.

    Windows Users

    To open your current tab in Markdown preview, use shift + ctrl + v.

    To create a split screen view (allowing you to edit your Markdown file in one screen while previewing in another, side-by-side), press ctrl + k, release the keys, then press v.

    Markdown Templates