Getting Started
More actions
On this page, we build a basic Hello World page with Wikven.
Wikven builds a static website from a directory of wikitext. There are three ways to install it: the standalone binary (Linux only), the Docker image (any platform), or built from source. This guide uses the binary or Docker, so pick whichever you have.
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/:
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 is the newest released version. To hold a build still, pin the version tag :1.3.0 or the digest (ghcr.io/chaotic-ground/wikven@sha256:...); shorter tags for the major and the minor version are published too, and move as that line gains releases. A dated nightly-YYYY-MM-DD tag is the main branch as it stood that day, for trying a change before it is released.
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 {{...}}:
mkdir -p src/Template && echo "'''Note:''' {{{1}}}" > src/Template/Note.wikitext
echo '{{Note|Rebuild the site after every edit.}}' >> src/index.wikitext
Build again: the home page now shows the note. See Pages#Templates for parameters and more.