4 ms·

I'm in the market for an SSG for documentation of a larger project (and therefore I'm looking for something quick and easy to maintain). Hoping to keep it withi

I'm in the market for an SSG for documentation of a larger project (and therefore I'm looking for something quick and easy to maintain). Hoping to keep it within the JS ecosystem so that would rule out Hugo and Jeckyll. Is Next.js easier to use than Gatsby, or is there an even simpler alternative I haven't come across yet? Ideally I'd be able to point this library to a glob of .md files and generate HTML + RSS.

pspeter3 7y ago
I've used Eleventy which was pretty solid. I'm curious about Next.js though since it seems like it does almost everything out of the box that I want. I'm unsure if can prerender non HTML content though which is interesting.
leerob 7y ago
Both Next.js and Gatsby are great to work with. If you're looking to stay in the JS ecosystem, you'll be happy with either choice. As for which is "easier", it comes down to your skill set and preference. If you're familiar with GraphQL and enjoy it, you might prefer to use Gatsby. You can use GQL to fetch your Markdown files. If you're not as familiar with GQL, then it could be seen as a barrier to entry. The biggest advantage Gatsby has over Next.js is its plugin system. For example, you're a simple config change away from an RSS feed -> https://www.gatsbyjs.org/packages/gatsby-plugin-feed/ https://www.gatsbyjs.org/packages/gatsby-plugin-feed/ The biggest advantage Next.js has over Gatsby is that it's a hybrid React framework. You can mix SSG and SSR together in the same application. This could be very beneficial if you want your main marketing site, SaaS app, and documentation to all live in the same project. A great example of MDX (Markdown) + Next.js for production docs would be the StaticKit site -> https://github.com/unstacked/statickit-site https://github.com/unstacked/statickit-site
kylemathews 7y ago
Gatsby is widely used for documentation sites (check out sites on the showcase https://www.gatsbyjs.org/showcase/?filters%5B0%5D=Documentation https://www.gatsbyjs.org/showcase/?filters%5B0%5D=Documentat...). Typescript is rebuilding their docs on Gatsby right now and wrote up their reasoning behind the choice here: https://www.gatsbyjs.org/blog/2020-01-23-why-typescript-chose-gatsby/ https://www.gatsbyjs.org/blog/2020-01-23-why-typescript-chos...
_bxg1 7y ago
I built my personal website with nothing but Express and JS template strings: https://github.com/brundonsmith/website https://github.com/brundonsmith/website. It's so simple to do that I almost question the necessity of "static site generators" in general (Next.js of course does much more than static site generation).
- lioeters 7y ago
  Interesting approach, how every page is a JS file that builds the HTML page as a string; structurally it looks almost the same as how React/Next.js do it. With that setup, I imagine it's fairly trivial to add a "static site generator": - Run the local server that serves the rendered pages. - Run a Node.js process that will take a given array of all page routes; make HTTP requests to those local URLs; and save the rendered HTML into folders, for a complete static site.
  - _bxg1 7y ago
    Yep, that's what it already does :) And a neat property is that I could freely move different render functions between static, request-time, and client-side if I wanted to. People tend to think of React rendering and the like as this special, mysterious process. But the only special thing about it is the way it efficiently reconciles and updates an existing DOM to match a new DOM. That initial render is really no different from PHP. Static site generators are just PHP with a prewarmed cache.
    - genuine_smiles 7y ago
      > I could freely move different render functions between static, request-time, and client-side if I wanted to You can do the same thing with Next.js, and you can move between client-side and static with Gatsby > But the only special thing I think there might be more to unpack here, but when using react being able to typecheck and lint my jsx is pretty sweet. React also makes it much harder to create cross site scripting vulnerabilities.
    - lioeters 7y ago
kiwicopple 7y ago
I’m using Docusaurus V2 on https://supabase.io https://supabase.io and couldn’t be happier. It’s still early in its development but has everything that you need from a React SSG
vosper 7y ago
I personally find Next easier to use than Gatsby, but I don't think I could really make a strong technical argument for choosing Next. It might just be familiarity and personal preference at this point. I think it might be easier to use Next for mixed static and SSR sites than it is with Gatsby? And I think at the time I tried Gatsby I wasn't as familiar with GraphQL as I am now.
k__ 7y ago
I once read that Next is much closer to regular React than Gatsby, which brings in many concepts of its own.
deleted 7y ago
[deleted]

pspeter3 7y ago

I've used Eleventy which was pretty solid. I'm curious about Next.js though since it seems like it does almost everything out of the box that I want. I'm unsure if can prerender non HTML content though which is interesting.

leerob 7y ago

Both Next.js and Gatsby are great to work with. If you're looking to stay in the JS ecosystem, you'll be happy with either choice. As for which is "easier", it comes down to your skill set and preference. If you're familiar with GraphQL and enjoy it, you might prefer to use Gatsby. You can use GQL to fetch your Markdown files. If you're not as familiar with GQL, then it could be seen as a barrier to entry. The biggest advantage Gatsby has over Next.js is its plugin system. For example, you're a simple config change away from an RSS feed -> https://www.gatsbyjs.org/packages/gatsby-plugin-feed/ https://www.gatsbyjs.org/packages/gatsby-plugin-feed/ The biggest advantage Next.js has over Gatsby is that it's a hybrid React framework. You can mix SSG and SSR together in the same application. This could be very beneficial if you want your main marketing site, SaaS app, and documentation to all live in the same project. A great example of MDX (Markdown) + Next.js for production docs would be the StaticKit site -> https://github.com/unstacked/statickit-site https://github.com/unstacked/statickit-site

kylemathews 7y ago

Gatsby is widely used for documentation sites (check out sites on the showcase https://www.gatsbyjs.org/showcase/?filters%5B0%5D=Documentation https://www.gatsbyjs.org/showcase/?filters%5B0%5D=Documentat...). Typescript is rebuilding their docs on Gatsby right now and wrote up their reasoning behind the choice here: https://www.gatsbyjs.org/blog/2020-01-23-why-typescript-chose-gatsby/ https://www.gatsbyjs.org/blog/2020-01-23-why-typescript-chos...

_bxg1 7y ago

I built my personal website with nothing but Express and JS template strings: https://github.com/brundonsmith/website https://github.com/brundonsmith/website. It's so simple to do that I almost question the necessity of "static site generators" in general (Next.js of course does much more than static site generation).

lioeters 7y ago
Interesting approach, how every page is a JS file that builds the HTML page as a string; structurally it looks almost the same as how React/Next.js do it. With that setup, I imagine it's fairly trivial to add a "static site generator": - Run the local server that serves the rendered pages. - Run a Node.js process that will take a given array of all page routes; make HTTP requests to those local URLs; and save the rendered HTML into folders, for a complete static site.
- _bxg1 7y ago
  Yep, that's what it already does :) And a neat property is that I could freely move different render functions between static, request-time, and client-side if I wanted to. People tend to think of React rendering and the like as this special, mysterious process. But the only special thing about it is the way it efficiently reconciles and updates an existing DOM to match a new DOM. That initial render is really no different from PHP. Static site generators are just PHP with a prewarmed cache.
  - genuine_smiles 7y ago
    > I could freely move different render functions between static, request-time, and client-side if I wanted to You can do the same thing with Next.js, and you can move between client-side and static with Gatsby > But the only special thing I think there might be more to unpack here, but when using react being able to typecheck and lint my jsx is pretty sweet. React also makes it much harder to create cross site scripting vulnerabilities.
  - lioeters 7y ago

kiwicopple 7y ago

I’m using Docusaurus V2 on https://supabase.io https://supabase.io and couldn’t be happier. It’s still early in its development but has everything that you need from a React SSG

vosper 7y ago

I personally find Next easier to use than Gatsby, but I don't think I could really make a strong technical argument for choosing Next. It might just be familiarity and personal preference at this point. I think it might be easier to use Next for mixed static and SSR sites than it is with Gatsby? And I think at the time I tried Gatsby I wasn't as familiar with GraphQL as I am now.

k__ 7y ago

I once read that Next is much closer to regular React than Gatsby, which brings in many concepts of its own.

deleted 7y ago

[deleted]