X-Git-Url: https://git.cworth.org/git?a=blobdiff_plain;f=README;h=1aa6099143d3ad176f1e9672ee034a9c977b0b94;hb=c346f0f9febf8d731774bad8d58bde3ae32c7396;hp=fe63d146efe7b1d0a02866e437e9cf05f3e5f062;hpb=a0806e45bfc29181195f3c801943607d7a3393e0;p=ikiwiki-bootstrap diff --git a/README b/README index fe63d14..1aa6099 100644 --- a/README +++ b/README @@ -1,14 +1,18 @@ 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. @@ -23,7 +27,7 @@ Here are some of the key features of what I've got setup: 3. Pre-configured for git - Most of the git-specific settings you need are already 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 @@ -33,37 +37,76 @@ Here are some of the key features of what I've got setup: 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 and -continue with the following commands (still with $gitrepo as the -current working directory): +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, and you should be able to just start -adding content under the src directory and use "git push" to publish -them. To preview things locally, just run "ikiwiki --setup -ikiwiki.setup", (and ensure the destination paths exist on the local -machine as well). +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: + + 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