Skip to content

DavidWells/advanced-markdown

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

50 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Advanced Markdown Guide

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!

Image with alt & title

![Alt text](/path/to/img.jpg "image title")

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="https://picsum.photos/100/100">

right alignment

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">

center alignment example

<p align="center">
  <img width="460" height="300" src="https://picsum.photos/460/300">
</p>

Horizontal images no gap

via comment

<p>
    <img src="https://picsum.photos/100/100" >
    <img src="https://picsum.photos/100/100" >
</p>


Horizontal images with gap

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>


Vertical images with gap

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>


Adding video

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

light/dark mode images

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.

Strikethru text in markdown

text with line through it

~~text with line through it~~

Tiny text in markdown

Normal text here.

Tiny text is here. Awwwww its so cuteeeeeeeeeee

How?

<sup><sub>Add your tiny text</sub></sup>

Text box

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>

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>

Call outs

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.

additional links

WebsiteEmail UpdatesGitterForumMeetupsTwitterFacebookContact 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])

Badges

CI Package Manager CI Web SIte Known Vulnerabilities Coverage Status js-standard-style

<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>

Nice looking file tree

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

Using CSS in Readme

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>

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

Footnotes

  1. Example footnote

About

Learn about advanced markdown techniques

Resources

Code of conduct

Security policy

Stars

Watchers

Forks

Releases

No releases published

Sponsor this project

 

Packages

No packages published