Wiki.js
Wiki.js is a free and open-source wiki application built on Node.js and written in JavaScript, designed for creating and managing documentation with a modern, intuitive user interface.[1][2] Developed primarily by Nicolas Giard and released initially in 2016, it emphasizes extensibility through a modular architecture, supporting various content editors including Markdown and visual options, while enabling easy installation on platforms like Docker, Linux, macOS, and Windows.[3][4] Licensed under the GNU Affero General Public License version 3 (AGPL-3.0), Wiki.js allows for self-hosting and customization, with compatibility for multiple databases such as PostgreSQL, MySQL, MariaDB, Microsoft SQL Server, and SQLite.[5] Key features include advanced authentication modules for local, social (e.g., Google, GitHub), and enterprise options (e.g., LDAP, SAML) with two-factor authentication support; over 50 integrations for services like Git, AWS, Azure, and search engines including Algolia; and high-performance capabilities with light/dark themes, scalability for large deployments, and security options for public or private access.[6][1] As of 2025, the stable version is 2.5.x, with version 3.0 under active development since a 2022 developer preview, focusing on enhanced performance and new features like real-time log streaming.[7][8] The project has garnered significant community support, boasting over 27,000 GitHub stars, more than 100 million downloads, and contributions from translators and sponsors via platforms like Open Collective and GitHub Sponsors, reflecting its popularity for personal, corporate, and developer documentation needs.[5][2]Introduction
Overview
Wiki.js is a Node.js-based wiki engine designed for creating and managing documentation wikis, providing a flexible platform for collaborative content creation.[1] It emphasizes simplicity and efficiency, allowing users to build structured knowledge repositories without the overhead of traditional wiki systems. The software's primary use cases include establishing team knowledge bases, maintaining project documentation, and setting up personal wikis for individual note-taking and organization.[1] What sets Wiki.js apart are its lightweight architecture, which ensures fast performance and low resource usage; extensibility via a modular system for custom integrations; built-in Git support for version control and storage; and a contemporary user interface that prioritizes ease of use and visual appeal. It also features Git-backed storage options and is distributed under the AGPLv3 license.[2] As of November 2025, the current stable version is 2.5.308, released on August 13, 2025. Version 3.0 has been in developer preview since October 30, 2022, but remains unreleased in stable form.[8] Wiki.js was created by Nicolas Giard under the Requarks project.[2]Development and creator
Wiki.js was created by Nicolas Giard, a senior software developer at IETF Administration LLC based in Montréal, Canada, who continues to lead its maintenance as an open-source project under the AGPL-3.0 license.[2] The project's development is community-driven and hosted on the GitHub repository requarks/wiki, where contributors collaborate on enhancements, bug fixes, and new features. As of 2025, the repository includes over 120 releases for version 2 and has facilitated over 1,000 merged pull requests from a diverse group of developers, including key contributors like Alexander Casassovici and Maxime Pierre.[2][9][10] It is sustained through sponsorships from organizations such as Cloudflare and DigitalOcean, as well as individual backers via GitHub Sponsors, Patreon, and Open Collective.[5] The development philosophy centers on modularity to enable easy extensibility, high performance for scalable deployments, and robust compatibility with evolving technologies like Node.js. Regular updates prioritize security patches and performance improvements, ensuring the platform remains reliable for production use.[1][11] One notable challenge has been the prolonged development of version 3.0, announced in 2021, which has seen periodic progress updates through 2023 but has stalled as of 2025 due to health issues affecting the lead developer, with community discussions expressing concern over its future; focus remains on stabilizing the current version 2 branch.[12][9][13][14]History
Initial release and early versions
Wiki.js was developed by Nicolas Giard as an open-source wiki platform to provide a modern, lightweight alternative to traditional software like MediaWiki, emphasizing simplicity within the Node.js ecosystem.[15] The project saw its first public release in 2016 with version 1.0, establishing foundational capabilities for collaborative documentation using Markdown and Git-based storage.[3] Throughout the 1.x series, significant milestones included the integration of core Git functionality for seamless version control of pages and assets, alongside basic authentication mechanisms such as local user management and support for external providers like Google.[15] Later updates in the series added features like OpenID Connect authentication and localization support for multiple languages, enhancing accessibility for diverse users.[15] Support for the 1.x branch concluded around 2022, when the repository was archived, paving the way for the architectural advancements in version 2.x.[15]Major version updates
The 2.x series of Wiki.js was launched with the stable release of version 2.0.1 on November 17, 2019, marking a significant rewrite that introduced a modular architecture based on microservices, a redesigned user interface using Vue.js, and expanded database support including PostgreSQL, MySQL, MariaDB, and SQLite. This version also added features like Git-based content storage, advanced authentication options, and extensibility through modules, enabling better customization and scalability for enterprise use.[16] Subsequent key releases in the 2.x series focused on stability, performance, and compatibility enhancements. Version 2.4.105, released on June 5, 2020, served as the initial stable build for the 2.4 branch, incorporating hotfixes for core stability issues and introducing the generic S3 storage module for cloud-based asset handling.[17] Later, version 2.5.299 arrived on June 4, 2023, adding support for Node.js versions 18 and 20, along with community-contributed improvements to logging and API endpoints.[18] The series continued with maintenance releases in 2024 and 2025, including security fixes and compatibility updates, culminating in version 2.5.308 on August 13, 2025, which included security enhancements such as updated dependencies to address vulnerabilities and refined access controls for administrative functions, establishing it as the latest stable release in the 2.x line as of November 2025.[19] Development of Wiki.js 3.0 began publicly with a developer preview released on October 30, 2022, showcasing a rebuilt core with improved performance and new paradigms like multi-site management and enhanced rendering engines.[8] In 2023, official blog posts previewed upcoming features, including native passkeys for authentication and a blocks-based editor for more flexible content creation using web components.[20] As of November 2025, an alpha/developer version remains available for testing via Docker, but the beta release has been delayed indefinitely with no estimated timeline, as the project maintainer has prioritized maintenance of the 2.x series amid resource constraints.[7] The 2.x updates have notably enhanced scalability through better database handling and module integrations, facilitating broader adoption in organizational documentation workflows.[1]Features
Content editing and management
Wiki.js employs a flexible Markdown-based editor as its primary tool for content creation, supporting both WYSIWYG (What You See Is What You Get) and source code modes to accommodate different user preferences.[21] The WYSIWYG mode allows intuitive visual editing with toolbar controls for formatting, while the source mode enables direct Markdown input. Live preview updates the rendered output in real-time as users type, facilitating immediate feedback during composition. Additionally, the editor includes syntax highlighting for code blocks to enhance readability and supports right-to-left (RTL) text direction for languages such as Arabic and Hebrew.[21] Page management in Wiki.js revolves around a path-based hierarchical structure, enabling users to organize content logically without explicit folder creation. Pages are defined by unique paths, such as/documentation/guides/setup, where sub-pages inherit the hierarchy from parent paths, and the system automatically infers intermediate folder representations for navigation.[22] This approach supports nested organization, with breadcrumbs providing quick access to parent pages. Table of contents generation is handled automatically for each page, compiling a navigable outline based on header levels (e.g., H1, H2) within the content to aid in skimming and internal linking.[4] Templates can be implemented by basing new pages on existing ones during creation, allowing reuse of structured content like boilerplates for consistent formatting.[23]
The rendering engine processes Markdown content through a modular pipeline that extends standard syntax for richer output. It natively supports Markdown tables for tabular data presentation, with customizable styling options via additional modules.[24] Diagram creation is facilitated by integrations like Mermaid, which converts textual diagram code into visual flowcharts, sequence diagrams, and graphs since version 2.3.[24] Embeds, such as interactive elements or external media, are enabled through HTML extension modules, allowing seamless incorporation of components like videos or code players into pages.[24]
Collaboration features in Wiki.js focus on asynchronous interaction rather than simultaneous editing, with real-time collaborative editing limited in version 2.x and primarily achieved through external tools or future modules.[25] Page comments provide a dedicated discussion layer, configurable via modules (e.g., internal or external providers) and enabled site-wide from version 2.4, supporting threaded replies with permissions for viewing, posting, and moderation.[26] Task lists are supported directly in Markdown using checkbox syntax (e.g., - [ ] item), rendering as interactive checklists for tracking progress within content.
Storage and version control
Wiki.js employs a hybrid storage approach that separates content from metadata to leverage both version control systems and relational databases for efficient data persistence and management. Page content is stored as individual Markdown files within a dedicated Git repository, which serves as the primary backend for version control. This setup allows for full Git functionalities, including the generation of diffs to compare changes, support for branches to manage parallel development streams, and rollbacks to previous states by reverting commits. The local repository is typically located at a configurable path such as./data/repo and can be synchronized bidirectionally with remote Git providers like GitHub or GitLab, enabling collaborative editing outside the Wiki.js interface.[27]
In contrast, metadata—including user accounts, permissions, page descriptions, tags, and configuration settings—is persisted in a relational database. Wiki.js supports several SQL-based databases for this purpose: PostgreSQL (recommended for optimal performance), MySQL 8.0 or later, MariaDB 10.2.7 or later, Microsoft SQL Server, and SQLite for lightweight deployments. Assets such as images, documents, and other media files are stored separately, either on the local file system or in cloud storage providers like AWS S3, Azure Blob Storage, or Google Cloud Storage, with metadata references maintained in the database to facilitate retrieval and management. This division ensures that content versioning remains lightweight and decentralized while centralizing structured data for quick queries.[28][1]
Revision history is handled through automatic Git commits triggered on every page save or update, capturing the full change log with author information and timestamps. The user interface provides access to this history via the Administration Area under the Storage > Git tab, where administrators can view commit details, compare revisions side-by-side, and revert to earlier versions directly from the page editor. Since the underlying system is Git, it inherently supports non-linear history, allowing merges from branches and resolution of complex edit timelines without data loss. For backups and migrations, Wiki.js enables exporting the entire content set to the Git repository for versioned archival or as a ZIP archive containing pages and assets; imports are supported from local files, Git repositories, or other wiki platforms like DokuWiki through dedicated scripts or the Local File Storage module.[27][29][30]
Access control and authentication
Wiki.js implements a comprehensive role-based access control (RBAC) system to manage user permissions securely. Permissions are organized through groups, which can be assigned to individual users via the administration interface. System-defined groups such as Administrators and Guests provide baseline roles, with custom groups allowing for fine-grained control. Roles typically include administrator (full access), editor (create and modify content), and viewer (read-only access), defined by specific permission scopes likeread:pages, write:pages, manage:users, and upload:assets.[31]
These permissions operate on three levels: global (wiki-wide), namespace (folder or path-based hierarchies), and individual page. Global permissions apply uniformly, while page rules enable targeted access, such as restricting edits to paths starting with /internal/ or exact matches like /project/docs. The system supports inheritance, where users gain permissions from all assigned groups, and follows a default-deny principle—access is prohibited unless explicitly granted via rules. Rule priority is determined by specificity, with exact path matches overriding broader patterns like "starts with" or "contains." To enforce privacy, administrators can configure the Guest group to require authentication for all content, effectively locking the wiki.[31]
Authentication in Wiki.js is modular and extensible, supporting a range of strategies to integrate with existing identity providers. Local accounts serve as the foundation, mandatory for the root administrator and configurable for self-registration with optional domain whitelisting (e.g., restricting to @company.com emails) and automatic group assignment. External options include LDAP/Active Directory for enterprise directories, SAML 2.0 for single sign-on, and OAuth 2.0/OpenID Connect via built-in providers like Google, Facebook, GitHub, Azure AD, Auth0, Okta, and CAS. Multiple strategies can run concurrently, mapping to the same user via email or username, with customizable login screens including branding options.[32]
For enhanced security, Wiki.js supports multi-factor authentication (MFA) using TOTP since version 2.5, compatible with apps like Google Authenticator. MFA can be mandated globally through the administration security settings or enabled per user, adding a second verification factor beyond passwords. Self-registration and login flows include protections like configurable minimum delays between attempts, though general rate limiting is applied selectively—for instance, comment posting is restricted to one request per IP address every 15 seconds to mitigate spam. Asset uploads are secured through permission controls, requiring appropriate group membership (e.g., upload:assets) before allowing file handling in the assets manager.[32][33][31]
Search and asset handling
Wiki.js provides robust search capabilities through its modular search engine system, allowing administrators to choose from built-in database-based options or integrations with external providers. The default search engine, DB-Basic, offers limited full-text search confined to page titles and descriptions, suitable for small-scale wikis but lacking advanced features like fuzzy matching or facets.[34] For more comprehensive functionality, the DB-PostgreSQL engine leverages PostgreSQL's native full-text search capabilities, including automatic content indexing and fuzzy matching enabled by the pg_trgm extension, while supporting configurable dictionary languages for multilingual queries.[35] External integrations enhance search performance, particularly for larger installations. The Elasticsearch module connects Wiki.js to a distributed RESTful search engine, enabling full-text search across page content with real-time indexing updates for new, edited, or deleted pages, and a manual rebuild option for initial or bulk indexing of existing content.[36] This setup supports fuzzy matching, facets for filtered results, and page suggestions, making it ideal for handling large-scale wikis with high query volumes. Similarly, the Algolia module integrates with a search-as-a-service platform, providing automatic indexing updates and advanced query handling, including facets and suggestions, via API configurations.[37] Asset management in Wiki.js facilitates the upload and storage of various media files directly within pages. Users can upload images, videos, attachments, and other file types—such as documents or ZIP archives—through an intuitive assets dialog supporting drag-and-drop or file browsing, with images automatically rendered inline and non-image files displayed as downloadable links.[38] Assets are organized into folders for better management, adhering to naming conventions that prohibit spaces, uppercase letters, or certain patterns to ensure compatibility. While core storage occurs in the database, storage modules allow synchronization with external providers like Azure Blob Storage for backup and distribution, potentially enabling CDN integration through cloud services.[39] The indexing process in Wiki.js varies by search engine but emphasizes efficiency for content discovery. Database-based engines like DB-PostgreSQL automatically create indexes upon activation, with a rebuild function available for populating indexes with pre-existing pages, while external engines such as Elasticsearch and Algolia handle real-time reindexing on content changes to maintain up-to-date search results.[35][36][37] This approach scales to large wikis by leveraging the underlying engine's distributed architecture, as seen in Elasticsearch, which distributes indexing tasks across nodes to manage extensive content volumes without performance degradation.[36] Advanced search queries are supported primarily through PostgreSQL and external engines, extending beyond basic keyword matching. The DB-PostgreSQL option utilizes PostgreSQL's query syntax for Boolean operators (AND, OR, NOT) and date range filtering on page metadata, enhanced by the pg_trgm extension for similarity-based fuzzy searches.[35] Elasticsearch integration inherits the engine's rich query language, allowing complex Boolean expressions, date ranges, fuzzy matching with edit-distance thresholds, and faceted navigation for refining results by tags or categories.[36] Algolia similarly enables advanced operators and external provider extensions, configurable via admin settings for tailored query behaviors.[37] These features ensure precise content retrieval, with page suggestions appearing in search interfaces to guide users to relevant results.[40]Extensibility and integrations
Wiki.js employs a modular architecture that enables extensive customization through plugins, allowing users and developers to extend core functionality without modifying the source code. Introduced in version 2.0, this system categorizes modules into areas such as authentication, storage, editors, search engines, logging, analytics, and databases, facilitating the integration of third-party components for specific needs. For instance, authentication providers support single sign-on (SSO) options like Azure Active Directory, enabling seamless enterprise logins, while storage backends include Git for bidirectional synchronization with external repositories. Developers can create custom modules using a structured format with adefinition.yml file for configuration and JavaScript for logic, placed in the server/modules directory, which supports local dependencies via package.json to avoid conflicts with the core application.[41][6]
The platform's API infrastructure further enhances extensibility by providing a GraphQL endpoint at /graphql for querying and mutating resources such as pages, users, and groups, secured via API tokens in the Authorization header. This allows automation of tasks like creating or updating content programmatically, with tools like GraphQL Playground available for testing at the same endpoint since version 2.2. Webhooks, introduced in later updates including the beta for version 3.0, enable notifications to external services on events such as page edits or revisions, supporting integrations for real-time updates in workflows. For example, the Git storage module leverages GitHub's webhook capabilities to detect changes pushed externally, ensuring content availability across systems.[42][43][44]
Integrations extend to collaboration tools and development pipelines, with authentication modules supporting providers like Slack and GitHub for user logins, and the Git backend enabling CI/CD workflows by allowing content pushes from tools like GitLab or Azure DevOps. While direct embedding in applications like Jira is facilitated through API calls or webhook triggers for issue-linked documentation updates, the modular design avoids deep dependencies, focusing instead on lightweight connections.[45][46][39]
Customization options include a theme engine that permits overrides via SCSS files like scss/app.scss for styling and JavaScript in js/app.js for behavior, with full custom themes compilable in development mode using yarn dev. The system also supports localization for multiple languages, displaying the interface and content in over 56 community-contributed locales, including right-to-left scripts, with multilingual page versions managed through locale-specific paths.[47][48][49]
Technical architecture
Core technologies
Wiki.js is powered by the Node.js runtime, with support for versions 18.x, 20.x, and 22.x as of 2025, enabling efficient server-side JavaScript execution.[50] The backend framework employs Express.js to manage HTTP requests, routing, and middleware, facilitating a lightweight and modular structure.[51] On the frontend, Wiki.js utilizes Vue.js to construct reactive UI components, paired with modern JavaScript and Pug templating for rendering dynamic interfaces.[51] Additional components include Git for content storage and versioning, allowing seamless integration with version control workflows.[27] Deployment is facilitated through containerization with Docker and orchestration via Kubernetes. The architecture leverages Node.js's asynchronous I/O model and event-driven paradigm, promoting scalability from single-instance setups to distributed environments.[2] For data persistence, it briefly interfaces with databases such as PostgreSQL or MySQL, though detailed configurations are handled separately.[50]Database and deployment options
Wiki.js supports several relational database management systems for storing its data, with PostgreSQL serving as the recommended option due to its robustness and full feature compatibility. Note that support for MySQL, MariaDB, Microsoft SQL Server, and SQLite is planned to be discontinued in version 3.0 and later; PostgreSQL is recommended for future compatibility.[50] PostgreSQL versions 9.5 and later are compatible, and it is advised to use the latest available version for optimal performance; thepg_trgm extension is required and typically included in standard installations or Docker images.[50] Other supported databases include MySQL 8.0 or later (with partial support for 5.7.8), MariaDB 10.2.7 or later, Microsoft SQL Server 2012 or later, and SQLite 3.9 or later, though SQLite is suitable only for testing and development environments rather than production use.[50] Schema migrations are handled automatically during upgrades, ensuring seamless transitions between versions without manual intervention.[52]
Deployment of Wiki.js can be accomplished through various methods to suit different environments, starting with a direct Node.js installation via npm for straightforward setups on supported operating systems.[53] Containerized deployment is facilitated by official Docker images, allowing easy orchestration with tools like Docker Compose for multi-container applications.[53] For orchestrated environments, Helm charts are available to deploy Wiki.js on Kubernetes clusters, including optional integration with PostgreSQL as the database backend and configurable persistence via persistent volume claims.[54] These methods extend to cloud platforms such as AWS (via EC2 or Elastic Beanstalk) and Azure (via App Service), enabling scalable hosting without significant modifications.[53]
Configuration for Wiki.js is managed through a YAML file named config.yml located at the installation root, which defines essential settings including database connections, server ports, and security options.[28] The default HTTP port is 3000, though it can be adjusted to 80 for direct access (requiring appropriate permissions), and HTTPS support is configurable via custom certificates in PEM or PFX formats or automated issuance through Let's Encrypt, specifying the domain and email for validation.[28] Clustering for high availability is enabled by setting ha: true in the configuration, which supports multi-instance operation but requires PostgreSQL and is best initialized on a single instance before scaling.[28] For production deployments, a reverse proxy like Nginx is commonly set up in front of Wiki.js to handle SSL termination, load balancing, and advanced routing, with official guidance recommending proxy configuration to forward requests to the internal port while preserving headers for proper functionality.[28]
To achieve scalability, Wiki.js supports horizontal scaling by running multiple instances that share a common database and storage backend, allowing load distribution across servers or nodes in a cluster.[28] This approach leverages the high-availability clustering feature to maintain consistency, with shared storage ensuring synchronized access to assets and content across replicas.[28]
Deployment and requirements
System requirements
Wiki.js requires modest hardware resources to operate, with minimum specifications of one CPU core, 1 GB of RAM (higher amounts recommended for Windows and macOS systems), and 1 GB of disk space for basic installations.[50] These can scale to multiple CPU cores and additional RAM for production environments handling larger user bases or extensive content volumes.[50] The software runs on Linux, macOS, Windows, and containerized platforms such as Docker and Kubernetes.[50] It necessitates Node.js version 22.0 or later (with long-term support versions preferred for stability), though earlier versions like 18.x and 20.x remain compatible with specific Wiki.js releases.[50] Supported databases include PostgreSQL 9.5 or later (recommended, with the pg_trgm extension for full-text search), MySQL 8.0 or later, MariaDB 10.2.7 or later, Microsoft SQL Server 2012 or later, and SQLite 3.9 or later (suitable only for development, not production).[50] Network configuration involves opening port 3000 by default for HTTP access when behind a reverse proxy, or port 80 for standalone servers; SSL/TLS certificates are essential for secure production deployments.[28] Wiki.js must be hosted on a dedicated subdomain (e.g., wiki.example.com) rather than a subfolder.[50] Additional prerequisites apply for optional features: Git version 2.7.4 or later is required if using the Git-based storage module for version control.[27] Elasticsearch can be integrated as an optional search engine for advanced full-text capabilities, but it is not mandatory for core functionality.[36]Installation process
Before installing Wiki.js, verify that the system meets the necessary prerequisites, including Node.js version 22.0 or later (required for latest releases; earlier LTS versions like 20.x compatible only with older Wiki.js releases), a supported database such as PostgreSQL 9.5+ (preferred), MySQL 8.0+, MariaDB 10.2.7+, or SQLite 3.9+, and Git 2.7.4+ if planning to use the Git storage backend.[50][27] The database must be pre-installed and configured, with the target database created in advance; for production environments, PostgreSQL with thepg_trgm extension is advised for optimal performance.[50] Git installation is essential only for enabling version control features but should be checked regardless to avoid integration issues later.[27]
The core installation on Linux involves downloading the latest release archive from GitHub using wget https://github.com/requarks/wiki/releases/latest/download/wiki-js.tar.gz, extracting it with tar xzf wiki-js.tar.gz -C ./wiki after creating a directory, and navigating to the extracted folder with cd ./wiki.[55] Next, copy the sample configuration file as cp config.sample.yml config.yml and edit config.yml to specify the database connection details under the db section (e.g., type: postgres, host: [localhost](/page/Localhost), port: 5432, user: wikijs, pass: wikijsrocks, db: wiki), along with the port (default 3000) and other basics; storage options, including Git, are configured during the setup wizard or in the admin interface after installation.[28][27] If using SQLite, run npm rebuild sqlite3, then start the server with node server.[55]
For Docker-based deployment, pull the official image with docker pull ghcr.io/requarks/wiki:2 and run the container using a command like docker run -d --name wiki -p 3000:3000 --restart unless-stopped -v /path/to/config.yml:/wiki/config.yml -e DB_TYPE=postgres -e DB_HOST=host -e DB_PORT=5432 -e DB_USER=user -e DB_PASS=pass -e DB_NAME=dbname ghcr.io/requarks/wiki:2, ensuring volume mounts for the configuration file and database persistence to maintain data across restarts.[56]
After starting the server or container, access Wiki.js via a web browser at http://[localhost](/page/Localhost):3000 (or the server's IP and mapped port), where the setup wizard will guide users through creating the first administrator account, configuring the site title, locale, initial storage options, and other basics.[55]
Common troubleshooting issues include port conflicts, resolved by checking if port 3000 is in use with tools like [netstat](/page/Netstat) and switching to an available port in config.yml or the Docker command, and database connection failures, often due to incorrect credentials or unsupported authentication protocols in MySQL 8.0+, which can be fixed by altering the user to use mysql_native_password via SQL commands.[57] For privileged ports below 1024 on Linux, use sudo [setcap](/page/Sudo) cap_net_bind_service=+ep $(which [node](/page/Node)) or configure a reverse proxy like Nginx.[57]