Basic wiki structure:
- root
- |- assets
- |- out
- |- pages
- |- templates
- | |- footer.html
- | |- header.html
- | |- menu.html
- | `- template.html
- `- config.ini
+~~~raw
+root
+|- assets
+|- out
+|- pages
+|- templates
+| |- footer.html
+| |- header.html
+| |- menu.html
+| `- template.html
+`- config.ini
+~~~
### pages
You can categorize your content in sections using sub-folders:
- pages
- |- section1
- | `- index.md
- |- section2
- | `- index.md
- |- page1.md
- |- page2.md
- `- index.md
+~~~raw
+pages
+|- section1
+| `- index.md
+|- section2
+| `- index.md
+|- page1.md
+|- page2.md
+`- index.md
+~~~
### assets
You can also use this directory to put some images or other files that will be
used in all your pages.
- assets
- |- css
- |- js
- `- logo.png
+~~~raw
+assets
+|- css
+|- js
+`- logo.png
+~~~
### templates
Just move to the directory where you want to store your source files and type:
- nitiwiki init
+~~~sh
+nitiwiki init
+~~~
This command will import the base structure of your wiki in the current directory.
At this point nitiwiki has created the main configuration file of your site:
* `wiki.name`: Displayed name
* `wiki.desc`: Long description
* `wiki.logo`: Logo image url
-* `wiki.root_url`: Base url used to resolve links
* `wiki.root_dir`: Absolute path of base directory
* `wiki.source_dir`: Source directory (relative path from `wiki.root_dir`)
* `wiki.out_dir`: Output directory (relative)
To add content in your wiki simply add markdown files (with `.md` extension) into the `pages/` folder.
+#### Write content
+
+Nitiwiki only support content written in
+[markdown format](http://daringfireball.net/projects/markdown/).
+
+#### Link wiki articles
+
+In nitiwiki, linking to a section or an article is done using the *wikilinks*.
+
+Wikilinks provide easy linking between pages of the wiki.
+To create a wikilink, just put the name of the page to link to in double brackets.
+For example `[[WikiLink]]`.
+
+If you ever need to write something like `[[WikiLink]]` without creating a wikilink,
+just prefix it with a `\\`, like `\\[[WikiLink]]`.
+
+There are some special linking precedence that come into play when linking between
+sections and sub-sections.
+
+Nitiwiki will chose the first entry that match the given wikilinks in that order:
+1. Looks in the current section
+2. Looks in the current section children recursively
+3. Looks in the current section parents until root
+
+To link to or from a subpage, you can use a regular wikilink that does not
+contain the name of the parent directory of the subpage.
+Nikiwiki descends the directory hierarchy looking for a page that matches your link.
+
+For example, if `FooBar/SubPage` links to `OtherPage`, nikiwiki will first prefer
+pointing the link to `FooBar/SubPage/OtherPage` if it exists, next to
+`FooBar/OtherPage` and finally to `OtherPage` in the root of the wiki.
+
+You can also specify a link that contains a relative section name,
+like `FooBar/OtherPage` to specify what page to link to.
+
+You can also use `/` at the start of a link, to specify exactly which page to link to,
+when there are multiple pages with similar names and the link goes to the wrong page by default.
+For example, linking from `FooBar/SubPage` to `/OtherPage` will link to the `OtherPage`
+in the root of the wiki, even if there is a `FooBar/OtherPage`.
+
+It's also possible to write a wikilink that uses something other than the page
+name as the link text.
+For example `[[Contact|Contact me!]]` links to the `Contact` page, but the link
+will appear like this: `Contact me!`.
+
+You can link to an anchor inside a page, using something like `[[WikiLink#foo]]`.
+
+#### Trails of Pages
+
+Wikilinks, with the directive `trail`, will register the target page as an element of a trail.
+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.
+
+For instance, if the page `doc.md` has the following content:
+
+~~~md
+To use nitiwiki, first [[trail: install|install it]],
+then [[trail: simple_wiki|create a first wiki]].
+
+You can also do advanced things like:
+
+* [[trail: github|editing pages with github]]
+* [[trail: templating| adapting the templates]]
+~~~
+
+A trail will be made and will consist of the sequence of pages `install`, `simple_wiki`, `github` and `templating`.
+On each one of these pages, there will be links for the previous page, the next page and the `doc.md` page.
+
+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.
+This nesting of trails can be used to have sections and sub-sections.
+
+#### Render the wiki in HTML
+
Once you have done your changes, use:
- nitiwiki --status
+~~~sh
+nitiwiki --status
+~~~
This will show the impacts of your changes on the wiki structure.
Then type:
- nitiwiki --render
+~~~sh
+nitiwiki --render
+~~~
This will the generate the html output of your new content.
The option `--force` can be used to regenerate all the wiki.
* `SUBTITLE`: Wiki description
* `LOGO`: Wiki logo image path
-Additionnal macros can be used in specialized templates.
+Additional macros can be used in specialized templates.
### Main template
The template file `template.html` represents the overall structure of your wiki pages.
- <!DOCTYPE html>
- <html>
- <head>
- <title>%TITLE%</title>
- <link href="%ROOT_URL%/assets/css/main.css" rel="stylesheet">
- </head>
- <body>
- %HEADER%
- %TOP_MENU%
- <div>
- %BODY%
- %FOOTER%
- </div>
- </body>
- </html>
+~~~html
+<!DOCTYPE html>
+<html>
+ <head>
+ <title>%TITLE%</title>
+ <link href="%ROOT_URL%/assets/css/main.css" rel="stylesheet">
+ </head>
+ <body>
+ %HEADER%
+ %TOP_MENU%
+ <div>
+ %TRAIL%
+ %BODY%
+ %TRAIL%
+ %FOOTER%
+ </div>
+ </body>
+</html>
+~~~
Additionnal macros:
* `TOP_MENU`: Wiki top menu (see [Topmenu template](#Topmenu_template))
* `HEADER`: Wiki header (see [Header template](#Header_template))
* `BODY`: Wiki body content
+* `TRAIL`: content of the trail navigational links, if any (see [Trails of Pages](#Trails_of_Pages))
### Header template
The template file `header.html` is generated on top of all the wiki pages.
- <header>
- <a href="#"><img src="%ROOT_URL%/%LOGO%" alt="logo"/></a>
- <h2>%SUBTITLE%</h2>
- <h1>%TITLE%</h1>
- </header>
+~~~html
+<header>
+ <a href="#"><img src="%ROOT_URL%/%LOGO%" alt="logo"/></a>
+ <h2>%SUBTITLE%</h2>
+ <h1>%TITLE%</h1>
+</header>
+~~~
### Footer template
The template file `footer.html` is generated on the bottom of all the wiki pages.
- <footer>
- <p>%TITLE% © %YEAR%</p>
- <p>last modification %GEN_TIME%</p>
- </footer>
+~~~html
+<footer>
+ <p>%TITLE% © %YEAR%</p>
+ <p>last modification %GEN_TIME%</p>
+</footer>
+~~~
Additionnal macros:
Its content can be static:
- <nav class="menu">
- <ul class="nav navbar-nav">
- <li><a href="#">Home</a></li>
- <li><a href="#">Page1</a></li>
- <li><a href="#">Page2</a></li>
- </ul>
- </nav>
+~~~html
+<nav class="menu">
+ <ul class="nav navbar-nav">
+ <li><a href="#">Home</a></li>
+ <li><a href="#">Page1</a></li>
+ <li><a href="#">Page2</a></li>
+ </ul>
+</nav>
+~~~
Or dynamic using the macro `MENUS`:
- <nav class="menu">
- <ul class="nav navbar-nav">
- %MENUS%
- </ul>
- </nav>
+~~~html
+<nav class="menu">
+ <ul class="nav navbar-nav">
+ %MENUS%
+ </ul>
+</nav>
+~~~
## Advanced usages
To automatically update your wiki when changes are pushed on the
origin repository you can use the following command in a git hook:
- nitiwiki --fetch --render
+~~~sh
+nitiwiki --fetch --render
+~~~
### Working with a remote server
Using the following command in your cron will update the web server instance
from git:
- nitiwiki --fetch --render --rsync
+~~~sh
+nitiwiki --fetch --render --rsync
+~~~
Be sure to set `wiki.rsync_dir` in order to correctly push your changes.
When using `--rsync`, keep in mind that the rendered output must be configured
-to work on the web server and set `wiki.root_url` accordingly.
+to work on the web server.
+
+### Serve and edit with nitiwiki_server
+
+nitiwiki_server is a lightweight web server to publish the generated files
+and accept modifications from a web form.
+
+The binary available in `bin/nitiwiki_server` is configured for simple usage or demo.
+The source of the server, at `src/wiki_edit`, can be tweaked for more advanced use.
+It is also possible to import the source and add an instance of `EditAction` to a custom nitcorn server.
+
+To launch the server, change directory to the root of the wiki and run `nitiwiki_server`.
+It uses `config.ini` from the local directory and listen on localhost:8080.
+The template should define the macro `%EDIT%` and `config.ini` should define `wiki.edit=/edit/`.
+To limit who can edit the wiki, list the md5 sum of accepted passwords (one per line) in the local file `passwords`.
nitlanguage / nit.git / blobdiff