Next.js 15 Markdown Boilerplate
45 comments
·August 30, 2025arandomhuman
pseudosavant
I was expecting a really simple static-site generator too, but this idea is interesting as well. The heavyweight aspect of using Next/React dampen things a bit.
If it is a client-side solution, I'm imagining a single index.html file (with inline JS/CSS) that you could have a content/ or markdown/ child folder for. The HTTP server would have directory listing on for that folder. The index.html file enumerate/fetch the markdown in the content and folder and render it. You could route using the URL hash.
No build process. Just a single file + your markdown content. Maybe I just like this kind of stuff (https://github.com/pseudosavant/player.html, https://github.com/pseudosavant/folder.api)? So tempted to vibe-code an example...
pvtmert
This is exactly how my (personal) page(s) work! I wrote it pre-covid.
Initially I was using the hash as you suggested, but the redirect/404 was flaky when I use github-pages as the host, hence I reverted to the query-string (? or search) as it creates a complete refresh. Which allows me to set up "virtual" routes like `/blog`.
Topping with worker/service worker, it is quite robust!
Link: https://mert.akeng.in/
JohnKemeny
Agreed. Pandoc with some webpage template (bootstrap).
palmfacehn
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.
dtedesco1
I agree, but it's just too difficult to get away from the React ecosystem...
Do you have suggestions on a better alternative?
politelemon
It is not difficult to get away from that ecosystem, they simply need to not be included. It is in fact more work to include them and introduced unnecessary complexity.
Several markdown to html generators exist that are well established which simply use the base languages: node, python, go, etc. Instead of using a framework that isn't suited to the task, they focus on structure and features and work on that. By working on the features, structure, and grammar, the tooling will emerge.
lelanthran
> I agree, but it's just too difficult to get away from the React ecosystem...
Why? What specifically are you using for "website with markdown" that needs React?
> Do you have suggestions on a better alternative?
Yes.
1. For turning markdown into html on the server (i.e. render the HTML on the server and then deliver it) use pandoc. I use it like this for my blog: https://gist.github.com/lelanthran/2634fc2508c93a437ba5ca511...
2. For turning markdown into html on the client, write a custom component that parses the markdown into DOM nodes allowing the page author to simply do `<dynamic-markdown remote-src=some/path/to/page.md>`. You can even use one of the many existing Vanilla JS libraries to do this within the custom component.
In either of those two options above, what value does React add?
taude
https://htmx.org/. - for smaller sites. Likely the type of site you'd make content in markdown and have it transformed?
dleeftink
Not op, but check out unsuck[0] for some inspiration.
iammrpayments
Not difficult at all
lawn
You could make it simpler in Python, Go, PHP, Rust, Elixir, Haskell, Ruby, and even in JavaScript if you want to step outside the JS ecosystem.
Just try to make something without React and you light see the light. It's actually not difficult.
adamgordonbell
Looks cool.
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.
switz
I published a more batteries-included sample RSC+MDX blog extracted out of my own personal blog[0]
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
belmead
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.
m-hodges
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.
malkosta
I do almost the same, with a simple bash script, and no JS junk: https://github.com/alexandremcosta/alexandremcosta.github.io...
james_marks
There's a lot of ways to convert MD to HTML, but fewer tools to collaborate with non-devs to edit and maintain those markdown files.
I've been considering Spinal[0] (no association) to bridge that gap, any others I should be looking at?
jrm4
Or, just use https://zim-wiki.org like I have for well over a decade.
redog
I do a github pages workflow + vue + vite
Push updates to the md file and it rebuilds itself.
Saris
The example page has very light colored text on a light background, almost impossible to read!
sholladay
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.
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.