/advanced-markdown

Learn about advanced markdown techniques

Primary LanguageJavaScript

Advanced Markdown with David Wells

Slides -> github.com/DavidWells/advanced-markdown

Table of Contents

"Click to expand"

Why markdown?

Markdown is a universal doc format that is easy to write and easy to add to a version control system.

  • Open - Anyone can submit content, fix typos & update anything via pull requests
  • Version control - Roll back & see the history of any given post
  • No CMS lock in - We can easily port to any static site generator
  • It's just simple - No user accounts to manage, no CMS software to upgrade, no plugins to install.

Markdown basics

The basics of markdown can be found here & here. Super easy!

Advanced Formatting tips

left alignment

This is the code you need to align images to the left:

<img align="left" width="100" height="100" src="http://www.fillmurray.com/100/100">

right alignment

This is the code you need to align images to the right:

<img align="right" width="100" height="100" src="http://www.fillmurray.com/100/100">

center alignment example

<p align="center">
  <img width="460" height="300" src="http://www.fillmurray.com/460/300">
</p>

collapse Sections

Collapsing large blocks of text can make your markdown much easier to digest

"Click to expand" this is hidden block 
<details>
<summary>"Click to expand"</summary>
this is hidden
</details>

Collapsing large blocks of Markdown text

To make sure markdown is rendered correctly in the collapsed section...
  1. Put an empty line after the <summary> block.
  2. Insert your markdown syntax
  3. Put an empty line before the </details> tag
<details>
<summary>To make sure markdown is rendered correctly in the collapsed section...</summary>

 1. Put an **empty line** after the `<summary>` block.
 2. *Insert your markdown syntax*
 3. Put an **empty line** before the `</details>` tag
 
</details>

additional links

Website • Email Updates • Gitter • Forum • Meetups • Twitter • Facebook • Contact Us

[Website](http://www.serverless.com) • [Email Updates](http://eepurl.com/b8dv4P) • [Gitter](https://gitter.im/serverless/serverless) • [Forum](http://forum.serverless.com) • [Meetups](https://github.com/serverless-meetups/main) • [Twitter](https://twitter.com/goserverless) • [Facebook](https://www.facebook.com/serverless) • [Contact Us](mailto:hello@serverless.com)

Badges

I hate them so. Don't use badges.

Useful packages

  1. gray-matter

YAML front-matter is your friend. You can keep metadata in markdown files

title: Serverless Framework Documentation
description: "Great F'in docs!"
menuText: Docs
layout: Doc
  1. Remark

Useful for rendering markdown in HTML/React

  1. Markdown Magic

Useful utilities

  1. Schedule Posts - Post scheduler for static sites

Show DEMO

  1. Zero friction inline content editing

Show DEMO

  1. Byword & Typora - Good Editors

  2. Monodraw - Flow charts for days

  3. Kap - Make gifs

  4. IDE markdown preview

  5. Stuck on WordPress? Try easy-markdown plugin

How Serverless uses markdown

Serverless.com is comprised of 3 separate repositories

Why multiple repos?

  1. We wanted documentation about the framework to live in the serverless github repo for easy access
  2. We wanted our blog content to be easily portable to any static site generator separate from the implementation (site)
  3. prebuild npm script pulls the content together & processes them for site build

A single repo is easier to manage but harder for people to find/edit/PR content.

DEMO

Other Markdown Resources

  • Verb - Documentation generator for GitHub projects
  • ACSII docs - Markdown alternative