From 9d431740a3e6a7caa09a57504856b5d1a4710a14 Mon Sep 17 00:00:00 2001 From: User Date: Tue, 13 Oct 2009 02:38:56 +0000 Subject: gitit\! --- Front Page.page | 13 ++ Gitit User's Guide.page | 538 ++++++++++++++++++++++++++++++++++++++++++++++++ Help.page | 325 +++++++++++++++++++++++++++++ 3 files changed, 876 insertions(+) create mode 100644 Front Page.page create mode 100644 Gitit User's Guide.page create mode 100644 Help.page diff --git a/Front Page.page b/Front Page.page new file mode 100644 index 0000000..a9ac8d8 --- /dev/null +++ b/Front Page.page @@ -0,0 +1,13 @@ +# 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](). + +asdf \ No newline at end of file diff --git a/Gitit User's Guide.page b/Gitit User's Guide.page new file mode 100644 index 0000000..c2dbde0 --- /dev/null +++ b/Gitit User's Guide.page @@ -0,0 +1,538 @@ +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][] or [darcs][] 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, or HTML +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 + +You can see a running demo at . + +[git]: http://git.or.cz +[darcs]: http://darcs.net +[pandoc]: http://johnmacfarlane.net/pandoc +[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 +------------------------------ + +You'll need the [GHC][] compiler and the [cabal-install][] tool. GHC can +be downloaded [here][]. Note that, starting with release 0.5, GHC 6.10 +or higher is required. For [cabal-install][] on *nix, follow the [quick +install][] instructions. + +[GHC]: http://www.haskell.org/ghc/ +[here]: http://www.haskell.org/ghc/ +[cabal-install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall +[quick install]: http://hackage.haskell.org/trac/hackage/wiki/CabalInstall#Quick Installation on Unix + +Once you've got cabal-install, installing gitit is trivial: + + cabal update + cabal install gitit + +These commands 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. + +Optional syntax highlighting support +------------------------------------ + +If pandoc was compiled with optional syntax highlighting support, +this will be available in gitit too. This feature is recommended +if you plan to display source code on your wiki. + +Highlighting support requires the [pcre][] library, so make sure that +is installed before continuing. + +[pcre]: http://www.pcre.org/ + +To install gitit with highlighting support, first ensure that pandoc +is compiled with highlighting support, then install gitit as above: + + cabal install pandoc -fhighlighting --reinstall + cabal install gitit + +Running gitit +------------- + +To run gitit, you'll need [git][] in your system path. (Or +[darcs][], if you're using darcs 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 +. + +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://johnmacfarlane.net/pandoc/README.html#delimited-code-blocks + +Configuring and customizing gitit +================================= + +Configuration options +--------------------- + +You can set some configuration options when starting gitit, using the +option `-f [filename]`. To get a copy of the default configuration file, +which you can customize, just type: + + gitit --print-default-config > default.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 darcs instead of 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 + +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`. + +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/templates` by copying +the file into `templates` and modifying it. 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 download page]: http://sourceforge.net/project/showfiles.php?group_id=172663 + +Plugins +======= + +Plugins are small Haskell programs that transform a wiki page after it +has been converted from Markdown or RST. 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 via git or darcs +=================================== + +All the pages and uploaded files are stored in a git or darcs +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`. + +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 and highlighted source files 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. + +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` module is +loaded, and set up a virtual host with the following configuration: + + + ServerName wiki.mysite.com + DocumentRoot /var/www/ + RewriteEngine On + ProxyPreserveHost On + ProxyRequests Off + + + Order deny,allow + Allow from all + + + 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 + + + +Reload your apache configuration 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 + + + Order deny,allow + Allow from all + + + ProxyPass /wiki/ http://127.0.0.1:5001/ + + + SetOutputFilter proxy-html + ProxyPassReverse / + ProxyHTMLURLMap / /wiki/ + RequestHeader unset Accept-Encoding + + +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 +. + +There is a mailing list for users and developers at +. + +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. +- Justin Bogner improved the appearance of the preview button. +- Kohei Ozaki contributed the ImgTexPlugin. +- 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 new file mode 100644 index 0000000..7caa4e9 --- /dev/null +++ b/Help.page @@ -0,0 +1,325 @@ +# 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://johnmacfarlane.net/pandoc +[pandoc User's Guide]: http://johnmacfarlane.net/pandoc/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: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
`*emphasized text*`*emphasized text*
`**strong emphasis**`**strong emphasis**
`` `literal text` ```literal text`
`\*escaped special characters\*`\*escaped special characters\*
`[external link](http://google.com)`[external link](http://google.com)
`![folder](/img/icons/folder.png)`![folder](/img/icons/folder.png)
Wikilink: `[Front Page]()`Wikilink: [Front Page]()
`H~2~O`H~2~O
`10^100^`10^100^
`~~strikeout~~`~~strikeout~~
+`$x = \frac{{ - b \pm \sqrt {b^2 - 4ac} }}{{2a}}$` + +$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.] +
+`A simple footnote.^[Or is it so simple?]` + +A simple footnote.^[Or is it so simple?] +
+
+> an indented paragraph,
+> usually used for quotations
+
+		 + +> an indented paragraph, +> usually used for quotations + +
+
+    #!/bin/sh -e
+    # code, indented four spaces
+    echo "Hello world"
+
+		 + + #!/bin/sh -e + # code, indented four spaces + echo "Hello world" + +
+
+* 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
+
+		 + +* 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 + +
+
+Fruit        Quantity
+--------  -----------
+apples         30,200
+oranges         1,998
+pears              42
+
+Table:  Our fruit inventory
+
+		 + +Fruit Quantity +-------- ----------- +apples 30,200 +oranges 1,998 +pears 42 + +Table: Our fruit inventory + +
+ +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. -- cgit v1.2.3