I wanted a dumb & simple way to make a modern website with text files, so I made one. Small, static-first Next.js boilerplate, intentionally minimal, just markdown → website, with optional React components when you want them.
Just updated it; what’s new:
• Next.js 15.5.2 + React 19.1.1
• Better typing for error boundaries (React 19)
• Robust handling for Next 15 async params
• Updated DaisyUI, MDX, and tooling
Use it for docs, personal sites, landing pages, or simple content sites that still want modern Next.js ergonomics.
I have a fairly old mental bookmark for this purpose: blot.im. Wondering if it still holds up, or perhaps newer entrants can do the same but more elegantly.
Seems like markdown is back in vogue. The more the merrier as far as I'm concerned.
Next.js and React are the problem here. Adding another layer adds complexity. To simplify, you should remove complexity. To comprehensively address the problem you should strike at the root causes, rather than adding yet another layer of duct tape.
obviously it's deeply unhinged to suggest this is method is easy, or indeed a good idea at all, but if you want actually easy ways to do this, Zola and eleventy are both actually quite easy and will get you OK looking static html output in a few minutes of effort.
If you prefer to generate a static site, take a look at https://soupault.app/
It generates a static website from markdown or other formats. Mentioning it here because it deserves more attention than it currently gets.
Looks great, but it is clearly crying for "yaml front matter", eg: `import ...\n----\n# Content ...`, either that or `<?mdx/php ... ?>` tags... ;-)
Seriously, love this simplification of content, and taking care of all the hairy details around `<CustomComponent>...</...>`. It's what the web should have been all along!
If you take an `*.mdx` file and run it through a typical markdown renderer, you'd get something like... well... lemme give the counter-example: if you had the "dashes" delimiting your "frontmatter" from the document, you'd get something like:
<hr>import foo, bar, baz<hr>\n<h1>Markdown</h1><ul><li>...etc...
...the critical part being to relatively unambiguously demarcate "junk" from "content" in the markdown ecosystem. In the far future when this project is but a forgotten memory of time, people can still just straight up render the markdown and "obviously" delete the stuff between the <hr's> up at the top.
The contrarian is that there's ambiguity as to when your `*.mdx` "import junk" stops and when the actual content starts. Do you stop parsing [for imports] after the first blank line? Do you stop parsing when you get a syntax error? Do you only parse lines that begin with [import ...]? What about [from ... import ...]?
...strong recommendation: demarcate "headers" from content (a-la HTTP). Your format effectively becomes `---\n $PROG_LANG_GOES_HERE ---\n $CONTENT_HERE`, and you slide 1000% into "pure HTTP":
GET /foo.mdx
Content-Type: application/mdx
Date: 2020-10-10 01:02:34
---
import SomeComponent
---
<SomeComponent>My Header</SomeComponent>
* Some
* Content
I actually previously used Jekyll! Built this largely because I want full React component functionality sometimes. Also I think Jelyll gave me some issues with routing that I didn’t like.
I was expecting a sort of MD to HTML conversion since it's hard to think of a simpler way of doing this. I don't see how react or nextjs constitutes this being easy or simple unless you're targeting folks with domain knowledge with those ecosystems.
You’re getting close. The biggest thing is that I want to be able to use React components sometimes and anywhere on the page. If you just want md -> html, there are of course much better options.
I highly recommend Astro and Starlight for building websites from Markdown. It is very simple to set up and can grow with you as your needs become more complex.
It has server-rendered mdx, client components, inline footnotes, layout bleeding, server-rendered code syntax highlighting, content-collections, and opengraph image generation. It can be rendered fully static or from a server. If you choose to deploy it as static, the "server"-rendering just happens at build-time.
It's a really decent starting point for someone who wants an efficient, lean, powerful, and flexible blog.
I like Quarto¹ which supports authoring websites, blogs,² books, and presentations. It also supports publishing directly from Jupyter Notebooks, if that's the type of work you're doing. My only (minor) complaint is there isn't much of a thriving theming community for it.
Neato indeed, but the color contrast for copy and other elements doesn't meet AA accessibility standards (even my young-ish eyes have a bit of trouble). Still, this is in line with a project I've been meaning to do, so this is pretty great stuff.
40 comments
[ 4.3 ms ] story [ 163 ms ] threadJust updated it; what’s new:
• Next.js 15.5.2 + React 19.1.1 • Better typing for error boundaries (React 19) • Robust handling for Next 15 async params • Updated DaisyUI, MDX, and tooling
Use it for docs, personal sites, landing pages, or simple content sites that still want modern Next.js ergonomics.
Seems like markdown is back in vogue. The more the merrier as far as I'm concerned.
https://github.com/obaqueiro/ezmdpage
And inspired by it made a similar thing for mermaid.
https://github.com/obaqueiro/mermaid-js-auto-renderer
Great to add /docs into code repos.
1. https://idratherbewriting.com/learnapidoc/pubapis_static_sit...
You are welcome.
Seriously, love this simplification of content, and taking care of all the hairy details around `<CustomComponent>...</...>`. It's what the web should have been all along!
Precisely! Thank you.
Can you share more about what you have in mind for frontmatter? I don’t really understand the need/use cases yet.
Basically:
eg: https://docs.github.com/en/contributing/writing-for-github-d... ... https://jekyllrb.com/docs/front-matter/ ... and google search for "rst yaml frontmatter"If you take an `*.mdx` file and run it through a typical markdown renderer, you'd get something like... well... lemme give the counter-example: if you had the "dashes" delimiting your "frontmatter" from the document, you'd get something like:
...the critical part being to relatively unambiguously demarcate "junk" from "content" in the markdown ecosystem. In the far future when this project is but a forgotten memory of time, people can still just straight up render the markdown and "obviously" delete the stuff between the <hr's> up at the top.The contrarian is that there's ambiguity as to when your `*.mdx` "import junk" stops and when the actual content starts. Do you stop parsing [for imports] after the first blank line? Do you stop parsing when you get a syntax error? Do you only parse lines that begin with [import ...]? What about [from ... import ...]?
More google searches: `http header demarcation rfc`, and eg: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/...
...strong recommendation: demarcate "headers" from content (a-la HTTP). Your format effectively becomes `---\n $PROG_LANG_GOES_HERE ---\n $CONTENT_HERE`, and you slide 1000% into "pure HTTP":
I consider my own static site generator [1] much simpler than this. Around 250 SLOC with 4 dependencies (markdown2, pyyaml, jinja2, Pygments)
[1]: https://github.com/oxalorg/genox
But isn't Hugo or Jekyll the easy way to turn markdown into a website?
Jekyll was literally made by github to have a simple way to turn a markdown page into a github pages site. Wasn't it?
Just put an index.md in the root of a empty repo and flip the right flags in Github and have a static site.
Hmmmmmm no
https://starlight.astro.build/
I've been considering Spinal[0] (no association) to bridge that gap, any others I should be looking at?
[0] https://spinalcms.com
Push updates to the md file and it rebuilds itself.
https://github.com/automationwise/awise.github.io
You can see it here: https://rsc-mdx-blog.saewitz.com
It has server-rendered mdx, client components, inline footnotes, layout bleeding, server-rendered code syntax highlighting, content-collections, and opengraph image generation. It can be rendered fully static or from a server. If you choose to deploy it as static, the "server"-rendering just happens at build-time.
It's a really decent starting point for someone who wants an efficient, lean, powerful, and flexible blog.
It is open sourced here: https://github.com/switz/rsc-mdx-blog-starter
[0] https://saewitz.com
¹ https://quarto.org/
² https://quarto.org/docs/websites/website-blog.html
[0]: https://imgur.com/a/ysgJbCp