tcswiki

wiki-style
git clone https://a3nm.net/git/tcswiki/
Log | Files | Refs

commit 787de1fcdc2a104b75e96fa91d0125f3d2473812
parent e7e5344b1b4b91d4bca4ee7dfcc6ad67a5d91959
Author: Antoine Amarilli <a3nm@a3nm.net>
Date:   Sun, 17 Jun 2018 02:23:36 +0200

import default pages

Diffstat:
Front Page.page | 16++++++++++++++++
Gitit User’s Guide.page | 639+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Help.page | 329+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 984 insertions(+), 0 deletions(-)

diff --git a/Front Page.page b/Front Page.page @@ -0,0 +1,16 @@ +--- +format: Markdown +... + +# Welcome to Gitit! + +This is the front page of your new gitit wiki. You can edit this +page by clicking on the "edit" tab at the top of the screen. +For instructions on how to make a link to another wiki page, see [the +Help page](Help#wiki-links). To create a new wiki page, just create a +link to it and follow the link. + +Help is always available through the "Help" link in the sidebar. +More details on installing and configurating gitit are available +in the [Gitit User’s Guide](). + diff --git a/Gitit User’s Guide.page b/Gitit User’s Guide.page @@ -0,0 +1,639 @@ +--- +format: Markdown +... + +Gitit +===== + +Gitit is a wiki program written in Haskell. It uses [Happstack] for +the web server and [pandoc] for markup processing. Pages and uploaded +files are stored in a [git], [darcs], or [mercurial] repository +and may be modified either by using the VCS's command-line tools or +through the wiki's web interface. By default, pandoc's extended version +of markdown is used as a markup language, but reStructuredText, LaTeX, HTML, +DocBook, or Emacs Org-mode markup can also be used. Pages can be exported in a +number of different formats, including LaTeX, RTF, OpenOffice ODT, and +MediaWiki markup. Gitit can be configured to display TeX math (using +[texmath]) and highlighted source code (using [highlighting-kate]). + +Other features include + +* plugins: dynamically loaded page transformations written in Haskell + (see "Network.Gitit.Interface") + +* categories + +* TeX math + +* syntax highlighting of source code files and code snippets (using + highlighting-kate) + +* caching + +* Atom feeds (site-wide and per-page) + +* a library, "Network.Gitit", that makes it simple to include a gitit + wiki in any happstack application + +[git]: http://git.or.cz +[darcs]: http://darcs.net +[mercurial]: http://mercurial.selenic.com/ +[pandoc]: http://pandoc.org +[Happstack]: http://happstack.com +[highlighting-kate]: http://johnmacfarlane.net/highlighting-kate/ +[texmath]: http://github.com/jgm/texmath/tree/master + +Getting started +=============== + +Compiling and installing gitit +------------------------------ + +The most reliable way to install gitit from source is to get the +[stack] tool. Then clone the gitit repository and use stack +to install: + + git clone https://github.com/jgm/gitit + cd gitit + stack install + +Alternatively, instead of using [stack], you can get the +[Haskell Platform] and do the following: + + cabal update + cabal install gitit + +This will install the latest released version of gitit. +To install a version of gitit checked out from the repository, +change to the gitit directory and type: + + cabal install + +The `cabal` tool will automatically install all of the required haskell +libraries. If all goes well, by the end of this process, the latest +release of gitit will be installed in your local `.cabal` directory. You +can check this by trying: + + gitit --version + +If that doesn't work, check to see that `gitit` is in your local +cabal-install executable directory (usually `~/.cabal/bin`). And make +sure `~/.cabal/bin` is in your system path. + +[stack]: https://github.com/commercialhaskell/stack +[Haskell Platform]: https://www.haskell.org/platform/ + +Running gitit +------------- + +To run gitit, you'll need `git` in your system path. (Or `darcs` or +`hg`, if you're using darcs or mercurial to store the wiki data.) + +Gitit assumes that the page files (stored in the git repository) are +encoded as UTF-8. Even page names may be UTF-8 if the file system +supports this. So you should make sure that you are using a UTF-8 locale +when running gitit. (To check this, type `locale`.) + +Switch to the directory where you want to run gitit. This should be a +directory where you have write access, since three directories, `static`, +`templates`, and `wikidata`, and two files, `gitit-users` and `gitit.log`, +will be created here. To start gitit, just type: + + gitit + +If all goes well, gitit will do the following: + + 1. Create a git repository, `wikidata`, and add a default front page. + 2. Create a `static` directory containing files to be treated as + static files by gitit. + 3. Create a `templates` directory containing HStringTemplate templates + for wiki pages. + 4. Start a web server on port 5001. + +Check that it worked: open a web browser and go to +<http://localhost:5001>. + +You can control the port that gitit runs on using the `-p` option: +`gitit -p 4000` will start gitit on port 4000. Additional runtime +options are described by `gitit -h`. + +Using gitit +=========== + +Wiki links and formatting +------------------------- + +For instructions on editing pages and creating links, see the "Help" page. + +Gitit interprets links with empty URLs as wikilinks. Thus, in markdown +pages, `[Front Page]()` creates an internal wikilink to the page `Front +Page`. In reStructuredText pages, `` `Front Page <>`_ `` has the same +effect. + +If you want to link to a directory listing for a subdirectory, use a +trailing slash: `[foo/bar/]()` creates a link to the directory for +`foo/bar`. + +Page metadata +------------- + +Pages may optionally begin with a metadata block. Here is an example: + + --- + format: latex+lhs + categories: haskell math + toc: no + title: Haskell and + Category Theory + ... + + \section{Why Category Theory?} + +The metadata block consists of a list of key-value pairs, each on a +separate line. If needed, the value can be continued on one or more +additional line, which must begin with a space. (This is illustrated by +the "title" example above.) The metadata block must begin with a line +`---` and end with a line `...` optionally followed by one or more blank +lines. (The metadata block is a valid YAML document, though not all YAML +documents will be valid metadata blocks.) + +Currently the following keys are supported: + +format +: Overrides the default page type as specified in the configuration file. + Possible values are `markdown`, `rst`, `latex`, `html`, `markdown+lhs`, + `rst+lhs`, `latex+lhs`. (Capitalization is ignored, so you can also + use `LaTeX`, `HTML`, etc.) The `+lhs` variants indicate that the page + is to be interpreted as literate Haskell. If this field is missing, + the default page type will be used. + +categories +: A space or comma separated list of categories to which the page belongs. + +toc +: Overrides default setting for table-of-contents in the configuration file. + Values can be `yes`, `no`, `true`, or `false` (capitalization is ignored). + +title +: By default the displayed page title is the page name. This metadata element + overrides that default. + +Highlighted source code +----------------------- + +If gitit was compiled against a version of pandoc that has highlighting +support (see above), you can get highlighted source code by using +[delimited code blocks]: + + ~~~ {.haskell .numberLines} + qsort [] = [] + qsort (x:xs) = qsort (filter (< x) xs) ++ [x] ++ + qsort (filter (>= x) xs) + ~~~ + +To see what languages your pandoc was compiled to highlight: + + pandoc -v + +[delimited code blocks]: http://pandoc.org/README.html#delimited-code-blocks + +Configuring and customizing gitit +================================= + +Configuration options +--------------------- + +Use the option `-f [filename]` to specify a configuration file: + + gitit -f my.conf + +The configuration can be split between several files: + + gitit -f my.conf -f additional.conf + +One use case is to keep sensible part of the configuration outside of a SCM +(oauth client secret for example). + +If this option is not used, gitit will use a default configuration. +To get a copy of the default configuration file, which you +can customize, just type: + + gitit --print-default-config > my.conf + +The default configuration file is documented with comments throughout. + +The `static` directory +---------------------- + +On receiving a request, gitit always looks first in the `static` +directory (or in whatever directory is specified for `static-dir` in +the configuration file). If a file corresponding to the request is +found there, it is served immediately. If the file is not found in +`static`, gitit next looks in the `static` subdirectory of gitit's data +file (`$CABALDIR/share/gitit-x.y.z/data`). This is where default css, +images, and javascripts are stored. If the file is not found there +either, gitit treats the request as a request for a wiki page or wiki +command. + +So, you can throw anything you want to be served statically (for +example, a `robots.txt` file or `favicon.ico`) in the `static` +directory. You can override any of gitit's default css, javascript, or +image files by putting a file with the same relative path in `static`. +Note that gitit has a default `robots.txt` file that excludes all +URLs beginning with `/_`. + +Note: if you set `static-dir` to be a subdirectory of `repository-path`, +and then add the files in the static directory to your repository, you +can ensure that others who clone your wiki repository get these files +as well. It will not be possible to modify these files using the web +interface, but they will be modifiable via git. + +Using a VCS other than git +-------------------------- + +By default, gitit will store wiki pages in a git repository in the +`wikidata` directory. If you'd prefer to use darcs instead of git, +you need to add the following field to the configuration file: + + repository-type: Darcs + +If you'd prefer to use mercurial, add: + + repository-type: Mercurial + +This program may be called "darcsit" instead of "gitit" when a darcs +backend is used. + +Note: we recommend that you use gitit/darcsit with darcs version +2.3.0 or greater. If you must use an older version of darcs, then +you need to compile the filestore library without the (default) +maxcount flag, before (re)installing gitit: + + cabal install --reinstall filestore -f-maxcount + cabal install --reinstall gitit + +Otherwise you will get an error when you attempt to access your +repository. + +Changing the theme +------------------ + +To change the look of the wiki, you can modify `custom.css` in +`static/css`. + +To change the look of printed pages, copy gitit's default `print.css` +to `static/css` and modify it. + +The logo picture can be changed by copying a new PNG file to +`static/img/logo.png`. The default logo is 138x155 pixels. + +To change the footer, modify `templates/footer.st`. + +For more radical changes, you can override any of the default +templates in `$CABALDIR/share/gitit-x.y.z/data/templates` by copying +the file into `templates`, modifying it, and restarting gitit. The +`page.st` template is the master template; it includes the others. +Interpolated variables are surrounded by `$`s, so `literal $` must +be backslash-escaped. + +Adding support for math +----------------------- + +To write math on a markdown-formatted wiki page, just enclose it +in dollar signs, as in LaTeX: + + Here is a formula: $\frac{1}{\sqrt{c^2}}$ + +You can write display math by enclosing it in double dollar signs: + + $$\frac{1}{\sqrt{c^2}}$$ + +Gitit can display TeX math in three different ways, depending on the +setting of `math` in the configuration file: + +1. `mathml` (default): Math will be converted to MathML using + [texmath]. This method works with IE+mathplayer, Firefox, and + Opera, but not Safari. + +2. `jsMath`: Math will be rendered using the [jsMath] javascript. + If you want to use this method, download `jsMath` and `jsMath + Image Fonts` from the [jsMath download page]. You'll have two + `.zip` archives. Unzip them both in the `static/js` directory (a new + subdirectory, `jsMath`, will be created). This works with all + browsers, but is slower and not as nice looking as MathML. + +3. `raw`: Math will be rendered as raw LaTeX codes. + +[jsMath]: http://www.math.union.edu/~dpvc/jsmath/ +[jsMath download page]: http://sourceforge.net/project/showfiles.php?group_id=172663 + +Restricting access +------------------ + +If you want to limit account creation on your wiki, the easiest way to do this +is to provide an `access-question` in your configuration file. (See the commented +default configuration file.) Nobody will be able to create an account without +knowing the answer to the access question. + +Another approach is to use HTTP authentication. (See the config file comments on +`authentication-method`.) + +Authentication through github +----------------------------- + +If you want to authenticate the user from github through oauth2, you need to +register your app with github to obtain a OAuth client secret and add the +following section to your configuration file: + +``` +[Github] +oauthclientid: 01239456789abcdef012 +oauthclientsecret: 01239456789abcdef01239456789abcdef012394 +oauthcallback: http://mysite/_githubCallback +oauthoauthorizeendpoint: https://github.com/login/oauth/authorize +oauthaccesstokenendpoint: https://github.com/login/oauth/access_token +## Uncomment if you are checking membership against an organization and change +## gitit-testorg to this organization: +# github-org: gitit-testorg +``` + +The github authentication uses the scope `user:email`. This way, gitit gets the +email of the user, and the commit can be assigned to the right author if the +wikidata repository is pushed to github. Additionally, it uses `read:org` if you +uses the option `github-org` to check membership against an organization. + +To push your repository to gitub after each commit, you can add the file +`post-commit` with the content below in the .git/hooks directory of your +wikidata repository. + +``` +#!/bin/sh +git push origin master 2>> logit +``` + +Plugins +======= + +Plugins are small Haskell programs that transform a wiki page after it +has been converted from Markdown or another source format. See the example +plugins in the `plugins` directory. To enable a plugin, include the path to the +plugin (or its module name) in the `plugins` field of the configuration file. +(If the plugin name starts with `Network.Gitit.Plugin.`, gitit will assume that +the plugin is an installed module and will not look for a source file.) + +Plugin support is enabled by default. However, plugin support makes +the gitit executable considerably larger and more memory-hungry. +If you don't need plugins, you may want to compile gitit without plugin +support. To do this, unset the `plugins` Cabal flag: + + cabal install --reinstall gitit -f-plugins + +Note also that if you compile gitit for executable profiling, attempts +to load plugins will result in "internal error: PAP object entered!" + +Accessing the wiki through git +============================== + +All the pages and uploaded files are stored in a git repository. By +default, this lives in the `wikidata` directory (though this can be +changed through configuration options). So you can interact with the +wiki using git command line tools: + + git clone ssh://my.server.edu/path/of/wiki/wikidata + cd wikidata + vim Front\ Page.page # edit the page + git commit -m "Added message about wiki etiquette" Front\ Page.page + git push + +If you now look at the Front Page on the wiki, you should see your changes +reflected there. Note that the pages all have the extension `.page`. + +If you are using the darcs or mercurial backend, the commands will +be slightly different. See the documentation for your VCS for +details. + +Performance +=========== + +Caching +------- + +By default, gitit does not cache content. If your wiki receives a lot of +traffic or contains pages that are slow to render, you may want to activate +caching. To do this, set the configuration option `use-cache` to `yes`. +By default, rendered pages, highlighted source files, and exported PDFs +will be cached in the `cache` directory. (Another directory can be +specified by setting the `cache-dir` configuration option.) + +Cached pages are updated when pages are modified using the web +interface. They are not updated when pages are modified directly through +git or darcs. However, the cache can be refreshed manually by pressing +Ctrl-R when viewing a page, or by sending an HTTP GET or POST request to +`/_expire/path/to/page`, where `path/to/page` is the name of the page to +be expired. + +Users who frequently update pages using git or darcs may wish to add a +hook to the repository that makes the appropriate HTTP request to expire +pages when they are updated. To facilitate such hooks, the gitit cabal +package includes an executable `expireGititCache`. Assuming you are +running gitit at port 5001 on localhost, and the environment variable +`CHANGED_FILES` contains a list of the files that have changed, you can +expire their cached versions using + + expireGititCache http://localhost:5001 $CHANGED_FILES + +Or you can specify the files directly: + + expireGititCache http://localhost:5001 "Front Page.page" foo/bar/baz.c + +This program will return a success status (0) if the page has been +successfully expired (or if it was never cached in the first place), +and a failure status (> 0) otherwise. + +The cache is persistent through restarts of gitit. To expire all cached +pages, simply remove the `cache` directory. + +Idle +---- + +By default, GHC's runtime will repeatedly attempt to collect garbage +when an executable like Gitit is idle. This means that gitit will, after +the first page request, never use 0% CPU time and sleep, but will use +~1%. This can be bad for battery life, among other things. + +To fix this, one can disable the idle-time GC with the runtime flag +`-I0`: + + gitit -f my.conf +RTS -I0 -RTS + + +Note: + +To enable RTS, cabal needs to pass the compile flag `-rtsopts` to GHC while installing. + + cabal install --reinstall gitit --ghc-options="-rtsopts" + +Using gitit with apache +======================= + +Most users who run a public-facing gitit will want gitit to appear +at a nice URL like `http://wiki.mysite.com` or +`http://mysite.com/wiki` rather than `http://mysite.com:5001`. +This can be achieved using apache's `mod_proxy`. + +Proxying to `http://wiki.mysite.com` +------------------------------------ + +Set up your DNS so that `http://wiki.mysite.com` maps to +your server's IP address. Make sure that the `mod_proxy`, `mod_proxy_http` and `mod_rewrite` modules are +loaded, and set up a virtual host with the following configuration: + + <VirtualHost *> + ServerName wiki.mysite.com + DocumentRoot /var/www/ + RewriteEngine On + ProxyPreserveHost On + ProxyRequests Off + + <Proxy *> + Order deny,allow + Allow from all + </Proxy> + + ProxyPassReverse / http://127.0.0.1:5001 + RewriteRule ^(.*) http://127.0.0.1:5001$1 [P] + + ErrorLog /var/log/apache2/error.log + LogLevel warn + + CustomLog /var/log/apache2/access.log combined + ServerSignature On + + </VirtualHost> + +Reload your apache configuration and you should be all set. + +Using nginx to achieve the same +------------------------------- + +Drop a file called `wiki.example.com.conf` into `/etc/nginx/conf.d` +(or where ever your distribution puts it). + + server { + listen 80; + server_name wiki.example.com + location / { + proxy_pass http://127.0.0.1:5001/; + proxy_set_header X-Real-IP $remote_addr; + proxy_redirect off; + } + access_log /var/log/nginx/wiki.example.com.log main; + } + +Reload your nginx config and you should be all set. + + +Proxying to `http://mysite.com/wiki` +------------------------------------ + +Make sure the `mod_proxy`, `mod_headers`, `mod_proxy_http`, +and `mod_proxy_html` modules are loaded. `mod_proxy_html` +is an external module, which can be obtained [here] +(http://apache.webthing.com/mod_proxy_html/). It rewrites URLs that +occur in web pages. Here we will use it to rewrite gitit's links so that +they all begin with `/wiki/`. + +First, tell gitit not to compress pages, since `mod_proxy_html` needs +uncompressed pages to parse. You can do this by setting the gitit +configuration option + + compress-responses: no + +Second, modify the link in the `reset-password-message` in the +configuration file: instead of + + http://$hostname$:$port$$resetlink$ + +set it to + + http://$hostname$/wiki$resetlink$ + +Restart gitit. + +Now add the following lines to the apache configuration file for the +`mysite.com` server: + + # These commands will proxy /wiki/ to port 5001 + + ProxyRequests Off + + <Proxy *> + Order deny,allow + Allow from all + </Proxy> + + ProxyPass /wiki/ http://127.0.0.1:5001/ + + <Location /wiki/> + SetOutputFilter proxy-html + ProxyPassReverse / + ProxyHTMLURLMap / /wiki/ + ProxyHTMLDocType "<!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Strict//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd'>" XHTML + RequestHeader unset Accept-Encoding + </Location> + +Reload your apache configuration and you should be set. + +For further information on the use of `mod_proxy_http` to rewrite URLs, +see the [`mod_proxy_html` guide]. + +[`mod_proxy_html` guide]: http://apache.webthing.com/mod_proxy_html/guide.html + +Using gitit as a library +======================== + +By importing the module `Network.Gitit`, you can include a gitit wiki +(or several of them) in another happstack application. There are some +simple examples in the haddock documentation for `Network.Gitit`. + +Reporting bugs +============== + +Bugs may be reported (and feature requests filed) at +<https://github.com/jgm/gitit/issues>. + +There is a mailing list for users and developers at +<http://groups.google.com/group/gitit-discuss>. + +Acknowledgements +================ + +A number of people have contributed patches: + +- Gwern Branwen helped to optimize gitit and wrote the + InterwikiPlugin. He also helped with the Feed module. +- Simon Michael contributed the patch adding RST support. +- Henry Laxen added support for password resets and helped with + the apache proxy instructions. +- Anton van Straaten made the process of page generation + more modular by adding Gitit.ContentTransformer. +- Robin Green helped improve the plugin API and interface, and + fixed a security problem with the reset password code. +- Thomas Hartman helped improve the index page, making directory + browsing persistent, and fixed a bug in template recompilation. +- Justin Bogner improved the appearance of the preview button. +- Kohei Ozaki contributed the ImgTexPlugin. +- Michael Terepeta improved validation of change descriptions. +- mightybyte suggested making gitit available as a library, + and contributed a patch to ifLoggedIn that was needed to + make gitit usable with a custom authentication scheme. + +I am especially grateful to the darcs team for using darcsit for +their public-facing wiki. This has helped immensely in identifying +issues and improving performance. + +Gitit's default visual layout is shamelessly borrowed from Wikipedia. +The stylesheets are influenced by Wikipedia's stylesheets and by the +bluetrip CSS framework (see BLUETRIP-LICENSE). Some of the icons in +`img/icons` come from bluetrip as well. + diff --git a/Help.page b/Help.page @@ -0,0 +1,329 @@ +--- +format: Markdown +... + +# Navigating + +The most natural way of navigating is by clicking wiki links that +connect one page with another. The "Front page" link in the navigation +bar will always take you to the Front Page of the wiki. The "All pages" +link will take you to a list of all pages on the wiki (organized into +folders if directories are used). Alternatively, you can search using +the search box. Note that the search is set to look for whole words, so +if you are looking for "gremlins", type that and not "gremlin". +The "go" box will take you directly to the page you type. + +# Creating and modifying pages + +## Registering for an account + +In order to modify pages, you'll need to be logged in. To register +for an account, just click the "register" button in the bar on top +of the screen. You'll be asked to choose a username and a password, +which you can use to log in in the future by clicking the "login" +button. While you are logged in, these buttons are replaced by +a "logout so-and-so" button, which you should click to log out +when you are finished. + +Note that logins are persistent through session cookies, so if you +don't log out, you'll still be logged in when you return to the +wiki from the same browser in the future. + +## Editing a page + +To edit a page, just click the "edit" button at the bottom right corner +of the page. + +You can click "Preview" at any time to see how your changes will look. +Nothing is saved until you press "Save." + +Note that you must provide a description of your changes. This is to +make it easier for others to see how a wiki page has been changed. + +## Page metadata + +Pages may optionally begin with a metadata block. Here is an example: + + --- + format: latex+lhs + categories: haskell math + toc: no + title: Haskell and + Category Theory + ... + + \section{Why Category Theory?} + +The metadata block consists of a list of key-value pairs, each on a +separate line. If needed, the value can be continued on one or more +additional line, which must begin with a space. (This is illustrated by +the "title" example above.) The metadata block must begin with a line +`---` and end with a line `...` optionally followed by one or more blank +lines. + +Currently the following keys are supported: + +format +: Overrides the default page type as specified in the configuration file. + Possible values are `markdown`, `rst`, `latex`, `html`, `markdown+lhs`, + `rst+lhs`, `latex+lhs`. (Capitalization is ignored, so you can also + use `LaTeX`, `HTML`, etc.) The `+lhs` variants indicate that the page + is to be interpreted as literate Haskell. If this field is missing, + the default page type will be used. + +categories +: A space or comma separated list of categories to which the page belongs. + +toc +: Overrides default setting for table-of-contents in the configuration file. + Values can be `yes`, `no`, `true`, or `false` (capitalization is ignored). + +title +: By default the displayed page title is the page name. This metadata element + overrides that default. + +## Creating a new page + +To create a new page, just create a wiki link that links to it, and +click the link. If the page does not exist, you will be editing it +immediately. + +## Reverting to an earlier version + +If you click the "history" button at the bottom of the page, you will +get a record of previous versions of the page. You can see the differences +between two versions by dragging one onto the other; additions will be +highlighted in yellow, and deletions will be crossed out with a horizontal +line. Clicking on the description of changes will take you to the page +as it existed after those changes. To revert the page to the revision +you're currently looking at, just click the "revert" button at the bottom +of the page, then "Save". + +## Deleting a page + +The "delete" button at the bottom of the page will delete a page. Note +that deleted pages can be recovered, since a record of them will still be +accessible via the "activity" button on the top of the page. + +# Uploading files + +To upload a file--a picture, a PDF, or some other resource--click the +"upload" button in the navigation bar. You will be prompted to select +the file to upload. As with edits, you will be asked to provide a +description of the resource (or of the change, if you are overwriting +an existing file). + +Often you may leave "Name on wiki" blank, since the existing name of the +file will be used by default. If that isn't desired, supply a name. +Note that uploaded files *must* include a file extension (e.g. `.pdf`). + +If you are providing a new version of a file that already exists on the +wiki, check the box "Overwrite existing file." Otherwise, leave it +unchecked. + +To link to an uploaded file, just use its name in a regular wiki link. +For example, if you uploaded a picture `fido.jpg`, you can insert the +picture into a (markdown-formatted) page as follows: `![fido](fido.jpg)`. +If you uploaded a PDF `projection.pdf`, you can insert a link to it +using: `[projection](projection.pdf)`. + + + +# Markdown + +This wiki's pages are written in [pandoc]'s extended form of [markdown]. +If you're not familiar with markdown, you should start by looking +at the [markdown "basics" page] and the [markdown syntax description]. +Consult the [pandoc User's Guide] for information about pandoc's syntax +for footnotes, tables, description lists, and other elements not present +in standard markdown. + +[pandoc]: http://pandoc.org +[pandoc User's Guide]: http://pandoc.org/README.html +[markdown]: http://daringfireball.net/projects/markdown +[markdown "basics" page]: http://daringfireball.net/projects/markdown/basics +[markdown syntax description]: http://daringfireball.net/projects/markdown/syntax + +Markdown is pretty intuitive, since it is based on email conventions. +Here are some examples to get you started: + +<table> +<tr> +<td>`*emphasized text*`</td> +<td>*emphasized text*</td> +</tr> +<tr> +<td>`**strong emphasis**`</td> +<td>**strong emphasis**</td> +</tr> +<tr> +<td>`` `literal text` ``</td> +<td>`literal text`</td> +</tr> +<tr> +<td>`\*escaped special characters\*`</td> +<td>\*escaped special characters\*</td> +</tr> +<tr> +<td>`[external link](http://google.com)`</td> +<td>[external link](http://google.com)</td> +</tr> +<tr> +<td>`![folder](/img/icons/folder.png)`</td> +<td>![folder](/img/icons/folder.png)</td> +</tr> +<tr> +<td>Wikilink: `[Front Page]()`</td> +<td>Wikilink: [Front Page]()</td> +</tr> +<tr> +<td>`H~2~O`</td> +<td>H~2~O</td> +</tr> +<tr> +<td>`10^100^`</td> +<td>10^100^</td> +</tr> +<tr> +<td>`~~strikeout~~`</td> +<td>~~strikeout~~</td> +</tr> +<tr> +<td> +`$x = \frac{{ - b \pm \sqrt {b^2 - 4ac} }}{{2a}}$` +</td> +<td> +$x = \frac{{ - b \pm \sqrt {b^2 - 4ac} }}{{2a}}$^[If this looks like +code, it's because jsMath is +not installed on your system. Contact your administrator to request it.] +</td> +</tr> +<tr> +<td> +`A simple footnote.^[Or is it so simple?]` +</td> +<td> +A simple footnote.^[Or is it so simple?] +</td> +</tr> +<tr> +<td> +<pre> +> an indented paragraph, +> usually used for quotations +</pre> +</td> +<td> + +> an indented paragraph, +> usually used for quotations + +</td> +<tr> +<td> +<pre> + #!/bin/sh -e + # code, indented four spaces + echo "Hello world" +</pre> +</td> +<td> + + #!/bin/sh -e + # code, indented four spaces + echo "Hello world" + +</td> +</tr> +<tr> +<td> +<pre> +* a bulleted list +* second item + - sublist + - and more +* back to main list + 1. this item has an ordered + 2. sublist + a) you can also use letters + b) another item +</pre> +</td> +<td> + +* a bulleted list +* second item + - sublist + - and more +* back to main list + 1. this item has an ordered + 2. sublist + a) you can also use letters + b) another item + +</td> +</tr> +<tr> +<td> +<pre> +Fruit Quantity +-------- ----------- +apples 30,200 +oranges 1,998 +pears 42 + +Table: Our fruit inventory +</pre> +</td> +<td> + +Fruit Quantity +-------- ----------- +apples 30,200 +oranges 1,998 +pears 42 + +Table: Our fruit inventory + +</td> +</tr> +</table> + +For headings, prefix a line with one or more `#` signs: one for a major heading, +two for a subheading, three for a subsubheading. Be sure to leave space before +and after the heading. + + # Markdown + + Text... + + ## Some examples... + + Text... + +## Wiki links + +Links to other wiki pages are formed this way: `[Page Name]()`. +(Gitit converts markdown links with empty targets into wikilinks.) + +To link to a wiki page using something else as the link text: +`[something else](Page Name)`. + +Note that page names may contain spaces and some special characters. +They need not be CamelCase. CamelCase words are *not* automatically +converted to wiki links. + +Wiki pages may be organized into directories. So, if you have +several pages on wine, you may wish to organize them like so: + + Wine/Pinot Noir + Wine/Burgundy + Wine/Cabernet Sauvignon + +Note that a wiki link `[Burgundy]()` that occurs inside the `Wine` +directory will link to `Wine/Burgundy`, and not to `Burgundy`. +To link to a top-level page called `Burgundy`, you'd have to use +`[Burgundy](/Burgundy)`. + +To link to a directory listing for a subdirectory, use a trailing +slash: `[Wine/]()` will link to a listing of the `Wine` subdirectory.