add

11 files changed, 219 insertions, 0 deletions

diff --git a/doc/ikiwiki.mdwn b/doc/ikiwiki.mdwn
new file mode 100644
index 000000000..ad5485bb7
--- /dev/null
+++ b/doc/ikiwiki.mdwn
@@ -0,0 +1,7 @@
+IkiWiki is the engine driving this wiki, which exists to document ikiWiki.
+The [[index]] is where you'll find actual useful info about it.
+
+Why call it IkiWiki? Well, partly because I'm sure some people will find
+this a pretty Iky Wiki, since it's so different from other Wikis. Partly
+because "ikiwiki" is a nice palindrome. Partly because its design turns
+the usual design for a Wiki inside-out and backwards.
diff --git a/doc/index.mdwn b/doc/index.mdwn
new file mode 100644
index 000000000..327e685af
--- /dev/null
+++ b/doc/index.mdwn
@@ -0,0 +1,36 @@
+[[Ikiwiki]] is a wiki compiler. It converts a directory full of wiki pages
+into html pages suitable for publishing on a website. Unlike a traditional
+wiki, ikiwiki does not have its own means of storing page history, its own
+markup language, or support for editing pages online. 
+
+To use [[ikiwiki]] to set up a wiki, you will probably want to use it with a
+revision control system, such as [[Subversion]], for keeping track of past
+versions of pages. ikiwiki can run as a Subversion post-commit hook, so
+that each committed change to your wiki is immediatly compiled and
+published. (It can also be run by hand, by cron, or integrated with any
+other revision control system.) 
+
+[[Subversion]] also offers a way to let others edit pages on your wiki.
+Just configure subversion to let appropriate users (or everyone) commit to
+the wiki's repository. There are some things you should keep in mind about
+[[Security]] when allowing the world to edit your ikiwiki.
+
+ikiwiki supports pages using [[MarkDown]] as their markup language. Any
+page with a filename ending in ".mdwn" is converted from markdown to html
+by ikiwiki. Markdown understands text formatted as it would be in an email,
+and is quite smart about converting it to html. The only additional markup
+provided by ikiwiki aside from regular markdown is the [[WikiLink]].
+
+ikiwiki also supports files of any other type, including raw html, text,
+images, etc. These are not converted to wiki pages, they are just copied
+unchanged by ikiwiki as it builds your wiki. So you can check in an image,
+program, or other special file and link to it from your wiki pages.
+ikiwiki also supports making one page that is a [[SubPage]] of another.
+
+[[TODO]] lists things that need to be added to ikiwiki before most people
+would consider it a full-fledged wiki.
+
+All wikis are supposed to have a [[SandBox]], so this one does to.
+If you'd like to try editing pages on this wiki, do whatever you'd like in 
+
+[[ikiwiki]] is developed by JoeyHess.
diff --git a/doc/joeyhess.mdwn b/doc/joeyhess.mdwn
new file mode 100644
index 000000000..c60c76fe8
--- /dev/null
+++ b/doc/joeyhess.mdwn
@@ -0,0 +1,6 @@
+Joey Hess is <a href="mailto:joey@kitenet.net">joey@kitenet.net</a>. 
+His web page is [here](http://kitenet.net/~joey/).
+
+Joey hates programming web crap, and hates being locked into a web browser
+to do something, and this probably shows in the design choices made in
+ikiwiki.
diff --git a/doc/markdown.mdwn b/doc/markdown.mdwn
new file mode 100644
index 000000000..9a0fff198
--- /dev/null
+++ b/doc/markdown.mdwn
@@ -0,0 +1,9 @@
+[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.
+
+For documentation about the markdown syntax, see
+[Markdown: syntax](http://daringfireball.net/projects/markdown/syntax).
+
+Note that [[WikiLink]]s are not part of the markdown syntax, and are the
+only bit of markup that this wiki handles internally.
diff --git a/doc/sandbox.mdwn b/doc/sandbox.mdwn
new file mode 100644
index 000000000..be5c51496
--- /dev/null
+++ b/doc/sandbox.mdwn
@@ -0,0 +1,35 @@
+This is the SandBox, a page anyone can edit to try out ikiwiki.
+
+See [[MarkDown]] for documentation of the markup syntax used on this page.
+
+----
+
+Here's a paragraph.
+
+Here's another one.
+
+# Header
+
+## Subheader
+
+> This is a blockquote.
+>
+> This is the first level of quoting.
+>
+> > This is nested blockquote.
+>
+> Back to the first level.
+
+Numbered list 
+
+1. First item.
+1. Another.
+1. And another..
+
+Bulleted list
+
+* item
+* item
+* item
+
+Link back to the [[index]].
diff --git a/doc/security.mdwn b/doc/security.mdwn
new file mode 100644
index 000000000..575ccbad8
--- /dev/null
+++ b/doc/security.mdwn
@@ -0,0 +1,39 @@
+If you are using ikiwiki to render pages that only you can edit, then there
+are no more security issues with this program than with cat(1). If,
+however, you let others edit pages in your wiki, then some security issues
+do need to be kept in mind.
+
+## html attacks
+
+ikiwiki does not attempt to do any santization of the html on the wiki.
+MarkDown allows embedding of arbitrary html into a markdown document. If
+you let anyone else edit files on the wiki, then anyone can have fun exploiting
+the web browser bug of the day. This type of attack is typically referred
+to as an XSS attack ([google](http://www.google.com/search?q=xss+attack)).
+
+## image files etc attacks
+
+If it enounters a file type it does not understand, ikiwiki just copies it
+into place. So if you let users add any kind of file they like, they can
+upload images, movies, windows executables, etc. If these files exploit
+security holes in the browser of someone who's viewing the wiki, that can
+be a security problem.
+
+## exploting ikiwiki with bad content
+
+Someone could add bad content to the wiki and hope to exploit ikiwiki.
+Note that ikiwiki runs with perl taint checks on, so this is unlikely;
+the only data that is not subject to full taint checking is the names of
+files, and filenames are sanitised.
+
+## cgi scripts
+
+ikiwiki does not allow cgi scripts to be published as part of the wiki. Or
+rather, the script is published, but it's not marked executable, so
+hopefully your web server will not run it.
+
+## web server attacks
+
+If your web server does any parsing of special sorts of files (for example,
+server parsed html files), then if you let anyone else add files to the wiki,
+they can try to use this to exploit your web server.
diff --git a/doc/subpage.mdwn b/doc/subpage.mdwn
new file mode 100644
index 000000000..88a964ac2
--- /dev/null
+++ b/doc/subpage.mdwn
@@ -0,0 +1,11 @@
+[[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/doc/subpage/linkingrules.mdwn b/doc/subpage/linkingrules.mdwn
new file mode 100644
index 000000000..83625ccbd
--- /dev/null
+++ b/doc/subpage/linkingrules.mdwn
@@ -0,0 +1,21 @@
+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".
diff --git a/doc/subversion.mdwn b/doc/subversion.mdwn
new file mode 100644
index 000000000..9c13dcabe
--- /dev/null
+++ b/doc/subversion.mdwn
@@ -0,0 +1,3 @@
+Subversion is a revision control system. While ikiwiki is relatively
+independant of the underlying revision control system, using it with
+Subversion is recommended.
diff --git a/doc/todo.mdwn b/doc/todo.mdwn
new file mode 100644
index 000000000..f252890ac
--- /dev/null
+++ b/doc/todo.mdwn
@@ -0,0 +1,43 @@
+## online page editing
+
+To support editing pages in a web browser,  a CGI script is needed that
+pulls the page out of [[Subversion]], presents it to the user for editing,
+and then commits the changed page back to [[Subversion]].
+
+Due to [[WikiSpam]], this will probably also need to incorporate a user
+registration system. So there will need to be a script that handles logins
+and registrations, sets a cookie, and the page editor can refuse to edit
+pages for users who arn't logged in, and include a not of who made the
+change in the svn log.
+
+If possible I'd prefer to use someone else's generic web user registration
+and login system, if one exists.
+
+## [[RecentChanges]]
+
+This will need to be another cgi script, that grubs through the
+[[Subversion]] logs.
+
+This should support RSS for notification of new and changed pages.
+
+## page history
+
+To see past versions of a page, we can either implement a browser for that,
+or just provide a way to link to the page in viewcvs.
+
+## pluggable renderers
+
+I'm considering a configurable rendering pipeline for each supported
+filename extension. So for ".mdwn" files, it would send the content through
+linkify, markdown, and finalize, while for ".wiki" files it might send it
+through just a wiki formatter and finalize.
+
+This would allow not only supporting more types of markup, but changing
+what style of [[WikiLink]]s are supported, maybe some people want to add
+[[CamelCase]] for example, or don't like the [[SubPage/LinkingRules]].
+
+The finalize step is where the page gets all the pretty junk around the
+edges, so that clearly needs to be pluggable too.
+
+There could also be a step before finalize, where stuff like lists of pages
+that linked back to it could be added to the page.
diff --git a/doc/wikilink.mdwn b/doc/wikilink.mdwn
new file mode 100644
index 000000000..7891add7c
--- /dev/null
+++ b/doc/wikilink.mdwn
@@ -0,0 +1,9 @@
+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
+examples "[[ WikiLink ]]" (without the added whitespace). 
+
+Note that there are some special [[SubPage/LinkingRules]] that come into
+play when linking between [[SubPage]]s.
+
+WikiLinks can be entered in any case you like, the page they link to is
+always lowercased.