This is a simple set of files for bootstrapping a git-backed instance
of ikiwiki.
-I put this together to make it easier to get started with ikiwiki than
-following the standad instructions:
+I put this together to make it easier for people who are already
+comfortable with git to start using ikiwiki with git. If you're not
+already comfortable with git, then you're probably much better off
+learning to use ikiwiki from its standard instructions:
http://ikiwiki.info/setup/
Features
========
-Here are some of the key features of what I've got setup:
+Here are some of the key features of what I've got set up, (and that
+are different than following the standard instruction for integrating
+ikiwiki with git).
1. Self-contained.
3. Pre-configured for git
- Most of the git-specific settings you need are already setup
- in ikiwiki.setup.
+ Most of the git-specific settings you need are already set up
+ in ikiwiki.setup. One that is not is that the generated
+ wrapper is placed into ikiwiki-post-update rather than going
+ directly into git's post-update---so you will have to manually
+ edit post-update to call ikiwiki-post-update, (perhaps in
+ addition to anything else you want to do in post-update). See
+ below.
Usage
=====
-To start choose where the bare git repository will exist on your web
+To start, choose where the bare git repository will exist on your web
server and where you'd like the HTML results to be published to. Edit
-ikiwiki.setup and fill these in for gitrepo and destdir.
+ikiwiki.setup and fill these in for gitrepo and destdir. Commit these
+changes, (git commit -a).
-Next, follow these steps to setup gitrepo along with a nested checkout
-inside of it that ikiwiki will use:
+Then use the following commands on the server to set up the bare git
+repository there:
mkdir -p $gitrepo
cd $gitrepo
GIT_DIR=. git init-db
+
+Then, push the contents of this repository out to $gitrepo. To do
+this, you'll probably want to edit .git/config to point origin at the
+repository you just setup on your web server at $gitrepo. Then do:
+
+ git push origin master:refs/heads/master
+
+Then, back on the server, (and still with $gitrepo as the current
+working directory) do:
+
git clone $gitrepo ikiwiki-checkout
+ cd ikiwiki-checkout
+ ikiwiki --setup ikiwiki.setup
+
+[And yes, if you're paying attention there, you just cloned from the
+bare repository into a directory that is also inside that same
+repository. I found this a neat place to hide away the
+clone-with-working-tree that ikiwiki needs to edit but that you
+shouldn't touch. If you think this is too creepy, you could put it
+anywhere else, and configure ikiwiki.setup to point to it there.]
+
+And finally, edit $gitrepo/hooks/post-update to call the new
+$gitrepo/hooks/ikiwiki-post-update program and also don't forget to
+actually enable the hook with:
+
+ chmod a+x $gitrepo/hooks/post-update
+
+Now, you're finally ready to go. You should be able to just start
+adding content under the src directory. You can give files a .mdwn
+extension to use markdown syntax to turn the contents into HTML. Here
+are some hints on doing that:
+
+ http://ikiwiki.info/helponformatting/
+
+To preview things locally, you can run "ikiwiki --setup
+ikiwiki.setup", (and ensure the destdir path exists on the local
+machine). When you're ready to publish to your server, it should be as
+simple as "git push".
+
+Problems
+========
+Here is a useful, (self explanatory), command-line options for
+debugging ikiwiki problems:
+
+ ikiwiki --verbose --setup ikiwiki.setup
+
+ ikiwiki --verbose --rebuild --setup ikiwiki.setup
+
+I've had occasions where the hook-based update fails for one reason or
+another, (for example, once when I moved the location of $gitrepo, but
+the compiled hook still had the old location). The basic recipe for
+unwedging things in this case was as simple as running the following
+on the server:
-Finally, push this repository out to $gitrepo, then start adding
-content in files under src.
+ cd $gitrepo/ikiwiki-checkout
+ git pull
+ ikiwiki --setup ikiwiki.setup
-Let me know if you have any problems or questions,
+I hope that's all helpful, and please feel free to let me know if you
+have any problems or questions,
Carl Worth <cworth@cworth.org>
projects / ikiwiki-bootstrap / blobdiff