Slides -> github.com/DavidWells/advanced-markdown
"Click to expand"
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.
The basics of markdown can be found here & here. Super easy!
This is the code you need to align images to the left:
<img align="left" width="100" height="100" src="https://picsum.photos/100/100">
This is the code you need to align images to the right:
<img align="right" width="100" height="100" src="https://picsum.photos/100/100">
<p align="center">
<img width="460" height="300" src="https://picsum.photos/460/300">
</p>
via comment
<p>
<img src="https://picsum.photos/100/100" >
<img src="https://picsum.photos/100/100" >
</p>
With hspace property you can set horizontal (left and right) padding for an image
<p>
<img src="https://picsum.photos/100/100" hspace="10" >
<img src="https://picsum.photos/100/100" hspace="10" >
</p>
We also have a property "vspace", which does what it sounds like, add vertical spacing. But it doesn't seem to work on GitHub, unlike VSCode's buit in markdown viewer. So probably just add a <p> tag in between.
<p>
<img src="https://picsum.photos/500/100" >
<p>
<img src="https://picsum.photos/500/100" >
<p>
<img src="https://picsum.photos/500/100" >
</p>
To add video you need to upload your video file and reference it inline
https://user-images.githubusercontent.com/1702215/158075475-c23004ab-827a-45ad-bdba-aee29ac5b582.mp4
Example:
demo.mp4
Tip via this tweet. Swap out images based on theme settings
Using footnotes
Here is a simple footnote1. With some additional text after it.
Here is a simple footnote[^1]. With some additional text after it.
[^1]: My reference.
text with line through it
~~text with line through it~~
Normal text here.
Tiny text is here. Awwwww its so cuteeeeeeeeeee
How?
<sup><sub>Add your tiny text</sub></sup>
Add a box with contents to markdown
|
This is text in the box. Much wow |
<div align="center">
<table>
<tbody>
<td align="center">
<img width="2000" height="0"><br>
<sub>This is text in the box. Much wow</sub><br>
<img width="2000" height="0">
</td>
</tbody>
</table>
</div>
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>
Add call outs in markdown
Note
Highlights information that users should take into account, even when skimming.
Tip
Optional information to help a user be more successful.
Important
Crucial information necessary for users to succeed.
Warning
Critical content demanding immediate user attention due to potential risks.
Caution
Negative potential consequences of an action.
> [!NOTE]
> Highlights information that users should take into account, even when skimming.
> [!TIP]
> Optional information to help a user be more successful.
> [!IMPORTANT]
> Crucial information necessary for users to succeed.
> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.
> [!CAUTION]
> Negative potential consequences of an action.
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)
For whatever reason the graphql syntax will nicely highlight file trees like below:
# Code & components for pages
./src/*
├─ src/assets - # Minified images, fonts, icon files
├─ src/components - # Individual smaller components
├─ src/fragments - # Larger chunks of a page composed of multiple components
├─ src/layouts - # Page layouts used for different types of pages composed of components and fragments
├─ src/page - # Custom pages or pages composed of layouts with hardcoded data components, fragments, & layouts
├─ src/pages/* - # Next.js file based routing
│ ├─ _app.js - # next.js app entry point
│ ├─ _document.js - # next.js document wrapper
│ ├─ global.css - # Global CSS styles
│ └─ Everything else... - # File based routing
└─ src/utils - # Utility functions used in various placesUse HTML/CSS in a readme via an SVG! source
The above image is embedded like so:
<div align="center">
<br/>
<a href="https://github.com/DavidWells/advanced-markdown/blame/master/svg-with-css.svg">
<img alt="Click to see the source" height="400" src="svg-with-css.svg" width="800" />
</a>
<br/>
</div>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
- 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
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.
- 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
- Extended markdown syntax
- Markdown snippets
- Verb - Documentation generator for GitHub projects
- ACSII docs - Markdown alternative
- Markdown parser performance comparison
- Handy markdown templates
Footnotes
-
Example footnote ↩