diff options
Diffstat (limited to 'doc/tips')
27 files changed, 1218 insertions, 54 deletions
diff --git a/doc/tips/DreamHost.mdwn b/doc/tips/DreamHost.mdwn index 6670f8090..070638e3e 100644 --- a/doc/tips/DreamHost.mdwn +++ b/doc/tips/DreamHost.mdwn @@ -150,6 +150,8 @@ Next, add your installed Perl module directory to the *libdir* parameter. It sh libdir => "/home/.server/user/site/perl/lib/perl5/", # CGI Wrapper +The CGI wrapper file will be created automatically by "ikiwiki --setup path/to/setup", as long as you have inserted a valid filename to be created into the setup file. On DreamHost, be careful not to put the ikiwiki.cgi file in a directory that has different owner/group than the file itself (such as the main site.domain.tld/ directory): this will cause suexec to fail. + The wrapper mode of "06755" doesn't seem to work. "755" appears to. However, this may be completely insecure and/or buggy, so if you know better than I, edit this doc and add it here. # Pre-created SVN repository diff --git a/doc/tips/Git_repository_and_web_server_on_different_hosts.mdwn b/doc/tips/Git_repository_and_web_server_on_different_hosts.mdwn new file mode 100644 index 000000000..58940b89f --- /dev/null +++ b/doc/tips/Git_repository_and_web_server_on_different_hosts.mdwn @@ -0,0 +1,61 @@ +One may want to provide ikiwiki hosting with [[rcs/git]]+ssh access and web +server located at different hosts. Here's a description for such +a setup, using password-less SSH as a way of communication between +these two hosts. + +Git server +========== + +Let's create a user called `ikiwiki_example`. This user gets SSH +access restricted to GIT pull/push, using `git-shell` as a shell. + +The root (bare) repository: + +- is stored in `~ikiwki_example/ikiwiki_example.git` +- is owned by `ikiwiki_example:ikiwiki_example` +- has permissions 0700 + +The master repository's post-update hook connects via SSH to +`webserver` as user `ikiwiki_example`, in order to run +`~/bin/ikiwiki.update` on `webserver`; this post-update hook, located +in `~ikiwki_example/ikiwiki_example.git/hooks/post-update`, is +executable and contains: + + #!/bin/sh + /usr/bin/ssh ikiwiki_example@webserver bin/ikiwiki.update + +Password-less SSH must be setup to make this possible; one can +restrict `gitserver:ikiwiki_example` to be able to run only the needed +command on the web server, using such a line in +`webserver:~ikiwiki_example/.ssh/authorized_keys`: + + command="bin/ikiwiki.update",from="gitserver.example.com",no-port-forwarding,no-X11-forwarding,no-agent-forwarding,no-pty ssh-rsa ... + +Web server +========== + +Let's create a user called `ikiwiki_example` on `webserver`. She needs +to have write permission to the destination directory. + +The working tree repository (`srcdir`): + +- is stored in `~ikiwki_example/src` +- is owned by `ikiwiki_example:ikiwiki_example` +- has permissions 0700 +- has the following origin: `ikiwiki_example@gitserver:ikiwiki_example.git` + +The CGI wrapper is generated with ownership set to +`ikiwiki_example:ikiwiki_example` and permissions `06755`. + +Password-less SSH must be setup so that `ikiwiki_example@webserver` is +allowed to push to the master repository. As told earlier, SSH access +to `ikiwiki_example@gitserver` is restricted to GIT pull/push, which +is just what we need. + +The Git wrapper is generated in `~ikiwiki_example/bin/ikiwiki.update`: + + git_wrapper => '/home/ikiwiki_example/bin/ikiwiki.update' + +As previously explained, this wrapper is run over SSH by the master +repository's post-update hook; it pulls updates from the master +repository and triggers a wiki refresh. diff --git a/doc/tips/Google_custom_search.mdwn b/doc/tips/Google_custom_search.mdwn index 7e8ac951c..1093029f5 100644 --- a/doc/tips/Google_custom_search.mdwn +++ b/doc/tips/Google_custom_search.mdwn @@ -5,3 +5,8 @@ Instead of the [[plugins/search]] plugin you could embed [Google Custom Search]( Once you've created your "custom search engine", just drop in the search box html like I've done in my [Debian tips and tricks](http://dabase.com/tips/) [source](http://git.webconverger.org/?p=faq.git;a=blob;f=tips.mdwn). If you have odd "save failed" error messages in Google's CSE's control panel, try `/usr/lib/WebKit/GtkLauncher` from [webkit](http://packages.qa.debian.org/w/webkit.html). + + +# Alternatively + +You could use the [[Google_plugin|plugins/google]] from version 2.67. diff --git a/doc/tips/apache_cgi.mdwn b/doc/tips/apache_cgi.mdwn deleted file mode 100644 index f10baed2e..000000000 --- a/doc/tips/apache_cgi.mdwn +++ /dev/null @@ -1,25 +0,0 @@ -Many ikiwiki examples name the [[cgi]] "ikiwiki.cgi", and put it somewhere -like `~/public_html/ikiwiki.cgi`, or `/var/www/wiki/ikiwiki.cgi`. - -If you follow those examples, you may find that when trying to edit a page -in your wiki, you see the raw contents of the ikiwiki.cgi program. Or get a -permission denied problem. - -This is because apache is generally not configured to run cgi scripts -unless they're in `/usr/lib/cgi-bin/`. While you can put ikiwiki.cgi in -there if you like, here's how to configure apache (version 2) to run `.cgi` -programs from anywhere. - -These instructions are for Debian systems, but the basic apache -configuration should work anywhere. - -* Edit /etc/apache2/apache2.conf and add a line like this: - - AddHandler cgi-script .cgi - -* Find the "Options" line for the directory where you've put the - ikiwiki.cgi, and add "ExecCGI" to the list of options. For example, if - ikiwiki.cgi is in /var/www/, edit `/etc/apache2/sites-enabled/000-default` - and add it to the "Options" line in the "Directory /var/www/" stanza. - Or, if you've put it in a `~/public_html`, edit - `/etc/apache2/mods-available/userdir.conf`. diff --git a/doc/tips/comments_feed.mdwn b/doc/tips/comments_feed.mdwn new file mode 100644 index 000000000..6f8137256 --- /dev/null +++ b/doc/tips/comments_feed.mdwn @@ -0,0 +1,10 @@ +You've enabled the [[plugins/comments]] plugin, so a set of pages on your +blog can have comments added to them. Pages with comments even have special +feeds that can be used to subscribe to those comments. But you'd like to +add a feed that contains all the comments posted to any page. Here's how: + + \[[!inline pages="internal(*/comment_*)" template=comment]] + +The special [[ikiwiki/PageSpec]] matches all comments. The +[[template|wikitemplates]] causes the comments to be displayed formatted +nicely. diff --git a/doc/tips/convert_MoinMoin_and_TWiki_to_ikiwiki.mdwn b/doc/tips/convert_MoinMoin_and_TWiki_to_ikiwiki.mdwn new file mode 100644 index 000000000..5565dbd8a --- /dev/null +++ b/doc/tips/convert_MoinMoin_and_TWiki_to_ikiwiki.mdwn @@ -0,0 +1,3 @@ +[[JoshTriplett]] has developed scripts to convert MoinMoin and TWiki wikis +to ikiwikis backed by a git repository, including full history. For +details, see [[his_user_page|JoshTriplett]]. diff --git a/doc/tips/convert_mediawiki_to_ikiwiki.mdwn b/doc/tips/convert_mediawiki_to_ikiwiki.mdwn new file mode 100644 index 000000000..f03703b46 --- /dev/null +++ b/doc/tips/convert_mediawiki_to_ikiwiki.mdwn @@ -0,0 +1,4 @@ +[[sabr]] explains how to [import MediaWiki content into +git](http://u32.net/Mediawiki_Conversion/index.html?updated), including +full edit hostory. The [[plugins/contrib/mediawiki]] plugin can then be +used by ikiwiki to build the wiki. diff --git a/doc/tips/convert_mediawiki_to_ikiwiki/discussion.mdwn b/doc/tips/convert_mediawiki_to_ikiwiki/discussion.mdwn new file mode 100644 index 000000000..15ddccb92 --- /dev/null +++ b/doc/tips/convert_mediawiki_to_ikiwiki/discussion.mdwn @@ -0,0 +1,612 @@ +The u32 page is excellent, but I wonder if documenting the procedure here +would be worthwhile. Who knows, the remote site might disappear. But also +there are some variations on the approach that might be useful: + + * using a python script and the dom library to extract the page names from + Special:Allpages (such as + <http://www.staff.ncl.ac.uk/jon.dowland/unix/docs/get_pagenames.py>) + * Or, querying the mysql back-end to get the names + * using WWW::MediaWiki for importing/exporting pages from the wiki, instead + of Special::Export + +Also, some detail on converting mediawiki transclusion to ikiwiki inlines... + +-- [[users/Jon]] + +> "Who knows, the remote site might disappear.". Right now, it appears to +> have done just that. -- [[users/Jon]] + + +The iki-fast-load ruby script from the u32 page is given below: + + #!/usr/bin/env ruby + + # This script is called on the final sorted, de-spammed revision + # XML file. + # + # It doesn't currently check for no-op revisions... I believe + # that git-fast-load will dutifully load them even though nothing + # happened. I don't care to solve this by adding a file cache + # to this script. You can run iki-diff-next.rb to highlight any + # empty revisions that need to be removed. + # + # This turns each node into an equivalent file. + # It does not convert spaces to underscores in file names. + # This would break wikilinks. + # I suppose you could fix this with mod_speling or mod_rewrite. + # + # It replaces nodes in the Image: namespace with the files themselves. + + + require 'rubygems' + require 'node-callback' + require 'time' + require 'ostruct' + + + # pipe is the stream to receive the git-fast-import commands + # putfrom is true if this branch has existing commits on it, false if not. + def format_git_commit(pipe, f) + # Need to escape backslashes and double-quotes for git? + # No, git breaks when I do this. + # For the filename "path with \\", git sez: bad default revision 'HEAD' + # filename = '"' + filename.gsub('\\', '\\\\\\\\').gsub('"', '\\"') + '"' + + # In the calls below, length must be the size in bytes!! + # TODO: I haven't figured out how this works in the land of UTF8 and Ruby 1.9. + pipe.puts "commit #{f.branch}" + pipe.puts "committer #{f.username} <#{f.email}> #{f.timestamp.rfc2822}" + pipe.puts "data #{f.message.length}\n#{f.message}\n" + pipe.puts "from #{f.branch}^0" if f.putfrom + pipe.puts "M 644 inline #{f.filename}" + pipe.puts "data #{f.content.length}\n#{f.content}\n" + pipe.puts + end + + +Mediawiki.pm - A plugin which supports mediawiki format. + + #!/usr/bin/perl + # By Scott Bronson. Licensed under the GPLv2+ License. + # Extends Ikiwiki to be able to handle Mediawiki markup. + # + # To use the Mediawiki Plugin: + # - Install Text::MediawikiFormat + # - Turn of prefix_directives in your setup file. + # (TODO: we probably don't need to do this anymore?) + # prefix_directives => 1, + # - Add this plugin on Ikiwiki's path (perl -V, look for @INC) + # cp mediawiki.pm something/IkiWiki/Plugin + # - And enable it in your setup file + # add_plugins => [qw{mediawiki}], + # - Finally, turn off the link plugin in setup (this is important) + # disable_plugins => [qw{link}], + # - Rebuild everything (actually, this should be automatic right?) + # - Now all files with a .mediawiki extension should be rendered properly. + + + package IkiWiki::Plugin::mediawiki; + + use warnings; + use strict; + use IkiWiki 2.00; + use URI; + + + # This is a gross hack... We disable the link plugin so that our + # linkify routine is always called. Then we call the link plugin + # directly for all non-mediawiki pages. Ouch... Hopefully Ikiwiki + # will be updated soon to support multiple link plugins. + require IkiWiki::Plugin::link; + + # Even if T:MwF is not installed, we can still handle all the linking. + # The user will just see Mediawiki markup rather than formatted markup. + eval q{use Text::MediawikiFormat ()}; + my $markup_disabled = $@; + + # Work around a UTF8 bug in Text::MediawikiFormat + # http://rt.cpan.org/Public/Bug/Display.html?id=26880 + unless($markup_disabled) { + no strict 'refs'; + no warnings; + *{'Text::MediawikiFormat::uri_escape'} = \&URI::Escape::uri_escape_utf8; + } + + my %metaheaders; # keeps track of redirects for pagetemplate. + my %tags; # keeps track of tags for pagetemplate. + + + sub import { #{{{ + hook(type => "checkconfig", id => "mediawiki", call => \&checkconfig); + hook(type => "scan", id => "mediawiki", call => \&scan); + hook(type => "linkify", id => "mediawiki", call => \&linkify); + hook(type => "htmlize", id => "mediawiki", call => \&htmlize); + hook(type => "pagetemplate", id => "mediawiki", call => \&pagetemplate); + } # }}} + + + sub checkconfig + { + return IkiWiki::Plugin::link::checkconfig(@_); + } + + + my $link_regexp = qr{ + \[\[(?=[^!]) # beginning of link + ([^\n\r\]#|<>]+) # 1: page to link to + (?: + \# # '#', beginning of anchor + ([^|\]]+) # 2: anchor text + )? # optional + + (?: + \| # followed by '|' + ([^\]\|]*) # 3: link text + )? # optional + \]\] # end of link + ([a-zA-Z]*) # optional trailing alphas + }x; + + + # Convert spaces in the passed-in string into underscores. + # If passed in undef, returns undef without throwing errors. + sub underscorize + { + my $var = shift; + $var =~ tr{ }{_} if $var; + return $var; + } + + + # Underscorize, strip leading and trailing space, and scrunch + # multiple runs of spaces into one underscore. + sub scrunch + { + my $var = shift; + if($var) { + $var =~ s/^\s+|\s+$//g; # strip leading and trailing space + $var =~ s/\s+/ /g; # squash multiple spaces to one + } + return $var; + } + + + # Translates Mediawiki paths into Ikiwiki paths. + # It needs to be pretty careful because Mediawiki and Ikiwiki handle + # relative vs. absolute exactly opposite from each other. + sub translate_path + { + my $page = shift; + my $path = scrunch(shift); + + # always start from root unless we're doing relative shenanigans. + $page = "/" unless $path =~ /^(?:\/|\.\.)/; + + my @result = (); + for(split(/\//, "$page/$path")) { + if($_ eq '..') { + pop @result; + } else { + push @result, $_ if $_ ne ""; + } + } + + # temporary hack working around http://ikiwiki.info/bugs/Can__39__t_create_root_page/index.html?updated + # put this back the way it was once this bug is fixed upstream. + # This is actually a major problem because now Mediawiki pages can't link from /Git/git-svn to /git-svn. And upstream appears to be uninterested in fixing this bug. :( + # return "/" . join("/", @result); + return join("/", @result); + } + + + # Figures out the human-readable text for a wikilink + sub linktext + { + my($page, $inlink, $anchor, $title, $trailing) = @_; + my $link = translate_path($page,$inlink); + + # translate_path always produces an absolute link. + # get rid of the leading slash before we display this link. + $link =~ s#^/##; + + my $out = ""; + if($title) { + $out = IkiWiki::pagetitle($title); + } else { + $link = $inlink if $inlink =~ /^\s*\//; + $out = $anchor ? "$link#$anchor" : $link; + if(defined $title && $title eq "") { + # a bare pipe appeared in the link... + # user wants to strip namespace and trailing parens. + $out =~ s/^[A-Za-z0-9_-]*://; + $out =~ s/\s*\(.*\)\s*$//; + } + # A trailing slash suppresses the leading slash + $out =~ s#^/(.*)/$#$1#; + } + $out .= $trailing if defined $trailing; + return $out; + } + + + sub tagpage ($) + { + my $tag=shift; + + if (exists $config{tagbase} && defined $config{tagbase}) { + $tag=$config{tagbase}."/".$tag; + } + + return $tag; + } + + + # Pass a URL and optional text associated with it. This call turns + # it into fully-formatted HTML the same way Mediawiki would. + # Counter is used to number untitled links sequentially on the page. + # It should be set to 1 when you start parsing a new page. This call + # increments it automatically. + sub generate_external_link + { + my $url = shift; + my $text = shift; + my $counter = shift; + + # Mediawiki trims off trailing commas. + # And apparently it does entity substitution first. + # Since we can't, we'll fake it. + + # trim any leading and trailing whitespace + $url =~ s/^\s+|\s+$//g; + + # url properly terminates on > but must special-case > + my $trailer = ""; + $url =~ s{(\&(?:gt|lt)\;.*)$}{ $trailer = $1, ''; }eg; + + # Trim some potential trailing chars, put them outside the link. + my $tmptrail = ""; + $url =~ s{([,)]+)$}{ $tmptrail .= $1, ''; }eg; + $trailer = $tmptrail . $trailer; + + my $title = $url; + if(defined $text) { + if($text eq "") { + $text = "[$$counter]"; + $$counter += 1; + } + $text =~ s/^\s+|\s+$//g; + $text =~ s/^\|//; + } else { + $text = $url; + } + + return "<a href='$url' title='$title'>$text</a>$trailer"; + } + + + # Called to handle bookmarks like [[#heading]] or <span class="createlink"><a href="http://u32.net/cgi-bin/ikiwiki.cgi?page=%20text%20&from=Mediawiki_Plugin%2Fmediawiki&do=create" rel="nofollow">?</a>#a</span> + sub generate_fragment_link + { + my $url = shift; + my $text = shift; + + my $inurl = $url; + my $intext = $text; + $url = scrunch($url); + + if(defined($text) && $text ne "") { + $text = scrunch($text); + } else { + $text = $url; + } + + $url = underscorize($url); + + # For some reason Mediawiki puts blank titles on all its fragment links. + # I don't see why we would duplicate that behavior here. + return "<a href='$url'>$text</a>"; + } + + + sub generate_internal_link + { + my($page, $inlink, $anchor, $title, $trailing, $proc) = @_; + + # Ikiwiki's link link plugin wrecks this line when displaying on the site. + # Until the code highlighter plugin can turn off link finding, + # always escape double brackets in double quotes: [[ + if($inlink eq '..') { + # Mediawiki doesn't touch links like [[..#hi|ho]]. + return "[[" . $inlink . ($anchor?"#$anchor":"") . + ($title?"|$title":"") . "]]" . $trailing; + } + + my($linkpage, $linktext); + if($inlink =~ /^ (:?) \s* Category (\s* \: \s*) ([^\]]*) $/x) { + # Handle category links + my $sep = $2; + $inlink = $3; + $linkpage = IkiWiki::linkpage(translate_path($page, $inlink)); + if($1) { + # Produce a link but don't add this page to the given category. + $linkpage = tagpage($linkpage); + $linktext = ($title ? '' : "Category$sep") . + linktext($page, $inlink, $anchor, $title, $trailing); + $tags{$page}{$linkpage} = 1; + } else { + # Add this page to the given category but don't produce a link. + $tags{$page}{$linkpage} = 1; + &$proc(tagpage($linkpage), $linktext, $anchor); + return ""; + } + } else { + # It's just a regular link + $linkpage = IkiWiki::linkpage(translate_path($page, $inlink)); + $linktext = linktext($page, $inlink, $anchor, $title, $trailing); + } + + return &$proc($linkpage, $linktext, $anchor); + } + + + sub check_redirect + { + my %params=@_; + + my $page=$params{page}; + my $destpage=$params{destpage}; + my $content=$params{content}; + + return "" if $page ne $destpage; + + if($content !~ /^ \s* \#REDIRECT \s* \[\[ ( [^\]]+ ) \]\]/x) { + # this page isn't a redirect, render it normally. + return undef; + } + + # The rest of this function is copied from the redir clause + # in meta::preprocess and actually handles the redirect. + + my $value = $1; + $value =~ s/^\s+|\s+$//g; + + my $safe=0; + if ($value !~ /^\w+:\/\//) { + # it's a local link + my ($redir_page, $redir_anchor) = split /\#/, $value; + + add_depends($page, $redir_page); + my $link=bestlink($page, underscorize(translate_path($page,$redir_page))); + if (! length $link) { + return "<b>Redirect Error:</b> <nowiki>[[$redir_page]] not found.</nowiki>"; + } + + $value=urlto($link, $page); + $value.='#'.$redir_anchor if defined $redir_anchor; + $safe=1; + + # redir cycle detection + $pagestate{$page}{mediawiki}{redir}=$link; + my $at=$page; + my %seen; + while (exists $pagestate{$at}{mediawiki}{redir}) { + if ($seen{$at}) { + return "<b>Redirect Error:</b> cycle found on <nowiki>[[$at]]</nowiki>"; + } + $seen{$at}=1; + $at=$pagestate{$at}{mediawiki}{redir}; + } + } else { + # it's an external link + $value = encode_entities($value); + } + + my $redir="<meta http-equiv=\"refresh\" content=\"0; URL=$value\" />"; + $redir=scrub($redir) if !$safe; + push @{$metaheaders{$page}}, $redir; + + return "Redirecting to $value ..."; + } + + + # Feed this routine a string containing <nowiki>...</nowiki> sections, + # this routine calls your callback for every section not within nowikis, + # collecting its return values and returning the rewritten string. + sub skip_nowiki + { + my $content = shift; + my $proc = shift; + + my $result = ""; + my $state = 0; + + for(split(/(<nowiki[^>]*>.*?<\/nowiki\s*>)/s, $content)) { + $result .= ($state ? $_ : &$proc($_)); + $state = !$state; + } + + return $result; + } + + + # Converts all links in the page, wiki and otherwise. + sub linkify (@) + { + my %params=@_; + + my $page=$params{page}; + my $destpage=$params{destpage}; + my $content=$params{content}; + + my $file=$pagesources{$page}; + my $type=pagetype($file); + my $counter = 1; + + if($type ne 'mediawiki') { + return IkiWiki::Plugin::link::linkify(@_); + } + + my $redir = check_redirect(%params); + return $redir if defined $redir; + + # this code was copied from MediawikiFormat.pm. + # Heavily changed because MF.pm screws up escaping when it does + # this awful hack: $uricCheat =~ tr/://d; + my $schemas = [qw(http https ftp mailto gopher)]; + my $re = join "|", map {qr/\Q$_\E/} @$schemas; + my $schemes = qr/(?:$re)/; + # And this is copied from URI: + my $reserved = q(;/?@&=+$,); # NOTE: no colon or [] ! + my $uric = quotemeta($reserved) . $URI::unreserved . "%#"; + + my $result = skip_nowiki($content, sub { + $_ = shift; + + # Escape any anchors + #s/<(a[\s>\/])/<$1/ig; + # Disabled because this appears to screw up the aggregate plugin. + # I guess we'll rely on Iki to post-sanitize this sort of stuff. + + # Replace external links, http://blah or [http://blah] + s{\b($schemes:[$uric][:$uric]+)|\[($schemes:[$uric][:$uric]+)([^\]]*?)\]}{ + generate_external_link($1||$2, $3, \$counter) + }eg; + + # Handle links that only contain fragments. + s{ \[\[ \s* (\#[^|\]'"<>&;]+) (?:\| ([^\]'"<>&;]*))? \]\] }{ + generate_fragment_link($1, $2) + }xeg; + + # Match all internal links + s{$link_regexp}{ + generate_internal_link($page, $1, $2, $3, $4, sub { + my($linkpage, $linktext, $anchor) = @_; + return htmllink($page, $destpage, $linkpage, + linktext => $linktext, + anchor => underscorize(scrunch($anchor))); + }); + }eg; + + return $_; + }); + + return $result; + } + + + # Find all WikiLinks in the page. + sub scan (@) + { + my %params = @_; + my $page=$params{page}; + my $content=$params{content}; + + my $file=$pagesources{$page}; + my $type=pagetype($file); + + if($type ne 'mediawiki') { + return IkiWiki::Plugin::link::scan(@_); + } + + skip_nowiki($content, sub { + $_ = shift; + while(/$link_regexp/g) { + generate_internal_link($page, $1, '', '', '', sub { + my($linkpage, $linktext, $anchor) = @_; + push @{$links{$page}}, $linkpage; + return undef; + }); + } + return ''; + }); + } + + + # Convert the page to HTML. + sub htmlize (@) + { + my %params=@_; + my $page = $params{page}; + my $content = $params{content}; + + + return $content if $markup_disabled; + + # Do a little preprocessing to babysit Text::MediawikiFormat + # If a line begins with tabs, T:MwF won't convert it into preformatted blocks. + $content =~ s/^\t/ /mg; + + my $ret = Text::MediawikiFormat::format($content, { + + allowed_tags => [#HTML + # MediawikiFormat default + qw(b big blockquote br caption center cite code dd + div dl dt em font h1 h2 h3 h4 h5 h6 hr i li ol p + pre rb rp rt ruby s samp small strike strong sub + sup table td th tr tt u ul var), + # Mediawiki Specific + qw(nowiki), + # Our additions + qw(del ins), # These should have been added all along. + qw(span), # Mediawiki allows span but that's rather scary...? + qw(a), # this is unfortunate; should handle links after rendering the page. + ], + + allowed_attrs => [ + qw(title align lang dir width height bgcolor), + qw(clear), # BR + qw(noshade), # HR + qw(cite), # BLOCKQUOTE, Q + qw(size face color), # FONT + # For various lists, mostly deprecated but safe + qw(type start value compact), + # Tables + qw(summary width border frame rules cellspacing + cellpadding valign char charoff colgroup col + span abbr axis headers scope rowspan colspan), + qw(id class name style), # For CSS + # Our additions + qw(href), + ], + + }, { + extended => 0, + absolute_links => 0, + implicit_links => 0 + }); + + return $ret; + } + + + # This is only needed to support the check_redirect call. + sub pagetemplate (@) + { + my %params = @_; + my $page = $params{page}; + my $destpage = $params{destpage}; + my $template = $params{template}; + + # handle metaheaders for redirects + if (exists $metaheaders{$page} && $template->query(name => "meta")) { + # avoid duplicate meta lines + my %seen; + $template->param(meta => join("\n", grep { (! $seen{$_}) && ($seen{$_}=1) } @{$metaheaders{$page}})); + } + + $template->param(tags => [ + map { + link => htmllink($page, $destpage, tagpage($_), rel => "tag") + }, sort keys %{$tags{$page}} + ]) if exists $tags{$page} && %{$tags{$page}} && $template->query(name => "tags"); + + # It's an rss/atom template. Add any categories. + if ($template->query(name => "categories")) { + if (exists $tags{$page} && %{$tags{$page}}) { + $template->param(categories => [map { category => $_ }, + sort keys %{$tags{$page}}]); + } + } + } + + 1 diff --git a/doc/tips/dot_cgi.mdwn b/doc/tips/dot_cgi.mdwn new file mode 100644 index 000000000..04d7a9721 --- /dev/null +++ b/doc/tips/dot_cgi.mdwn @@ -0,0 +1,57 @@ +It's common to name the [[cgi]] "ikiwiki.cgi", and put it somewhere +like `~/public_html/ikiwiki.cgi`, or `/var/www/wiki/ikiwiki.cgi`. + +If you do that, you may find that when trying to edit a page in your wiki, +you see the raw contents of the ikiwiki.cgi program. Or get a permission +denied problem. + +This is because web servers are generally not configured to run cgi scripts +unless they're in `/usr/lib/cgi-bin/`. While you can put ikiwiki.cgi in +there if you like, it's better to configure your web server to +run `.cgi` programs from anywhere. + +These instructions are for Debian systems, but the basic +configuration changes should work anywhere. + +## apache 2 + +* Edit /etc/apache2/apache2.conf and add a line like this: + + AddHandler cgi-script .cgi + +* Find the "Options" line for the directory where you've put the + ikiwiki.cgi, and add "ExecCGI" to the list of options. For example, if + ikiwiki.cgi is in /var/www/, edit `/etc/apache2/sites-enabled/000-default` + and add it to the "Options" line in the "Directory /var/www/" stanza. + Or, if you've put it in a `~/public_html`, edit + `/etc/apache2/mods-available/userdir.conf`. + +* You may also want to enable the [[plugins/404]] plugin. + To make apache use it, the apache config file will need a further + modification to make it use ikiwiki's CGI as the apache 404 handler. + Something like this, with the path adjusted to where you've put the CGI: + + ErrorDocument 404 /cgi-bin/ikiwiki.cgi + +## lighttpd + +Here is how to enable cgi on [lighttpd](http://www.lighttpd.net/) and +configure it in order to execute ikiwiki.cgi wherever it is located. + +* Activate cgi by linking `/etc/lighttpd/conf-available/10-cgi.conf` into `/etc/lighttpd/conf-enabled` ([doc](http://trac.lighttpd.net/trac/wiki/Docs%3AModCGI)). + +* Create `/etc/lighttpd/conf-available/90-ikiwiki-cgi.conf` and add a line like this: + + cgi.assign = ( "ikiwiki.cgi" => "", ) + +* Activate ikiwiki-cgi by linking `/etc/lighttpd/conf-available/90-ikiwiki-cgi.conf` into `/etc/lighttpd/conf-enabled`. + +* Restart lighttpd server with something like `/etc/init.d/lighttpd restart`. + +Note that the first part enables cgi server wide but depending on default +configuration, it may be not enough. The second part creates a specific +rule that allow `ikiwiki.cgi` to be executed. + +**Warning:** I only use this on my development server (offline). I am not +sure of how secure this approach is. If you have any thought about it, feel +free to let me know. diff --git a/doc/tips/emacs_syntax_highlighting.mdwn b/doc/tips/emacs_syntax_highlighting.mdwn new file mode 100644 index 000000000..941cf5415 --- /dev/null +++ b/doc/tips/emacs_syntax_highlighting.mdwn @@ -0,0 +1,3 @@ +A [markdown mode](http://jblevins.org/projects/markdown-mode/) for +emacs can help in editing of ikiwiki +[[ikiwiki/markdown]] files. diff --git a/doc/tips/embedding_content.mdwn b/doc/tips/embedding_content.mdwn new file mode 100644 index 000000000..142acd16e --- /dev/null +++ b/doc/tips/embedding_content.mdwn @@ -0,0 +1,35 @@ +Content from sites such as YouTube can be embedded into a web page. Maybe +you want to do this. But you'll find that the [[plugins/htmlscrubber]] +doesn't let you. It blocks the tags used to embed such content, because +they can be abused in many evil ways. + +Some plugins have been written to try to work around this problem, by +whitelisting the html needed to embed things from a few sites like Google +maps, calendar, videos, and YouTube. The problem with these plugins is that +they have to be kept up to date to add new sites, and follow changes to the +html such sites use for embedding. + +(Digression: The real problem with the plugins is that they hide the +underlying trust relationship. If you decide to embed html from a site, +you'd better trust that site. And if ikiwiki lets you enter such html, it +needs to trust you.) + +The [[plugins/htmlscrubber]] offers a different way around this problem. +You can configure it to skip scrubbing certian pages, so that content from +elsewhere can be embedded on those pages. Then use [[plugins/lockedit]] +to limit who can edit those unscrubbed pages. + +For example, suppose your blog is all under `blog/*`, and you want +only yourself to be able to post there, and you'd like to be able to embed +youtube videos etc in your blog. Other users can edit some pages in the +wiki (Discussion pages, say), but not your blog posts. Then you could configure +ikiwiki as follows: + + htmlscrubber_skip => 'blog/* and !*/Discussion', + locked_pages => '!*/Discussion', + +More simply, you might want to allow yourself to embed content anywhere +on the wiki, but scrub content written on Discussion pages: + + htmlscrubber_skip => '!*/Discussion', + locked_pages => '!*/Discussion', diff --git a/doc/tips/github.mdwn b/doc/tips/github.mdwn new file mode 100644 index 000000000..c3fdab734 --- /dev/null +++ b/doc/tips/github.mdwn @@ -0,0 +1,64 @@ +Here's how to set up a static wiki or blog using ikiwiki with no hosting +fees. Everything is hosted on github, both the git repository and the web +site. Your laptop is used to generate and publish changes to it. + +This is possible because github now supports +[github pages](http://github.com/blog/272-github-pages). + +Note that github limits free accounts to 100 mb of git storage. It's +unlikely that a small wiki or blog will outgrow this, but we are keeping +two copies of the website in git (source and the compiled site), and all +historical versions too. So it could happen. If it does, you can pay github +for more space, or you can migrate your site elsewhere. + +## Github Setup + +* Go to [github](http://github.com/) and sign up for an account, if you haven't already. +* Be sure to add your laptop's ssh key to it so you can push to github. +* Create a repository on github named `$YOU.github.com`, substituting your + *username*. This repository will be used to publish your compiled website. +* Create a repository on github named `$YOU` (or anything else you like). + This repository will be used to publish the source of your website. + This is actually optional. + +## Local Setup + +* On your laptop, create two empty git repositories to correspond to the github repositories: <br /> + `YOU = your github username here` <br /> + `mkdir ~/$YOU.github.com` <br /> + `cd ~/$YOU.github.com` <br /> + `git init` <br /> + `git remote add origin git@github.com:$YOU/$YOU.github.com.git` <br /> + `mkdir ~/$YOU` <br /> + `cd ~/$YOU` <br /> + `git init` <br /> + `git remote add origin git@github.com:$YOU/$YOU.git` <br /> +* Add some wiki pages, such as an `index.mdwn`, to `~/$YOU`, and check them + in and commit them to git. You need something to push to github. Run + `git push origin master` to push the source pages to github. + +## Publishing to Github + +* Now build your wiki with a command such as: <br /> + `ikiwiki ~/$YOU ~/$YOU.github.com --refresh` +* Each time you build the wiki you will need to commit the changes + to git, and push the compiled pages to github: <br /> + `cd ~/YOU.github.com` <br /> + `git add .` <br /> + `git commit -a -m update` <br /> + `git push origin master` <br /> + +Your wiki will show up at `http://$YOU.github.com/` within ten +minutes after the first push, and changes you push to it from then on +should show up immediately. + +## Enhancements + +You can follow the instructions in [[laptop_wiki_with_git]] to set up an +editable version of your wiki on your laptop. Then you can use the web +interface for editing. You'll still need to follow the instructions above +to publish your changes to github. + +It would also be possible to teach ikiwiki to push compiled pages to github +itself via a plugin, as was done with the [[plugins/amazon_s3]] plugin. Not +done yet! diff --git a/doc/tips/howto_avoid_flooding_aggregators.mdwn b/doc/tips/howto_avoid_flooding_aggregators.mdwn index 98cef9249..e45b96689 100644 --- a/doc/tips/howto_avoid_flooding_aggregators.mdwn +++ b/doc/tips/howto_avoid_flooding_aggregators.mdwn @@ -1,27 +1,27 @@ If you have a [[blog]] that is aggregated, either on a site like Planet Debian, or just through user subscriptions, one common problem is that -changes to the guids of items in the blog can "flood" the aggregator, +changes to the guids of items in the blog can “flood” the aggregator, causing all recent blog entries to be posted to the top of it. This can happen in a lot of situations: -* Perhaps you've just switched to ikiwiki from some other blog engine and +* Perhaps you’ve just switched to ikiwiki from some other blog engine and imported your data. -* Perhaps you've turned on the `usedirs` setting, which changes all the +* Perhaps you’ve turned on the `usedirs` setting, which changes all the urls in your wiki. Even if you set up [[redirections|redirections_for_usedirs]] for the old urls, you still face the issue of flooding aggregators. -* Perhaps you've just moved stuff around in your wiki. +* Perhaps you’ve just moved stuff around in your wiki. -To avoid annoying readers in these situations, it's a good idea to remove -any existing items from your blog's news feed. That way only new items will +To avoid annoying readers in these situations, it’s a good idea to remove +any existing items from your blog’s news feed. That way only new items will show up in the aggregator. The best way to do this is to add a `feedpages` parameter to the `inline` directive for your blog, with a condition such as: feedpages=created_after(blog/posts/old_post) -Where "old_post" is the name of the last post you made to the blog before -making the change. This will limit the feed to only newer posts, while stil +Where “old_post” is the name of the last post you made to the blog before +making the change. This will limit the feed to only newer posts, while still displaying the old posts in the blog page. Alternatively, you can add the [[plugins/meta]] guid directives to pages, diff --git a/doc/tips/inside_dot_ikiwiki.mdwn b/doc/tips/inside_dot_ikiwiki.mdwn index b649636dc..b81ffae8d 100644 --- a/doc/tips/inside_dot_ikiwiki.mdwn +++ b/doc/tips/inside_dot_ikiwiki.mdwn @@ -63,3 +63,28 @@ To remove that user: I've not written actual utilities to do this yet because I've only needed to do it rarely, and the data I've wanted has been different each time. --[[Joey]] + +## the session database + +`.ikiwiki/sessions.db` is the session database. See the [[!cpan CGI::Session]] +documentation for more details. + +## lockfiles + +In case you're curious, here's what the various lock files do. + +* `.ikiwiki/lockfile` is the master ikiwiki lock file. Ikiwiki takes this + lock before reading/writing state. +* `.ikiwiki/commitlock` is locked as a semophore, to disable the commit hook + from doing anything. +* `.ikiwiki/cgilock` is locked by the cgi wrapper, to ensure that only + one ikiwiki process is run at a time to handle cgi requests. + +## plugin state files + +Some plugins create other files to store their state. + +* `.ikiwiki/aggregate` is a plain text database used by the aggregate plugin + to record feeds and known posts. +* `.ikiwiki/xapian/` is created by the search plugin, and contains xapian-omega + configuration and the xapian database. diff --git a/doc/tips/inside_dot_ikiwiki/discussion.mdwn b/doc/tips/inside_dot_ikiwiki/discussion.mdwn index c05e7a3e0..34d5b9252 100644 --- a/doc/tips/inside_dot_ikiwiki/discussion.mdwn +++ b/doc/tips/inside_dot_ikiwiki/discussion.mdwn @@ -16,3 +16,50 @@ No idea how this happened. I've blown it away and recreated it but, for future >>> --getctime does. --[[Joey]] >> Alas, I seem to have lost the bad index file to periodic /tmp wiping; I'll send it to you if it happens again. --[[sabr]] + +<!-- Add by Blanko --> + +## Lost password for an user + +This morning, a person has lost its password. I was able to do something to make another password. This is the way I take : + +> You can certianly do that, but do note that ikiwiki will offer to mail a +> user a password reset link if they lost their password. --[[Joey]] + +### Locate the user database + +As tips show us, the user database is in the source file, for an example : + + src/.ikiwiki/userdb + +### See which user to modify + +Because I don't know the real login of the user, I have to read all the database : + + perl -le 'use Storable; my $index=Storable::retrieve("userdb"); use Data::Dumper; print Dumper $index' + +Then I was able to find this : + + 'Utilisateur' => { + 'email' => 'user@pl.fr', + 'cryptresettoken' => '$2a$10$cfVeOoVbFw9VzMlgEbPMsu34pwHIFP84mWlkrs2RCKknZYPZkPffm', + 'password' => '', + 'resettoken' => '', + 'cryptpassword' => '$2a$10$H8bYq.dlb68wpnfJgVZQhOdsF9JQ06cteRfhPQPB5eHKnD5Y3u7au', + 'regdate' => '1226574052' + }, + +Let's have a look to modify lines. + +### Modify the line + +When you have found the line to modify, take the user name, and change its password to **sc** (for an example) : + + perl -le 'use Storable; my $userinfo=Storable::retrieve("userdb"); $userinfo->{"Utilisateur"}->{cryptpassword}=q{$2a$10$7viOHCrUkdAVL135Kr6one1mpZQ/FWYC773G1yZ0EtQciI11sSDRS}; Storable::lock_nstore($userinfo, "userdb")' + perl -le 'use Storable; my $userinfo=Storable::retrieve("userdb"); $userinfo->{"Utilisateur"}->{cryptresettoken}=q{}; Storable::lock_nstore($userinfo, "userdb")' + +Because I don't know how suppress cryptresettoken and resettoken fields, I change their content with *null*. + +After all these modifications, the user *Utilisateur* could connect to its account with the password **sc**, and go to Preferences, then change its password. + +<!-- End of Blanko's modifications --> diff --git a/doc/tips/laptop_wiki_with_git.mdwn b/doc/tips/laptop_wiki_with_git.mdwn index 998ac7443..9758beb80 100644 --- a/doc/tips/laptop_wiki_with_git.mdwn +++ b/doc/tips/laptop_wiki_with_git.mdwn @@ -15,7 +15,7 @@ for setting up ikiwiki with git. Next, `git clone` the source (`$REPOSITORY`, not `$SRCDIR`) from the server to the laptop. -Now, set up a [[web_server|apache_cgi]] on your laptop, if it doesn't +Now, set up a [[web_server|dot_cgi]] on your laptop, if it doesn't already have one. Now you need to write a setup file for ikiwiki on the laptop. Mostly this diff --git a/doc/tips/laptop_wiki_with_git/discussion.mdwn b/doc/tips/laptop_wiki_with_git/discussion.mdwn index 234833ca7..6ce72ae7b 100644 --- a/doc/tips/laptop_wiki_with_git/discussion.mdwn +++ b/doc/tips/laptop_wiki_with_git/discussion.mdwn @@ -5,3 +5,8 @@ Or, was this last remark about rebuilding after pulling meant to apply to rebuil [[DavidBremner]] * *Updated* Now that I play with this a bit, this seems not so important. Having a seperate sync operation that I run from the laptop is no big deal, and lets me update the parts of my site not yet managed by ikiwiki at the same time. + +* Ok, I have finally finished to set this up. I have a question for you :) Is it mandatory to have a locally running webserver on the laptop ? I mean, do I need to setup the CGI wrapper on the laptop ? Is it possible to just add/edit/delete/whatever, git commit all the stuff and git push back to the server ? Thank you. --[[xma]] + +> Of course you don't need a web server on the laptop. It is useful for +> previewing pages before publishing them though. --[[Joey]] diff --git a/doc/tips/lighttpd_cgi.mdwn b/doc/tips/lighttpd_cgi.mdwn deleted file mode 100644 index 5504b0658..000000000 --- a/doc/tips/lighttpd_cgi.mdwn +++ /dev/null @@ -1,15 +0,0 @@ -Here is how to enable cgi on [lighttpd](http://www.lighttpd.net/) and configure it in order to execute ikiwiki.cgi wherever it is located. - -* Activate cgi by linking `/etc/lighttpd/conf-available/10-cgi.conf` into `/etc/lighttpd/conf-enabled` ([doc](http://trac.lighttpd.net/trac/wiki/Docs%3AModCGI)). - -* Create `/etc/lighttpd/conf-available/90-ikiwiki-cgi.conf` and add a line like this: - - cgi.assign = ( "ikiwiki.cgi" => "", ) - -* Activate ikiwiki-cgi by linking `/etc/lighttpd/conf-available/90-ikiwiki-cgi.conf` into `/etc/lighttpd/conf-enabled`. - -* Restart lighttpd server with something like `/etc/init.d/lighttpd restart`. - -Note that the first part enables cgi server wide but depending on default configuration, it may be not enough. The second part creates a specific rule that allow `ikiwiki.cgi` to be executed. - -**Warning:** I only use this on my development server (offline). I am not sure of how secure this approach is. If you have any thought about it, feel free to let me know. diff --git a/doc/tips/markdown_and_eclipse.mdwn b/doc/tips/markdown_and_eclipse.mdwn new file mode 100644 index 000000000..9e8e9bfa9 --- /dev/null +++ b/doc/tips/markdown_and_eclipse.mdwn @@ -0,0 +1,4 @@ +For people that were not born with GNU emacs fingers, +there is a markdown editor (with preview and outline) +for [eclipse](http://www.eclipse.org) available +[here](http://www.winterwell.com/software/markdown-editor.php). diff --git a/doc/tips/nearlyfreespeech.mdwn b/doc/tips/nearlyfreespeech.mdwn index 6715f0c29..4b3b02eac 100644 --- a/doc/tips/nearlyfreespeech.mdwn +++ b/doc/tips/nearlyfreespeech.mdwn @@ -81,7 +81,8 @@ Here is an example of how I set up a wiki: nano ikiwiki.setup # Set destdir to /home/htdocs # Set srcdir to /home/private/wiki - # Set url to http://yoursite.nfshost.com/ , set cgiurl likewise + # Set url to http://yoursite.nfshost.com/ + # Set cgiurl to http://yoursite.nfshost.com/ikiwiki.cgi # Uncomment the `rcs => "git"` line. # Set the cgi_wrapper path to /home/htdocs/ikiwiki.cgi # Set the git_wrapper path to /home/private/wiki.git/hooks/post-update diff --git a/doc/tips/untrusted_git_push.mdwn b/doc/tips/untrusted_git_push.mdwn new file mode 100644 index 000000000..aef67a3db --- /dev/null +++ b/doc/tips/untrusted_git_push.mdwn @@ -0,0 +1,122 @@ +This tip will describe how to allow anyone on the planet to `git push` +changes into your wiki, without needing a special account. All a user needs +to know is: + + git clone git://your.wiki/path + # now modify any of the files the wiki would let you modify on the web + git push + +This is a wonderful thing to set up for users, because then they can work +on the wiki while offline, and they don't need to mess around with web +browsers. + +## security + +But, you might be wondering, how can this possibly be secure. Won't users +upload all sorts of garbage, change pages you don't want them to edit, and so +on. + +The key to making it secure is configuring ikiwiki to run as your git +repository's `pre-receive` hook. There it will examine every change that +untrusted users push into the wiki, and reject pushes that contain changes +that cannot be made using the web interface. + +So, unless you have the [[plugins/attachment]] plugin turned on, +non-page files cannot be added. And if it's turned on, whatever +`allowed_attachments` checks you have configured will also check files +pushed into git. + +And, unless you have the [[plugins/remove]] plugin turned on, no +files can be deleted. + +And if you have `locked_pages` configured, then it will also affect what's +pushed into git. + +Untrusted committers will also not be able to upload files with strange +modes, or push to any branch except for the configured `gitorigin_branch`, +or manipulate tags. + +One thing to keep an eye on is uploading large files. It may be easier to +do this via git push than using the web, and that could be abused. + +Also, no checking is done that the authors of commits are right, so people +can make a commit that pretends to be done by someone else. + +## user setup + +Add a dedicated user who will push in untrusted commits. This user should have +a locked password, and `git-shell` as its shell. + + root@bluebird:/home/joey>adduser --shell=/usr/bin/git-shell --disabled-password anon + Adding user `anon' ... + +## ikiwiki setup + +You should set up ikiwiki before turning on anonymous push in git. + +Edit your wiki's setup file, and uncomment the lines for +`git_test_receive_wrapper` and `untrusted_committers`. + + # git pre-receive hook to generate + git_test_receive_wrapper => '/srv/git/ikiwiki.info/.git/hooks/pre-receive', + # unix users whose commits should be checked by the pre-receive hook + untrusted_committers => ['anon'], + +The `git_test_receive_wrapper` will become the git `pre-receive` hook. The +`untrusted_committers` list is the list of unix users who will be pushing in +untrusted changes. It should *not* include the user that ikiwiki normally runs +as. + +Once you're done modifying the setup file, don't forget to run +`ikiwiki -setup --refresh --wrappers` on it. + +## git setup + +You'll need to arrange the permissions on your bare git repository so that +user anon can write to it. One way to do it is to create a group, and put +both anon and your regular user in that group. Then make make the bare git +repository owned and writable by the group. See [[rcs/git]] for some more +tips on setting up a git repository with multiple committers. + +Note that anon should *not* be able to write to the `srcdir`, *only* to the bare git +repository for your wiki. + +If you want to allow git over `ssh`, generate a ssh key for anon, and +publish the *private* key for other people to use. This is optional; you +can use `git-daemon` instead and not worry about keys. + +Now set up `git-daemon`. It will need to run as user `anon`, and be +configured to export your wiki's bare git repository. I set it up as +follows in `/etc/inetd.conf`, and ran `/etc/init.d/openbsd-inetd restart`. + + git stream tcp nowait anon /usr/bin/git-daemon git-daemon --inetd --export-all --interpolated-path=/srv/git/%H%D /srv/git + +At this point you should be able to `git clone git://your.wiki/path` from +anywhere, and check out the source to your wiki. But you won't be able to +push to it yet, one more change is needed to turn that on. Edit the +`config` file of your bare git repository, and allow `git-daemon` to +receive pushes: + + [daemon] + receivepack = true + +Now pushes should be accepted, and your wiki immediatly be updated. If it +doesn't, check your git repo's permissions, and make sure that the +`post-update` and `pre-receive` hooks are suid so they run as the user who +owns the `srcdir`. + +## infelicities + +If a user tries to push a changeset that ikiwiki doesn't like, it will +abort the push before refs are updated. However, the changeset will still +be present in your repository, wasting space. Since nothing refers to it, +it will be expired eventually. You can speed up the expiry by running `git +prune`. + +When aborting a push, ikiwiki displays an error message about why it didn't +accept it. If using git over ssh, the user will see this error message, +which is probably useful to them. But `git-daemon` is buggy, and hides this +message from the user. This can make it hard for users to figure out why +their push was rejected. (If this happens to you, look at "'git log --stat +origin/master..`" and think about whether your changes would be accepted +over the web interface.) diff --git a/doc/tips/untrusted_git_push/discussion.mdwn b/doc/tips/untrusted_git_push/discussion.mdwn new file mode 100644 index 000000000..d95c01ecf --- /dev/null +++ b/doc/tips/untrusted_git_push/discussion.mdwn @@ -0,0 +1,33 @@ +I've just tried this (commit c1fa07a). Recent changes shows: + +<div id="change-c1fa07ad4f165b42c962ba2a310681107f38c4f7" class="metadata"> +<span class="desc"><br />Changed pages:</span> +<span class="pagelinks"> + +<a href="http://git.ikiwiki.info/?p=ikiwiki;a=blobdiff;h=8bfa3dd7601a09b11ecbd20026849a777dc4b1b9;hp=c6302616f52ec058de5a8f5956fc512149a2f1a3;hb=1ea66c3d3f0a33bc3f04d073457b525a70380c37;f=doc/users/jondowland.mdwn"><img src="/wikiicons/diff.png" alt="diff" /></a><a href="http://ikiwiki.info/ikiwiki.cgi?page=users%2Fjondowland&do=recentchanges_link">users/jondowland</a> + + +</span> +<span class="desc"><br />Changed by:</span> +<span class="committer"> + +<a href="http://ikiwiki.info/ikiwiki.cgi?page=users%2Fjon&do=recentchanges_link">jon</a> + +</span> +<span class="desc"><br />Commit type:</span> +<span class="committype">git</span> +<span class="desc"><br />Date:</span> +<span class="changedate"><span class="relativedate" title="Mon, 10 Nov 2008 18:24:22 -0500">18:24:22 11/10/08</span> +</div> + +Note that the user for the commit is 'jon', and the link points at cgi to +create users/jon. I was wondering if that is configurable for users pushing +via git. It would be nice perhaps to specify it in some way, perhaps via a +git-config setting (user.name?). I'm not too familiar with exactly what the +changeset contains. -- [[users/Jon]] + +> All ikiwiki can do it look at who git has recorded as the author of +> the change (and it looks at the username part of the email address). +> You can set `user.email` in `.git/config`. --[[Joey]] + +> > Ah, excellent. In which case this *should* DTRT... -- [[users/Jon]] diff --git a/doc/tips/upgrade_to_3.0.mdwn b/doc/tips/upgrade_to_3.0.mdwn new file mode 100644 index 000000000..d22813bf2 --- /dev/null +++ b/doc/tips/upgrade_to_3.0.mdwn @@ -0,0 +1,95 @@ +Version 3.0 of ikiwiki makes some significant changes, which +you will need to deal with when upgrading from ikiwiki 2.x. + +[[!toc ]] + +## setup file format change + +The layout of the setup file changed in a significant way in version 2.60 +of ikiwiki. If you have not changed yours to the new format, now would be a +good time to do so. Some new features, like the [[plugins/websetup]] +interface, need the new format setup file. + +You can convert old setup files into the new format by running +`ikiwiki-transition setupformat your.setup` + +## moving settings from Preferences page + +The admin preferences page used to have settings for allowed attachments, +locked pages, and banned users. These three settings have moved to the +setup file, and will no longer appear on the admin preferences page once +your wiki is upgraded to 3.0. + +You can move these preferences into the setup file by running +`ikiwiki-transition moveprefs your.setup; ikiwiki -setup your.setup -refresh -wrappers` + +(Make sure you have converted the setup file to the new format first.) + +## prefix directives + +In 3.0, the syntax ikiwiki uses for [[directives|ikiwiki/directive]] has +changed, requiring that the directive start with a bang: + + \[[!directive ...]] + +If you would like to keep the old syntax, it is still supported, add the +following to your setup file: + + prefix_directives => 0, + +To convert to the new syntax, make sure that your setup file does *not* +contain the above, then run `ikiwiki-transition prefix_directives your.setup` + +(And then commit the changes it makes to pages in your srcdir.) + +## GlobLists + +In 3.0, the old "GlobList" syntax for [[PageSpecs|ikiwiki/PageSpec]] is no +longer supported. A GlobList contains multiple term, but does not separate +them with "and" or "or": + + sandbox !*/Discussion + +To convert this to a modern PageSpec, simply add "and" or "or" as +appropriate between terms: + + sandbox and !*/Discussion + +GlobLists have been deprecated for more than two years. If your wiki dates +to the ikiwiki 1.0 era, you should check it for any that might have lurked +unnoticed in it since back then. Ikiwiki version 2.72 will print warnings +about any GlobLists it sees. + +## aggregateinternal + +If your wiki uses the [[aggregate|plugins/aggregate]] plugin, it will start +to aggregate feeds to special "internal" pages. + +If you don't want this change, you can add the following to your setup +file: + + aggregateinternal => 0, + +Otherwise, follow this procedure to upgrade a wiki using the aggregate plugin: + +1. Update all [[PageSpecs|ikiwiki/PageSpec]] that refer to the aggregated + pages -- such as those in inlines. Put "internal()" around globs + in those PageSpecs. For example, if the PageSpec was `foo/*`, it should + be changed to `internal(foo/*)`. This has to be done because internal + pages are not matched by regular globs. +2. Use [[ikiwiki-transition]] to rename all existing aggregated `.html` + files in the srcdir. The command to run is + `ikiwiki-transition aggregateinternal your.setup`, +3. Refresh the wiki. (`ikiwiki -setup your.setup -refresh`) + +## embed / googlecalendar + +The googlecalendar plugin has been deprecated for a long time, and is +removed in 3.0. + +The embed plugin is also now deprecated, though not yet removed. + +If you use either plugin to embed content from google, youtube, etc, +into your wiki, you should instead configure the [[plugins/htmlscrubber]] +to skip sanitising some pages, via the `htmlscrubber_skip` setting. +See [[embedding_content]] for examples. diff --git a/doc/tips/using_the_web_interface_with_a_real_text_editor.mdwn b/doc/tips/using_the_web_interface_with_a_real_text_editor.mdwn index d696bacdb..cf9327395 100644 --- a/doc/tips/using_the_web_interface_with_a_real_text_editor.mdwn +++ b/doc/tips/using_the_web_interface_with_a_real_text_editor.mdwn @@ -4,3 +4,10 @@ you to use a real text editor like Emacs or Vim to edit the contents of text areas. This allows you to edit ikiwiki pages with a real text editor through the ikiwiki web interface, rather than only with direct commit access. --[[JoshTriplett]] + +For Firefox or Iceweasel users, the vimperator extension is also a good +idea. You can press Ctrl-I in the insert mode of vimperator and switch to +an external editor, e.g. Vim. --[[WeakishJiang]] + +Finally, with wikis configured to allow, [[untrusted_git_push]], you can +ditch the browser altogether. --[[Joey]] diff --git a/doc/tips/vim_syntax_highlighting.mdwn b/doc/tips/vim_syntax_highlighting.mdwn index 453efa8d1..172b763c3 100644 --- a/doc/tips/vim_syntax_highlighting.mdwn +++ b/doc/tips/vim_syntax_highlighting.mdwn @@ -1,2 +1,4 @@ -[[ikiwiki.vim]] is a vim syntax highlighting file for ikiwiki. Installation -instructions are at the top of the file. +[[ikiwiki.vim]] is a vim syntax highlighting file for ikiwiki +[[ikiwiki/markdown]] files. + +Installation instructions are at the top of the file. diff --git a/doc/tips/vim_syntax_highlighting/discussion.mdwn b/doc/tips/vim_syntax_highlighting/discussion.mdwn index b1637e758..72cb52aab 100644 --- a/doc/tips/vim_syntax_highlighting/discussion.mdwn +++ b/doc/tips/vim_syntax_highlighting/discussion.mdwn @@ -1 +1,8 @@ -I'm going to look at merging this with potwiki.vim (a vim-based personal wiki) so that you can follow wiki-links and auto-create pages etc., direct from vim. (I'm writing this incase I don't get around to it) -- [[JonDowland]] +I'm going to look at merging this with potwiki.vim (a vim-based personal wiki) so that you can follow wiki-links and auto-create pages etc., direct from vim. (I'm writing this incase I don't get around to it) -- [[users/Jon]] + +---- + +Another attempt at the same thing is here: +<http://plasticboy.com/markdown-vim-mode/> + +In my tests, [[ikiwiki.vim]] works better than that one, YMMV. --[[Joey]] diff --git a/doc/tips/vim_syntax_highlighting/ikiwiki.vim b/doc/tips/vim_syntax_highlighting/ikiwiki.vim index fd87f49a2..bbcad4239 100644 --- a/doc/tips/vim_syntax_highlighting/ikiwiki.vim +++ b/doc/tips/vim_syntax_highlighting/ikiwiki.vim @@ -1,6 +1,6 @@ " Vim syntax file " Language: Ikiwiki (links) -" Maintainer: Recai Okta (roktasATdebian.org) +" Maintainer: Recai Oktaş (roktasATdebian.org) " Last Change: 2007 May 29 " Instructions: |