From 1744198c8b528ceb4f9d66ad076347d5a00858fd Mon Sep 17 00:00:00 2001 From: =?utf8?q?Paul=20H=C3=A4nsch?= Date: Fri, 30 Aug 2024 13:15:47 +0200 Subject: [PATCH] test wiki links and some full pages --- tests-markdown.sh | 803 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 800 insertions(+), 3 deletions(-) diff --git a/tests-markdown.sh b/tests-markdown.sh index f67cfbf..ff56c02 100755 --- a/tests-markdown.sh +++ b/tests-markdown.sh @@ -1,5 +1,7 @@ #!/bin/sh +runtimes="gawk bawk goawk" + BR=' ' CR="$(printf \r)" @@ -9,15 +11,20 @@ awk() { /bin/awk "$@"; } md_gawk() { gawk -f markdown.awk "$@"; } md_bawk() { busybox awk -f markdown.awk "$@"; } md_mawk() { mawk -f markdown.awk "$@"; } +md_goawk() { goawk -f markdown.awk "$@"; } acnt=1 # assertion count assert() { - local md comp="$2" msg="$3" + local md comp="$2" msg="$3" ex printf "%3i: %s ... " $acnt "$msg" - for proc in gawk bawk mawk; do + for proc in $runtimes; do printf '%s ' $proc - md="$(printf '%s' "$1" |md_"$proc")" + md="$(printf '%s' "$1" |md_"$proc")"; ex=$? + if [ "$ex" != 0 ]; then + printf "Fail!\nExit Code: %i\n" $ex + exit 1 + fi if [ "$md" != "$comp" ]; then printf "Fail!\n:\n%s\n:\n%s\n" "$md" "$comp" exit 1 @@ -57,6 +64,10 @@ assert '\©' "

©

" "escape" assert 'AT&T' "

AT&T

" "escape" assert '`©`' "

©

" "code span escape" +# Wiki Links +assert '[[Link/]]' '

Link/

' "Wiki Link" +assert '[[Link/|Linked Page]]' '

Linked Page

' "Wiki Link" + # Automatic Links assert '' "

https://de.wikipedia.org

" "automatic link" assert '' "

http://de.wikipedia.org

" "automatic link" @@ -415,4 +426,790 @@ assert '![Image] [1] assert '<" _foo_>>' 'macro /test -- "* weird <args>" _foo_' "Macros/Block" + +printf '\n## Testing example pages ##\n' + +assert 'Markdown.awk +============ + +Supported Features / TODO: +-------------------------- +- [x] done +- [ ] todo +- [-] not planned +- ? unsure (whether to implement) +- [/] partial + +### Basic Markdown - Block elements: ### +- [x] Paragraphs + - [x] Double space line breaks +- [x] Proper block element nesting +- [x] Headings +- [x] ATX-Style Headings +- [x] Blockquotes +- [x] Lists (ordered, unordered) +- [x] Code blocks (using indention) +- [x] Horizontal rules +- [x] Verbatim HTML block (disabled by default) + +### Basic Markdown - Inline elements: ### +- [x] Links +- [x] Reference style links +- [x] Emphasis *em*/**strong** (*Asterisk*, _Underscore_) +- [x] `code`, also ``code containing `backticks` `` +- [x] Images / reference style images +- [x] +- [x] backslash escapes +- [x] Verbatim HTML inline (disabled by default) +- [x] HTML escaping + +NOTE: Set the environment variable `MD_HTML=true` to enable verbatim HTML + +### Extensions - Block elements: ### +- [x] Automatic
-wrapping (custom) +- ? Heading identifiers (php md, pandoc) + - [x] Heading attributes (custom) +- [x] Automatic heading identifiers (custom) +- [x] Fenced code blocks (php md, pandoc) + - [x] Fenced code attributes +- [x] Images (as block elements,
-wrapped) (custom) + - [x] reference style block images +- [/] Tables + - ? Simple table (pandoc) + - ? Multiline table (pandoc) + - [x] Grid table (pandoc) + - [x] Headerless + - [x] Pipe table (php md, pandoc) +- [x] Line blocks (pandoc) +- [x] Task lists (pandoc, custom) +- [x] Definition lists (php md, pandoc) +- [-] Numbered example lists (pandoc) +- [-] Metadata blocks (pandoc) +- [x] Metadata blocks (custom) +- [x] Fenced Divs (pandoc) + +### Extensions - Inline elements: ### +- [x] Ignore embedded_underscores (php md, pandoc) +- [x] ~~strikeout~~ (pandoc) +- [x] ^Superscript^ ~Subscript~ (pandoc) +- [-] Bracketed spans (pandoc) + - [-] Inline attributes (pandoc) +- [x] Image attributes (custom, pandoc inspired, not for reference style) +- [x] Wiki style links [[PageName]] / [[PageName|Link Text]] +- [-] TEX-Math (pandoc) +- ? Footnotes (php md) +- ? Abbreviations (php md) +- ? "Curly quotes" (smartypants) +- [ ] em-dashes (--) (smartypants old) +- ? ... three-dot ellipsis (smartypants) +- [-] en-dash (smartypants) +- [ ] Automatic em-dash / en-dash +- [x] Automatic -> Arrows <- (custom) + +Compatibility +------------- +Markdown.awk can run in GNU awk (`gawk`) and in Busybox awk. It is _not_ fully POSIX compliant and does not run in `mawk` or `nawk`. In particular it makes heavy use of the `gensub()` function and its ability to use paranthesized subexpressions in the replacement text. This feature is not available in the POSIX specified `sub()` and `gsub()` functions. Hence it cannot be replaced without effort. + +Tests +----- +[Link with Title](https://en.wikipedia.org/wiki/Markdown "Markdown in Wikipedia"), *emphasis*, **strong**, **strong containing *emphasis***, `inline code`, `` code with `backticks` ``. See more tests [here](./tests/).' \ +'

Markdown.awk

+

Supported Features / TODO:

+
    +
  • done
    • +
  • todo
    • +
  • not planned
    • +
  • ? unsure (whether to implement)
    • +
  • partial
    • +
+

Basic Markdown - Block elements:

+
    +

  • Paragraphs

    +
      +
    • Double space line breaks
      • +
    +
    • +
  • Proper block element nesting
    • +
  • Headings
    • +
  • ATX-Style Headings
    • +
  • Blockquotes
    • +
  • Lists (ordered, unordered)
    • +
  • Code blocks (using indention)
    • +
  • Horizontal rules
    • +
  • Verbatim HTML block (disabled by default)
    • +
+

Basic Markdown - Inline elements:

+
    +
  • Links
    • +
  • Reference style links
    • +
  • Emphasis em/strong (Asterisk, Underscore)
    • +
  • code, also code containing `backticks`
    • +
  • Images / reference style images
    • +
  • <automatic links>
    • +
  • backslash escapes
    • +
  • Verbatim HTML inline (disabled by default)
    • +
  • HTML escaping
    • +
+

NOTE: Set the environment variable MD_HTML=true to enable verbatim HTML

+ +

Extensions - Block elements:

+
    +
  • Automatic <section>-wrapping (custom)
    • +

  • ? Heading identifiers (php md, pandoc)

    +
      +
    • Heading attributes (custom)
      • +
    +
    • +
  • Automatic heading identifiers (custom)
    • +

  • Fenced code blocks (php md, pandoc)

    +
      +
    • Fenced code attributes
      • +
    +
    • +

  • Images (as block elements, <figure>-wrapped) (custom)

    +
      +
    • reference style block images
      • +
    +
    • +

  • Tables

    +
      +
    • ? Simple table (pandoc)
      • +
    • ? Multiline table (pandoc)
      • +

    • Grid table (pandoc)

      +
        +
      • Headerless
        • +
      +
      • +
    • Pipe table (php md, pandoc)
      • +
    +
    • +
  • Line blocks (pandoc)
    • +
  • Task lists (pandoc, custom)
    • +
  • Definition lists (php md, pandoc)
    • +
  • Numbered example lists (pandoc)
    • +
  • Metadata blocks (pandoc)
    • +
  • Metadata blocks (custom)
    • +
  • Fenced Divs (pandoc)
    • +
+

Extensions - Inline elements:

+
    +
  • Ignore embedded_underscores (php md, pandoc)
    • +
  • strikeout (pandoc)
    • +
  • Superscript Subscript (pandoc)
    • +

  • Bracketed spans (pandoc)

    +
      +
    • Inline attributes (pandoc)
      • +
    +
    • +
  • Image attributes (custom, pandoc inspired, not for reference style)
    • +
  • Wiki style links PageName / Link Text
    • +
  • TEX-Math (pandoc)
    • +
  • ? Footnotes (php md)
    • +
  • ? Abbreviations (php md)
    • +
  • ? "Curly quotes" (smartypants)
    • +
  • em-dashes (--) (smartypants old)
    • +
  • ? ... three-dot ellipsis (smartypants)
    • +
  • en-dash (smartypants)
    • +
  • Automatic em-dash / en-dash
    • +
  • Automatic → Arrows ← (custom)
    • +
+

Compatibility

+

Markdown.awk can run in GNU awk (gawk) and in Busybox awk. It is not fully POSIX compliant and does not run in mawk or nawk. In particular it makes heavy use of the gensub() function and its ability to use paranthesized subexpressions in the replacement text. This feature is not available in the POSIX specified sub() and gsub() functions. Hence it cannot be replaced without effort.

+ +

Tests

+

Link with Title, emphasis, strong, strong containing emphasis, inline code, code with `backticks`. See more tests here.

+
' \ +'Full Page (cgilite markdown)' + +assert 'Headline First Order +==================== + +Headline Second Order +--------------------- + + Code Block + with indentation + +> Blockquote +> ---------- +> like in an email + +### Headline 3rd order + +- unordered List +1. with sub points + + sometimes longer ones + +2. which are ordered +3. [ ] and have a Todo item +- more list points + - and a sublist +- [x] some of which ae done + +---------- ++ A lazy, lazy, list +item. + ++ Another one; this looks +bad but is legal. + + Second paragraph of second +list item. + +--------- + +~~~ {.blue} +Fenced Code Block +# with verbatim Text +`and an attribute` +~~~ + +| The limerick packs laughs anatomical +| In space that is quite economical. +| But the *good* ones I'\''ve seen +| So seldom are *clean* +| And the clean ones so seldom are comical + +| The Right Honorable Most Venerable and Righteous Samuel L. + Constable, Jr. +| 200 Main St. +| Berkeley, CA 94718 + +Term 1 + +: This is a definition with two paragraphs. Lorem ipsum + dolor sit amet, consectetuer adipiscing elit. Aliquam + hendrerit mi posuere lectus. + + Vestibulum enim wisi, viverra nec, fringilla in, laoreet + vitae, risus. + +: Second definition for term 1, also wrapped in a paragraph + because of the blank line preceding it. + +Term 2 + +: This definition has a code block, a blockquote and a list. + + code block. + + > block quote + > on two lines. + + 1. first list item + 2. second list item' \ +'

Headline First Order

+

Headline Second Order

+
Code Block
+with indentation
+

Blockquote

+

like in an email

+
+ +

Headline 3rd order

+
    +
  • unordered List
    • +
+
    +

  1. with sub points

    + +

    sometimes longer ones

    +
    2. +

  2. which are ordered

    +
    3. +

  3. and have a Todo item

    +
    4. +
+
    +

  • more list points

    +
      +
    • and a sublist
      • +
    +
    • +
  • some of which ae done
    • +
+
+
    +

  • A lazy, lazy, list +item.

    +
    • +

  • Another one; this looks +bad but is legal.

    + +

    Second paragraph of second +list item.

    +
    • +
+
+ +
Fenced Code Block
+# with verbatim Text
+`and an attribute`
+
The limerick packs laughs anatomical
+In space that is quite economical.
+ But the good ones I've seen
+ So seldom are clean
+And the clean ones so seldom are comical
+
The Right Honorable Most Venerable and Righteous Samuel L. Constable, Jr.
+200 Main St.
+Berkeley, CA 94718
+
+
Term 1
+

This is a definition with two paragraphs. Lorem ipsum +dolor sit amet, consectetuer adipiscing elit. Aliquam +hendrerit mi posuere lectus.

+ +

Vestibulum enim wisi, viverra nec, fringilla in, laoreet +vitae, risus.

+
+
Second definition for term 1, also wrapped in a paragraph +because of the blank line preceding it.
+
Term 2
+

This definition has a code block, a blockquote and a list.

+ +
code block.
+

block quote +on two lines.

+ +
    +
  1. first list item
    2. +
  2. second list item
    3. +
+
+
+
' \ +'Full Page (MD Tests)' + +assert '%css shellwiki.css + +Shellwiki +========= +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: + + - **easy deployment** + + *ShellWiki* can run on any Unix-Like web server. It requires no + scripting languages beyound the regular (Bourne style) Unix + shell, `awk`, and `sed`, all of which can be providede by + `busybox`. It can be launched via `netcat`, `inetd`, `systemd`, + or any cgi capable webserver like `apache` or `lighttpd`. + *ShellWiki* can run easily on embedded systems like OpenWRT or + RaspberryPi, and just as easily on internet web servers + providing multisite setups. + + - **accessibility** + + *ShellWiki* requires no browserside scripting. It aims to be rendered + in all web browsers including `w3m` and `links` besides graphical + browsers like `chromium` or `firefox`. It is as accessible on mobile + screens as on desktop computers. + *ShellWiki* uses the well known `markdown` syntax for formatting and + aims to provide consistent UI controls for various use cases. + + - **adaptability** + + *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. + + - **simplicity** + + *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. + +<> + +Features +-------- + - **Markdown Wiki Syntax** + + The wiki syntax is based on [John Grubers Markdown](https://daringfireball.net/projects/markdown/) + with extensions inspired by [Pandoc](https://pandoc.org/MANUAL.html#pandocs-markdown), + [PHP Markdown Extra](https://michelf.ca/projects/php-markdown/extra/), and + [Github Flavored Markdown](https://github.github.com/gfm/). + Additional Macros are provided to enable functions like an automatic table of contents, listing of + sub pages, etc. + + See [Markdown](/software/cgilite/markdown/) + and [Macros](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](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](themes/) + - [Macros](macros/) + - [URL Handlers](handlers/) + - [Custom Syntax parsers](parsers/) + +Dependencies +------------ +Shellwiki is based on [cgilite](/software/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](https://daringfireball.net/projects/markdown/) with extensions borrowed from [Pandoc](https://pandoc.org/MANUAL%202.html#pandocs-markdown) and [PHP Markdown Extra](https://michelf.ca/projects/php-markdown/extra/). The Markdown parser is provided by [Cgilite](/software/cgilite/) and its full documentation can be looked at [here](/software/cgilite/markdown/). + +<> + +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 + + <> + +in your page. Macros can receive additional parameters, which modify their behaviour. + +Macros are the most easy to write type of extension. See [Macros](macros/) for a full list of available macros. + +Themes +------ +Also see -> [[theming/]] + +While Shellwiki supports plugins for [theming](dev-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](/[wiki]/) 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](https://en.wikipedia.org/wiki/ISO_639-1) 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. + +### 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. + +Developer Documentation +----------------------- +How to write: + + - [Themes](dev-theming/) + - [Macros](dev-macros/) + - [Handlers](dev-handlers/) + - [Parsers](dev-parsers/)' \ +'

Shellwiki

+

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:

+
    +

  • easy deployment

    + +

    ShellWiki can run on any Unix-Like web server. It requires no +scripting languages beyound the regular (Bourne style) Unix +shell, awk, and sed, all of which can be providede by +busybox. It can be launched via netcat, inetd, systemd, +or any cgi capable webserver like apache or lighttpd.
    +ShellWiki can run easily on embedded systems like OpenWRT or +RaspberryPi, and just as easily on internet web servers +providing multisite setups.

    +
    • +

  • accessibility

    + +

    ShellWiki requires no browserside scripting. It aims to be rendered +in all web browsers including w3m and links besides graphical +browsers like chromium or firefox. It is as accessible on mobile +screens as on desktop computers.
    +ShellWiki uses the well known markdown syntax for formatting and +aims to provide consistent UI controls for various use cases.

    +
    • +

  • adaptability

    + +

    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.

    +
    • +

  • simplicity

    + +

    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.

    +
    • +
+toc 2 2

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

    + +
    • +
+

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.

+ +include --nolink /[wiki]/editorhelp/

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.

+ +

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.
    • +
+

Developer Documentation

+

How to write:

+ +
' \ +'Full Page (ShellWiki)' + printf '\nAll tests passed!\n' -- 2.39.2