[website] consider gatsby instead of hugo

[zebapy]

Change netlifycms.org website (website folder in this repo) to use Gatsby instead of Hugo

Seems like there could be benefits to using Gatsby instead of Hugo since netlify cms is React based and gatsby has a growing presence in the react static site realm.

Reasons to move

• No need for all the gulp set up (remove a lot of deps)
• Would remove jquery plugins in favor of react components
• React templating benefits should be obvious here

I'd love to take a crack at this if there's buy-in. I'd just try to recreate the existing site 1:1

Edit

I've got most of this done here https://github.com/zebapy/netlify-cms/tree/gatsby-site/website

[flexchar]

I think it should be static-site-generator agnostic, and thus, based on API rather than tailored to a specific structure. As such, end users could simply define configuration to work with whichever SSG they wish, just as it does now with collections.

[zebapy]

@flexchar I'm talking about the netlifycms.org website in this repo. Not sure I follow how you're talking about the same thing? I could be wrong

[flexchar]

@zebapy You are absolutely right, my apologies. I have no idea how I managed to miss such thing. Consider my comment as completely irrelevant.

[erquhart]

Especially considering our interactive documentation ambitions, and the docs therefore potentially becoming more app-like, I'm in agreement with this.

And we don't even have to ask @talves I know he'll be in complete agreement. :trollface:

Seriously though, thoughts anyone? I'm inclined to say go for it.

[talves]

Seriously though. Converting the site to Gatsby or React-Static is more of a preference and a testament to how awesome the JAMStack is today. My vote is React-Static but, if someone is willing to take on Gatsby, I would not be apposed to it. 😋

Admission: Gatsby is a very well supported and maintained project. It is well done. Just not my preferred SSG at the moment.

[zebapy]

Out of desire to practice Gatsby, I have a Gatsby version about 80% done. I'll post it shortly!

On Sat, May 12, 2018, 12:39 PM Tony Alves notifications@github.com wrote:

Seriously though. Converting the site to Gatsby or React-Static is more of a preference and a testament to how awesome the JAMStack is today. My vote is React-Static but, if someone is willing to take on Gatsby, I would not be apposed to it. 😋

Admission: Gatsby is a very well supported and maintained project. It is well done. Just not my preferred SSG at the moment.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/netlify/netlify-cms/issues/1351#issuecomment-388567301, or mute the thread https://github.com/notifications/unsubscribe-auth/ACGRJY5OJIJe3WS7wP6fp8S2KRrkUhc8ks5txxBIgaJpZM4T6F_W .

[knpwrs]

My vote is React-Static but, if someone is willing to take on Gatsby, I would not be apposed to it. 😋

Casting my vote for react-static as well. I've found it to be a lot simpler than Gatsby. It's also ultimately better at splitting out routes if you want some reasoning that's more objective (for instance, on my site, currently powered by Gatsby, all of the blog posts are in one bundle with other pages in their own bundles, I would prefer for each blog post to be in its own bundle).

[zebapy]

@knpwrs For the gatsby version of the site I'm almost done with, I see each doc page as their own bundle/js file. So it sounds like gatsby has what you're saying you desire?

I still advocate for gatsby since seems to have a larger presence, its plugin system works rather well instead of manually setting everything up for prism, manifest, yaml, markdown, postcss, autolink headers, table of contents... React static looks like you have to do some extra work to get these.

I get that the learning curve looks lower for react static, and routing is vastly simpler, but this site doesn't require much beyond the basic gatsby blog examples and what the docs thoroughly cover.

[zebapy]

@erquhart I have a lot of this done here if you want to check it out https://github.com/zebapy/netlify-cms/tree/gatsby-site/website

I still need to fix a couple things but wanted to share it earlier.

[knpwrs]

@zebapy Gatsby only splits on routes or individual items rather than collections of items. I'll quote Kyle Matthews from an email correspondence:

A few things that might be confusing about code splitting. We only code split in production not development. It simplifies things a lot in development if we just have a single bundle.js. Also we only create code splits on "routes". Meaning if multiple pages share the same React component e.g. blog posts then there'll only be one bundle created for all the blog posts.

[knpwrs]

Another good candidate could be VuePress. I haven't used it myself but I like that they let you use Vue components inside Markdown. It reminds me of mdx.

[erquhart]

Apparently VuePress is tailored to technical documentation, very interesting. The default theme includes:

Responsive layout Optional Homepage Simple out-of-the-box header-based search Algolia Search Customizable navbar and sidebar Auto-generated GitHub link and page edit links

Very interesting.

_{Sent with GitHawk}

[zebapy]

There's also https://docusaurus.io/

I think part of the reason I opened this was so docs site was in React since the cms is.

On Sat, May 12, 2018, 6:51 PM Shawn Erquhart notifications@github.com wrote:

Apparently VuePress is tailored to technical documentation, very interesting. The default theme includes:

Responsive layout Optional Homepage Simple out-of-the-box header-based search Algolia Search Customizable navbar and sidebar Auto-generated GitHub link and page edit links

Very interesting.

Sent with GitHawk http://githawk.com

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/netlify/netlify-cms/issues/1351#issuecomment-388588749, or mute the thread https://github.com/notifications/unsubscribe-auth/ACGRJQEL1IkR7Vn2nqT7tu-SfG7zAgXuks5tx2d7gaJpZM4T6F_W .

[erquhart]

@zebapy I just got to check out your fork, it really is 80% to a production ready Gatsby migration. You have my vote, killer work my friend. Thanks so much for jumping in like this!

[zebapy]

@erquhart Thanks! I'll try to wrap this up soon

[DirtyF]

For the record, here's a webpagetest on the actual website. It would be interesting to compare results between both SSG. Gatsby should score better at LightHouse by default.

[bep]

React templating benefits should be obvious here

How is this obvious in a documentation site? Can you elaborate? Are there downsides to picking a React static generator? Does it make it easier or harder for people to contribute content?

[erquhart]

@bep here are a few reasons why a React based SSG feels right for this project:

• I expect these docs to become highly interactive and app-like moving forward - little pieces of CMS in various places, potentially including static pages like the home page. With React as our templating language, that will be a more natural progression than when interweaving that interactivity layer between React and Hugo.
• Netlify CMS is written in React, and that goes beyond the source - most customization and extension API's only accept React components. Templating the site with React means anyone that contributes to Netlify CMS already knows how to work with the docs templates.
• Golang templating has a tougher learning curve than other templating languages.
• Gatsby has it's own front end build pipeline, so we don't need to maintain our own.

Since the vast majority of content contributions happen in Markdown files, I expect docs contributions to be largely unaffected.

I know very well how world class Hugo is! This project is just so JS/React centric that it makes a JS/React SSG for interactive docs a super close fit.

[erquhart]

@DirtyF webpagetest of the in-progress deploy preview: https://www.webpagetest.org/result/180525_GC_a9486c40a857bef10a68b25d6791a59e/

[bep]

Since the vast majority of content contributions happen in Markdown files, I expect docs contributions to be largely unaffected.

Sure, I just wanted you to think about it and not just dive into some "would it not be cool to do the docs in react" simple arguments.

From a documentation contributor perspective (i.e. as someone who wants to write documentation), I would, of course (I'm biased), prefer something static that I could just git clone; somebinary run; edit and commit. I have not looked at your current distribution, but that should be possible with Hugo and compiled JS/CSS. That is not the case with a JS static generator where you would need to do the whole NPM dance to get it up and running.

So, there are trade-offs to consider. Your docs may get "richer" in its UI, but it may also be harder to reason about for editors. Trade-offs.

[erquhart]

Agreed, the risk of fad following is real. We have a front end build pipeline already, we just maintain it ourselves. Running the project locally from scratch is currently npm install && npm start, and still will be after the switch. (Yes I realize every time someone runs Hugo via npm scripts a puppy dies, it is very sad.)