1 This tutorial will walk you through setting up a wiki with ikiwiki.
3 1. [[Install]] ikiwiki. See [[download]] for where to get it.
5 2. Decide where your wiki's files will go.
7 As a wiki compiler, ikiwiki builds a wiki from files in a source
8 directory, and outputs the files to a destination directory.
10 For the purposes of this tutorial, we'll set shell variables
11 for these locations, and use those variables in the commands that follow.
14 DESTDIR=~/public_html/wiki/
16 3. Create the beginnings of your wiki.
18 This will create a simple main page for the wiki.
24 In the editor, you could start by entering a simple page like this one:
26 Welcome to your new wiki.
28 All wikis are supposed to have a [[SandBox]], so this one does too.
32 This wiki is powered by [ikiwiki](http://ikiwiki.kitenet.net).
34 See [[HelpOnFormatting]] for details about the markup language.
36 Note that several standard wiki pages will be added to your wiki, from
37 files in `/usr/share/ikiwiki/basewiki/`, so your wiki will automatically
38 get a [[SandBox]], and some other useful pages.
40 4. Build your wiki for the first time.
42 ikiwiki --verbose $SRCDIR $DESTDIR --url=http://host/~you/wiki/
44 Replace the url with the real url to your wiki. You should now
45 be able to visit the url and see your wiki.
47 5. Repeat steps 3 and 4 as desired, editing or adding pages and rebuilding
48 the wiki. You can play around with other ikiwiki parameters such as
49 `--wikiname` and `--rebuild` too. Get comfortable with its command line
52 6. By now you should be getting tired of typing in all the command line
53 options each time you change something in your wiki's setup. Time to
54 introduce setup files.
56 A sample setup file is [[ikiwiki.setup]]. Download it (or copy it from
57 `doc/ikiwiki.setup` in the ikiwiki sources), and edit it.
59 Most of the options, like `wikiname` in the setup file are the same as
60 ikiwiki's command line options (documented in [[usage]]. `srcdir` and
61 `destdir` are the two directories you specify when running ikiwiki by
62 hand. Make sure that these are pointing to the right directories, and
63 read through and configure the rest of the file to your liking.
65 When you're satisfied, run `ikiwiki --setup ikiwiki.setup`, and it
66 will set everything up.
68 7. Turn on additional features.
70 Now you have a basic wiki with a configuration file. Time to experiment
71 with ikiwiki's many features.
73 Let's first enable a key wiki feature and set up [[CGI]] to allow
74 editing the wiki from the web. Just edit ikiwiki.setup, uncomment the
75 block for the cgi wrapper, make sure the filename for the cgi wrapper
76 is ok, run `ikiwiki --setup ikiwiki.setup`, and you're done!
78 There are lots of other configuration options in ikiwiki.setup that you
79 can uncomment, configure, and enable by re-running
80 `ikiwiki --setup ikiwiki.setup`. Be sure to browse through all the
83 8. Put your wiki in revision control.
85 At this point you might want to check your wiki in to a revision control
86 system you can get history of past changes and revert edits. Depending
87 on the revision control system you choose, the way this is done varies.
89 There's little that's ikiwiki specific about these instructions; this is
90 just how you put a directory under revision control using the various
91 systems ikiwiki supports:
95 svnadmin create $REPOSITORY
96 svn import $SRCDIR file://$REPOSITORY/trunk -m "initial import"
98 svn co file://$REPOSITORY/trunk $SRCDIR
101 REPOSITORY=~/wikirepo
107 git commit -m "initial import" -a
109 git clone -l -s $REPOSITORY $SRCDIR
112 REPOSITORY=~/wikirepo
113 tla make-archive me@localhost--wiki $REPOSITORY
114 tla my-id "<me@localhost>"
116 tla archive-setup me@localhost--wiki/wiki--0
117 tla init-tree me@localhost--wiki/wiki--0
118 # Edit {arch}/=tagging-method and change the precious
119 # line to add the .ikiwiki directory to the regexp.
127 9. Configure ikiwiki to use revision control.
129 Once your wiki is checked in to the revision control system,
130 you should configure ikiwiki to use revision control. Edit your
131 ikiwiki.setup, and uncomment the lines for the revision control system
132 you chose to use. Be sure to set `svnrepo` to $REPOSITORY, if using
133 subversion. Uncomment the block for the wrapper for your revision
134 control system, and configure the wrapper path in that block
137 Once it's all set up, run `ikiwiki --setup ikiwiki.setup` once more.
138 Now you should be able to edit files in $SRCDIR, and use your revision
139 control system to commit them, and the wiki will automatically update.
140 And in the web interface, RecentChanges should work, and files changed
141 by web users will also be committed using revision control.
143 10. Enjoy your new wiki! Add yourself to [[IkiWikiUsers]].