Skip to content

Nixinova/Wikity

Repository files navigation

Latest version Last updated npm downloads

Wikity

Wikity is a tool that allows you to use Wikitext (used by Wikipedia, Fandom, etc) as a templating language to create HTML pages.

This package comes with built-in support for compilation using Eleventy.

Install

Wikity is available on npm. Install locally to use in a Node package or install globally for use from the command-line.

Local install Global install
npm install wikity npm install -g wikity

API

Node

  • wikity.compile(folder?: string, options?: object): void

    • Compile all Wikitext (.wiki) files from an input folder (defaults to the current directory, .) into HTML.
  • wikity.parse(input: string, options?: object): string

    • Parse raw wikitext input into HTML.
  • Options:

    • eleventy: boolean = false
      • Whether front matter will be added to the outputted HTML for Eleventy to read (default: false). (This parameter must be set to true if you want to use this with Eleventy.)
    • outputFolder: string
      • Used only with compile().
      • Where outputted HTML files shall be placed.
      • Default: 'wikity-out'.
    • templatesFolder: string
      • What folder to place templates in.
      • Default: 'templates'.
    • imagesFolder: string
      • What folder to place images in.
      • Default: 'images'.
    • defaultStyles: boolean
      • Used only with compile().
      • Whether to use default wiki styling.
      • Default: to true when called from compile() and false when called from parse().
    • customStyles: string
      • Used only with compile().
      • Custom CSS styles to add to the wiki pages.
      • Default: empty ('').

Example

const wikity = require('wikity');

// compile all .wiki files inside this directory
wikity.compile();

// parse wikitext from an input string
let html = wikity.parse(`'''bold''' [[link|text]]`); // <b>bold</b> <a href="link"...>text</a>

As an Eleventy plugin

Use Wikity along with Eleventy to have all your wiki files compiled during the build process:

// .eleventy.js (eleventy's configuration file)
const wikity = require('wikity');
module.exports = function (eleventyConfig) {
    const rootFolder = 'src';
    const templatesFolder = 'templates', imagesFolder = 'images'; // defaults; relative to root folder
    const outputFolder = 'wikity-out'; // default
    const wikityOptions = { eleventy: true, templatesFolder, imagesFolder, outputFolder };
    const wikityPlugin = () => wikity.compile(rootFolder, wikityOptions);
    eleventyConfig.addPlugin(wikityPlugin);
    eleventyConfig.addPassthroughCopy({ 'src/images': 'wiki/' + imagesFolder }); // Eleventy does not pass through images by default
}

The above will use the following file structure (with some example wiki files given):

  • src/
    • templates/: Directory for wiki templates (called like {{this}})
    • images/: Directory to place images (called like [[File:this]])
    • Index.wiki: Example file
    • Other_Page.wiki: Example other file
  • wikity-out/: File templates compiled from the .wiki files (add this to .gitignore)
  • wiki/: Output HTML files compiled from wikity-out/ (add this to .gitignore)

(View the above starting at the URL path /wiki/ when ran in an HTTP server.)

Command-line

$ wikity help
Display a help message
$ wikity compile [<folder>] [-o <folder>] [-t <folder>] [-e] [-d]
Compile Wikity with various options
$ wikity parse <input>
Parse raw input into HTML
$ wikity version
Display the latest version of Wikity

Usage

Use Wikitext (file extension .wiki) to create your pages.

Any wiki templates (called using {{template name}}) must be inside the templates/ folder by default. Any files must be inside the images/ folder by default. Your wikitext (*.wiki) files go in the root directory by default.

Wiki markup

Markup Preview
'''bold''' bold
''italic'' italic
'''''bold italic''''' bold italic
``code`` code
```code block```
code block
=heading= heading
==subheading== subheading
*bulleted
  • bulleted
**sub-bulleted
    • sub-bulleted
#numbered
  1. numbered
##sub-numbered
    1. sub-numbered
;term
term
:definition
 definition
<ref>Text</ref> [1]
<references/> 1. Text
[[internal link]] internal link
[[link|display text]] display text
[external-link] [1]
[external-link display text] display text
[[File:Example.png|Caption.]] Caption
{{tp name}} (contents of templates/tp_name.wiki)
{{tp name|arg=val}} (ditto but {{{arg}}} is set to 'val')
{{{arg}}} (value given by template)
{{{arg|default val}}} (ditto but 'default val' if unset)
{| style="margin:1em" table opening
! Cell heading Cell heading
|- class="new-row" new table row
| Cell content Cell content
|} table closing
{{#if:non-empty-string|text}} text
{{#ifeq:1|2|true|false}} false
{{#vardefine:varname|text}} (saved to memory)
{{#var:varname}} text (from memory)
{{#var:varname|default val}} (ditto but 'default val' if unset)
{{#switch:a|a=1|b=2|c=3}} 1
{{#time:dd/mm/yy|2021-03-28}} 28/03/21
{{#lc:TEXT}} text
{{#ucfirst:text}} Text
{{#len:12345}} 5
{{#sub:string|2|4}} ring
{{#pos:text|x}} 2
{{#padleft:text|5|_}} _text
{{#padright:msg|5|_}} msg__
{{#replace:Message|e|3}} M3ssag3
{{#explode:A-B-C-D|-|2}} C
{{#urlencode:t e x t}} t%20e%20x%20t
{{#urldecode:a%20b%27c}} a b'c
{{#ev:youtube|dQw4w9WgXcQ}} (YouTube embed)
<noinclude>No</noinclude> (blank outside a template)
<onlyinclude>Yes</onlyinclude> Yes
<includeonly>Yes</includeonly> Yes (blank inside a template)
<nowiki>[[no link]]</nowiki> [[no link]]