A practical run-through of the commands used to create this ikiwiki site. On Debian Sid, using Mercurial as backend. My paths will be used as reference, exchange them wherever necessary.
Package installation
sudo aptitude install ikiwiki python-docutils librpc-xml-perl libhighlight-perl
Auto-installation script
$ ikiwiki --setup /etc/ikiwiki/auto-blog.setup
What will the blog be named? notes
What revision control system to use? mercurial
What wiki user (or openid) will be admin? daniel
warning: do not know how to set up the mercurial_wrapper hook!
Setting up notes ...
Importing /home/daniel/notes into mercurial
adding .hgignore
adding archives.mdwn
adding comments.mdwn
adding index.mdwn
adding posts.mdwn
adding posts/first_post.mdwn
adding sidebar.mdwn
adding tags.mdwn
Directory /home/daniel/notes is now set up as a mercurial repository
rcs_getmtime is not implemented for mercurial
rcs_getmtime is not implemented for mercurial
rcs_getmtime is not implemented for mercurial
rcs_getmtime is not implemented for mercurial
rcs_getmtime is not implemented for mercurial
rcs_getmtime is not implemented for mercurial
rcs_getmtime is not implemented for mercurial
Creating wiki admin daniel ...
Choose a password:
Confirm password:
ikiwiki-update-wikilist: cannot write to /etc/ikiwiki/wikilist
** Failed to add you to the system wikilist file.
** (Probably ikiwiki-update-wikilist is not SUID root.)
** Your wiki will not be automatically updated when ikiwiki is upgraded.
Successfully set up notes:
url: http://d-f05.rot.sgsnet.se/~daniel/notes
srcdir: ~/notes
destdir: ~/public_html/notes
To modify settings, edit ~/notes.setup and then run:
ikiwiki -setup ~/notes.setup
The warning: do not know how to set up the mercurial_wrapper hook!
comes from a lack of support of this in /usr/share/perl5/IkiWiki/Setup/Automator.pm
. I've got it working locally, and am sending a patch upstream.
The rcs_getmtime
messages come from the fact that the Mercurial backend doesn't support that function (see ikiwiki/ Revision Control Systems). The implication is that ikiwiki can't restore dates of blog posts from Mercurial's history, should one have to recreate the files. It repeats 8 times since 8 files have been automatically installed as a skeleton. I've fixed rcs_getctime
and rcs_getmtime
for Mercurial and sent it upstream. Update: it has been accepted.
Directory structure
I prefer to keep the site in a separate directory ~/notes
with subdirs (build
|source
).
mkdir ~/notes-tmp
mv ~/notes ~/notes-tmp/source
mv ~/public_html/notes ~/notes-tmp/build
rmdir ~/public_html
mv ~/notes.setup ~/notes-tmp
mv ~/notes-tmp ~/notes
echo "daniel /home/daniel/notes/notes.setup" | sudo tee -a /etc/ikiwiki/wikilist
The last line will make the site automatically regenerate on ikiwiki package updates.
Modifying the setup file
Below are the changes I made, described by row number and content.
13:adminemail => 'your@email.here',
19:srcdir => '/home/daniel/notes/source',
21:destdir => '/home/daniel/notes/build',
23:url => 'http://510x.se/notes',
25:cgiurl => 'http://510x.se/notes/ikiwiki.cgi',
URL:s relative to Apache DocumentRoot
are possible to declare, but ikiwiki actually parses this out by itself anyway, and currently ikiwiki --setup
will spit out a number of (harmless) error messages in that exact code if the URL is already in relative format (a bug where undefined strings are assumed to be defined: currently line 570 in /usr/share/perl5/IkiWiki.pm
).
27:cgi_wrapper => '/home/daniel/notes/build/ikiwiki.cgi',
All settings so far are to reflect local conditions.
33:add_plugins => [qw{goodstuff comments blogspam calendar sidebar more}],
more
adds the !more
-directive, which enables you to show only parts of posts on the main page with a "more"-link to the full content.
35:disable_plugins => [qw{editpage}],
This is not a wiki, and I won't use the web interface to edit the pages, so I don't want it to be editable over www.
63:timeformat => '%Y-%m-%d %H:%M:%S %Z',
Just another date format that I find as international and unambiguous as can be.
119:historyurl => '/hg/ikiwiki/notes/log/tip/<span class="createlink">file</span>',
121:diffurl => '/hg/ikiwiki/notes/?fd=<span class="createlink">r2</span>;file=<span class="createlink">file</span>',
I linked the source directory to my hgweb interface at http://510x.se/hg/ikiwiki/notes. The above lines gives a history view of the pages through hgweb.
215:comments_commit => 0,
comments_commit
is disabled since the Mercurial backend doesn't support rcs_commit_staged
, which is an internal ikiwiki function needed to automatically commit e.g. comments. I have submitted a patch upstream to extend the Mercurial backend to support this functionality. It works locally for me, but more testing is needed before merging upstream. See ikiwiki/ Revision Control Systems for updates on the Mercurial support. Update: it has been accepted.
336:tag_autocreate => 1,
This makes the tag list automatically update as you tag your post. I can't see why this isn't the default.
Setup calendar
Weeks start on Monday, not Sunday. At least in my world.
mkdir ~/notes/source/templates
cp /usr/share/ikiwiki/templates/calendar* ~/notes/source/templates/
sed -i 's/^\(\[\[!calendar\)/\1 week_start_day="1"/' ~/notes/source/templates/calendar* ~/notes/source/sidebar.mdwn
Otherwise ikiwiki-calendar
will use the default week_start_day=0
(==Sunday) when run. Templates in the local source directory will override global ones, so by copying and modifying templates, the changes won't get overwritten during package upgrades. Newer versions of the templates, however, won't be reflected unless manually copied and re-edited. I contributed this to http://ikiwiki.info/tips/Make_calendar_start_week_on_Monday/. See that page for additions and corrections by other people.
Run
ikiwiki-calendar ~/notes/notes.setup 'posts/* and !*/Discussion'
for initial calendar generation.
Modify crontab (crontab -e
) and add
0 0 * * * ikiwiki-calendar ~/notes/notes.setup 'posts/* and !*/Discussion' 2>/dev/null
to update current date daily and generate new calendar archive pages when the year changes. 2>/dev/null
since with the Mercurial backend, the command will always throw rcs_commit_staged not implemented for mercurial
, which will generate an email notification. This error also means that the calendar won't actually get updated until ikiwiki --setup
is run, which is an open issue. See earlier discussion about rcs_commit_staged
. Personally, I don't need or use 2>/dev/null
since I run my patched version of the Mercurial backend.
If you update the local templates, run
ikiwiki-calendar -f ~/notes/notes.setup 'posts/* and !*/Discussion'
to update existing archive pages (followed by ikiwiki --setup
in line with above discussion concerning rcs_commit_staged
).
Configure Apache
Create /etc/apache2/conf.d/notes.local
:
Alias /notes /home/daniel/notes/build
<Directory /home/daniel/notes/build>
Options +ExecCGI
AddHandler cgi-script .cgi
</Directory>
Reload Apache config:
sudo service apache2 reload
Mercurial hooks
Create ~/notes/source/.hg/hgrc
:
[hooks]
post-commit = ikiwiki --setup ../notes.setup --post-commit
incoming = ikiwiki --setup ../notes.setup --post-commit
Is this the correct way to setup the ikiwiki hooks for Mercurial? I can't find crystal clear information. A wrapper script is mentioned in places, but I don't know if it's deprecated. This seems to work without error.
Update: it should really be handled by the wrapper script generated by ikiwiki. I've sent patches regarding this in combination with the Mercurial backend upstream, and I'll update the info when it has been accepted.
Style the page
The basic theme is a good base for a personal CSS to modify appearance. Save your locally modified CSS file as ~/notes/source/local.css
.
This site's local.css (if it had a name, it would probably be "pastel"). I will most likely upload it to http://ikiwiki.info/css_market/ as it matures.
Generate site
ikiwiki --setup ~/notes/notes.setup
View your creation
Go to the URL defined in the setup file and the Apache config. In my case, http://510x.se/notes.
Add to your creation
The by ikiwiki autogenerated "first post" says it all. Add pages to ~/notes/source/posts/
and commit them (or manually run ikiwiki --setup ~/notes/notes-setup
or similar, see man ikiwiki
. The idea of having the site in a VCS is to commit your changes, though) to make ikiwiki generate new pages (if hooks are set up). If web editing is allowed, you can also create pages that way.
By default, ikiwiki supports Markdown syntax for posts (other alternatives are available, see Supports many markup languages). Suffix the Markdown file with .mdwn
to make ikiwiki pick them up.
For more info, visit primarily http://ikiwiki.info/.
Patches
I have made some patches kept (mostly) at my Mercurial repository. They will probably go upstream soon, though, when they are ready and have been discussed. They concern
- support for
rcs_commit_staged
as described earlier (done), - support for fast retrieval of time info (done, but sketching a possibly faster method),
- automatic merge and conflict handling when multiple edits on the same revision are done simultaneously (working, but could be more refined),
- speed-ups regarding RCS information retrieval and parsing using XML (95% done),
- support for rolling back pages to earlier versions through the web interface,
- parsing of OpenID user strings (done)