Do you use Markdown to store your content?

You want users to easily edit content, so you put an "edit" button on the page. From there, you can choose between the power of HTML or the limitations of Markdown.

<imageEmbed
  alt="Image"
  size="large"
  showBorder={false}
  figureEmbed={{
    preset: "default",
    figure: '"Edit" button to encourage users updating the content',
    shouldDisplay: true
  }}
  src="/uploads/rules/using-markdown-to-store-your-content/edit-button.jpg"
/>

**HTML** is frightening for unfamiliar users, as one wrong tag or an inline styling can break the whole page view.

**Markdown** is simpler and encourages more editing without breaking the page.

The [original spec for Markdown](https://daringfireball.net/projects/markdown/syntax) does not specify the syntax unambiguously – so there are different flavours of the spec available. Some popular ones include:

* [Commonmark Spec](https://spec.commonmark.org/0.29/)
* [GitHub Simple](https://guides.github.com/features/mastering-markdown/)
* [GitHub the Spec](https://github.github.com/gfm/)
* [markdown-it](https://github.com/markdown-it/markdown-it) (really flexible, pluggable library based on CommonMark)

The [Markdown Cheatsheet](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) is a great page to reference when learning Markdown.

Depending on the Markdown parser you choose, there are many plugins that allow you to extend it. [SugarLearning](https://sugarlearning.com) and [SSW.People](https://ssw.com.au/people) provide more extensive cheatsheets which include a number of custom templates and plugins:

* [SugarLearning cheatsheet](https://my.sugarlearning.com/SSW/items/13308/markdown-cheatsheet) (using Markdown-it parser)
* [SSW.People cheatsheet](https://ssw.com.au/people/sample) (using CommonMark parser)
* [SSW.Rules cheatsheet](https://github.com/SSWConsulting/SSW.Rules.Content/wiki/Using-Markdown) (using CommonMark parser)


<imageEmbed
  alt="Image"
  size="large"
  showBorder={false}
  figureEmbed={{
    preset: "default",
    figure: 'Markdown Icon',
    shouldDisplay: true
  }}
  src="/uploads/rules/using-markdown-to-store-your-content/markdown.jpg"
/>

<asideEmbed
  variant="info"
  body={<>
    **Tip:** To make it extra easy for editors, use [TinaCMS](https://tina.io/markdown-cms) into your Markdown-based project to provide a WYSIWYG (what you see is what you get) editor experience.
  </>}
  figureEmbed={{
    preset: "default",
    figure: 'XXX',
    shouldDisplay: false
  }}
/>

### Videos

<youtubeEmbed url="https://www.youtube.com/embed/p_SsHtKRj-8" description="Video: "Markdown -  How to use it, What is it and Why Use it | Ask a Dev" (9 min)" />

---

<youtubeEmbed url="https://www.youtube.com/embed/j3ix99MdSic" description="Using GitHub and Markdown to store you content by Thiago Passos (4 min)" />

### Don't store content as HTML - It's a trap

Rich HTML Editors make your life easier at the beginning and produce content that looks nice and clean, but behind the scenes, it generates HTML which can get out of control quickly especially if you need to edit the source code (E.g. include a special style). It becomes incredibly difficult to maintain over time.

Some examples of rich HTML editors that you can embed in your web applications:

* [Kendo Editor](https://www.telerik.com/kendo-angular-ui/components/editor/)
* [TinyMCE](https://www.tiny.cloud/)
* [CKEditor](https://ckeditor.com/)

**Note:** None of these are recommended because of the HTML that is generated.

<imageEmbed
  alt="Image"
  size="large"
  showBorder={false}
  figureEmbed={{
    preset: "badExample",
    figure: 'Bad example - HTML generated by a rich editor gets harder to maintain over time',
    shouldDisplay: true
  }}
  src="/uploads/rules/using-markdown-to-store-your-content/HTML-bad.jpg"
/>

### Store content in Markdown

Content is typically either stored in files (eg. git) or a database. When stored in files, it is common to use a static site generator with a JAMStack approach (e.g. Gatsby, Vuepress, Hexo, etc). That is, you commit content into git and a CI/CD pipeline is executed. The resulting files (HTML and CSS) are then served from storage which is cheaper and typically more scalable than compute resources in the cloud. In this case, the workflow will be a development style workflow (commit to git, push, etc) and the editor will be the one you choose. (e.g. GitHub editor or VS Code) These editors are not likely to produce a rich editing experience, nor do they need to.

For a non-technical audience, it helps to store your content as Markdown in a database and convert to HTML on the fly. This removes the code repository/CI/CD pipelines and can feel more natural for a non-developer audience. In this case, you will provide an editor and it is recommended that this be a rich editor.

#### Markdown rich editors

The Markdown rich editors are not as good as the HTML ones, but at least the content they produce is maintainable over time.

Some example of rich Markdown editors are:

* [ProseMirror](http://prosemirror.net/)
* [Editor.Md](https://pandao.github.io/editor.md/)
   **Note:** It is the #1 editor on [Top 7: Best Markdown editors Javascript and jQuery plugins](https://ourcodeworld.com/articles/read/359/top-7-best-markdown-editors-javascript-and-jquery-plugins)
* [ToastUI Editor](https://ui.toast.com/tui-editor/) (recommended)
   **Note:** ToastUI provides more customization options (menu and language) than Editor.md

<imageEmbed
  alt="Image"
  size="large"
  showBorder={false}
  figureEmbed={{
    preset: "goodExample",
    figure: 'Good example - Markdown looks clean',
    shouldDisplay: true
  }}
  src="/uploads/rules/using-markdown-to-store-your-content/markdown-good.jpg"
/>

### Markdown can have rich content too

Markdown is simple and limited, but you can make it richer.

One way is to use inline HTML, this allows you to use HTML tags that you are familiar with (only if you need to) and embed things like YouTube videos or JavaScript.


<imageEmbed
  alt="Image"
  size="large"
  showBorder={false}
  figureEmbed={{
    preset: "default",
    figure: 'OK Example – you can use raw HTML in your Markdown, and mostly it will work pretty well. But you can’t use Markdown’s syntactic sugar in the HTML',
    shouldDisplay: true
  }}
  src="/uploads/rules/using-markdown-to-store-your-content/use-html-in-markdown.png"
/>

The other way is to use templates or containers:

::: bad img-medium

<imageEmbed
  alt="Image"
  size="large"
  showBorder={false}
  figureEmbed={{
    preset: "default",
    figure: 'Bad example – The danger of using HTML in your Markdown files is that you add too much formatting e.g. use Bootstrap classes that create a tight coupling between the content and the presentation',
    shouldDisplay: true
  }}
  src="/uploads/rules/using-markdown-to-store-your-content/danger-html-and-markdown.png"
/>
:::

A better way is to use a plugin (if your Markdown engine supports it).

::: good img-medium

<imageEmbed
  alt="Image"
  size="large"
  showBorder={false}
  figureEmbed={{
    preset: "default",
    figure: 'Good example – VuePress has a custom container that generates nice alert boxes like Bootstrap but without tying the presentation to the CSS framework in the content',
    shouldDisplay: true
  }}
  src="/uploads/rules/using-markdown-to-store-your-content/vuepress-custom-container.png"
/>
:::

Unfortunately, Markdown does not support YouTube videos embedding out of the box. However, there is a workaround to embed it.

``` markdown
[![What is SSW TV](http://img.youtube.com/vi/dQw4w9WgXcQ/0.jpg)](http://www.youtube.com/watch?v=dQw4w9WgXcQ)
```

<figureEmbed figureEmbed={{
  preset: "goodExample",
  figure: 'Figure: Good example - Workaround to embed YouTube video using YouTube\'s generated thumbnail',
  shouldDisplay: true
} } />


If your site is using "[markdown-it](https://www.npmjs.com/package/markdown-it)" parser, you can also install "[markdown-it-video](https://www.npmjs.com/package/markdown-it-video)" to allow YouTube videos directly embedded into the page, rather than providing just an image and a link.

``` markdown
@[youtube](http://www.youtube.com/embed/dQw4w9WgXcQ)
```

<figureEmbed figureEmbed={{
  preset: "goodExample",
  figure: 'Figure: Better example - YouTube video embedding using a plugin',
  shouldDisplay: true
} } />


### Markdown to HTML rendering processes


<imageEmbed
  alt="Image"
  size="large"
  showBorder={false}
  figureEmbed={{
    preset: "default",
    figure: 'The Markdown rendered either Client-side or Server-side',
    shouldDisplay: true
  }}
  src="/uploads/rules/using-markdown-to-store-your-content/markdown-rendering.jpg"
/>