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_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
 124
 125 For more details on each option see `WikiConfig`.
 126
 127 ### Add content
 128
 129 To add content in your wiki simply add markdown files (with `.md` extension) into the `pages/` folder.
 130
 131 Once you have done your changes, use:
 132
 133         nitiwiki --status
 134
 135 This will show the impacts of your changes on the wiki structure.
 136
 137 Then type:
 138
 139         nitiwiki --render
 140
 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.
 144
 145 ### Configure sections
 146
 147 Section appearance can be customized using config files.
 148
 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.
 152
 153 Allowed options are:
 154
 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
 161   sitemaps.
 162
 163 ## Customize templates
 164
 165 Templating your wiki involves modifying 4 template files:
 166
 167 * `template.html`
 168 * `header.html`
 169 * `footer.html`
 170 * `menu.html`
 171
 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.
 174
 175 Every template can access to:
 176
 177 * `ROOT_URL`: Wiki root url
 178 * `TITLE`: Wiki name
 179 * `SUBTITLE`: Wiki description
 180 * `LOGO`: Wiki logo image path
 181
 182 Additionnal macros can be used in specialized templates.
 183
 184 ### Main template
 185
 186 The template file `template.html` represents the overall structure of your wiki pages.
 187
 188         <!DOCTYPE html>
 189         <html>
 190                 <head>
 191                         <title>%TITLE%</title>
 192                         <link href="%ROOT_URL%/assets/css/main.css" rel="stylesheet">
 193                 </head>
 194                 <body>
 195                         %HEADER%
 196                         %TOP_MENU%
 197                         <div>
 198                                 %BODY%
 199                                 %FOOTER%
 200                         </div>
 201                 </body>
 202         </html>
 203
 204 Additionnal macros:
 205
 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
 211
 212 ### Header template
 213
 214 The template file `header.html` is generated on top of all the wiki pages.
 215
 216         <header>
 217                 <a href="#"><img src="%ROOT_URL%/%LOGO%" alt="logo"/></a>
 218                 <h2>%SUBTITLE%</h2>
 219                 <h1>%TITLE%</h1>
 220         </header>
 221
 222 ### Footer template
 223
 224 The template file `footer.html` is generated on the bottom of all the wiki pages.
 225
 226         <footer>
 227                 <p>%TITLE% &copy; %YEAR%</p>
 228                 <p>last modification %GEN_TIME%</p>
 229         </footer>
 230
 231 Additionnal macros:
 232
 233 * `YEAR`: Current year
 234 * `GEN_TIME`: Page generation date
 235
 236 ### Topmenu template
 237
 238 The template file `menu.html` contains the menu structure generated on all your pages.
 239
 240 Its content can be static:
 241
 242         <nav class="menu">
 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>
 247                 </ul>
 248         </nav>
 249
 250 Or dynamic using the macro `MENUS`:
 251
 252         <nav class="menu">
 253                 <ul class="nav navbar-nav">
 254                 %MENUS%
 255                 </ul>
 256         </nav>
 257
 258 ## Advanced usages
 259
 260 ### Working with git
 261
 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.
 265
 266 Be sure to set `wiki.git_origin` and `wiki.git_branch`
 267 in order to correctly pull changes.
 268
 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:
 271
 272         nitiwiki --fetch --render
 273
 274 ### Working with a remote server
 275
 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`.
 279
 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.
 283
 284 Using the following command in your cron will update the web server instance
 285 from git:
 286
 287         nitiwiki --fetch --render --rsync
 288
 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.