Pandoc Powered Wiki

File Structure

File structure on the server

  • /pages - markup files with online edit support
  • /templates - template files where converted markup files are included
  • /config - configuration files
  • /public - static files
  • /public/stylesheets - common CSS files
  • /public/javascript - common js files
  • /public/files - uploaded files with online edit support
  • /public/pages - static html files converted from markup


View page

GET: /route/page

Server just return static pre-generated file from /public/ folder. This can be handled by web server directly.

Review page

GET: /review/route/page

This view can highlight dead page/file links or other formatting hints.

Edit page

GET: /edit/route/page

Edit view allow page markup to be edited directly.

Possible features

  • optional WYSIWYG view could be shown for easier editing
  • code completion for page/file references would be useful

Post update

POST: /edit/route/page
  1. Tries to convert markup via rendering engine (pandoc) and store converted file to /public/published
  2. New page references are extracted and created as new empty pages
  3. Commit change to version control system (hg)
  4. Then an automatic redirect to (re-)view page

A page meta header (in JSON) can include:

  • Markup language
  • Template

Example header

    template: "default"
    markup: "markdown"

Page text ...

Current markup for page is included afterwards.

Upload file

Handle file upload to /public/files

Version history and revert

Show version history from vcs and support revert to a previous version is probably best supported by version control system directly.

Show pages

GET: /allpages

A list of all pages (and folder structure) with the following parameters:

  • Created time
  • Last modified time
  • Markup size

Special markup

  • <!include page> - include one page in another
  • templates may include a page which makes it possible to have a dynamic header, footer and navigation
  • [page](local/ref) - regular markdown links are used to reference local pages (no special page markup is required)

Redirect to edit page for new pages

NGINX may be used to automatically redirect (try_files) to edit page when static content file is not found.

Javascript could be used to add new CSS class to links that doesn’t exist, but review view is an alternative solution.