diff options
| -rw-r--r-- | wiki/editing.mdwn | 127 |
1 files changed, 127 insertions, 0 deletions
diff --git a/wiki/editing.mdwn b/wiki/editing.mdwn new file mode 100644 index 0000000..1ae1cbb --- /dev/null +++ b/wiki/editing.mdwn @@ -0,0 +1,127 @@ +[[!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]. + +This page offers instructions to help new editors work with this wiki. +Additonal assistance may be requested on the IRC channel. + + +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.os.libiquity.com/www/wiki.git embedded-os-wiki + cd embedded-os-wiki + +Editing, Staging, and Committing +-------------------------------- + +Now 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 (50-character summary, +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. + +However, the Web authentication and editing interface for this wiki is not yet +well-tested. Committing to the repository is currently the recommended method +to edit this wiki. + + +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.os.libiquity.com/www/wiki.git/ +[mdwn-syn]: http://daringfireball.net/projects/markdown/syntax +[ikiwiki-meta]: http://ikiwiki.info/ikiwiki/directive/meta/ +[ikiwiki-wikilink]: http://ikiwiki.info/ikiwiki/wikilink/ +[ikiwiki-img]: http://ikiwiki.info/ikiwiki/directive/img/ |