Getting Started

On this page, we build a basic Hello World page with Wikven.

This page assumes a unix-like shell. The standalone binary is Linux-only; on macOS or Windows, use the Docker image.

Wikven builds a static website from a directory of wikitext. There are three ways to install it: the standalone binary, the Docker image, or built from source. This guide uses the binary or Docker, pick whichever you have.

Requirement

the standalone binary (Linux), or Docker (any platform). See Installation to get either.

Create a source directory and add a wikitext file. Any file ending in .wikitext becomes a wiki article. Name your entry page index so it builds to index.html, the file a browser opens at the site root.

mkdir src
echo 'Hello, World!' > src/index.wikitext

Then build the site. The rendered pages are written to dist/. Pick the tab for how you run Wikven:

Run it in the directory that holds src/ (see Installation to get it):

wikven build

Mount the source and output directories into the container:

docker run --rm \
  -v "$(pwd)/src:/workspace/src" \
  -v "$(pwd)/dist:/workspace/dist" \
  ghcr.io/chaotic-ground/wikven

The untagged image tracks the latest build; append a release tag such as :1.0.0 to pin a specific version.

Preview the site locally, then open http://localhost:8080:

wikven serve

docker run --rm -p 8080:8080 \
  -v "$(pwd)/dist:/workspace/dist" \
  ghcr.io/chaotic-ground/wikven serve

Opening dist/index.html directly also works, though some links and assets resolve correctly only when served. To publish it online, see Deploying.

Setting the title of the site

For configuration, create a .wikven.yaml file in your src directory.

cat <<EOF > src/.wikven.yaml
config:
  Sitename: My Site
EOF

Build again with the same command as before, and the site is titled "My Site".

Adding a second page

Every .wikitext file becomes a page. Add another one and link to it from the first with [[...]]:

echo 'This is the help page.' > src/Help.wikitext
echo 'Read the [[Help]].' >> src/index.wikitext

Build again: the home page now links to Help.html, and the link works with no server. See Pages for how file names map to page titles and namespaces.

Adding a template

Templates, the main reason to reach for Wikven over Markdown, let you reuse content. Put a Template: page in your source and transclude it with {{...}}:

echo "'''Note:''' {{{1}}}" > "src/Template:Note.wikitext"
echo '{{Note|Back up your wiki first.}}' >> src/index.wikitext

Build again: the home page now shows the note. See Pages#Templates for parameters and more.

← Installation

Pages →