Next.js 15 Markdown Boilerplate

Posted4 months agoActive4 months ago

dtedesco1

45 points

68 comments

github.comProgrammingstory

informativeneutral

Debate

0/100

Next.jsMarkdownBoilerplateReact

Key topics

Next.js

Markdown

Boilerplate

React

The quest for simplicity in building modern websites has sparked a lively debate around a new Next.js 15 Markdown Boilerplate. While the creator, dtedesco1, aimed to simplify the process with a minimal, static-first approach, commenters questioned whether Next.js and React were the right tools for the job, citing added complexity. Alternatives like blot.im, unsuckjs.com, and htmx.org were suggested, with dtedesco1 probing their compatibility with existing React components. As the discussion unfolded, a consensus emerged that stripping away unnecessary complexity is key to simplicity, with some advocating for a more radical departure from the React ecosystem.

Snapshot generated from the HN discussion

Discussion Activity

Very active discussion

First comment

N/A

Peak period

Day 4

Avg / period

13.6

Comment distribution68 data points

Loading chart...

Based on 68 loaded comments

Key moments

01Story posted
Aug 29, 2025 at 11:08 PM EDT
4 months ago
Step 01
02First comment
Aug 29, 2025 at 11:08 PM EDT
0s after posting
Step 02
03Peak activity
42 comments in Day 4
Hottest window of the conversation
Step 03
04Latest activity
Sep 9, 2025 at 11:32 AM EDT
4 months ago
Step 04

Generating AI Summary...

Analyzing up to 500 comments to identify key contributors and discussion patterns

Discussion (68 comments)

Showing 68 comments

Fade_Dance

4 months ago

1 reply

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.

dtedesco1Author

4 months ago

Intriguing. Does it render React components when you want to add them?

palmfacehn

4 months ago

1 reply

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.

dtedesco1Author

4 months ago

7 replies

I agree, but it's just too difficult to get away from the React ecosystem...

Do you have suggestions on a better alternative?

dleeftink

4 months ago

1 reply

Not op, but check out unsuck[0] for some inspiration.

[0]: https://unsuckjs.com/

dtedesco1Author

4 months ago

These look really promising! Can I bring existing React components with me to any of them? That might be the biggest hold up. I’d also worry about maintainability as web standards evolve, since these (mostly) seem like pretty small projects.

taude

4 months ago

1 reply

https://htmx.org/. - for smaller sites. Likely the type of site you'd make content in markdown and have it transformed?

dtedesco1Author

4 months ago

Can I still bring my React components when I want them? Haven’t tried out HTMX yet.

politelemon

4 months ago

1 reply

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.

dtedesco1Author

4 months ago

This makes sense for one-way posting, but there are two issues for my main use case (personal and small company websites):

1. I want to edit the pages sometimes, and I want to do so using markdown without extra steps.

2. I still want to use React components *sometimes*.

3. I want it to be really easy to deploy and monitor. Nextjs is really easy for those things.

Solving the first issue and third issues don’t require React, but the second definitely does. So I’m still stuck.

lelanthran

4 months ago

1 reply

> 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?

dtedesco1Author

4 months ago

It’s the I-sometimes-want-to-use-React-components issue that is my holdup. They make it easy to do some visual/behavioral stuff and are often directly portable from other sites or oss projects.

lawn

4 months ago

1 reply

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.

dtedesco1Author

4 months ago

Yep, but I still want to use React components sometimes. That’s my biggest holdup.

pvtmert

4 months ago

1 reply

Why not using marked.js or equivalent, plugging it with a Fetch API instead?

example:

  <html>
  <head><title>hello</title></head>
  <body>
  <main id=root ></main>
  <script src=./marked.min.js async defer ></script>
  <script>
  async function load() {
    let element = document.querySelector("main#root");
    await fetch("./index.md") 
      .then(resp => resp.text())
      .then(text => marked(text, { ... }))
      .then(html => {
        element.innerHTML = html;
      });
  }
  window.onload = load;
  </script>
  </body>
  </html>

since it directly injects the resulting html, you may set "unsafe HTML" option in marked (or markdown.js) and include <title> tags within your markdown document. this will _also_ rewrite the browser title(s)

> edit: formatting

dtedesco1Author

4 months ago

That’s good if I’m really *only* ever using Markdown. But what about wanting to use React components sometimes? That’s my biggest problem.

iammrpayments

4 months ago

Not difficult at all

bananapub

4 months ago

1 reply

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.

pavel_lishin

4 months ago

1 reply

True, and I was going to comment the same thing, but I think this project is about explicitly allowing React components - which presumably means some level of interaction higher than eleventy can provide.

dtedesco1Author

4 months ago

Bingo!

nashashmi

4 months ago

3 replies

Markdown should be baked in to browsers as native now.

lelanthran

4 months ago

1 reply

> Markdown should be baked in to browsers as native now.

That is not hard to do, if you're okay with adding a script tag in your header.

nashashmi

4 months ago

1 reply

Yeah but then the script tag will show up in markdown viewers.

lelanthran

4 months ago

I meant add a `<script src=...>` to the `<head>` section of the page.

Not perfect, to be sure, but it lets you create a custom element `<mark-down src=...>` that lets the page author sprinkle markdown everywhere in their page.

prmoustache

4 months ago

Well since markdown has been designed to be relatively comfortable to read in its source form, I initially thought this link would be an opinion piece on serving raw markdown pages using the browser ability to show text files as is.

dtedesco1Author

4 months ago

Ha! I would love that.

xtracto

4 months ago

1 reply

I've been using this:

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.

dtedesco1Author

4 months ago

This is great! Thanks for sharing.

ZeroClickOk

4 months ago

1 reply

Or just use Obsidian + Obsidian Publish,

You are welcome.

dtedesco1Author

4 months ago

Does Obsidian support React components when you want to add them? That’s my biggest issue.

ramses0

4 months ago

1 reply

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!

dtedesco1Author

4 months ago

1 reply

> taking care of all the hairy details around `<CustomComponent>...</...>`

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.

ramses0

4 months ago

Sorry to have missed your comment.

Basically:

    ---
    import foo, bar, baz
    ---
    # Markdown
    
     * Goes
     * <https://here.com>

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:

    <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 ...]?

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":

    GET /foo.mdx

    Content-Type: application/mdx
    Date: 2020-10-10 01:02:34

    ---
    import SomeComponent
    ---
    <SomeComponent>My Header</SomeComponent>

     * Some
     * Content

oxalorg

4 months ago

1 reply

Sorry but this is anything but simple to me.

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

oneshtein

4 months ago

2 replies

I use one line static site generator:

  for I in *.md; do pandoc "$I" --template=template.html --metadata title="My Site" -o "${I%.md}.html"; done

masfuerte

4 months ago

pandoc is awesome. As well as standard markdown it can handle syntax highlighting, convert LaTeX equations to MathML and much else besides.

0xbadcafebee

4 months ago

Came here to post this too. Pandoc and a few lines of shell, all you need. Here is a super fancy Makefile:

  CONTENT_DIR  := content
  BUILD_DIR    := public
  MD_FILES := $(shell find $(CONTENT_DIR) -name '*.md')
  HTML_OUT := $(patsubst $(CONTENT_DIR)/%.md,$(BUILD_DIR)/%.html,$(MD_FILES))
  .PHONY: all clean assets serve
  
  all: $(HTML_OUT) assets
  assets:
   @mkdir -p $(BUILD_DIR) && cp -a static/style.css $(BUILD_DIR)/
  $(BUILD_DIR)/%.html: $(CONTENT_DIR)/%.md templates/default.html site.yaml
   @mkdir -p $(dir $@)
   pandoc --standalone --from gfm --to html5 \
     --template=templates/default.html \
     --metadata-file=site.yaml \
     --toc --toc-depth=3 \
     -o $@ $<

Ask ChatGPT, it'll spit out the rest (sample posts, template, CSS, YAML, Makefile, etc)

adamgordonbell

4 months ago

1 reply

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.

dtedesco1Author

4 months ago

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.

arandomhuman

4 months ago

3 replies

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.

pseudosavant

4 months ago

2 replies

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

4 months ago

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/

dtedesco1Author

4 months ago

These are great for adding more flavor to md -> html, but I want to be able to use React components sometimes, not just JS/CSS.

JohnKemeny

4 months ago

Agreed. Pandoc with some webpage template (bootstrap).

dtedesco1Author

4 months ago

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.

HuwFulcher

4 months ago

2 replies

> Next.js

Hmmmmmm no

dtedesco1Author

4 months ago

Agreed! Give me a better option that supports React components?

lawn

4 months ago

The timing is awesome: https://news.ycombinator.com/item?id=45099922

switz

4 months ago

1 reply

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

[0] https://saewitz.com

dtedesco1Author

4 months ago

Awesome work. Very snappy and crisp. For this project, I’m still stuck in React hell though because I want to use React components XD

belmead

4 months ago

1 reply

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.

dtedesco1Author

4 months ago

Thanks for calling out. I’ve opened [an issue to look into this](https://github.com/dtedesco1/nextjs-markdown-boilerplate/iss...).

pityJuke

4 months ago

1 reply

One of the first things I would do to evaluate a solution like this is to look at a demo. The demo looks... utterly broken to me? [0]

[0]: https://imgur.com/a/ysgJbCp

dtedesco1Author

4 months ago

Haven’t gotten this feedback from anyone else. Are you using a browser extension(s) that might be affecting how it renders?

handzhiev

4 months ago

1 reply

Hit the back button as soon as I saw nextjs

dtedesco1Author

4 months ago

but nextjs is in the title… :)

jrm4

4 months ago

Or, just use https://zim-wiki.org like I have for well over a decade.

sholladay

4 months ago

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.

https://starlight.astro.build/

redog

4 months ago

I do a github pages workflow + vue + vite

Push updates to the md file and it rebuilds itself.

https://github.com/automationwise/awise.github.io

firesteelrain

4 months ago

I have used MkDocs to do this in the past.

1. https://idratherbewriting.com/learnapidoc/pubapis_static_sit...

m-hodges

4 months ago

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.

¹ https://quarto.org/

² https://quarto.org/docs/websites/website-blog.html

4b11b4

4 months ago

lol

dtedesco1Author

4 months ago

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.

james_marks

4 months ago

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?

[0] https://spinalcms.com

Saris

4 months ago

The example page has very light colored text on a light background, almost impossible to read!

KronisLV

4 months ago

Nobody mentioned it yet, so I really liked mdbook: https://wofwca.github.io/mdBook/cli/init.html

The output is just a bundle of files for your web server of your choice, supports good navigation with the sidebar, custom theming if you need it (but otherwise gets out of your way), alongside being a single executable.

raphinou

4 months ago

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.

malkosta

4 months ago

I do almost the same, with a simple bash script, and no JS junk: https://github.com/alexandremcosta/alexandremcosta.github.io...

View full discussion on Hacker News

ID: 45071592Type: storyLast synced: 11/20/2025, 4:41:30 PM

Want the full context?

Jump to the original sources

Read the primary article or dive into the live Hacker News thread when you're ready.

Open link View on HN