Shellwiki is a Wiki and Content Management System with minimal dependencies. It can run on embedded devices, as well as full size web servers. Its goals are:
ShellWiki can run on any Unix-Like web server. It requires no scripting languages beyound the regular (Bourne style) Unix shell,
sed, all of which can be providede by
busybox. It can be launched via
systemd, or any cgi capable webserver like
ShellWiki can run easily on embedded systems like OpenWRT or RaspberryPi, and just as easily on internet web servers providing multisite setups.
ShellWiki requires no browserside scripting. It aims to be rendered in all web browsers including
linksbesides graphical browsers like
firefox. It is as accessible on mobile screens as on desktop computers.
ShellWiki uses the well known
markdownsyntax for formatting and aims to provide consistent UI controls for various use cases.
ShellWiki is extensible through plugins and provides theming and styling capabilities that make it suitable not only as a wiki, but also as a CMS, including access scopes for different authors and stylisticly distinct subpages.
ShellWiki avoids complexity in both software design and user interface. It aims to be secure and predictable. Extensions can be written and modified by system administrators.
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.
Plain file Storage
Pages and attachments are stored as plain files on disk. There is no need for a separate database system.
gitis 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.
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
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.
ImageMagickis 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.
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.
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)
nawkwill 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.
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/.
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.
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
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.
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.
To enable a multilingual setup you must set a default language in your configuration environment:
Once this is the case, pagenames starting with a colon (
:) will be considered translated versions of their parent pages. I.e. the pages
/: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
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.
Constraints of the current implementation
- There can be only one default language, with no priority of different fallback languages
- Page URLs can currently not be translated. Doing so would require a model for manually assigning translated page names and would not be trivial to use.
How to write: