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');
wikity.compile();
let html = wikity.parse(`'''bold''' [[link|text]]`);
As an Eleventy plugin
Use Wikity along with Eleventy to have all your wiki files compiled during the build process:
const wikity = require('wikity');
module.exports = function (eleventyConfig) {
const wikiFolder = 'src';
const templatesFolder = 'templates', imagesFolder = 'images', outputFolder = 'wikity-out';
const wikityOptions = { templatesFolder, imagesFolder, outputFolder };
const wikityPlugin = () => wikity.compile(wikiFolder, { eleventy: true, ...wikityOptions });
eleventyConfig.addPlugin(wikityPlugin);
eleventyConfig.addPassthroughCopy({[imagesFolder]: 'wiki/' + imagesFolder});
}
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]]
)wikity-out/
: File templates compiled from the .wiki
files (add this to .gitignore
)Index.wiki
: Example fileOther_Page.wiki
: Example other file
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 | |
**sub-bulleted | |
#numbered | - numbered
|
##sub-numbered | - 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.]] | |
{{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 |
<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]] |