This chapter explain how to register a Git repository and what it should contain.
- give a name to this repository (ex: mywiki)
- create a new section in profiles.ini.php, with this name and a prefix "gtwrepo:" (ex: "gtwrepo:mywiki")
- indicate the path to this repository in a "path" parameter. This should be a bare repository or the .git directory of your repository. You can use the alias "app:" as prefix to indicate a path relative to the gitiwiki directory. There is a gitiwiki/var/repositories/ where you can put your repository. However it can be anywhere on your hard drive.
- in the "branch" parameter, indicate the branch that gitiwiki should use
- in the "basepath" parameter, indicate the directory inside the repository from which file will be retrieve. By default, its value is "/".
[gtwrepo:mywiki]
path=app:var/repositories/mywiki/.git
; is equals to
; path=/home/myaccount/mysite/mywiki/gitiwiki/var/repositories/mywiki/.git
branch=master
title= A title
basepath="/"
You can also indicate a title for the list of wikis.
Your repository can contain many type of files:
- wiki pages, with the
.wiki
or.gtw
extension. The syntax is the dokuwiki syntax. Later, gitiwiki will supports markdown and other syntaxes etc. - hidden files (see below)
- a .config.ini file at the root of the repository, containing some configuration values for gitiwiki.
- meta files: file that can contain meta information about a file (useful for images, redirections...)
- and any other files. Gitiwiki simply send them to the browser, with the right mime-type if it knows it.
This is a file (in the ini format) that can contain some parameters for Gitiwiki:
- "multiviews" to indicate multiview extensions (see below)
- global redirections informations (see below)
- and protocol aliases, see urls
Notice that you don't have to indicate the extension for wiki page, in URLs. For example,
if you target article.wiki, you can indicate simply article
.
Gitiwiki will then try different extensions, indicated into a .config.ini
file at
the root of your repository.
Here is an example of .config.ini
multiviews=".wiki, .html, .txt"
With this configuration, when the url myarticle
is given, Gitiwiki try to load first
the file myarticle.wiki. If it doesn't exist, it tries then to load myarticle.html,
and then myarticle.txt. If none of file are existing, a 404 error is returned.
The home page should be stored into a file named "index" with one of the extension indicated into the multiviews parameter. For example: index.wiki.
When the url correspond to a directory, Gitiwiki tries to load first a file with the same name + a prefix indicated into the multiviews option, in the parent directory.
For exemple, if the url is dir/subdir/
, it searches the file dir/subdir.wiki
(and
then dir/subdir.html etc).
If this file doesn't exist, it searches an index.wiki
(or index.html
etc) file
inside the directory, so dir/subdir/index.wiki
, then dir/subdir/index.html
and so on.
Gitiwiki supports redirection. When you rename a file or move it into an other directory, it is a good practice to do a HTTP redirection when the browser tries to load the old file. It is better for search engines like Google for example.
When a file does not exist, Gitiwiki doesn't search into the git repository if it was moved or renamed, because Git does not have a quick way to know it, and so it could be take times and ressources to search. When there are several merge, it can be very difficult and it could even fails. If the file have been moved and modified at the same time, it is impossible to find this rename.
So you have to indicate these changes into the .config.ini
file, in the redirection
parameter. In the future, when editing/renaming a file will be possible with the browser,
this parameter will be filled automatically of course.
Here an example (since there are several redirection parameters, you should use []
):
redirection[] = "^manual2\.old/(.*)$ -> manual2/%s"
redirection[] = "^manual2/unexistant -> manual2/article2"
redirection[] = "^manual/moved-page-outside.txt -> //new-page.txt"
redirection[] = "^something/elsewhere.txt -> http://jelix.org/new-page.txt"
A redirection information begins with a regular expression that matches the old url, followed by an arrow "->", followed by the new url (which will be processed by sprintf to do replacements). Not that new urls used the same rules as urls in links (see above).
The first redirection, redirects all URLS starting with "manual2.old/" to URLS starting with "manual2/". It means: all files into the manual2.old directory were moved into the manual2 directory.
The second redirection, redirects an URL of a simple file, to a new URL. It means: manual2/unexistant has been renamed to manual2/article2
The third redirection means that the file moved-page-outside.txt of the wiki have been moved to new-page.txt which is now outside the wiki, but it is still in the same web site.
The fourth redirection means that elsewhere.txt have been moved to an other web site.
You can also indicate redirections in meta files. See below.
Hidden files
All files that have names starting with a dot, will be ignored. All files inside a directory that have a name starting with a dot, will be ignored two.
'ignored' means that a user cannot access to it, a simple "404" error will be returned.
Meta files are files containing extra-information about a specific file. A meta
file is stored in a .meta
directory in the same directory of the target file.
its name is the same name of the target file + '.ini'.
For example, the meta file of mydir/article.wiki is mydir/.meta/article.wiki.ini.
You can have meta file for any file: images, pdf, text etc.
A meta file is an "ini" file, and could contain a title, a description, some keywords etc..
For the moment, only a "redirection" parameter is supported. It is an alternative way to the .config.ini file, to indicate a redirection. It means too that you can have a meta file for an unexistant file.
For example, you moved a file mydir/article.wiki to otherdir/article.wiki, you can have a mydir/.meta/article.wiki.ini file indicating:
redirection="/otherdir/article.wiki"