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

Hey,

Thanks for your questions.

See my comments inline.

On Friday, July 12, 2013 at 2:43 AM, Rebecca Hauck wrote: 
> 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?
WFM. 
> 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 (http://www.testthewebforward-staging.org)"
Yes. This cannot be avoided. The trick here is to use topic branches (a good practice anyway) and not push to the gh-pages branch of your repo.
> 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 (http://testharness-documentation.md), for example).
Apologies for the above. This is due to me blindly pulling in a number of pending pull requests despite numerous known issues with them. I'll fix this shortly.



> Anyway:
> 1) How can I build and preview my pages locally before pushing (and ultimately sending a PR)?

Use a local Jekyll server.
> 2) How to deal with the CNAME file - can I tell git to ignore it or something?

Only push topic branches to your GH fork.

--tobie

Received on Friday, 12 July 2013 09:27:36 UTC