I've spent the past few months working on hosted.md, a tool that turns Markdown files into websites. The goal was clear: make it easy for anyone to host a static site without dealing with build pipelines, config files, or deployment steps.
I thought it would be a straightforward project. Static site generation has been around for a long time, and there are plenty of tools that already do it. But building something that feels truly simple, especially for people who aren't already familiar with static tooling, turned out to be more complicated than I expected.
The Illusion of Simplicity
In the static site world, a lot of complexity is hidden behind layers of tools and assumptions. If you've used Jekyll, Hugo, or Astro, you know how it goes. You write your content, run a build command, and upload the result.
That’s manageable for developers. But not everyone wants to install a package manager, configure a theme, write frontmatter, set up a deploy script, link it to GitHub, and configure their domain with a cloud provider. Even for experienced devs, doing all that just to get a few pages online can feel heavy.
The first real challenge was figuring out how to actually remove those steps rather than just wrapping them in automation.
Static Content, Dynamic Process
The idea behind hosted.md is that you write Markdown and the site builds on its own. You can store your content in a Git repo or use a built-in editor. The result is a static site, but behind the scenes there’s a live system that handles builds, file changes, previews, and eventually analytics.
That internal system brought a lot of unexpected problems. I had to think about how to trigger builds without requiring a command-line tool. How to detect partial changes when only one file is updated. How to serve static content from S3 and still let users connect their own domains.
I spent a lot of time working on pieces that the user would never even see. And that was kind of the point. The experience needed to feel like it all just worked, even though a lot was happening under the surface.
Scope is a Moving Target
Just when I thought I had the basics covered, new edge cases would show up.
- What happens when someone wants a custom sidebar order?
- What if the homepage file is accidentally deleted?
- How should invalid Markdown be handled?
- What if a user changes their domain while a build is in progress?
I started building a settings interface to handle all these things, but pretty quickly it started to feel more like a CMS than a static site tool. That wasn’t what I wanted this to become. The original idea was to keep it focused: Markdown goes in, a working site comes out.
I took a step back and wrote down a few guiding rules:
- If a feature doesn’t help someone build a blog or documentation site, it doesn’t make the cut.
- If a setting takes more than one screen to configure, it stays out.
- If it adds extra logic just to handle rare edge cases, it can wait.
Once I started following those guidelines, the direction of the project became much clearer.
Accepting the Tradeoffs
To keep the experience as focused as possible, I had to let go of some nice-to-have features.
- There are no plugins or custom build steps at the moment.
- There’s no way to fine-tune caching headers.
- There’s no full version history for every edit.
I know some users will want those features. That’s okay. I’m building this for the people who want to create a site without getting pulled into hours of configuration or debugging.
It’s always a balance between giving people control and keeping the tool approachable. The hardest part is deciding where to draw that line and being willing to stick with it.
What This Has Taught Me
- Making something feel easy often requires more thought than building a more complex tool.
- Good defaults reduce decision-making. If the defaults are right, people don’t need to touch the settings at all.
- Most of the difficulty isn’t in writing the code. It’s in shaping the experience so it makes sense without needing explanation.
I’m still building hosted.md. There’s a lot left to do. But it’s getting closer to what I set out to make: a way to publish content using Markdown that doesn’t turn into a weekend-long project.
If that sounds interesting or if you’ve been down a similar path, I’d love to hear what you've learned. You can follow the progress on Bluesky, or sign up to the wait list at hosted.md for early access when it’s ready.