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!
![Alt text](/path/to/img.jpg "image title")
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
![Logo](./dark.png#gh-dark-mode-only)
![Logo](./light.png#gh-light-mode-only)
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
<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>
You can add fancy zoomable charts
%%{ init: { "er" : { "layoutDirection" : "LR" } } }%%
erDiagram
User ||--o{ Vote : submits
Vote o{--|| Link : on
Link o{--|| Score : has
Here's another cool example of a sequence diagram
sequenceDiagram
actor Extension
participant API
participant Database
Extension->>API: POST /vote {link, vote, user_id}`
activate API
API->>API: Validate parameters
alt Invalid parameters
API->>Extension: Error: Invalid parameters
end
API->>Database: Check user history & settings. GetBatchItems(___________)
Note over API,Database: Voting disabled? GetItem(PK=settings, SK=settings)
Note over API,Database: Too many votes? GetItem(PK=date, SK=user_id)
Note over API,Database: User exists? User banned? GetItem(PK=user_id, SK=user_id)
Note over API,Database: Already voted? GetItem(PK=link, SK=user_id)
activate Database
alt Database Error
Database->>API: Database Error (connection / server...)
API->>Extension: Server Error
end
Database->>API: Return UserHistory & Settings
deactivate Database
API->>API: Check user history & Settings
alt Failed
API->>Extension: 403 Forbidden: Too many votes / banned / voting disabled
end
activate Database
API->>Database: Submit vote. BatchWriteItems(_________________)
alt If user does not exist
Note over API,Database: Put(PK=user_id, SK=user_id | not_banned,created_at)
Note over API,Database: <run [First time user voting on link]>
else First time user voting on link
Note over API,Database: Put(PK=link, SK=user_id | vote)
Note over API,Database: Update(PK=link, SK=link | count_of_votes++, sum_of_votes+=vote)
Note over API,Database: -- Add history
Note over API,Database: Update(PK=day, SK=link | count++, sum+=vote)
Note over API,Database: Update(PK=day, SK=user | count++, sum+=vote)
else If user already voted on link
Note over API,Database: Put(PK=link, SK=user_id | vote)
Note over API,Database: Update(PK=link, SK=link | sum_of_votes+=(-old_vote+new_vote))
Note over API,Database: -- Undo old history
Note over API,Database: Update(PK=old_day, SK=link | count--, sum-=old_vote)
Note over API,Database: Update(PK=old_day, SK=user | count--, sum-=old_vote)
Note over API,Database: -- Add history
Note over API,Database: Update(PK=day, SK=link | count++, sum+=vote)
Note over API,Database: Update(PK=day, SK=user | count++, sum+=vote)
end
activate Database
alt Database Error
Database->>API: Database Error (connection / server...)
API->>Extension: Server Error
end
Database->>API: Return success
API->>Extension: Return success
deactivate Database
deactivate API
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:[email protected])
<div align="center">
[![CI](https://github.com/fastify/fastify/workflows/ci/badge.svg)](https://github.com/fastify/fastify/actions/workflows/ci.yml)
[![Package Manager CI](https://github.com/fastify/fastify/workflows/package-manager-ci/badge.svg)](https://github.com/fastify/fastify/actions/workflows/package-manager-ci.yml)
[![Web SIte](https://github.com/fastify/fastify/workflows/website/badge.svg)](https://github.com/fastify/fastify/actions/workflows/website.yml)
[![Known Vulnerabilities](https://snyk.io/test/github/fastify/fastify/badge.svg)](https://snyk.io/test/github/fastify/fastify)
[![Coverage Status](https://coveralls.io/repos/github/fastify/fastify/badge.svg?branch=main)](https://coveralls.io/github/fastify/fastify?branch=main)
[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](https://standardjs.com/)
</div>
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 places
Use 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)
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.
- 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 ↩