1 # nitiwiki, a simple wiki manager based on markdown.
3 Basically, nitiwiki compiles a set of markdown files into an HTML wiki.
5 The wiki content is structured by `sections` represented by the wiki folders. Sections can contain `articles` represented by markdown files.
9 * automatic wiki structure from folders hierarchy
13 * easy and rapid templating
14 * customizable section templates and menus
15 * rsync synchronization
35 This is where goes all the content of your wiki.
36 Nitiwiki will render an article for each markdown file found in `pages`.
38 You can categorize your content in sections using sub-folders:
51 This is where you store CSS and JavaScript files used in the design of your site.
53 You can also use this directory to put some images or other files that will be
54 used in all your pages.
63 This folder contains the templates used to generate the HTML pages of your wiki.
65 The main template is called `template.html`.
66 It contains the HTML structure of your pages and some macros that will be replaced
71 This is where your wiki will be rendered by nitiwiki.
72 Do not put anything in this folder since it will be overwritten at the
75 The wiki rendering consists in:
77 1. copy the `assets` directory to `out`
78 2. copy attached article files from `pages` to `out`
79 3. translate markdown files from `pages` to html files in `out`
83 This is the main config file of your wiki. For more details see [Configure the wiki](#Configure_the_wiki).
89 Just move to the directory where you want to store your source files and type:
93 This command will import the base structure of your wiki in the current directory.
94 At this point nitiwiki has created the main configuration file of your site:
97 ### Configure the wiki
99 All the nitiwiki configuration is done using
100 [ini files](http://en.wikipedia.org/wiki/INI_file).
102 The wiki configuration is contained in the `config.ini` file located at the root
103 directory of your wiki.
104 This file can be edited to change nitiwiki settings.
108 * `wiki.name`: Displayed name
109 * `wiki.desc`: Long description
110 * `wiki.logo`: Logo image url
111 * `wiki.root_url`: Base url used to resolve links
112 * `wiki.root_dir`: Absolute path of base directory
113 * `wiki.source_dir`: Source directory (relative path from `wiki.root_dir`)
114 * `wiki.out_dir`: Output directory (relative)
115 * `wiki.assets_dir`: Assets directory (relative)
116 * `wiki.templates_dir`: Templates directory (relative)
117 * `wiki.template`: Wiki main template file
118 * `wiki.header`: Wiki main header template file
119 * `wiki.footer`: Wiki main footer template file
120 * `wiki.menu`: Wiki main menu template file
121 * `wiki.rsync_dir`: Directory used to rsync output
122 * `wiki.git_origin`: Git origin used to fetch data
123 * `wiki.git_branch`: Git branch used to fetch data
125 For more details on each option see `WikiConfig`.
129 To add content in your wiki simply add markdown files (with `.md` extension) into the `pages/` folder.
133 Nitiwiki only support content written in
134 [markdown format](http://daringfireball.net/projects/markdown/).
136 #### Link wiki articles
138 In nitiwiki, linking to a section or an article is done using the *wikilinks*.
140 Wikilinks provide easy linking between pages of the wiki.
141 To create a wikilink, just put the name of the page to link to in double brackets.
142 For example `[[WikiLink]]`.
144 If you ever need to write something like `[[WikiLink]]` without creating a wikilink,
145 just prefix it with a `\\`, like `\\[[WikiLink]]`.
147 There are some special linking precedence that come into play when linking between
148 sections and sub-sections.
150 Nitiwiki will chose the first entry that match the given wikilinks in that order:
151 1. Looks in the current section
152 2. Looks in the current section children recursively
153 3. Looks in the current section parents until root
155 To link to or from a subpage, you can use a regular wikilink that does not
156 contain the name of the parent directory of the subpage.
157 Nikiwiki descends the directory hierarchy looking for a page that matches your link.
159 For example, if `FooBar/SubPage` links to `OtherPage`, nikiwiki will first prefer
160 pointing the link to `FooBar/SubPage/OtherPage` if it exists, next to
161 `FooBar/OtherPage` and finally to `OtherPage` in the root of the wiki.
163 You can also specify a link that contains a relative section name,
164 like `FooBar/OtherPage` to specify what page to link to.
166 You can also use `/` at the start of a link, to specify exactly which page to link to,
167 when there are multiple pages with similar names and the link goes to the wrong page by default.
168 For example, linking from `FooBar/SubPage` to `/OtherPage` will link to the `OtherPage`
169 in the root of the wiki, even if there is a `FooBar/OtherPage`.
171 It's also possible to write a wikilink that uses something other than the page
172 name as the link text.
173 For example `[[Contact|Contact me!]]` links to the `Contact` page, but the link
174 will appear like this: `Contact me!`.
176 You can link to an anchor inside a page, using something like `[[WikiLink#foo]]`.
178 #### Render the wiki in HTML
180 Once you have done your changes, use:
184 This will show the impacts of your changes on the wiki structure.
190 This will the generate the html output of your new content.
191 The option `--force` can be used to regenerate all the wiki.
192 This can be uselful when you perform changes on the template files.
194 ### Configure sections
196 Section appearance can be customized using config files.
198 Each section in the `pages/` folder can contain a `config.ini` file.
199 Options set on a section will be propagated to all its children unless
200 they have their own config file.
204 * `section.title`: Custom title for this section
205 * `section.template`: Custom template file
206 * `section.header`: Custom header template file
207 * `section.footer`: Custom footer template file
208 * `section.menu`: Custom menu template file
209 * `section.is_hidden`: Set this to `true` will hide the section in all menus and
212 ## Customize templates
214 Templating your wiki involves modifying 4 template files:
221 Each of these file contains an HTML skeletton used by nitiwiki to render your files.
222 Templates can contains macros marked `%MACRO%` that will be replaced by dynamic content.
224 Every template can access to:
226 * `ROOT_URL`: Wiki root url
228 * `SUBTITLE`: Wiki description
229 * `LOGO`: Wiki logo image path
231 Additionnal macros can be used in specialized templates.
235 The template file `template.html` represents the overall structure of your wiki pages.
240 <title>%TITLE%</title>
241 <link href="%ROOT_URL%/assets/css/main.css" rel="stylesheet">
255 * `HEADER`: Wiki header (see [Header template](#Header_template))
256 * `FOOTER`: Wiki footer (see [Footer template](#Footer_template))
257 * `TOP_MENU`: Wiki top menu (see [Topmenu template](#Topmenu_template))
258 * `HEADER`: Wiki header (see [Header template](#Header_template))
259 * `BODY`: Wiki body content
263 The template file `header.html` is generated on top of all the wiki pages.
266 <a href="#"><img src="%ROOT_URL%/%LOGO%" alt="logo"/></a>
273 The template file `footer.html` is generated on the bottom of all the wiki pages.
276 <p>%TITLE% © %YEAR%</p>
277 <p>last modification %GEN_TIME%</p>
282 * `YEAR`: Current year
283 * `GEN_TIME`: Page generation date
287 The template file `menu.html` contains the menu structure generated on all your pages.
289 Its content can be static:
292 <ul class="nav navbar-nav">
293 <li><a href="#">Home</a></li>
294 <li><a href="#">Page1</a></li>
295 <li><a href="#">Page2</a></li>
299 Or dynamic using the macro `MENUS`:
302 <ul class="nav navbar-nav">
311 nitiwiki allows you to store your wiki changes in git.
312 Using the option `--fetch` will update the local wiki instance
313 according to git informations found in the config file.
315 Be sure to set `wiki.git_origin` and `wiki.git_branch`
316 in order to correctly pull changes.
318 To automatically update your wiki when changes are pushed on the
319 origin repository you can use the following command in a git hook:
321 nitiwiki --fetch --render
323 ### Working with a remote server
325 Sometimes you cannot do what you want on your webserver (like setting crons).
326 For this purpose, nitiwiki provide a quick way to update a distant instance
327 through `ssh` using `rsync`.
329 With the option `--rsync`, nitwiki will update a distant location with the
330 last rendered output. This way you can manually update your webserver
331 after changes or set a cron on a different server that you can control.
333 Using the following command in your cron will update the web server instance
336 nitiwiki --fetch --render --rsync
338 Be sure to set `wiki.rsync_dir` in order to correctly push your changes.
339 When using `--rsync`, keep in mind that the rendered output must be configured
340 to work on the web server and set `wiki.root_url` accordingly.