Gatsby: Create marketing/docs site

[KyleAMathews]

If anyone is interested in a doc writing party in SF/online let me know :)

Stuff (beyond the normal) to document

• Default webpack config (which loaders/plugins are added + why) + how to modify it + common modifications
• Deployment
• Project philosophy. What it isn't and isn't. Constraints you should be aware + their advantages/disadvantages.
• List starters #56
• document how to accomplish common patterns in Gatsby/React.js e.g. Disqus, generating Atom/RSS feeds & site maps, etc.
• Pointers to learning React to React newbies.

Other things that should be there? E.g. what did you find confusing when playing with Gatsby?

Let's continue to flesh out the list of topics to cover and then start writing docs (in markdown) and land them as PRs against the 1.0 branch in a /docs directory.

[tychota]

in common pattern , generating an atom/rss feed could be added ! I manage to do it, using the post-build from your blog but I wasn't an easy road.

[KyleAMathews]

@tychota absolutely, I'll add that to the list.

[kaihendry]

Keen for some pointers how to generate an RSS feed from the starter blog template. Cheers!

[KyleAMathews]

@kaihendry check out what I did for my personal blog (need to convert this to JS) https://github.com/KyleAMathews/blog/blob/master/post-build.coffee

[KyleAMathews]

Hey folks — been working on design + components for Gatsby powered documentation sites. As a test case I've been working on a PR to convert the new Webpack website to use Gatsby. Would love feedback on the design, etc. as whatever that ends up being will be what we will use here (or very similar).

https://github.com/webpack/webpack.js.org/pull/202

[kaihendry]

Looks good @KyleAMathews. My only niggle is that View Source is FUGLY.
view-source:https://webpack-gatsby.netlify.com/concepts/targets/

I know one is supposed to use Chrome Dev tools to explore the markup in 2016, but I prefer to have readable markup. It's the way I learnt the Web and as a result, any site that has fugly markup gets minus points from me.

Oh btw CONFIGURATION is line breaked? http://s.natalian.org/2016-10-05/1475643336_2558x1404.png

[KyleAMathews]

@kaihendry ahhh I see you're an old-timey web developer who likes the fine patina developed on hand-crafted, hand-polished HTML ;-)

You'll love the new plugin system with Gatsby 1.0 as you could create a plugin to pretty-print Gatsby's output :-)

Hmmm... yeah, it looks like that line breaks at 872 pixels wide on my mac chrome. I'll shrink it down or set a min-width on that column in the morning.

[MoOx]

@KyleAMathews I think the current visible css is very redundant. Is this something that can be improved?

[KyleAMathews]

@MoOx not sure I understand what you mean? Which css? Redundant to what?

[MoOx]

view-source:https://webpack-gatsby.netlify.com/concepts/targets/

[KyleAMathews]

@MoOx oh gotcha... hmmm you're right, there is a lot of duplicates there. That's the output from extracting styles from Glamor — I'll file an issue there about deduping rules when server rendering. In the meantime though, all hail the magic of gzip :-)

[threepointone]

my bad, spotted this earlier today, will get a fix in soon.

[kaihendry]

Btw the hero graphic doesn't look good http://s.natalian.org/2016-10-06/iphone7+.PNG

Actually I'm pretty confused by https://webpack-gatsby.netlify.com/93881a5096732dfdf25532ff4596690a.png

I thought the "idea" with Webpack is that you can put js,css,png,jpg(as data uris) etc etc all in one payload, the bundle.js! https://www.youtube.com/watch?v=WQue1AN93YU

[KyleAMathews]

Interesting write-up on doc sites' sidebar navigation http://idratherbewriting.com/2016/10/23/coding-sidebar-navigation-for-documentation-websites/

[KyleAMathews]

Very early preview of new site is up — https://gatsbyjs.netlify.com/

Going to be working on a sketch soon for a proposal for the information architecture.

[KyleAMathews]

Something that'd be fun/useful to explore for mobile is a bottom navigation bar. Perhaps with links to home, docs, news, and a hamburger menu with an extended navigation menu.

Links:

• https://material.google.com/components/bottom-navigation.html
• https://www.smashingmagazine.com/2016/11/the-golden-rules-of-mobile-navigation-design/

Quartz is a web site that showcases this nicely http://qz.com/

[KyleAMathews]

StackOverflow's documentation project is really interesting — http://meta.stackoverflow.com/questions/339974/the-dawn-of-documentation-a-solstice-update?cb=1

This bit is suggestive of some things we could add to Gatsby's docs:

Wikipedia offered low transaction costs to participation, and it de-emphasized the social ownership of content. Editing Wikipedia is easy, and instant, and virtually commitment-free. “You can come along and do a drive-by edit and never make a contribution again,” Hill pointed out. And the fact that it’s difficult to tell who wrote an article, or who edited it — rather than discouraging contribution, as you might assume — actually encouraged contributions, Hill found. “Low textual ownership resulted in more collaboration,” he put it.

It might be helpful to let people edit the Gatsby docs site directly on the site so you click a button on a page and up pops a model.

[erlend-sh]

It might be helpful to let people edit the Gatsby docs site directly on the site so you click a button on a page and up pops a model.

I pitched such a thing for Jekyll, and @mushishi78 actually rolled with it and developed a working prototype:

https://github.com/wiki-hub
https://jekyll-anon.surge.sh/gods/2015/02/18/vesta.html (live demo)

It needs to be running persistently on a service like Heroku though. As far as I know there's no way around that.

[KyleAMathews]

@erlend-sh nifty! Yeah, that's exactly what I was thinking of. User clicks edit, auths against github, makes change w/ commit message, and a PR is created.

[m4rrc0]

Maybe using Netlify CMS. Though I don't know if you can even access the Editing UI if you are not a collaborator on the repo...

[mchandleraz]

I'm trying to get Disqus integrated to a new Gatsby project and I'm not having much success so far. I saw #133, but the link from @KyleAMathews 404s now and I wasn't able to find anything disqus related in that repo.

I'd be happy to write the docs, if someone can point me in the direction of some more info or a reference implementation.

Thanks!

[KyleAMathews]

@mchandleraz this is the react component that I was using https://github.com/mzabriskie/react-disqus-thread

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale[bot]]

This issue has been automatically closed due to inactivity.