[docs] Workflow for previewing docs in the testtwf-website repo

Hi,

First, let me know if this isn't the proper list for doc questions. If this list is ok,  shall we tag subject lines to separate doc stuff from actual infrastructure discussions?

Questions for Tobie or anyone else updating docs:

What's the recommended workflow for previewing new and modified docs?  As I push to my my forked repo, I consistently get 'Page build failure' errors.

First, the error was:

"The page build failed with the following error:

CNAME already taken: www.testthewebforward-staging.org"

That makes sense b/c I've forked the CNAME file with everything else. When I remove that file (temporarily with the intention of putting it back before the PR), I keep getting the oh-so-helpful:

"The page build failed with the following error:

page build failed"

Upon installing and running a Jekyll build locally, I'm getting slews of parsing errors from Maruku (?) - all mostly to do with the many code blocks we have in our docs.  I fixed some of the errors in the docs I'm working on (most notably exchanging triple backticks for indentation), but it seems like Jekyll or Maruku or whoever seems is trying to be too smart for his own good. Like you apparently can't have an inline <head> tag in a sentence because there's no closing tag!  And since I'm building the site from the root, I'm hitting these issues not just with the docs I'm touching, but others that I haven't (testharness-documentation.md, for example).

Anyway:
  1) How can I build and preview my pages locally before pushing (and ultimately sending a PR)?
2) How to deal with the CNAME file - can I tell git to ignore it or something?


Thanks,
-Rebecca

Received on Friday, 12 July 2013 00:43:35 UTC