README
Wikity
Wikity is a tool that allows you to use Wikitext (used by Wikipedia, Fandom, etc) as a templating language to create HTML pages, useful in build tools such as Eleventy.
Install
Wikity is available on npm.
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.
- Compile all Wikitext (
wikity.eleventyPlugin(folder?: string, options?: object): void
- An implementation of
compile()
for use with Eleventy'saddPlugin
API. Identical tocompile()
except that optioneleventy
istrue
by default.
- An implementation of
wikity.parse(input: string, options?: object): string
- Parse raw wikitext input into HTML. Only option available is
templatesFolder
.
- Parse raw wikitext input into HTML. Only option available is
Options:
outputFolder?: string
- Where outputted HTML files shall be placed (default:
wikity-out
).
- Where outputted HTML files shall be placed (default:
templatesFolder?: string
- What folder to place templates in (default:
'templates'
).
- What folder to place templates in (default:
imagesFolder?: string
- What folder to place images in (default:
'images'
). Make sure to pass through this folder to your build output if applicable.
- What folder to place images in (default:
eleventy?: boolean
- Whether front matter will be added to the outputted HTML for Eleventy to read (default:
false
). defaultStyles?: boolean
- Whether to use default wiki styling (default:
true
).
- Whether to use default wiki styling (default:
customStyles?: string
- Custom CSS to style the wiki pages (default:
''
).
- Custom CSS to style the wiki pages (default:
- Whether front matter will be added to the outputted HTML for Eleventy to read (default:
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>
Use Wikity along with Eleventy to compile your wiki files during the build process:
// .eleventy.js (eleventy's configuration file)
const wikity = require('wikity');
module.exports = function (eleventyConfig) {
const wikiFolder = '.'; // current directory
const wikityOptions = {templatesFolder: 'templates', imagesFolder: 'images'}; // set as needed
const wikityPlugin = () => wikity.eleventyPlugin(wikiFolder, wikityOptions);
eleventyConfig.addPlugin(wikityPlugin);
eleventyConfig.addPassthroughCopy({[imagesFolder]: 'wiki/' + imagesFolder}); // Eleventy does not pass through images by default
}
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.
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 |
|
##sub-numbered |
|
;term |
|
: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]] |