diff options
Diffstat (limited to 'ikiwiki')
| -rw-r--r-- | ikiwiki/directive.mdwn | 43 | ||||
| -rw-r--r-- | ikiwiki/formatting.mdwn | 106 | ||||
| -rw-r--r-- | ikiwiki/markdown.mdwn | 11 | ||||
| -rw-r--r-- | ikiwiki/openid.mdwn | 28 | ||||
| -rw-r--r-- | ikiwiki/pagespec.mdwn | 84 | ||||
| -rw-r--r-- | ikiwiki/pagespec/attachment.mdwn | 38 | ||||
| -rw-r--r-- | ikiwiki/pagespec/po.mdwn | 23 | ||||
| -rw-r--r-- | ikiwiki/pagespec/sorting.mdwn | 26 | ||||
| -rw-r--r-- | ikiwiki/searching.mdwn | 20 | ||||
| -rw-r--r-- | ikiwiki/subpage.mdwn | 12 | ||||
| -rw-r--r-- | ikiwiki/subpage/linkingrules.mdwn | 33 | ||||
| -rw-r--r-- | ikiwiki/wikilink.mdwn | 29 |
12 files changed, 453 insertions, 0 deletions
diff --git a/ikiwiki/directive.mdwn b/ikiwiki/directive.mdwn new file mode 100644 index 0000000..fb88aa7 --- /dev/null +++ b/ikiwiki/directive.mdwn @@ -0,0 +1,43 @@ +[[!meta robots="noindex, follow"]] +Directives are similar to a [[ikiwiki/WikiLink]] in form, except they +begin with `!` and may contain parameters. The general form is: + + \[[!directive param="value" param="value"]] + +This gets expanded before the rest of the page is processed, and can be used +to transform the page in various ways. + +The quotes around values can be omitted if the value is a simple word. +Also, some directives may use parameters without values, for example: + + \[[!tag foo]] + +A directive does not need to all be on one line, it can be +wrapped to multiple lines if you like: + + \[[!directive foo="baldersnatch" + bar="supercalifragilisticexpialidocious" baz=11]] + +Also, multiple lines of *quoted* text can be used for a value. +To allow quote marks inside the quoted text, delimit the block +of text with triple-quotes: + + \[[!directive text=""" + 1. "foo" + 2. "bar" + 3. "baz" + """]] + +ikiwiki also has an older syntax for directives, which requires a space in +directives to distinguish them from [[wikilinks|ikiwiki/wikilink]]. This +syntax has several disadvantages: it requires a space after directives with +no parameters (such as `\[[pagecount ]]`), and it prohibits spaces in +[[wikilinks|ikiwiki/wikilink]]. ikiwiki now provides the `!`-prefixed +syntax shown above as default. However, ikiwiki still supports wikis using +the older syntax, if the `prefix_directives` option is disabled. + +[[!if test="enabled(listdirectives)" then=""" +Here is a list of currently available directives in this wiki: + +[[!listdirectives ]] +"""]] diff --git a/ikiwiki/formatting.mdwn b/ikiwiki/formatting.mdwn new file mode 100644 index 0000000..befbce9 --- /dev/null +++ b/ikiwiki/formatting.mdwn @@ -0,0 +1,106 @@ +[[!meta title="Formatting wiki pages"]] +[[!meta robots="noindex, follow"]] + +Text on this wiki is, by default, written in a form very close to how you +might write text for an email message. This style of text formatting is +called [[MarkDown]], and it works like this: + +Leave blank lines between paragraphs. + +You can *\*emphasise\** or **\*\*strongly emphasise\*\*** text by placing it +in single or double asterisks. + +To create a list, start each line with an asterisk: + +* "* this is my list" +* "* another item" + +To make a numbered list, start each line with a number (any number will +do) followed by a period: + +1. "1. first line" +2. "2. second line" +2. "2. third line" + +To create a header, start a line with one or more `#` characters followed +by a space and the header text. The number of `#` characters controls the +size of the header: + +# # h1 +## ## h2 +### ### h3 +#### #### h4 +##### ##### h5 +###### ###### h6 + +To create a horizontal rule, just write three or more dashes or stars on +their own line: + +---- + +To quote someone, prefix the quote with ">": + +> To be or not to be, +> that is the question. + +To write a code block, indent each line with a tab or 4 spaces: + + 10 PRINT "Hello, world!" + 20 GOTO 10 + +To link to an url or email address, you can just put the +url in angle brackets: <<http://ikiwiki.info>>, or you can use the +form \[link text\]\(url\) + +---- + +In addition to basic html formatting using [[MarkDown]], this wiki lets +you use the following additional features: + +* To link to another page on the wiki, place the page's name inside double + square brackets. So you would use `\[[WikiLink]]` to link to [[WikiLink]]. + +[[!if test="enabled(smiley) and smileys" then=""" +* Insert [[smileys]] and some other useful symbols. :-) +"""]] + +[[!if test="enabled(shortcut) and shortcuts" then=""" +* Use [[shortcuts]] to link to common resources. + + \[[!wikipedia War\_of\_1812]] +"""]] + +[[!if test="enabled(template) and templates" then=""" +* Create and fill out [[templates]] for repeated chunks of + parameterized wiki text. +"""]] + +* Insert various [[directives|directive]] onto a page to perform useful + actions. +[[!if test="enabled(toc) or enabled(meta) or enabled(inline)" then=""" + For example, you can: +"""]] + +[[!if test="enabled(toc)" then=""" + * Add a table of contents to a page: + + \[[!toc]] +"""]] + + +[[!if test="enabled(meta)" then=""" + * Change the title of a page: + + \[[!meta title="full page title"]] +"""]] + +[[!if test="enabled(inline)" then=""" + * Create a blog by inlining a set of pages: + + \[[!inline pages="blog/*"]] +"""]] + +[[!if test="enabled(listdirectives)" then=""" + Full list of [[directives|directive]] enabled for this wiki: + [[!listdirectives ]] +"""]] diff --git a/ikiwiki/markdown.mdwn b/ikiwiki/markdown.mdwn new file mode 100644 index 0000000..6841919 --- /dev/null +++ b/ikiwiki/markdown.mdwn @@ -0,0 +1,11 @@ +[[!meta robots="noindex, follow"]] +[Markdown](http://daringfireball.net/projects/markdown/) +is a minimal markup language that resembles plain text as used in +email messages. It is the markup language used by this wiki by default. + +For documentation about the markdown syntax, see [[formatting]] and +[Markdown: syntax](http://daringfireball.net/projects/markdown/syntax). + +Note that [[WikiLinks|WikiLink]] and [[directives|directive]] are not part +of the markdown syntax, and are the only bit of markup that this wiki +handles internally. diff --git a/ikiwiki/openid.mdwn b/ikiwiki/openid.mdwn new file mode 100644 index 0000000..2fa972e --- /dev/null +++ b/ikiwiki/openid.mdwn @@ -0,0 +1,28 @@ +[[!meta title="OpenID"]] +[[!meta robots="noindex, follow"]] + +[[!if test="enabled(openid)" + then="This wiki has OpenID **enabled**." + else="This wiki has OpenID **disabled**."]] + +[OpenID](http://openid.net) is a decentralized authentication mechanism +that allows you to have one login that you can use on a growing number of +websites. + +If you have an account with some of the larger web service providers, +you might already have an OpenID. +[Directory of OpenID providers](http://openiddirectory.com/openid-providers-c-1.html) + +[[!if test="enabled(openid)" then=""" +To sign in to this wiki using OpenID, just enter it in the OpenID field in the +signin form. You do not need to give this wiki a password or go through any +registration process when using OpenID. +"""]] + +--- + +It's also possible to make a page in the wiki usable as an OpenID url, +by delegating it to an openid server. Here's an example of how to do that: + + \[[!meta openid="http://yourid.myopenid.com/" + server="http://www.myopenid.com/server"]] diff --git a/ikiwiki/pagespec.mdwn b/ikiwiki/pagespec.mdwn new file mode 100644 index 0000000..6aec561 --- /dev/null +++ b/ikiwiki/pagespec.mdwn @@ -0,0 +1,84 @@ +[[!meta robots="noindex, follow"]] +To select a set of pages, such as pages that are locked, pages +whose commit emails you want subscribe to, or pages to combine into a +blog, the wiki uses a PageSpec. This is an expression that matches +a set of pages. + +The simplest PageSpec is a simple list of pages. For example, this matches +any of the three listed pages: + + foo or bar or baz + +More often you will want to match any pages that have a particular thing in +their name. You can do this using a glob pattern. "`*`" stands for any part +of a page name, and "`?`" for any single letter of a page name. So this +matches all pages about music, and any [[SubPage]]s of the SandBox, but does +not match the SandBox itself: + + *music* or SandBox/* + +You can also prefix an item with "`!`" to skip pages that match it. So to +match all pages except for Discussion pages and the SandBox: + + * and !SandBox and !*/Discussion + +Some more elaborate limits can be added to what matches using these functions: + +* "`glob(someglob)`" - matches pages and other files that match the given glob. + Just writing the glob by itself is actually a shorthand for this function. +* "`page(glob)`" - like `glob()`, but only matches pages, not other files +* "`link(page)`" - matches only pages that link to a given page (or glob) +* "`tagged(tag)`" - matches pages that are tagged or link to the given tag (or + tags matched by a glob) +* "`backlink(page)`" - matches only pages that a given page links to +* "`creation_month(month)`" - matches only files created on the given month +* "`creation_day(mday)`" - or day of the month +* "`creation_year(year)`" - or year +* "`created_after(page)`" - matches only files created after the given page + was created +* "`created_before(page)`" - matches only files created before the given page + was created +* "`internal(glob)`" - like `glob()`, but matches even internal-use + pages that globs do not usually match. +* "`title(glob)`", "`author(glob)`", "`authorurl(glob)`", + "`license(glob)`", "`copyright(glob)`", "`guid(glob)`" + - match pages that have the given metadata, matching the specified glob. +* "`user(username)`" - tests whether a modification is being made by a + user with the specified username. If openid is enabled, an openid can also + be put here. Glob patterns can be used in the username. For example, + to match all openid users, use `user(*://*)` +* "`admin()`" - tests whether a modification is being made by one of the + wiki admins. +* "`ip(address)`" - tests whether a modification is being made from the + specified IP address. +* "`comment(glob)`" - matches comments to a page matching the glob. +* "`comment_pending(glob)`" - matches unmoderated, pending comments. +* "`postcomment(glob)`" - matches only when comments are being + posted to a page matching the specified glob + +For example, to match all pages in a blog that link to the page about music +and were written in 2005: + + blog/* and link(music) and creation_year(2005) + +Note the use of "and" in the above example, that means that only pages that +match each of the three expressions match the whole. Use "and" when you +want to combine expression like that; "or" when it's enough for a page to +match one expression. Note that it doesn't make sense to say "index and +SandBox", since no page can match both expressions. + +More complex expressions can also be created, by using parentheses for +grouping. For example, to match pages in a blog that are tagged with either +of two tags, use: + + blog/* and (tagged(foo) or tagged(bar)) + +Note that page names in PageSpecs are matched against the absolute +filenames of the pages in the wiki, so a pagespec "foo" used on page +"a/b" will not match a page named "a/foo" or "a/b/foo". To match +relative to the directory of the page containing the pagespec, you can +use "./". For example, "./foo" on page "a/b" matches page "a/foo". + +To indicate the name of the page the PageSpec is used in, you can +use a single dot. For example, `link(.)` matches all the pages +linking to the page containing the PageSpec. diff --git a/ikiwiki/pagespec/attachment.mdwn b/ikiwiki/pagespec/attachment.mdwn new file mode 100644 index 0000000..fa2bc58 --- /dev/null +++ b/ikiwiki/pagespec/attachment.mdwn @@ -0,0 +1,38 @@ +[[!meta robots="noindex, follow"]] +[[!if test="enabled(attachment)" + then="This wiki has attachments **enabled**." + else="This wiki has attachments **disabled**."]] + +If attachments are enabled, the wiki admin can control what types of +attachments will be accepted, via the `allowed_attachments` +configuration setting. + +For example, to limit most users to uploading small images, and nothing else, +while allowing larger mp3 files to be uploaded by joey into a specific +directory, and check all attachments for viruses, something like this could be +used: + + virusfree() and ((user(joey) and podcast/*.mp3 and mimetype(audio/mpeg) and maxsize(15mb)) or (mimetype(image/*) and maxsize(50kb))) + +The regular [[ikiwiki/PageSpec]] syntax is expanded with the following +additional tests: + +* "`maxsize(size)`" - tests whether the attachment is no larger than the + specified size. The size defaults to being in bytes, but "kb", "mb", "gb" + etc can be used to specify the units. + +* "`minsize(size)`" - tests whether the attachment is no smaller than the + specified size. + +* "`ispage()`" - tests whether the attachment will be treated by ikiwiki as a + wiki page. (Ie, if it has an extension of ".mdwn", or of any other enabled + page format). + + So, if you don't want to allow wiki pages to be uploaded as attachments, + use `!ispage()` ; if you only want to allow wiki pages to be uploaded + as attachments, use `ispage()`. + +* "`mimetype(foo/bar)`" - checks the MIME type of the attachment. You can + include a glob in the type, for example `mimetype(image/*)`. + +* "`virusfree()`" - checks the attachment with an antiviral program. diff --git a/ikiwiki/pagespec/po.mdwn b/ikiwiki/pagespec/po.mdwn new file mode 100644 index 0000000..f995640 --- /dev/null +++ b/ikiwiki/pagespec/po.mdwn @@ -0,0 +1,23 @@ +[[!if test="enabled(po)" + then="This wiki has po support **enabled**." + else="This wiki has po support **disabled**."]] + +If the [[!iki plugins/po desc=po]] plugin is enabled, the regular +[[ikiwiki/PageSpec]] syntax is expanded with the following additional +tests that can be used to improve user navigation in a multi-lingual +wiki: + +* "`lang(LL)`" - tests whether a page is written in the language + specified as a ISO639-1 (two-letter) language code. +* "`currentlang()`" - tests whether a page is written in the same + language as the current page. +* "`needstranslation()`" - tests whether a page needs translation + work. Only slave pages match this PageSpec. A minimum target + translation percentage can optionally be passed as an integer + parameter: "`needstranslation(50)`" matches only pages less than 50% + translated. + +Note that every non-po page is considered to be written in +`po_master_language`, as specified in `ikiwiki.setup`. + +[[!meta robots="noindex, follow"]] diff --git a/ikiwiki/pagespec/sorting.mdwn b/ikiwiki/pagespec/sorting.mdwn new file mode 100644 index 0000000..ccd7f7e --- /dev/null +++ b/ikiwiki/pagespec/sorting.mdwn @@ -0,0 +1,26 @@ +Some [[directives|ikiwiki/directive]] that use +[[PageSpecs|ikiwiki/pagespec]] allow +specifying the order that matching pages are shown in. The following sort +orders can be specified. + +* `age` - List pages from the most recently created to the oldest. + +* `mtime` - List pages with the most recently modified first. + +* `title` - Order by title (page name). +[[!if test="enabled(sortnaturally)" then=""" +* `title_natural` - Orders by title, but numbers in the title are treated + as such, ("1 2 9 10 20" instead of "1 10 2 20 9") +"""]] +[[!if test="enabled(meta)" then=""" +* `meta(title)` - Order according to the `\[[!meta title="foo" sortas="bar"]]` + or `\[[!meta title="foo"]]` [[ikiwiki/directive]], or the page name if no + full title was set. `meta(author)`, `meta(date)`, `meta(updated)`, etc. + also work. +"""]] + +In addition, you can combine several sort orders and/or reverse the order of +sorting, with a string like `age -title` (which would sort by age, then by +title in reverse order if two pages have the same age). + +[[!meta robots="noindex, follow"]] diff --git a/ikiwiki/searching.mdwn b/ikiwiki/searching.mdwn new file mode 100644 index 0000000..4c12879 --- /dev/null +++ b/ikiwiki/searching.mdwn @@ -0,0 +1,20 @@ +[[!meta robots="noindex, follow"]] + +[[!if test="enabled(search)" +then="This wiki has searching **enabled**." +else="This wiki has searching **disabled**."]] + +If searching is enabled, you can enter search terms in the search field, +as you'd expect. There are a few special things you can do to construct +more powerful searches. + +* To match a phrase, enclose it in double quotes. +* `AND` can be used to search for documents containing two expressions. +* `OR` can be used to search for documents containing either one of + two expressions. +* Parentheses can be used to build up complicated search expressions. For + example, "(foo AND bar) OR (me AND you)" +* Prefix a search term with "-" to avoid it from appearing in the results. + For example, "-discussion" will omit "discussion". +* To search for a page with a given title, use "title:foo". +* To search for pages that contain a "bar" link, use "link:bar". diff --git a/ikiwiki/subpage.mdwn b/ikiwiki/subpage.mdwn new file mode 100644 index 0000000..862f45e --- /dev/null +++ b/ikiwiki/subpage.mdwn @@ -0,0 +1,12 @@ +[[!meta robots="noindex, follow"]] +ikiwiki supports placing pages in a directory hierarchy. For example, +this page, [[SubPage]] has some related pages placed under it, like +[[SubPage/LinkingRules]]. This is a useful way to add some order to your +wiki rather than just having a great big directory full of pages. + +To add a SubPage, just make a subdirectory and put pages in it. For +example, this page is subpage.mdwn in this wiki's source, and there is also +a subpage subdirectory, which contains subpage/linkingrules.mdwn. Subpages +can be nested as deeply as you'd like. + +Linking to and from a SubPage is explained in [[LinkingRules]]. diff --git a/ikiwiki/subpage/linkingrules.mdwn b/ikiwiki/subpage/linkingrules.mdwn new file mode 100644 index 0000000..e547f30 --- /dev/null +++ b/ikiwiki/subpage/linkingrules.mdwn @@ -0,0 +1,33 @@ +[[!meta robots="noindex, follow"]] +To link to or from a [[SubPage]], you can normally use a regular +[[WikiLink]] that does not contain the name of the parent directory of +the [[SubPage]]. Ikiwiki descends the directory hierarchy looking for a +page that matches your link. + +For example, if FooBar/SubPage links to "OtherPage", ikiwiki will first +prefer pointing the link to FooBar/SubPage/OtherPage if it exists, next +to FooBar/OtherPage and finally to OtherPage in the root of the wiki. + +Note that this means that if a link on FooBar/SomePage to "OtherPage" +currently links to OtherPage, in the root of the wiki, and FooBar/OtherPage +is created, the link will _change_ to point to FooBar/OtherPage. On the +other hand, a link from BazBar to "OtherPage" would be unchanged by this +creation of a [[SubPage]] of FooBar. + +You can also specify a link that contains a directory name, like +"FooBar/OtherPage" to more exactly specify what page to link to. This is +the only way to link to an unrelated [[SubPage]]. + +You can use this to, for example, to link from BazBar to "FooBar/SubPage", +or from BazBar/SubPage to "FooBar/SubPage". + +You can also use "/" at the start of a link, to specify exactly which page +to link to, when there are multiple pages with similar names and the link +goes to the wrong page by default. For example, linking from +"FooBar/SubPage" to "/OtherPage" will link to the "OtherPage" in the root +of the wiki, even if there is a "FooBar/OtherPage". + +Also, if the wiki is configured with a userdir, you can link to pages +within the userdir without specifying a path to them. This is to allow for +easy linking to a user's page in the userdir, to sign a comment. These +links are checked for last of all. diff --git a/ikiwiki/wikilink.mdwn b/ikiwiki/wikilink.mdwn new file mode 100644 index 0000000..cf3b89c --- /dev/null +++ b/ikiwiki/wikilink.mdwn @@ -0,0 +1,29 @@ +[[!meta robots="noindex, follow"]] +WikiLinks provide easy linking between pages of the wiki. To create a +[[WikiLink]], just put the name of the page to link to in double brackets. +For example `\[[WikiLink]]`. + +If you ever need to write something like `\[[WikiLink]]` without creating a +wikilink, just prefix it with a `\`, like `\\[[WikiLink]]`. + +There are some special [[SubPage/LinkingRules]] that come into play when +linking between [[SubPages|SubPage]]. + +WikiLinks are matched with page names in a case-insensitive manner, so you +don't need to worry about getting the case the same, and can capitalise +links at the start of a sentence, and so on. + +It's also possible to write a WikiLink that uses something other than the page +name as the link text. For example `\[[foo_bar|SandBox]]` links to the SandBox +page, but the link will appear like this: [[foo_bar|SandBox]]. + +To link to an anchor inside a page, you can use something like +`\[[WikiLink#foo]]` . + +If the file linked to by a WikiLink looks like an image, it will +be displayed inline on the page. + +--- + +You can also put an url in a WikiLink, to link to an external page. +Email addresses can also be used to generate a mailto link. |