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.
131 Once you have done your changes, use:
135 This will show the impacts of your changes on the wiki structure.
141 This will the generate the html output of your new content.
142 The option `--force` can be used to regenerate all the wiki.
143 This can be uselful when you perform changes on the template files.
145 ### Configure sections
147 Section appearance can be customized using config files.
149 Each section in the `pages/` folder can contain a `config.ini` file.
150 Options set on a section will be propagated to all its children unless
151 they have their own config file.
155 * `section.title`: Custom title for this section
156 * `section.template`: Custom template file
157 * `section.header`: Custom header template file
158 * `section.footer`: Custom footer template file
159 * `section.menu`: Custom menu template file
160 * `section.is_hidden`: Set this to `true` will hide the section in all menus and
163 ## Customize templates
165 Templating your wiki involves modifying 4 template files:
172 Each of these file contains an HTML skeletton used by nitiwiki to render your files.
173 Templates can contains macros marked `%MACRO%` that will be replaced by dynamic content.
175 Every template can access to:
177 * `ROOT_URL`: Wiki root url
179 * `SUBTITLE`: Wiki description
180 * `LOGO`: Wiki logo image path
182 Additionnal macros can be used in specialized templates.
186 The template file `template.html` represents the overall structure of your wiki pages.
191 <title>%TITLE%</title>
192 <link href="%ROOT_URL%/assets/css/main.css" rel="stylesheet">
206 * `HEADER`: Wiki header (see [Header template](#Header_template))
207 * `FOOTER`: Wiki footer (see [Footer template](#Footer_template))
208 * `TOP_MENU`: Wiki top menu (see [Topmenu template](#Topmenu_template))
209 * `HEADER`: Wiki header (see [Header template](#Header_template))
210 * `BODY`: Wiki body content
214 The template file `header.html` is generated on top of all the wiki pages.
217 <a href="#"><img src="%ROOT_URL%/%LOGO%" alt="logo"/></a>
224 The template file `footer.html` is generated on the bottom of all the wiki pages.
227 <p>%TITLE% © %YEAR%</p>
228 <p>last modification %GEN_TIME%</p>
233 * `YEAR`: Current year
234 * `GEN_TIME`: Page generation date
238 The template file `menu.html` contains the menu structure generated on all your pages.
240 Its content can be static:
243 <ul class="nav navbar-nav">
244 <li><a href="#">Home</a></li>
245 <li><a href="#">Page1</a></li>
246 <li><a href="#">Page2</a></li>
250 Or dynamic using the macro `MENUS`:
253 <ul class="nav navbar-nav">
262 nitiwiki allows you to store your wiki changes in git.
263 Using the option `--fetch` will update the local wiki instance
264 according to git informations found in the config file.
266 Be sure to set `wiki.git_origin` and `wiki.git_branch`
267 in order to correctly pull changes.
269 To automatically update your wiki when changes are pushed on the
270 origin repository you can use the following command in a git hook:
272 nitiwiki --fetch --render
274 ### Working with a remote server
276 Sometimes you cannot do what you want on your webserver (like setting crons).
277 For this purpose, nitiwiki provide a quick way to update a distant instance
278 through `ssh` using `rsync`.
280 With the option `--rsync`, nitwiki will update a distant location with the
281 last rendered output. This way you can manually update your webserver
282 after changes or set a cron on a different server that you can control.
284 Using the following command in your cron will update the web server instance
287 nitiwiki --fetch --render --rsync
289 Be sure to set `wiki.rsync_dir` in order to correctly push your changes.
290 When using `--rsync`, keep in mind that the rendered output must be configured
291 to work on the web server and set `wiki.root_url` accordingly.