Status: Total work in progress - I'm learning as I go. These are mostly notes - not much editing. They might help you learn what I have learned. If this works out well, I'll create a step-by-step guide.
If you are a writer, and you don't want to learn about coding and git, but you still want to collaborate with others on your work, then try something like Penflip, Authorea, or Draftin. Github is uncomfortably complex for (most) writers who are not coders. But heck, what do I know? Maybe this is your way into learning git?
If you are a coder, or are becoming one, AND you like to write creatively, then you probably already use git and the command line all day long. Since you are using git all the time anyway, you don't much care to be dragged between systems - it's better to keep it all in one context. This article is for you.
The main advantage of this method for coders is that it saves time. Git also happens to be the least wonky way to maintain versions of things when you collaborate, so you get some built-in pluses.
A longer list of things that are theoretically awesome and exciting about this:
1) A build process including c.i./c.d. adds flexibility - automatically build different versions of your stuff, spellcheck, etc. and publish to your site.
2) Collaboration with other people *like yourself* is not only possible, but easy - with a solid, well-known process.
3) As long as you are publishing to your site with continuous integration/deployment, you can feel free to decorate your documents up with links and images and other web-stuff, which can be stripped or kept in the pdf, mobi, epub versions.
4) Only a few people do this.
5) Alternative works: I'm not so sure coders who are also creative writers want to write the standard large works like a novel. Creative works containing pictures, animations, links, choose-your-own-adventures, games, and such will be less boring and more common to us. Those ideas are *certainly* less boring to me. I think version control should be a big part of complex alternative works like these.
Here are my notes on how to do it:
Starting out
Create a public github repo, add some files
Simple. You already know how to do that. If not, read this and maybe watch this, and refer to this when in doubt.
Add a private section to the repo for all the drafts and notes and stuff in progress that no one wants to read.
I'm going to try using submodules for this. Scm-book chapter on submodules is here.
1) Create a new repo called writing_drafts that is private.
2) $git submodule add git@github.com:richbodo/writing_drafts.git
Your directory should have a .gitmodules in the directory you added the submodule in.
This is working pretty well. I have a main directory for my stories, and a submodule for drafts, and I'll create another submodule for each collection. The only thing that you have to remember to do, when cloning the repo again, is:
git submodule init
git submodule update
Also, the internet contains are a few pages of misinformation about removing git submodules, as the method changes from version to version. I have had luck with this stackoverflow advice:
git rm the_submodule
rm -rf .git/modules/the_submodule
My directory structure currently looks like this:
Richards-MacBook-Pro-2:git_shortstories rsb$ tree -d .
.
└── shortstories
├── 2012
├── 2013
├── 2014
├── 2015
└── writing_drafts
├── janet_drafts
│ ├── not_scenes
│ ├── scenes
│ └── sort
└── short_story_drafts
Where my private repo "writing_drafts" is a submodule of my public repo "shortstories".
No one but I can see the writing_drafts stuff, but I can commit everything - drafts and published stories - at once.
Create a gh-pages site so that your writing is more friendly/findable to non coders.
Oh, this is kind of awesome. If you don't know about github pages, you should read up on them.
The short version is that you can host static web sites for free, courtesy of a service called "github pages".
This step *should* be dirt simple. Github wrote auto-documentation that tries to start you with the simplest thing that works on pages.github.com. Unfortunately, even after putting in a lot of effort into ostensibly awesome docs, the docs don't always match use-cases to outcomes, so you might end up repeating yourself a bit. I did.
My use case is as follows:
I want a User Pages site instead of a project pages site, running Jekyll at a custom URL
that that has DNS served through Cloudflare, that uses Githubs CDN.
I'm guessing that's scenario numero uno for most users of github pages. That's what I wanted. To get that done, I recommend the following order of operations:
1) Get used to Jekyll - read this, this, this, and this, then build a little jekyll site that you can test locally. You might need stackoverflow.com to help you resolve package dependencies, so dump errors messages into that site. Bookmark Daring Fireballs jekyll syntax page, or just read it - it's not that long.
Jekyll, by the way, is a conversion tool that github pages can use to build static web sites out of various bits and pieces of text. Github will run it for you every time you check in a change to a web page. The best description of what Jekyll actually is, is on the page about Jekyll Structure, which describes what Jekyll is like so:
Jekyll is, at its core, a text transformation engine. The concept behind the system is this: you give it text written in your favorite markup language, be that Markdown, Textile, or just plain HTML, and it churns that through a layout or series of layout files. Throughout that process you can tweak how you want the site URLs to look, what data gets displayed in the layout, and more. This is all done through editing text files, and the static web site is the final product.
2) Create a username.github.io repo, clone and add a CNAME file for your custom domain.
3) (Optional) Setup free DNS with cloudflare. Use only CNAMES so we use githubs CDN - this is possible because Cloudflare is usefully extending DNS. StackOverflow has you covered. Cloudflares quest for utility will blow up in everyones faces someday, but right now they are a fantastic free DNS service for http sites (and probably the market leader). If you don't know anything about DNS, there are lots of good resources.
4) Check your Jekyll stuff into your username.github.io site.
Now all of your writing is going to be a page, post, or collection.
Notes on this step:
a) It's definitely easy to screw up your local jekyll installation by trying out new packages, and not super easy to debug/fix. If you screw it up, just revert, don't spend a ton of time on packages, most of them won't work with gh-pages anyway.
b) You should run jekyll with --watch, add a post manually, and check the formatting, before trying to automate generation of posts from existing files. You'll need to get used to markdown and jekyll a bit before your posts begin to look reasonable. Then read the docs on jekyll templates.
c) You can run into *so many* weird problems with github pages. I saw strange issues with submodules, failures to update, etc. So it's a challenge. As I explore further, I'll list workarounds and important links here. This one was useful - have to recreate branches and add a dummy commit to kick github pages back into action sometimes. Also note - you will receive error messages on your site via email from github, so anytime you are seeing strange behaviour, check your email first!
Continuous integration for spell check
Work in progress. Here's what I'm doing right now:
1) Create a travis.ci account, and learn how to use it with your github pages site.
Travis.ci offers a non-root account on an Ubuntu 12.04 LTS virtual machine (as of this writing).
They also offer a service that can check out your code every time you check it in, and run other code that you specify to test your code.
That's pretty much how I look at that service.
You will want configure travis to install packages, run scripts, and output test results every time you push.
First go through the travis.ci complete beginners guide, then the continuous integration example on jekylls site. Get those examples working. You will have to make a few changes, but when travis goes green there will be great celebration. The things I had to change:
- Whitelist the master branch in .travis.yml
- Ignore the vendor directory in _config.yml
- Ignore links to "#" in the cibuild script
2) In progress - Get automatic spell checking going with Travis.ci:
On my mac: $brew install aspell --with-lang-en
On travis.ci, you can install packages using apt. So getting spell check going should be easy.
Notes on this step:
a) While debugging that step, I found github instructions referring to the github-pages gem. I don't think it's necessary for you to install it, but it might help keep you up to date. From that site: "To ensure your computer most closely matches the GitHub Pages settings, you can use the GitHub Pages Gem. " I'm giving it a shot.
My gemfile now looks like this:
source "https://rubygems.org"
gem "jekyll"
gem 'github-pages'
gem 'html-proofer'
b) If you are using brew, it's a good idea to run 'brew update and 'brew doctor' once in a while and resolve all the errors you find (the ones that make sense anyway) - easy to run into problems with brew if you don't.
c) I would have used the package hunspell, but , people who host good spelling dictionaries (openoffice, mozilla) don't offer a mac users a programmatic way to get them (could be in the repo of some linux distro?). The GNU stuff just works in this case, so for convenience, aspell it is.
d) I ended up with a few undetectably weird characters in my .travis.yml file. Easy to do when you are copying and pasting. Travis.ci is understandably sensitive.
Continuous deployment to push to your site, and conversion to PDF, ePub, mobi
TBD
Notes on this step:
I just spent a good four hours exploring this, so I'm going to document my work. Honestly, continuous deployment with travis.ci is not *that* important compared to the other features I need, so integrating with travis in that way is the last thing on my list.
I'm having trouble at this point with continuous deployment. I originally hoped I could make travis convert, test, and push files to the jekyll site. However, I have a public repo, and a .travis.yml in there. I can't just put deploy keys in my .travis_yml and leave it in a public repo. I also don't want to put my keys to github in .travis_yml. Given a public github repo and a public travis-ci.org account, I can't figure out how to fully automate the way I would like.
This is clearly the way to use travis on the cli: https://github.com/travis-ci/travis.rb - if you read the install docs and the api docs, I'm sure you'll agree. If I understand him correctly, Neemzy explains that you can use the "travis" utility to set secret keys in environment variables on the travis virt securely - storing them in plaintext only on your local system. Once they are brokered to travis, they can be decrypted (I assume using the travis cli app again) and used to deploy your stuff to a server via scp. There is more for me to read here.
That's cool, and maybe there is more for me to read, but I think I still have to run a deploy script locally, each time, to make that work. It also feels unnecessary - this whole thing should be made easier by the fact that I probably just need to check in files to my gh-pages site to get them on the site, which is unlike "traditional deployment". Travis already has access to my github account, so there should be some way to access it's key and do stuff with it in a fully automated way. Anyway, the travis gem is an interesting app, but I'm not sure it will help me. Maybe.
The other thing that's changing my strategy is that I can't keep my desired submodule structure. I was hoping to put all my writing-related repos in one directory. A submodule hierarchy like so: name.github.io(public) -> writing(public) -> drafts(private).
However, one of travis's rules is that you can't have a private github repo as a submodule of a public repo and still use travis-ci.org. Further, you can't tell travis to ignore a submodule. So, I have to rearrange my strategy.
I'm sure there is a way to do this. I will still use travis, but I will go with a local script at this point for all the heavy lifting. It's easier than any other option. These limitations just make things a bit more complex and less clean for me.
Here is what I am thinking I should do now:
Try this hierarchy:
~/src/my_writing
creative_writing_tools (public repo)
writing_drafts (private repo)
richbodo.github.io (public repo)
shortstories (submodule)
Start writing tools - here are some tool ideas:
creative_writing_tool_ideas:
Note to self - everyone seems to be using ruby for this sort of thing - also check out some of the more robust rake files out there to see if there is anything that covers this (i.e. https://github.com/jekyll/jekyll/blob/master/rake/site.rake)
- checkformat.rb - spell checks all posts, htmlproofs
- makepost.rb - can move a short story into the jekyll gh-pages as a post
- issuesbutton.rb - add issues button to gp-pages post that links to the github issues page
- tags.rb - add tags to the post, that can be somehow browsed. (http://charliepark.org/tags-in-jekyll/)
- editbutton.rb - add a link that brings you to the github URL for editing that document on the github website
- makemobile.rb - converts a post into epub, mobi, pdf, and puts the links at the top of the post
- novelize.rb - could turn a bunch of short stories into a novel that is a single jekyll post, and a release
- strunk_white_checker.rb - check against the rules of strunk and white as well as possible
- summarizer.rb - use a summarizer to put an abstract at the bottom of the page, with a link at top.
- classifier.rb - use a bayesian classifier to add tags
- indexpage.rb - build an index page of stories that is sortable by tags, and adds, next to each story title: tags, summary, word count, issues link, etc.
- pp_pupu.rb - parsey mcparseface pun publishing pre-parsing time wasting sentence diagrammer. because.
Future Exploration:
- Figure out what this github writing section is all about
- Look into Github Releases to see if it would be appropriate for favorite versions of longer works (My_Novel_1.0, etc.)
Things you might not be able to do with a gh-pages site:
- Upvote or comment on jekyll hosted posts - better to have that feature for individual files in github, and link to the github.com page, but that feature doesn't exist on github - you can't "upvote" a file in a repo on github.com. There might be a Jekyll-based workaround for upvoting stuff - but you have to stick to the plugins github allows.
- More complex, interactive pages - I'm not sure I could make a gh-pages site particularly interactive - it's meant for static pages. You could get a choose your own adventure in there, for sure. That could be a fun tool to write.
Not knowing jekyll, I can only imagine the wonky workarounds...creative writing tools could store data in json and check that into your jekyll site, then build pages based on that database. Anyway, pretty far from the juncture where that matters.
See Also:
https://github.com/btford/write-good
http://zachholman.com/posts/how-github-writes-blog-posts/
http://www.jacobtomlinson.co.uk/jekyll/2015/02/18/test-you-jekyll-blog-with-travis-ci/
https://github.com/JJ/hoborg
https://github.com/blog/1379-zen-writing-mode
https://medium.com/@jjmerelo/top-ten-reasons-github-is-a-great-tool-for-creative-writers-d0e8b27de71d
https://technikhil.wordpress.com/2012/01/14/open-source-writing-using-git/
https://github.com/schacon/git-scribe
http://www.developer.com/open/10-ways-git-version-control-can-streamline-your-writing-projects.html
Comments (0)
You don't have permission to comment on this page.