doc/tips/github.mdwn

   1 Here's how to set up a static wiki or blog using ikiwiki with no hosting
   2 fees. Everything is hosted on github, both the git repository and the web
   3 site. Your laptop is used to generate and publish changes to it.
   4
   5 This is possible because github now supports
   6 [github pages](http://github.com/blog/272-github-pages).
   7
   8 Note that github limits free accounts to 100 mb of git storage. It's
   9 unlikely that a small wiki or blog will outgrow this, but we are keeping
  10 two copies of the website in git (source and the compiled site), and all
  11 historical versions too. So it could happen. If it does, you can pay github
  12 for more space, or you can migrate your site elsewhere.
  13
  14 ## github setup
  15
  16 * Go to [github](http://github.com/) and sign up for an account, if you
  17   haven't already.
  18 * Be sure to add your laptop's ssh key to it so you can push
  19   to github.
  20 * Create a repository on githib named `$YOU.github.com`, substituting your
  21   username. This repository will be used to publish your compiled website.
  22 * Create a repository on github named `$YOU` (or anything else you like).
  23   This repository will be used to publish the source of your website.
  24   This is actually optional.
  25
  26 ## local setup
  27
  28 * On your laptop, create two empty git repositories to correspond to the
  29   github repositories:
  30         YOU=# your github username here
  31         mkdir ~/$YOU.github.com
  32         cd ~/$YOU.github.com
  33         git init
  34         git remote add origin git@github.com:$YOU/$YOU.github.com.git
  35         mkdir ~/$YOU
  36         cd ~/$YOU
  37         git init
  38         git remote add origin git@github.com:$YOU/$YOU.git
  39 * Add some wiki pages, such as an `index.mdwn`, to `~/$YOU`, and check them
  40   in and commit them to git. You need something to push to github. Run
  41   `git push origin master` to push the source pages to github.
  42
  43 ## publishing to github
  44
  45 * Now build your wiki with a command such as:
  46         ikiwiki ~/$YOU ~/$YOU.github.com --refresh
  47 * Each time you build the wiki you will need to commit the changes
  48   to git, and push the compiled pages to github:
  49         cd ~/YOU.github.com
  50         git add .
  51         git commit -a -m update
  52         git push origin master
  53
  54 Your wiki will show up at `http://$YOU.github.com/` within ten
  55 minutes after the first push, and changes you push to it from then on
  56 should show up immediatly.
  57
  58 ## enhancements
  59
  60 You can follow the instructions in [[laptop_wiki_with_git]] to set up an
  61 editable version of your wiki on your laptop. Then you can use the web
  62 interface for editing. You'll still need to follow the instructions above
  63 to publish your changes to github.
  64
  65 It would also be possible to teach ikiwiki to push compiled pages to github
  66 itself via a plugin, as was done with the [[plugins/amazon_s3]] plugin. Not
  67 done yet!