Convert website to Gatsby

[KyleAMathews]

As of the initial commit, you can't run this locally as it's relying on not-yet released changes to Gatsby. I've published the site however to https://webpack-gatsby.netlify.com/

The conversion isn't quite yet feature complete. I'll be working on converting the remaining styling options, etc. the first few days of next week. I took some liberties and made some design changes. I like my changes but they're more experimental/playful than anything else. I don't want to denigrate any of the great work y'all have been doing already.

I added the Geomanist font we're using for the new logo (but didn't check it in). I also switched to use the open source Cabin font for body text. I also integrated my Typography.js library and used it for setting various spacings.

Curious what people feel about javascript styles. I've been using them exclusively the past few years. Planning on adding Glamor for styles to this site Monday.

Incomplete todo list:

• Finish porting/restoring design
• add responsive design
• make sidebar sticky so remains in viewport as you scroll.

I haven't finished looking through all the issues so let me know what are the other big ticket items to work through!

As I mentioned in our original discussion I'm building several documentation sites in parallal right now and will be converting all this work into reusable React components and (once I add support for this in Gatsby), a Gatsby documentation theme. So I'd really love ideas & feedback about how to make this design amazing. I see documentation sites as a natural strength for Gatsby so will be investing a lot of time over the next weeks and months in this area.

If you're not familiar with Gatsby, its project page provides a good intro — https://github.com/gatsbyjs/gatsby

I'm building the site on the 1.0 branch — you can see its roadmap here: gatsbyjs/gatsby#419

I've been working on Gatsby full-time the past few months and have been diving deep into Webpack and really appreciate this opportunity to contribute back.

[oliverturner]

@KyleAMathews let me know what your plans for implementing responsiveness are: it would be a shame (from my perspective) to have the work I did on #203 to have been a waste of time.

That said, liking what you've done so far!

[skipjack]

@KyleAMathews I like what you did with the typography and background. After the original backgrounds in the design I've been feeling like the Sidebar's background was creating more noise than separation.

Curious what people feel about javascript styles. I've been using them exclusively the past few years.

Personally I'm not a huge fan of pure JS styling. @oliverturner and I have been discussing relocating the component stylesheets back with the actual component files. It would also be nice to move the images into the component-specific directories as well.

I took some liberties and made some design changes. I like my changes but they're more experimental/playful than anything else. I don't want to denigrate any of the great work y'all have been doing already.

The only thing I've noticed so far that I'm not a huge fan of is going back to light theme for the code blocks. And, as @oliverturner mentioned, I think we should use his work on the breakpoints in #203 and keep adding to that.

If we are going with this port I think we should get it merged and then finish the other things you've mentioned like the Sidebar and breakpoint work. I don't think everything needs to be done in one PR. Interested in @bebraw's thoughts as well.

[bebraw]

@gregvenech I know the authors of Phenomic and spike had interest in maintaining the site too so we probably should wait before merging anything.

[skipjack]

@bebraw yea I figured I'd leave this to you.

[KyleAMathews]

Built a take on a responsive design + sidebar. I'm not entirely happy with it yet but I wanted to push it out for feedback for quitting for the day.

Try it out on your phone — https://webpack-gatsby.netlify.com/concepts/

I looked at some docs sites that put links to sub-sections in a select so I thought I'd try that. After building it I think just leaving all navigation in the sidebar works better. It's a bit confusing the relationship between the sidebar links and the select links and the sidebar is just faster to use as well.

Since we're using the header for navigation now, I think it'd make sense to add React Headroom so the sidebar is always easily accessible regardless of where you're on the page.

I'll try both of those changes tomorrow plus make the sidebar sticky on desktop.

@gregvenech I restored the original dark code theme.

@oliverturner I hear ya — it sucks to spend a lot of time on something if it ends up not being used. I wasn't able to completely copy your styles over to my take as Gatsby differs significantly in some ways from Antwar (though a lot is the same as both use React) plus I did some refactoring of the component hierarchy to make the mobile sidebar possible but I copied over as much of styles as possible.

[KyleAMathews]

Some more updates.

• Added react-headroom
• Restored Ubuntu Mono as code font (code looks odd on Android without it)
• Made sidebar sticky on desktop
• Moved page links to sidebar on mobile.
• Made contributor images retina

GIF of navigation on mobile.

Pretty happy with how things are coming together!

Latest stuff is at https://webpack-gatsby.netlify.com/concepts/

[mxstbr]

I like it!

Getting some visual artifacts in the link icon on my Android in Chrome, see the Screenshots.

[KyleAMathews]

Oh thanks @mxstbr — needed to remove the (rotated) text-decoration there.

[KyleAMathews]

Next steps for me:

• Will be building several other docs sites with same components starting tomorrow. I'll extract the various components here and generalize them + work at making them increasingly bulletproof. I'll be contributing fixes back here as I make changes.
• I identified several improvements to Gatsby that'll help here. Primarily around making data queries more powerful. Gatsby 1.0 is using GraphQL to power its data layer so you can write queries against Markdown (or any other backend source). Making data queries more powerful will mean we have to do less data manipulation client-side. E.g. I want to be able to write a query which pulls out the menu structure for the sidebar directly from which folder the markdown files are in.

[MoOx]

That's some great work done here. I like the navigation.

That said, not sure if it make sense to make those changes in this PR since this will make things hard for maintainers to decide what solution to use if more people make PR to replace antwar by another react (or not) static site generator.

@KyleAMathews my 2 cents: maybe make 2 PRs: one to show the minimal changes to switch the engine, and one other (on your first PR) that brings the enhancement. I think this will facilitate the review.

Maintainers: not sure how to handle a similar PR: should I integrate similar changes? Should I just provide a minimal PR?

[KyleAMathews]

If a more minimal PR is helpful, that was effectively my first commit e8ff05c

[SpaceK33z]

I really like the new styles, it looks a lot cleaner now (and the hover on the logo is awesome).

One small bug I noticed with the "sticky" navigation menu on the left: when I click on the anchor icon next to a heading, the navigation menu on the left suddenly disappears.

[SpaceK33z]

@KyleAMathews, could you split this up in two parts (design-related change and Gatsby conversion)? For now, we really want to focus on getting the content ready and making quick fixes to the existing engine. We feel that converting to Gatsby now could potentially result in problems we can't quickly fix, which in turn can have an impact on the amount of content or delay the webpack launch.

We will look at the Gatsby PR somewhat later, when webpack is stable and the @MoOx has his PR ready.

We really appreciate the effort you've put into this!

[KyleAMathews]

We feel that converting to Gatsby now could potentially result in problems we can't quickly fix

Not sure what you mean by this? Both Gatsby & Phenomic are built the same as Antwar — they're just React and Webpack under the hood. You won't have unusual problems doing normal react/webpack stuff. And if there are any Gatsby-related problems, I'm working on Gatsby full-time so any problems would be fixed ASAP.

But I get wanting to go with someone the core team already has experience with.

On a design PR — most of the design changes I made rely on having React loaded into the client which wouldn't be possible (or easy?) to replicate with Antwar e.g. the React Headroom change, the sticky sidebar, the mobile sidebar experience, etc. I could make just the Typography.js related changes. Typography.js renders its styles to <head> during server rendering — it looks like I can pass custom vars into the html template right @bebraw? Let me know if a conversion to using Typography.js is acceptable.

In the meantime, I'll go out and keep working on my Gatsby documentation theme :-). Let me know when you'd like a PR to convert things over.

[bebraw]

Typography.js renders its styles to during server rendering — it looks like I can pass custom vars into the html template right @bebraw? Let me know if a conversion to using Typography.js is acceptable.

Yeah, we have good access to <head>. We can inject per page and so on and I can push the mechanism to whatever direction we want. The basic flow goes like this:

1. Generate routing bundle (contains literally all pages of the site) through webpack.
2. Render each page against that and apply them through EJS (gets head/body/etc.). In this step the system picks up Interactive bits and writes bundles for those (webpack again) if they exist. It does some level of checking to share bundles and avoid work. This process has also been parallelized.

It's not isomorphic, but something in between. The payloads we get out of the system seem somewhat small. You'll lose out when it comes to routing (no fancy transitions etc.) and async loading (hard problem regardless). But for a light doc site it seems passable.

I expect we'll see plenty of overlap (same stack after all) so it would be cool to find overlap wherever possible and avoid some work that way.

[KyleAMathews]

Cool sounds great. I'll be busy on paid work the rest of the week but could do a design pass sometime next week with Typography.js.

And yeah — definitely lots of overlap. Hopefully there's more ways we can collaborate in the future!

[bebraw]

Cool sounds great. I'll be busy on paid work the rest of the week but could do a design pass sometime next week with Typography.js.

Ok, cool.

I think the situation will get a little easier once we complete the MVP. Good luck with the work. 👍

[skipjack]

I'm going to close this for now as it seems like it will be a longer conversation and might not be implemented for a while. Feel free to re-open down the road.

See #225 for similar design updates.