contrib/nitiwiki/README.md

   1 # nitiwiki, a simple wiki manager based on markdown.
   2
   3 Basically, nitiwiki compiles a set of markdown files into an HTML wiki.
   4
   5 The wiki content is structured by `sections` represented by the wiki folders. Sections can contain `articles` represented by markdown files.
   6
   7 Features:
   8
   9 * automatic wiki structure from folders hierarchy
  10 * automatic site menu
  11 * automatic sitemap
  12 * automatic summaries
  13 * easy and rapid templating
  14 * customizable section templates and menus
  15 * rsync synchronization
  16 * git synchronization
  17
  18 ## Wiki structure
  19
  20 Basic wiki structure:
  21
  22 ~~~raw
  23 root
  24 |- assets
  25 |- out
  26 |- pages
  27 |- templates
  28 |       |- footer.html
  29 |       |- header.html
  30 |       |- menu.html
  31 |       `- template.html
  32 `- config.ini
  33 ~~~
  34
  35 ### pages
  36
  37 This is where goes all the content of your wiki.
  38 Nitiwiki will render an article for each markdown file found in `pages`.
  39
  40 You can categorize your content in sections using sub-folders:
  41
  42 ~~~raw
  43 pages
  44 |- section1
  45 |       `- index.md
  46 |- section2
  47 |       `- index.md
  48 |- page1.md
  49 |- page2.md
  50 `- index.md
  51 ~~~
  52
  53 ### assets
  54
  55 This is where you store CSS and JavaScript files used in the design of your site.
  56
  57 You can also use this directory to put some images or other files that will be
  58 used in all your pages.
  59
  60 ~~~raw
  61 assets
  62 |- css
  63 |- js
  64 `- logo.png
  65 ~~~
  66
  67 ### templates
  68
  69 This folder contains the templates used to generate the HTML pages of your wiki.
  70
  71 The main template is called `template.html`.
  72 It contains the HTML structure of your pages and some macros that will be replaced
  73 by the wiki articles.
  74
  75 ### out
  76
  77 This is where your wiki will be rendered by nitiwiki.
  78 Do not put anything in this folder since it will be overwritten at the
  79 next wiki rendering.
  80
  81 The wiki rendering consists in:
  82
  83 1. copy the `assets` directory to `out`
  84 2. copy attached article files from `pages` to `out`
  85 3. translate markdown files from `pages` to html files in `out`
  86
  87 ### config.ini
  88
  89 This is the main config file of your wiki. For more details see [Configure the wiki](#Configure_the_wiki).
  90
  91 ## Manage the wiki
  92
  93 ### Create a new wiki
  94
  95 Just move to the directory where you want to store your source files and type:
  96
  97 ~~~sh
  98 nitiwiki init
  99 ~~~
 100
 101 This command will import the base structure of your wiki in the current directory.
 102 At this point nitiwiki has created the main configuration file of your site:
 103 `config.ini`.
 104
 105 ### Configure the wiki
 106
 107 All the nitiwiki configuration is done using
 108 [ini files](http://en.wikipedia.org/wiki/INI_file).
 109
 110 The wiki configuration is contained in the `config.ini` file located at the root
 111 directory of your wiki.
 112 This file can be edited to change nitiwiki settings.
 113
 114 Settings:
 115
 116 * `wiki.name`: Displayed name
 117 * `wiki.desc`: Long description
 118 * `wiki.logo`: Logo image url
 119 * `wiki.root_dir`: Absolute path of base directory
 120 * `wiki.source_dir`: Source directory (relative path from `wiki.root_dir`)
 121 * `wiki.out_dir`: Output directory (relative)
 122 * `wiki.assets_dir`: Assets directory (relative)
 123 * `wiki.templates_dir`: Templates directory (relative)
 124 * `wiki.template`: Wiki main template file
 125 * `wiki.header`: Wiki main header template file
 126 * `wiki.footer`: Wiki main footer template file
 127 * `wiki.menu`: Wiki main menu template file
 128 * `wiki.rsync_dir`: Directory used to rsync output
 129 * `wiki.git_origin`: Git origin used to fetch data
 130 * `wiki.git_branch`: Git branch used to fetch data
 131
 132 For more details on each option see `WikiConfig`.
 133
 134 ### Add content
 135
 136 To add content in your wiki simply add markdown files (with `.md` extension) into the `pages/` folder.
 137
 138 #### Write content
 139
 140 Nitiwiki only support content written in
 141 [markdown format](http://daringfireball.net/projects/markdown/).
 142
 143 #### Link wiki articles
 144
 145 In nitiwiki, linking to a section or an article is done using the *wikilinks*.
 146
 147 Wikilinks provide easy linking between pages of the wiki.
 148 To create a wikilink, just put the name of the page to link to in double brackets.
 149 For example `[[WikiLink]]`.
 150
 151 If you ever need to write something like `[[WikiLink]]` without creating a wikilink,
 152 just prefix it with a `\\`, like `\\[[WikiLink]]`.
 153
 154 There are some special linking precedence that come into play when linking between
 155 sections and sub-sections.
 156
 157 Nitiwiki will chose the first entry that match the given wikilinks in that order:
 158 1. Looks in the current section
 159 2. Looks in the current section children recursively
 160 3. Looks in the current section parents until root
 161
 162 To link to or from a subpage, you can use a regular wikilink that does not
 163 contain the name of the parent directory of the subpage.
 164 Nikiwiki descends the directory hierarchy looking for a page that matches your link.
 165
 166 For example, if `FooBar/SubPage` links to `OtherPage`, nikiwiki will first prefer
 167 pointing the link to `FooBar/SubPage/OtherPage` if it exists, next to
 168 `FooBar/OtherPage` and finally to `OtherPage` in the root of the wiki.
 169
 170 You can also specify a link that contains a relative section name,
 171 like `FooBar/OtherPage` to specify what page to link to.
 172
 173 You can also use `/` at the start of a link, to specify exactly which page to link to,
 174 when there are multiple pages with similar names and the link goes to the wrong page by default.
 175 For example, linking from `FooBar/SubPage` to `/OtherPage` will link to the `OtherPage`
 176 in the root of the wiki, even if there is a `FooBar/OtherPage`.
 177
 178 It's also possible to write a wikilink that uses something other than the page
 179 name as the link text.
 180 For example `[[Contact|Contact me!]]` links to the `Contact` page, but the link
 181 will appear like this: `Contact me!`.
 182
 183 You can link to an anchor inside a page, using something like `[[WikiLink#foo]]`.
 184
 185 #### Trails of Pages
 186
 187 Wikilinks, with the directive `trail`, will register the target page as an element of a trail.
 188 Each `trail` are chained together and will display navigational link `prev` for the previous page of the trail, `next` for the next page of the trail and `up` to go to the pages that has used the `trail` wikilink.
 189
 190 For instance, if the page `doc.md` has the following content:
 191
 192 ~~~md
 193 To use nitiwiki, first [[trail: install|install it]],
 194 then [[trail: simple_wiki|create a first wiki]].
 195
 196 You can also do advanced things like:
 197
 198 * [[trail: github|editing pages with github]]
 199 * [[trail: templating| adapting the templates]]
 200 ~~~
 201
 202 A trail will be made and will consist of the sequence of pages `install`, `simple_wiki`, `github` and `templating`.
 203 On each one of these pages, there will be links for the previous page, the next page and the `doc.md` page.
 204
 205 If a page includes trail wikilinks and is also the target for trail wikilinks, then the two trails are merged and pages will be visitable in a depth-first order.
 206 This nesting of trails can be used to have sections and sub-sections.
 207
 208 #### Render the wiki in HTML
 209
 210 Once you have done your changes, use:
 211
 212 ~~~sh
 213 nitiwiki --status
 214 ~~~
 215
 216 This will show the impacts of your changes on the wiki structure.
 217
 218 Then type:
 219
 220 ~~~sh
 221 nitiwiki --render
 222 ~~~
 223
 224 This will the generate the html output of your new content.
 225 The option `--force` can be used to regenerate all the wiki.
 226 This can be uselful when you perform changes on the template files.
 227
 228 ### Configure sections
 229
 230 Section appearance can be customized using config files.
 231
 232 Each section in the `pages/` folder can contain a `config.ini` file.
 233 Options set on a section will be propagated to all its children unless
 234 they have their own config file.
 235
 236 Allowed options are:
 237
 238 * `section.title`: Custom title for this section
 239 * `section.template`: Custom template file
 240 * `section.header`: Custom header template file
 241 * `section.footer`: Custom footer template file
 242 * `section.menu`: Custom menu template file
 243 * `section.is_hidden`: Set this to `true` will hide the section in all menus and
 244   sitemaps.
 245
 246 ## Customize templates
 247
 248 Templating your wiki involves modifying 4 template files:
 249
 250 * `template.html`
 251 * `header.html`
 252 * `footer.html`
 253 * `menu.html`
 254
 255 Each of these file contains an HTML skeletton used by nitiwiki to render your files.
 256 Templates can contains macros marked `%MACRO%` that will be replaced by dynamic content.
 257
 258 Every template can access to:
 259
 260 * `ROOT_URL`: Wiki root url
 261 * `TITLE`: Wiki name
 262 * `SUBTITLE`: Wiki description
 263 * `LOGO`: Wiki logo image path
 264
 265 Additional macros can be used in specialized templates.
 266
 267 ### Main template
 268
 269 The template file `template.html` represents the overall structure of your wiki pages.
 270
 271 ~~~html
 272 <!DOCTYPE html>
 273 <html>
 274         <head>
 275                 <title>%TITLE%</title>
 276                 <link href="%ROOT_URL%/assets/css/main.css" rel="stylesheet">
 277         </head>
 278         <body>
 279                 %HEADER%
 280                 %TOP_MENU%
 281                 <div>
 282                         %TRAIL%
 283                         %BODY%
 284                         %TRAIL%
 285                         %FOOTER%
 286                 </div>
 287         </body>
 288 </html>
 289 ~~~
 290
 291 Additionnal macros:
 292
 293 * `HEADER`: Wiki header (see [Header template](#Header_template))
 294 * `FOOTER`: Wiki footer (see [Footer template](#Footer_template))
 295 * `TOP_MENU`: Wiki top menu (see [Topmenu template](#Topmenu_template))
 296 * `HEADER`: Wiki header (see [Header template](#Header_template))
 297 * `BODY`: Wiki body content
 298 * `TRAIL`: content of the trail navigational links, if any (see [Trails of Pages](#Trails_of_Pages))
 299
 300 ### Header template
 301
 302 The template file `header.html` is generated on top of all the wiki pages.
 303
 304 ~~~html
 305 <header>
 306         <a href="#"><img src="%ROOT_URL%/%LOGO%" alt="logo"/></a>
 307         <h2>%SUBTITLE%</h2>
 308         <h1>%TITLE%</h1>
 309 </header>
 310 ~~~
 311
 312 ### Footer template
 313
 314 The template file `footer.html` is generated on the bottom of all the wiki pages.
 315
 316 ~~~html
 317 <footer>
 318         <p>%TITLE% &copy; %YEAR%</p>
 319         <p>last modification %GEN_TIME%</p>
 320 </footer>
 321 ~~~
 322
 323 Additionnal macros:
 324
 325 * `YEAR`: Current year
 326 * `GEN_TIME`: Page generation date
 327
 328 ### Topmenu template
 329
 330 The template file `menu.html` contains the menu structure generated on all your pages.
 331
 332 Its content can be static:
 333
 334 ~~~html
 335 <nav class="menu">
 336         <ul class="nav navbar-nav">
 337                 <li><a href="#">Home</a></li>
 338                 <li><a href="#">Page1</a></li>
 339                 <li><a href="#">Page2</a></li>
 340         </ul>
 341 </nav>
 342 ~~~
 343
 344 Or dynamic using the macro `MENUS`:
 345
 346 ~~~html
 347 <nav class="menu">
 348         <ul class="nav navbar-nav">
 349         %MENUS%
 350         </ul>
 351 </nav>
 352 ~~~
 353
 354 ## Advanced usages
 355
 356 ### Working with git
 357
 358 nitiwiki allows you to store your wiki changes in git.
 359 Using the option `--fetch` will update the local wiki instance
 360 according to git informations found in the config file.
 361
 362 Be sure to set `wiki.git_origin` and `wiki.git_branch`
 363 in order to correctly pull changes.
 364
 365 To automatically update your wiki when changes are pushed on the
 366 origin repository you can use the following command in a git hook:
 367
 368 ~~~sh
 369 nitiwiki --fetch --render
 370 ~~~
 371
 372 ### Working with a remote server
 373
 374 Sometimes you cannot do what you want on your webserver (like setting crons).
 375 For this purpose, nitiwiki provide a quick way to update a distant instance
 376 through `ssh` using `rsync`.
 377
 378 With the option `--rsync`, nitwiki will update a distant location with the
 379 last rendered output. This way you can manually update your webserver
 380 after changes or set a cron on a different server that you can control.
 381
 382 Using the following command in your cron will update the web server instance
 383 from git:
 384
 385 ~~~sh
 386 nitiwiki --fetch --render --rsync
 387 ~~~
 388
 389 Be sure to set `wiki.rsync_dir` in order to correctly push your changes.
 390 When using `--rsync`, keep in mind that the rendered output must be configured
 391 to work on the web server.
 392
 393 ### Serve and edit with nitiwiki_server
 394
 395 nitiwiki_server is a lightweight web server to publish the generated files
 396 and accept modifications from a web form.
 397
 398 The binary available in `bin/nitiwiki_server` is configured for simple usage or demo.
 399 The source of the server, at `src/wiki_edit`, can be tweaked for more advanced use.
 400 It is also possible to import the source and add an instance of `EditAction` to a custom nitcorn server.
 401
 402 To launch the server, change directory to the root of the wiki and run `nitiwiki_server`.
 403 It uses `config.ini` from the local directory and listen on localhost:8080.
 404 The template should define the macro `%EDIT%` and `config.ini` should define `wiki.edit=/edit/`.
 405 To limit who can edit the wiki, list the md5 sum of accepted passwords (one per line) in the local file `passwords`.