Documentation as static site

[imevro]

I saw new docs and it looks fantastic clean.
But I think GitHub isn't good place for it, because doesn't have navigation between documents.

I propose static site at GitHub Pages, but I understand how hard is maintain 2 versions. We can use static site generator from markdown like metalsmith or jekyll.

[gaearon]

I don't mind as long as somebody else can take the task, and we agree on the appearance (I'll need to vet the look and feel). My only requirement is this has to be a JS site generator, no Ruby please. :-) We want npm install and npm run build-site to just work.

[imevro]

I agree, npm scripts is small solution. I'll try tomorrow basic setup. If anyone has ideas about generator, it'll be great.
Also, what you think about JSDoc? Will you generate API Reference from it?

[gaearon]

I'd like to try, although I'm not convinced it's going to be better than just doing it manually.

[imevro]

Hm, what you think about gulp for build by metalsmith and publish to GitHub pages? I know about webpack but I didn't found module for deploy to ghpages. I think npm docs-generate (which calls gulp docs:generate) and npm docs-publish (for gulp docs:publish) is good commands.

https://www.npmjs.com/package/gulp-gh-pages

[imevro]

Oh, I'm sorry, misclick.

[gaearon]

Webpack is just JS bundler, so it's not needed here.

I'd avoid Gulp to be honest. Can't we just write a JS script to push to gh-pages?
Does metalsmith require Gulp? It seems like it has a simple Node API, which is just what I wanted.

[imevro]

Metalsmith doesn't require gulp, right. But I don't found package for deploy to GitHub pages. I don't think you want go to dist folder everytime, then checkout to gh-pages, then push. Routine is boring.

But I'll try extract code from gulp-gh-pages and publish as node package. It will be better.

[acdlite]

For the Flummox site I hacked together a system where Markdown docs were converted to JSON files and hosted by GH pages, then loaded by an isomorphic Flummox/React app. Then we used wget to pre-render all the pages, so it created the illusion of a fully-isomorphic site with pushHistory() support (no hash urls). The implementation is a bit rough— I threw it together one night with the intention of eventually improving it / turning into a module, but never got around to it. But conceptually it's pretty simple.

Perhaps we could do something similar for Redux?

https://github.com/acdlite/flummox/tree/master/docs

On Thu, Jul 23, 2015 at 2:50 PM, Dan Abramov [email protected]
wrote:

Webpack is just JS bundler, so it's not needed here.
I'd avoid Gulp to be honest. Can't we just write a JS script to push to gh-pages?

Does metalsmith require Gulp? It seems like it has a simple Node API, which is just what I wanted.

Reply to this email directly or view it on GitHub:
#311 (comment)

[gaearon]

@acdlite

I like this approach but I want to avoid messing with styles. I also want to do that after we have some official React Router integration.

That said maybe it's time to start hacking on that :-P

[KyleAMathews]

Happy to help you all set up a site with Gatsby :)

I created a dummy docs site as a demo—http://gatsbyjs.github.io/gatsby-starter-documentation/

[gaearon]

Gatsby looks pretty much what I wanted.
Can we have code highlighting there without much effort?

[KyleAMathews]

All Markdown is run through highlight.js by default (though that's very easy to swap out with another syntax highlighter.

[gaearon]

Can you try generating something from rewrite-docs branch? I have some stubs in docs folder there, as well as the new README.

[KyleAMathews]

Be happy too. Probably will have time this weekend.

[gaearon]

Excited to have you onboard!

cc @faassen who was frustrated that we don't have one documentation tool to rule them all. Maybe finally we can converge on something.

[emmenko]

...and we need a logo of course! ;)

[KyleAMathews]

Woah. Just had an idea. What do you think about the idea of "composable" websites? Gatsby is already doing this to some extent as it has fallbacks for most critical files you need but you can override them easily but we could extend that concept further to something like Object.assign(Gatsby, website_base, actual_website).

So in practice how this would work is there'd be a base documentation site hosted on github. When you want a new docs site you'd just set the github url for the base site and then start adding markdown files. Anything else you'd want to modify could be set in the site config file.

[gaearon]

That would be rad. :-)

[knowbody]

@KyleAMathews great idea!

[xgrommx]

https://github.com/GitbookIO/gitbook? As example my book about RxJS

[gaearon]

I'd say Gitbook looks very similar to what I want.

[xgrommx]

@gaearon Additionally you can use some custom theme.

[damassi]

I would avoid Metalsmith because it can get pretty buggy and slow, particularly when compared to the React.js flow we're all now familiar with. And @KyleAMathews - Damn! We're almost done rebuilding our Marketing site and I just saw your work on this. Looks awesome.

[gaearon]

We'll use Gitbook as implemented in #331. It answers all my needs.

[KyleAMathews]

@damassi Thanks! Cut my teeth as a programmer on CMS stuff so fun to integrate those + react.js + ssg ideas together.

@gaearon +1 to Gitbook. My open source time is very limited right now and Gitbook looks great.