Shellwiki

Features

• Markdown Wiki Syntax

  The wiki syntax is based on John Grubers Markdown with extensions inspired by Pandoc, PHP Markdown Extra, and Github Flavored Markdown. Additional Macros are provided to enable functions like an automatic table of contents, listing of sub pages, etc.

  See Markdown
  and Macros

• Plain file Storage

  Pages and attachments are stored as plain files on disk. There is no need for a separate database system.

• Git revisioning

  If git is available on the web server, pages can be revisioned so that past versions can be revisited. Optionally attachments can be revisioned too. Server administrators may use the git archives to synchronise sites across servers by adding their own mechanics.

• Multisite Installation

  Code and data directories are stricly separate on the server. Directory pathes are obtained from environment variables, so that multiple sites can be served from the same installation directory.

  See also: Installation

• Semantic HTML5

  for accessible rendering of pages

• Descriptive Page Names

  URLs of pages can be freely provided by the user. User access can be constrained to specific sub pages. Within their access permissions users can move and rename pages as they like.

• File Upload / Attachment

  While pages are merely text documents themselves, users can upload additional attachments and link to them in a page. Images and media files can be embedded directly into a page.

• Image scaling

  If ImageMagick is available on the web server, huge attachment images are automatically compressed and scaled to HD resolution when referred to in a page. Of course the original version can still be linked to.

• Permissions via ACL

  Grant read/write access for pages and sub-pages

• User provided CSS

  Aside from full theming in the installation directory, pages can be styled using CSS files uploaded as attachments.

• No reliance on Javascript

  Authors and visitors can use the site without being forced to run untrusted code. The main theme still provides collapsible menus and a responsive layout.

• Complete GDPR Compliance without consent walls

  Because shellwiki does not track page visitors and does not serve cookies to visitors by default it does not need to coerce visitors into handling GDPR "consent" forms.

  (Login for authors still requires a session cookie)

• True multilanguage capability

  • Pages can be translated
  • Switching language does not require a cookie
  • Fallback language for missing translations
  • Users stay on a translated version, even if single page translations are missing

• Full text indexing and search

  Shellwiki contains its own basic text indexer without external dependencies.

• Extensibility through

  • Themes
  • Macros
  • URL Handlers
  • Custom Syntax parsers

Dependencies

Shellwiki is based on cgilite, which is included in the installation. It is written in posix compliant shell script, and the markdown renderer is written in posix compliant AWK. The entire wiki system can run with nothing more than a busybox. In fact it can be served from the rescue shell in a Debian initrd, or from an OpenWRT router.

Its precise requirements are:

• A Posix Shell (as provided by busybox, but bash is OK)

• An AWK interpreter (as provided by busybox, but GNU AWK is OK)

  • mawk and nawk will currently not work

• inetd (as provided by busybox)

  or any CGI-Capable web server

• Optional: GIT for revisioning

• Optional: ImageMagick for image compression

• Optional: Sendmail for sending password reminders, etc.

Installation

Also see → installation/

You can try out shellwiki right now using busybox:

~$ git clone https://git.plutz.net/git/shellwiki ~/shellwiki
~$ _DATA=~/wikidata busybox nc -llp 1080 -e ~/shellwiki/index.cgi

For additional examples, regarding permanent installation and configuration in webservers see installation/.

Syntax

The wiki syntax is based on John Grubers Markdown with extensions borrowed from Pandoc and PHP Markdown Extra. The Markdown parser is provided by Cgilite and its full documentation can be looked at here.

Macros

Also see → macros/

In addition to the Markdown syntax, wiki pages can include Macros, which perform additional functions on a page, like generating an image gallery, including parts of other pages, etc. Macros make Shellwiki truly dynamic and flexible.

For example you can include a table of content for the current page by including the line

<<toc>>

in your page. Macros can receive additional parameters, which modify their behaviour.

Macros are the most easy to write type of extension. See Macros for a full list of available macros.

Themes

Also see → theming/

While Shellwiki supports plugins for theming, it's apearance can mostly be configured by the user. Pages can be configured to use custom CSS files. In addition page headers and footers are themselves wiki pages which can be modified to add menus, custom logos, links, etc. The same goes for error pages.

For an example, see the technical pages for this wiki.

Multiple Languages

To enable a multilingual setup you must set a default language in your configuration environment:

export LANGUAGE_DEFAULT=en

Once this is the case, pagenames starting with a colon (:) will be considered translated versions of their parent pages. I.e. the pages /, /:de, and /:fr will serve as the default, german, and french home page respectively.

The names of the languages can be arbitrary, but I recommend using ISO-639 codes, because the code is used in the lang="" attribute of the pages top level html element. You can however make up non-standardised or fantastic language names as well.

Links on each page will automatically be suffixed with the same language tag, so a visitor keeps browsing the same language without needing a cookie. Attachments should only be uploaded to the default language page, and attachment links in the translated pages will correctly point to the main page attachments. You can create a language menu on the header page, simply by linking to ./:en, ./:es , ./:fr, etc.

Header, footer, and error pages will be included from their respective language version, as will all macro includes, etc. Should a page not exist in a given language, the default page will be displayed instead. However, included elements will still be taken from the respective language version, possibly mixing languages between the selected user language and the default.

Developer Documentation

How to write:

• Themes
• Macros
• Handlers
• Parsers