Flask-Wiki

A lightweight, file-based wiki system built as a Flask extension. Create, edit, search, and manage wiki pages stored as Markdown files on the filesystem -- no database required.

Features

• Markdown pages with metadata (title, tags)
• Full-text search powered by Whoosh
• File/image uploads
• WikiLinks ([[Page Name]] syntax)
• Multilingual support
• Markdown editor with a server-rendered preview tab
• No CDN: every front-end asset is served by the application
• Customizable templates and permissions

Installation

pip install flask-wiki

Quick start

from flask import Flask
from flask_wiki import Wiki

app = Flask(__name__)
app.config["SECRET_KEY"] = "your-secret-key"
Wiki(app)

Or using the application factory pattern:

from flask import Flask
from flask_wiki import Wiki

wiki = Wiki()


def create_app():
    app = Flask(__name__)
    app.config["SECRET_KEY"] = "your-secret-key"
    wiki.init_app(app)
    return app

The wiki will be available at /help by default (configurable via WIKI_URL_PREFIX).

Initialize the search index

Before using search, initialize the Whoosh index:

flask flask_wiki init-index
flask flask_wiki index

How it works

Wiki pages are plain Markdown files stored in a content directory (./data by default). The URL structure mirrors the filesystem, and every page belongs to a language: /help/guides/setup maps to data/guides/setup_en.md for an English reader. See Internationalization.

Each page file has an optional metadata header followed by the Markdown body:

title: My Page Title
tags: setup, guide

# Content starts here

Regular markdown content...

The wiki registers a Flask Blueprint with routes for viewing, editing, searching, and managing pages. Uploaded files (images) are stored in a subfolder and served via middleware.

Permissions

Flask-Wiki uses a callable-based permission system. The host application provides functions that return True or False to control access. By default, everything is open (all lambdas return True).

There are four permission settings:

Each permission is a callable (no arguments) that is evaluated per-request. This lets you integrate with any authentication system -- Flask-Login, session-based auth, API tokens, etc.

Example: integrating with Flask-Login

from flask_login import current_user

app.config["WIKI_READ_VIEW_PERMISSION"] = lambda: current_user.is_authenticated
app.config["WIKI_EDIT_VIEW_PERMISSION"] = lambda: current_user.is_authenticated and current_user.has_role("editor")
app.config["WIKI_EDIT_UI_PERMISSION"] = app.config["WIKI_EDIT_VIEW_PERMISSION"]

The VIEW permissions are enforced server-side via route decorators. The UI permissions only toggle visibility of buttons and links in the templates -- they do not enforce access control on their own. Typically you'll set the UI permissions to match the view permissions, but you can separate them if needed (e.g., show a "log in to edit" button to anonymous users).

Configuration

Content & storage

Templates

All templates can be overridden by setting these config values to your own template paths:

Front-end assets

The wiki needs no build step, no CDN and no vendored third-party asset. Its whole front-end comes from bootstrap-flask:

Set BOOTSTRAP_SERVE_LOCAL = True so bootstrap-flask serves its own assets instead of a CDN, which is what makes the wiki work without internet access:

app.config["BOOTSTRAP_SERVE_LOCAL"] = True

Icons

Templates never name a glyph directly. They ask for an intent — search, copy, edit, upload, delete, language, save — and WIKI_ICON_TEMPLATE supplies the markup for it:

The Font Awesome variant emits class names only; it bundles nothing. Use it in an application that already ships Font Awesome — through a webpack bundle, for instance — and the wiki icons match the rest of that application:

app.config["WIKI_ICON_TEMPLATE"] = "wiki/icons/fontawesome.html"

Any template exposing an icon(name) macro works, so an application needing different styles or a third icon set can point the key at its own file.

Pages are edited in a plain <textarea>; the Preview tab posts the body to wiki.preview and renders it with the same Markdown pipeline as a saved page, so WikiLinks, captions and syntax highlighting show up exactly as they will.

Internationalization

Every page belongs to a language: its filename carries a language code (page_fr.md, page_de.md), and /help/page serves the variant matching WIKI_CURRENT_LANGUAGE. Pages created or edited through the wiki are always saved with a language code.

When a page has no variant in the current language, the wiki walks WIKI_FALLBACK_LANGUAGES in order and serves the first translation it finds, with a banner telling the reader which language the page is displayed in. A page is only a 404 when it exists in no language at all. Set WIKI_FALLBACK_LANGUAGES = [] to disable the cascade.

Page listings (index, tags) and search results follow the same cascade: one entry per page, in the current language when it exists.

Files without a language code (page.md) are still served, as a last resort, for wikis created before language codes became mandatory. They are read-only: editing one writes the variant of the current language and leaves the original untouched. To migrate such a wiki, rename its files to page_<language>.md and re-run flask flask_wiki index.

Markdown

The extensions toc, meta, tables, and a built-in Bootstrap extension are always loaded.

Development

Requirements

• Python >=3.14,<3.15
• uv

Setup

git clone <repo-url>
cd flask-wiki
uv sync --frozen

Run the example app

cd examples
uv run flask flask_wiki init-index
uv run flask flask_wiki index
uv run flask run --debug
# Visit http://localhost:5000/help

Run tests

uv run poe run_tests

License

BSD 3-Clause. See LICENSE for details.