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