Markdown Madness

#

Static Sites for Fun & Profit

#

Gilbert Sanchez @HeyItsGilbert

Agenda

#

• Markup? Markdown?
• Static Sites
• Tools
• Demos
• Q&A

Thanks

#

Hey! It’s Gilbert

#

• Staff Software Development Engineer
• ADHD 🌶️🧠
• Links.GilbertSanchez.com

But First… A Warning

#

This talk is mostly about markdown… but anything goes when it comes to static generation!

#

What is Markdown?

#

A lightweight markup language for easily formatting text.

#

What is Markdown?

#

A lightweight markup language for easily formatting text.

• Markdown (md)
• Asciidoc (adoc)
• reStructuredText (reST)

You think this is PowerPoint you’re watching?

Flavor Examples

#

• Strikethroughs
• Footnotes [^1]
• ^Superscript
• Tables
• Math
• Mermaid
• Task List

Hello world time

#

# Hello

Hello world!

## Turtles

I *like* them!

Front Matter

#

Front matter is YAML provides metadata or configuration.

---
title: Hello
---
# Hello

Hello world!

Static Sites

#

Static sites are:

1. CLI-generated
2. Output as HTML
3. No runtime server.

Jekyll

#

• Written in Ruby
• Great for docs and blogs
• GitHub Pages built-in support
• Liquid templating
• Mature ecosystem with many themes

MkDocs

#

• Written in Python
• Purpose-built for documentation
• Material for MkDocs theme is excellent
• Simple mkdocs.yml configuration
• Live reload dev server

Hugo

#

• Written in Go
• Blazingly fast builds
• Docs, blogs, portfolios, and more
• Powerful templating and shortcodes
• Single binary, no dependencies

Docusaurus

#

• Written in React
• Built for documentation sites
• MDX support (Markdown + JSX)
• Versioned docs out of the box
• Built-in search and i18n

VSCode Extensions

#

• GitHub Markdown Preview
• markdownlint
• Reflow Markdown
• Markdown All in One
• Marp for VS Code

FrontMatter CMS

#

VSCode Extension to punches above it’s weight class.

Tools

#

• markdownlint: Markdown best practices.
• Vale: Prose syntax.
• alex: Catch insensitive writing.
• Docker: Run in a container.

Maybe Your Favorite LLM?

Deploying Services

#

• GitHub Pages
• Netlify
• Cloudflare
• Vercel
• So many more…

Demo Time

#

THANK YOU

#

Feedback is a gift

#

Please review this session via the mobile app

Questions? Find me @heyitsgilbert