1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
|
[[!meta title="Editing this Wiki"]]
This wiki is managed using [ikiwiki][ikiwiki]. Pages are formatted in
[Markdown][mdwn] and stored in [a Git repository][wiki-git].
The wiki may be edited by anyone through either Git or a Web interface.
This page offers instructions to help new editors work with this wiki.
Additonal assistance may be requested on [the IRC channel][irc].
Repository Editing
==================
These sections assume at least a basic familiarity with the Git revision control
system. Numerous books and tutorials for Git exist on the Web, and Git's
included manual pages are a great reference.
Cloning
-------
To work with the wiki repository, you first need to clone it (using
**git-clone**(1)). The following commands will get you a copy of the full
repository and make it your working directory:
git clone git://git.proteanos.com/www/wiki.git proteanos-wiki
cd proteanos-wiki
Editing, Staging, and Committing
--------------------------------
With the repository cloned, you can simply edit files in your favorite text
editor.
When you've made some changes, stage them to the index with **git-add**(1) and
commit them to the repository with **git-commit**(1). For example:
git add wiki/editing.mdwn
git commit
All of the usual recommendations for commit messages (a summary no longer than
50 characters, followed optionally by an empty line and detailed text wrapped at
72 characters) apply.
Be aware that the author usernames shown in the wiki's
[[change_log|recentchanges]] come from the author email addresses in commits.
You can set just this value (and thus your username for the wiki) by setting the
`GIT_AUTHOR_EMAIL` environment variable before running `git commit`.
Pushing
-------
When you've committed some changes, you can push them to the public repository
(the "origin" which you cloned) using **git-push**(1). For example:
git push origin master:master
The shorter `git push` should also work, unless you modified the default remote
and/or ref in your repository configuration.
As soon as the Git daemon receives your changes, it will run ikiwiki's Git hook
to rebuild the pages you've edited. You can then immediately view the new pages
on the wiki in your Web browser.
Pulling
-------
You might need to fetch and merge recent changes using **git-pull**(1),
especially if you haven't fetched anything from the public repository in a
while. For example:
git pull origin master
Web Editing
===========
This wiki also supports editing by authenticated users through an interactive
Web interface.
On most pages, you can click the "Edit" link in the sidebar to log in and begin
editing.
Formatting Syntax
=================
Basic Syntax and File Extensions
--------------------------------
The basic formatting syntax used by this wiki is [Markdown][mdwn]. It is easy
to read and can be learned quickly. See John Gruber's [Markdown syntax
description][mdwn-syn] to learn more.
All wiki page files must have names ending in ".mdwn". This tells ikiwiki that
they should be rendered into HTML using the Markdown processor.
Page Titles
-----------
Each wiki page should be given a title. This can be done using the [`meta`
directive][ikiwiki-meta] of ikiwiki's "meta" plugin. For example, this page
begins with the following directive:
\[[!meta title="Editing this Wiki"]]
Wiki Links
----------
Ikiwiki has [[its_own_syntax|ikiwiki/wikilink]] for links to other pages within
the wiki. For example, `\[[editing_this_wiki|wiki/editing]]` results in a link
like this: [[editing_this_wiki|wiki/editing]].
Images
------
Images may be committed and pushed to the wiki.
They can then be included on wiki pages using the [`img` directive][ikiwiki-img]
of ikiwiki's "img" plugin.
[ikiwiki]: http://ikiwiki.info/
[mdwn]: http://daringfireball.net/projects/markdown/
[wiki-git]: http://git.proteanos.com/www/wiki.git/
[irc]: irc://chat.freenode.net/#poteanos-dev
[mdwn-syn]: http://daringfireball.net/projects/markdown/syntax
[ikiwiki-meta]: http://ikiwiki.info/ikiwiki/directive/meta/
[ikiwiki-img]: http://ikiwiki.info/ikiwiki/directive/img/
|
