Your Notes Are Already Publish-Ready: A Folder of Markdown Is a Website

A folder of plain Markdown is already a website's source. A static-site generator reads the files and writes HTML; the pattern was first shown publicly on November 17, 2008, and the file format has not changed. You do not need a vendor's publish button to put your notes on the web.

The receipt is older than most people remember. On that date, Tom Preston-Werner wrote a post called "Blogging Like a Hacker" and announced a tool with one job: "Jekyll is a simple, blog aware, static site generator. It takes a template directory (representing the raw form of a website), runs it through Textile and Liquid converters, and spits out a complete, static website suitable for serving with Apache or your favorite web server."¹

Seventeen years on, the Jekyll repository still ships under the same MIT license, the CommonMark specification the modern generation reads is a public standard at version 0.31.2 dated 2024-01-28,² and Hugo — the most popular successor — is now an 88,753-star project under Apache-2.0, with its current release v0.163.3 dated 2026-06-18.³ The mechanism is unchanged: your notes, your folder, your HTML.

What does it mean to publish a folder of Markdown?

To publish a folder of Markdown is to point a static-site generator at it and let the generator emit HTML. The Markdown stays. The HTML appears in an output directory ready to upload, or built for you on a host. Jekyll's homepage states the contract: "Markdown, Liquid, HTML & CSS go in. Static sites come out ready for deployment."⁴

The build step is the load-bearing verb. Preston-Werner named it in 2008 — the generator "runs it through… converters, and spits out" a website¹ — and every modern descendant does the same thing in a different language.

Hugo, the speed-focused Go project, describes itself as "a static site generator written in Go, optimized for speed and designed for flexibility,"⁵ with sites that "build in seconds, often less."⁵ Eleventy, the JavaScript option, calls itself "a simpler static site generator,"⁶ and its docs describe a template as "a content file written in a format such as Markdown, HTML, Liquid, Nunjucks, and more, which Eleventy transforms into a page (or pages) when building our site."⁷ Three projects, three languages, one verb: read Markdown, write HTML.

How is a Markdown link actually published?

A Markdown link becomes an HTML anchor because the CommonMark specification defines exactly what the bracket-and-parenthesis shape means, and every conformant generator reads it the same way. The text you type — [Title](https://example.com) — passes through the build step and lands as <a href="https://example.com">Title</a> in the output file. Your file does not change. A new file appears next to it.

The spec is precise. CommonMark §6.3 defines the link form in one sentence: "An inline link consists of a link text followed immediately by a left parenthesis (, an optional link destination, an optional link title, and a right parenthesis )."⁸ Jekyll, Hugo, and Eleventy all read that sentence the same way, because they all read the spec.

That is why the same .md note can move between generators, and between editors, without the link breaking. The shape is the contract — which is also why your in-note cross-references survive an app change, covered separately in Your Hyperlinks Survive the App.

What does a static-site generator actually do?

A static-site generator takes a folder of inputs — Markdown content, a template, a tiny configuration — and writes a folder of outputs you can serve as a website. The inputs stay; the outputs are disposable. Build, deploy, throw away the build, rebuild from the same files tomorrow. The source of truth never leaves your hands.

notes/
├── _config.yml          # tells the generator what to do
├── about.md             # plain Markdown — the source
├── 2026-06-27-hello.md  # plain Markdown — the source
└── _site/               # generated by the build step
    ├── about.html
    ├── 2026/06/27/hello.html
    └── index.html

The exact shape of that tree varies by generator (Hugo uses content/ and public/; Eleventy uses an input directory and an _site output; Jekyll uses what is above). The principle does not vary. The Markdown files are the canonical version of the writing; the HTML is a render, the same way a checkbox in a task list is a render of the three characters underneath. If a generator vanishes tomorrow, the Markdown is still your Markdown.

What is the simplest workflow, end to end?

The simplest end-to-end workflow has four steps, runs once, and then becomes a habit. The longest part is the first one — choosing where the HTML lives. After that the loop is write a note, commit, push, and the host builds and deploys the site for you.

1. Write a note in plain Markdown. A heading, a few paragraphs, a link. Save it as 2026-06-27-my-note.md in the same folder as your other notes. The filename becomes part of the URL on most generators; see How to Name Your Note Files for the conventions.
2. Add a tiny header. Most generators read a few lines of YAML at the top — title, date, optional tags. This is the metadata layer the generator uses to build a listing page. The yaml-frontmatter post covers what goes in it; you do not need to memorize the syntax to start.
3. Point a generator at the folder once. jekyll new my-site or hugo new site my-site or npx @11ty/eleventy --serve initializes the project. After that you mostly forget the generator exists. The folder of .md is the part you touch.
4. Pick a host and connect the folder. The next section names four good options. The host runs the build for you on every commit; you push the Markdown, the website appears.

Read that loop back to yourself. Step one is write. Step four is push. The middle two are configuration you do once. The publishing surface is doing the work of converting and serving.

The four publishing surfaces that take Markdown as input

Four hosting surfaces will accept a folder of Markdown today and turn it into a public website without a vendor's editing app in between. Each is documented, free at the tier most personal sites need, and well-trodden. The choice between them is about preference and existing accounts, not about whether the underlying pattern works.

GitHub Pages

GitHub Pages is the surface with the shortest path. Put a Jekyll-shaped Markdown folder in a public repository, switch on Pages in the repo settings, and the site builds on every push. The "build" is invisible to you. GitHub's own documentation states the contract: "Jekyll is a static site generator with built-in support for GitHub Pages and a simplified build process."⁹ If you already use GitHub for code, this is the path with the fewest new accounts.

Cloudflare Pages

Cloudflare Pages takes any framework that emits static files. The framework-guides directory documents step-by-step deployment for Hugo, Jekyll, Eleventy, Next.js, Astro, and roughly twenty more — the Hugo guide is at developers.cloudflare.com/pages/framework-guides/deploy-a-hugo-site/.¹⁰ You point Cloudflare at your git repository, name the build command (hugo, jekyll build, eleventy), and the host runs it on each commit. The setup is mechanical and the build logs are public to you, which makes debugging easy.

Netlify

Netlify pioneered the "git push to deploy" pattern for static sites and remains a default in many setups. Hugo, Jekyll, and Eleventy each have first-class build hooks; you connect a repository, pick a generator, and Netlify handles the deployment chain. The hand-wavy part of "deploy a Markdown site" stops being hand-wavy: the build command runs in their cloud, the HTML appears at a URL, and your folder of .md did not have to move.

Any HTTP server you control

The path most people forget is the oldest one. A static-site generator's output is a directory of .html, .css, and image files. Drop that directory on an Apache or nginx server you already own and the website is live; no third-party service is involved at all. This was the original promise — "suitable for serving with Apache or your favorite web server"¹ — and it remains true. Bandwidth and a domain are the only ongoing costs.

The honesty caveats nobody mentions until you have a problem

Six caveats sit underneath the "just publish your folder" pitch. None of them break the pattern; all of them break specific assumptions readers usually carry into it. Read them before you start, and the rest of the work is straightforward — the failure modes are known, named, and small.

• You still need a build step. Your notes do not auto-publish; a generator has to run, either on your machine or on the host. Preston-Werner named this in 2008 — the generator "runs it through… converters, and spits out" a website¹ — and the verb is still load-bearing. On GitHub Pages and Cloudflare Pages the build runs for you on each commit, which is why those surfaces feel friction-free; locally, you run hugo or jekyll build yourself.
• Front-matter is non-standard. The YAML header most generators read (title, date, layout) is not part of CommonMark. The block at the top of the file is plain text, which is why a renderer that does not understand it ignores it cleanly, but a different generator may expect TOML or JSON instead. The yaml-frontmatter post covers what to put in it; the warning is just that the convention varies by generator.
• Image attachments are the portability bug. Pasting an image into a note app creates an attachment somewhere in the vault, and not every generator resolves the path the same way. The fix is mechanical — keep images in a known folder next to the .md and link them with standard ![alt](path.jpg) syntax — but it has to be done deliberately. The bug is documented at length in Your Markdown Is Portable Until You Add an Image.
• Wikilinks are not plain Markdown. Obsidian-style [[Page]] links do not render in vanilla Jekyll, Hugo, or Eleventy without a plugin. Tools built for the Obsidian world — Quartz, for example, which describes itself as "a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites"¹² — handle them natively. If you use vanilla SSGs, convert wikilinks to standard [Page](page.md) syntax. The discipline is covered in Wikilinks Aren't Plain Markdown.
• A vendor "Publish" button is faster, but it locks the format. For comparison, Obsidian's hosted publish product, Obsidian Publish, lists pricing at $8 per site per month billed annually, or $10 billed monthly,¹³ with the tagline "Give your knowledge a home on the web."¹³ That product is a convenience: you click a button and a site appears. The trade is the door — your storage backend, your URL structure, and your migration story all live with that vendor. The plain-Markdown route is slower to set up once and faster to escape forever. Obsidian Publish is a serious product; the comparison here is between patterns (vendor-hosted convenience vs. file-owned permanence), not between brands.
• "Free" applies to the publishing pattern, not necessarily the bill. GitHub Pages and Cloudflare Pages have free tiers that cover personal sites comfortably. A high-traffic site, a custom domain with paid DNS, or a CDN add-on can move the cost from zero to a few dollars a month. Do not oversell free hosting; sell instead what the pattern actually gives you, which is ownership of the source.

Why this pattern outlives any single tool

The pattern outlives any single tool because the file format is open, the build step is interchangeable, and the host is replaceable. Your notes do not depend on a vendor's editor staying in business, a vendor's database staying online, or a vendor's pricing staying the same. The thing on disk is the thing that lasts.

Two voices, on their own domains, name what the pattern protects. Steph Ango, the CEO of Obsidian and an essayist on his own site, puts it the bluntest way: "Apps are ephemeral, but your files have a chance to last."¹⁴ Maggie Appleton, writing on her own garden site, frames the same point as a principle of ownership: gardening online is "claiming a small patch of the web for yourself, one you fully own and control."¹⁵ Both lines work because they are about files, not features.

The pattern is older than the audience usually thinks. Andy Matuschak's notes site at notes.andymatuschak.org predates most of the modern "digital garden" movement and stays online without an app between the writer and the reader. His own description is characteristically dry: "These notes are mostly written for myself: they're roughly my thinking environment."¹⁶ The reader who follows a link in a search engine and lands on his page is reading a .html file that started life as a .md file in a folder — the same shape this post is about.

The demand is current. The most popular Hacker News thread on this topic from the last two years — Gautham Shankar's "How I blog with Obsidian, Hugo, GitHub, and Cloudflare," posted by ingav on 2025-04-23 — collected 336 points and 237 comments.¹¹ On his own site, Shankar names the value the comment section was reaching for: "This stack gives me full control: no subscriptions, no vendor lock-in, and no risk of platforms disappearing or changing policies."¹⁷

That sentence is one practitioner's, not a manifesto, but it does the work an honest pitch should: it names what is gained and what is given up. The given-up part is the click. The gained part is the rest of the life of the file.

This piece is the publishing-mechanism companion to How to Grow a Digital Garden in Plain Markdown, which covers the garden as a mental model — link by topic, not by date — without committing to a build pipeline. Read together they describe the same idea on two layers: the why (a garden you own) and the how (a folder you can build into a website).

How this works with a folder of plain Markdown notes

In a note app that writes plain .md files locally, the publishing step is the same as anywhere else. The static-site generator reads the file the editor saved; there is no vendor-specific export between the two. The file in the folder is the file the build step consumes — your editor and your website share one source.

Tools like Jekyll, Hugo, Eleventy, and Quartz are external generators that all speak the same Markdown your notes already use; nothing about the format is owned by any one editor.

That is the entire point. A note app's job is to make the file pleasant to write; the format's job is to make the file pleasant to keep. When the two stay separate — open Markdown on your own device on one side, an open static-site generator on the other — the publish step is glue, not lock-in. You can change the editor without changing the website, and you can change the website without rewriting your notes. The folder is the contract between them.

Frequently asked questions

How do I publish my Markdown notes as a website? Point a static-site generator at the folder of .md files and host the output. Jekyll, Hugo, and Eleventy all read Markdown that conforms to the CommonMark specification² and write HTML you can serve from GitHub Pages, Cloudflare Pages, Netlify, or any HTTP server.¹⁹¹⁰ The Markdown files stay as they are; the HTML is built next to them.

Can I publish my Obsidian vault as a blog? Yes. An Obsidian vault is a folder of Markdown, so it works with any generator that reads Markdown. If the vault uses Obsidian-specific wikilinks ([[Page]]), use a generator built for those conventions — Quartz describes itself as "a fast, batteries-included static-site generator that transforms Markdown content into fully functional websites,"¹² and Obsidian's own help URL for obsidian.md/publish is the vendor-managed alternative.¹³ Vanilla Jekyll or Hugo will publish vault notes too, provided you convert wikilinks to standard [Page](page.md) links first.

Do I need Obsidian Publish to put my notes online? No. Obsidian Publish is one paid product — currently $8 per site per month billed annually, or $10 billed monthly,¹³ with the tagline "Give your knowledge a home on the web."¹³ The same .md files render via Jekyll, Hugo, Eleventy, or Quartz on free or self-hosted infrastructure. The choice is between the convenience of a click and the permanence of a folder you own.

How do I set up Hugo with Obsidian? Treat the Obsidian vault as Hugo's content/ folder, or copy notes into it. Hugo describes itself as "a static site generator written in Go, optimized for speed and designed for flexibility,"⁵ and Cloudflare Pages documents the deployment step with a dedicated Hugo framework guide.¹⁰ The recurring catch is wikilinks (see the caveats above) and image attachment paths — both worth resolving before you push the first commit.

What is the difference between Jekyll, Hugo, and Eleventy? All three read Markdown and write HTML; they differ in language and convention. Jekyll runs on Ruby and is bundled with GitHub Pages.⁹ Hugo runs on Go, is built for speed, and uses TOML or YAML configuration.⁵ Eleventy runs on JavaScript and is positioned as the simpler option.⁶⁷ Pick the one whose ecosystem and language you already touch — the format you write in does not change between them.

Do I have to know HTML to publish a Markdown site? No. The generator writes the HTML; you write the Markdown. CommonMark §6.3 spells out the link form precisely — "An inline link consists of a link text followed immediately by a left parenthesis (, an optional link destination, an optional link title, and a right parenthesis )."⁸ — and that level of structure is enough to publish. You will eventually want to read the templates if you want to change the design, but you do not have to.

Where should I host a Markdown blog for free? The honest answer is "where your existing accounts already are." GitHub Pages is free for public repositories and builds Jekyll for you.⁹ Cloudflare Pages has a free tier and documents many frameworks, including Hugo.¹⁰ Netlify offers a comparable free tier with broad framework support.¹¹ All three remove the local build step by running it on each commit.

What is a digital garden, and is that the same as a Markdown blog? A digital garden is a publishing mental model — pages linked by topic and updated over time rather than dated posts — while this post is about the mechanism. The garden side of the same idea is covered in How to Grow a Digital Garden in Plain Markdown; the mechanism here works for either shape, garden or blog, because the input is the same folder of Markdown files.

A folder of Markdown was always a website's source. Tom Preston-Werner showed it could be published on November 17, 2008; the format has not needed to change since. A note kept on your own device, in open Markdown, like the ones in mnmnote.com, is already most of the way to a website you control.