Markdown Madness

Static Sites for Fun & Profit

Gilbert Sanchez
@HeyItsGilbert

Agenda

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

Thanks

Hey! It's Gilbert

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 thats ppt you're watching?

You think this is PowerPoint you're watching?

Flavor Examples

  • Strikethroughs
  • Footnotes [^1]
  • ^Superscript
  • Tables
  • Math
  • Mermaid
  • [x] Task List
[^1]: Give 5 stars

Hello world time

# Hello

Hello world!

## Turtles

I *like* them!

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.

screenshot of frontmatter CMS

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

10:30a Thursday Description: You already write Markdown. README.md, meeting notes, maybe even your grocery list. But what if that Markdown could become a blog, a polished docs site, a personal resume, or even a link-in-bio page? Turns out, it can - and the tools are way cooler (and easier) than you think. In this session, we'll go on a whirlwind tour of static site generators: Jekyll, MkDocs, Hugo, Docusaurus, plus some delightful "non-docs" options like jsonresume and littlelink.io. We'll talk about what each is good at, how to pick the right one, and how to actually get it online without sacrificing weekends to YAML. Along the way, we'll also cover Markdown/MDX tricks and VS Code extensions to keep things sane. Whether you're looking to document your project, polish your personal brand, or just hack together something fun, you'll leave knowing how to take plain Markdown and ship it as something awesome. Key Take-Aways from your session: - Learn the strengths and tradeoffs of popular static site generators (Jekyll, MkDocs, Hugo, Docusaurus, etc.). - Discover "non-docs" generators like jsonresume and littlelink.io. - Understand Markdown vs. MDX and when each makes sense. - Use VS Code tools to lint, edit, and manage Markdown like a pro. - Deploy your site easily (GitHub Actions, Netlify, containers) without breaking a sweat.

- Slides (~25m) - Markup Languages - Markdown Flavors - Static Sites - Tools - 10m Break - Demos - Q&A I can fill 90m+ on this topic, but beyond just Q&A I want to step through real requests.

Author slide

Formerly known as Senor Systems Engineer at Meta Audience Poll: Who has a blog? My history as a "webmaster"

This is actually marp!

Flavors - GitHub Flavored - ExtraMark - etc.

There is also back matter at the bottom.

The OG of static site generators. Been around since 2008. GitHub Pages runs Jekyll natively — zero config deploy.

If you're documenting a project, this is probably the one. Material theme makes it look professional with minimal effort.

Hugo is the Swiss Army knife. Fast builds even with thousands of pages. Great if you want more than just docs.

From Meta (Facebook). If your team already knows React, this is a natural fit. MDX lets you embed interactive components in your docs.

Goal: 25m - ~11a