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:

BinaryDocker

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:

BinaryDocker

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 →