More accessible docs, hosted on GH pages

[mjackson]

Instead of building to a single-page app on the v4 branch and deploying to now, we should build the website to a bunch of static HTML files in the docs dir so we can serve it with GitHub pages. Then the router docs will live at https://reacttraining.github.io/react-router.

[ryanflorence]

agreed. can we point it at the v4 branch or do we need to merge this code t
master?
On Sat, Sep 17, 2016 at 9:15 AM Michael Jackson [email protected]
wrote:

Instead of building to a single-page app on the v4 branch and deploying to
now, we should build the website to a bunch of static HTML files in the
docs dir so we can serve it with GitHub pages. Then the router docs will
live at https://reacttraining.github.io/react-router.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
#3893, or mute the
thread
https://github.com/notifications/unsubscribe-auth/AAGHaCJ8tbTTLOBLwg8DoG_FALErR0Bsks5qrBI9gaJpZM4J_o0M
.

[timdorr]

It would live on the gh-pages branch. Redux has a one-liner to publish to that branch via gitbook. Feel free to copy that structure here.

[kitze]

@timdorr it doesn't have to be specifically on the gh-pages branch anymore. You can point GitHub pages to any branch :)

[mjackson]

Yep, @kitze has the right idea. I'd like to be able to just build to our docs dir and then point GH pages there.

[timdorr]

No, that doesn't work. They would be in HTML format, so they wouldn't be rendered nicely when viewing on GitHub. And you would need to clutter up the master branch with built assets and build commits.

We blow away the git history on every build of the gh-pages branch on Redux for this exact reason. Keeping the docs in plain markdown under /docs has lowered the barrier to entry significantly and allowed just about anyone to participate in their development. Now, the 4.0 docs are obviously more complex than Redux's, but they should be accessible to as many people as possible, not only to read but to contribute changes back. The current structure impedes that IMHO.

I'm willing to do the heavy lifting, but there really should be a /docs with plain markdown, a /examples with example code, and a /website to build it all.

Btw, I hope this doesn't come off as harsh. Ryan worked really hard on the docs site and it's great as a result. I think most of my suggestions boil down to just moving some stuff around. But I do think it's important to allow anyone to peek under the hood without much trouble and be able to simply contribute back.

[markdalgleish]

If you're interested, I actually built a webpack plugin for this exact purpose, which I personally use to render universal React Router sites to static HTML: https://github.com/markdalgleish/static-site-generator-webpack-plugin

[mjackson]

@timdorr If you've got a strong opinion on this I'd love to leave this up to you. I'm not too familiar w what you guys are doing in the Redux repo, but if it's working well for you and you're able to host w/out hacks on GH pages and you think it'd be easier for people to contribute then let's just do that. Only reason I suggested we build to docs is it seems like the smallest step to get from where we are now to a statically generated folder of HTML files.

Agree that the current docs structure makes it difficult for people to contribute and find stuff.

[mjackson]

I should be clear that I don't want to do exactly what Redux are doing. I'm not a huge fan of gitbook. :P

[DavidWells]

I highly highly recommend using phenomic.io for this.

100% react powered static site and plug in something like algolia for search https://community.algolia.com/docsearch/

For an example implementation checkout https://github.com/serverless/site/tree/master/src

[thangngoc89]

@mjackson Phenomic is looking for upgrading to react router v4. I think this is a good chance for us to investigate react router v4. Can I give it a try?

[MoOx]

I also think that Phenomic would be a good fit: you don't have to care about webpack config since the setup create something for you. You just have to write some React component and some markdown & boom, you got a website.
If you are interested, Phenomic does some dogfooding and have it's docs here https://github.com/MoOx/phenomic/tree/master/docs
You mainly have a source folder for components/layouts etc & a content folder for the markdown (obviously, all of the paths can be adjusted).

We can try to make a PR for you with basic layouts so we can iterate together (should be easy to do, obviously you can still close the PR the project does not fit for you). What do you think?

[MoOx]

Note that Phenomic provides out of the box offline support via Service Worker ("just" require https, but easy to do with free cloudflare account + github pages). Users can access your website even when they are in a plane. How cool?

[timdorr]

@mjackson

I should be clear that I don't want to do exactly what Redux are doing. I'm not a huge fan of gitbook. :P

Yep, I'm not saying that either. It's more about getting the same spirit of openness that Redux has to it's docs. For instance, git blame on any doc file and you'll see the majority of them aren't even written by Dan or myself. In fact, @markerikson just wrote a freaking novel's worth of new docs for the project and has even more up his sleeve. The best docs are the ones you don't have to write 😄

Interestingly, the gitbook team is attempting to reach out to the community more, which is awesome. While it's a good source of inspiration, it's ultimately not a good tool for this project, as we need live examples to really make it shine. I think the existing website tooling is pretty good for the job at the moment.

[mjackson]

OK, I think we can close this one now. We're just going to host the docs at reacttraining.com, so no need to generate everything to static files.