6.9 KiB
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...
- Put an empty line after the
<summary>block. - Insert your markdown syntax
- 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
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
Useful for rendering markdown in HTML/React
Useful utilities
- Schedule Posts - Post scheduler for static sites
Show DEMO
Show DEMO
-
Monodraw - Flow charts for days
-
Kap - Make gifs
-
Stuck on WordPress? Try easy-markdown plugin
How Serverless uses markdown
Serverless.com is comprised of 3 separate repositories
- https://github.com/serverless/blog
- https://github.com/serverless/serverless | Shoutout to Phenomic.io
- https://github.com/serverless/site
Why multiple repos?
- We wanted documentation about the framework to live in the serverless github repo for easy access
- We wanted our blog content to be easily portable to any static site generator separate from the implementation (site)
prebuildnpm 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
- Site structure
- Serverless build process
- Validation
- Editing Flow
- Github optimizations
- Link from top of each doc to live link on site
- use markdown magic =) to auto generate tables etc
- Hide yaml frontmatter from github folks
- consider linking everything to site
Other Markdown Resources
- Verb - Documentation generator for GitHub projects
- ACSII docs - Markdown alternative