search

friendly / VCDR

Visualizing categorical data with R
0 stars 0 forks source link

Web pages for the book #39

Open friendly opened 9 years ago

friendly commented 9 years ago

Now that the book has been sent for copy-editing, it's time to think about an associated "companion website." For example, one very useful thing would be to provide notes, hints or solutions for the lab exercises.

I know this can be done via github (gh-pages?) but am not familiar with the details of how to set this up. Would this content be just another folder in the revision1 branch, or should it be a separate branch? Should it all be done in markdown format? I'm planning on engaging a student to help with the content over the summer. Can someone help with this?

philchalmers commented 9 years ago

If you go the gh-pages route, you basically need to make a completely new branch that has a brand new history (takes a step or two with git to do this). Then the HTML and other files can be uploaded to this usual repo location via git push and the like, but the files will be available via a path like http://friendly.github.io/book/file.html or whatever.

The question is, is a full blow website necessary, or would something like a linked wiki be easier? Here's what I've done with the Github wiki associated with mirt, and this just points to the hosted files on the gh-branch. https://github.com/philchalmers/mirt/wiki. So ultimately the question is, how polished do you need the hosting website to be?

philchalmers commented 9 years ago

I should also add that gh-pages are only available for public repos, so unless you want to make the book source code public upon publication it would probably be better to create a new public location on Github....maybe call it something like VCDR-materials.

friendly commented 9 years ago

Thanks, Phil Aside from how you set them up and how they are reflected in github, are there any differences in terms of how the content is or can be displayed? E.g., Hadley's web sites for Adv R and others look really nice and polished.

philchalmers commented 9 years ago

That's exactly what I was getting at. How polished should this hosting site be? The gh-pages should be able to render/host anything from simple HTML and markdown files to very polished websites rendered with Jekyll, but of course the latter is more about website design than content. So, it all depends on how the end product should look. A good start might be to checkout either the ggplot2 or knitr repositories and git checkout gh-pages to see how Hadley and Yihui set up theirs. It's probably not too complicated (at least as far as I can tell), but someone with more web design experience would certainly be a better judge than I.

friendly commented 9 years ago

A decent beginning template is provided by the stub page for Graphical Data Analysis with R, by Antony Unwin, http://rosuda.org/GDA

philchalmers commented 9 years ago

Something like this?

http://philchalmers.github.io/VCDR-pages/Home.html

I'll create a suitable branch on this repo with this template if it's what you are after. Apparently you can host gh-pages from private repositories. Who knew? I guess the meaning of 'private' on Github is fuzzy when it comes to gh-pages....

friendly commented 9 years ago

That's a good start. We've changed the book title to "Discrete Data Analysis with R", so the acronym should become DDAR I think, if that doesn't conflict with github naming.

If you set this up, Ryan can begin to work on that branch.

philchalmers commented 9 years ago

Done. Very minimal and markdown isn't required (editing HTML is fine), but that's enough to get the gist of it.

friendly commented 9 years ago
philchalmers commented 9 years ago

On Mon, Jun 8, 2015 at 10:42 AM, Michael Friendly notifications@github.com wrote:

-

Is there any reason that the main file is called Home.md rather than index.md?

You can create whatever md or html files you'd like, I just used Home as a working stub. Feel free to rename it or create others.

-

What will the URL of the pages be? I tried http://friendly.github.io/gh-pages/Home.html but I get a 404 error

Currently it should be http://friendly.github.io/VCDR/Home.html

  • Is there anything you can recommend for a site-generation tool to give a consistent look w/o having to code everything in markdown? I see that Yihui and others use Jekyll, but maybe this is overkill.

I think just attaching a CSS file would be fine, which can be passed through pandoc as well. Jekyll is nice but it's a little strange to configure correctly, and is largely outside my comfort zone anyway. That being said, using a high-level GUI's to create web-pages is fair game (like with Adobe products), so if you want to focus just on generating and editing HTML files that's fine too. I tend to use BlueGriffon on Ubuntu for that kind of stuff.

— Reply to this email directly or view it on GitHub https://github.com/friendly/VCDR/issues/39#issuecomment-110018924.