Raneto: a file-based Markdown knowledge base on Node.js

What Raneto replaces, and for whom

Raneto is a Node.js application that turns a directory of Markdown files into a browsable knowledge base. The README describes it as a free, open, simple Markdown-powered knowledge base, and lists five features: all content is file-based, search covers file names and contents, there is a Markdown editor in the browser, a login system protects editing, and the whole thing is described as simple and lightweight. That list is the product. There is no database, no content API, and no plugin registry.

The audience is narrow and identifiable. If your team already writes documentation as .md files in a repository, Raneto gives those files a URL, a sidebar, and a search box without a migration step. The files stay where they are. The alternative that Raneto is implicitly arguing against is a wiki backed by a database, where the canonical copy of a page lives inside the application and leaving means exporting. Raneto inverts that: the filesystem is the source of truth and the web app is a view over it. For a small team that reviews documentation through pull requests, that inversion is the entire value proposition.

It is a poor fit for anyone who wants a wiki that non-technical contributors edit directly as the primary workflow, or who needs structured content types, comments, or page-level permissions. The README does not claim any of those.

The mechanism: Markdown files, a content directory, and a search index over both

The core mechanism visible in the material is a configurable content directory. The CONTENT_DIR environment variable maps to the content_dir config key and is documented as the path to the content directory containing .md files, defaulting to content/pages. Everything the site serves is read from that path. There is no import step described in the README, which implies the application reads the directory at request or startup time rather than maintaining a separate store.

Search is described as covering file names and contents. That is a meaningfully different scope from a full-text index built over rendered HTML: the filename is part of the searchable surface, so naming conventions such as 01-installation.md or api-authentication.md affect what users find. Teams that treat filenames as arbitrary identifiers will get worse search results than teams that treat them as titles.

The edit path is separate from the read path. ALLOW_EDITING (config key allow_editing) controls whether the browser editor is enabled, and AUTHENTICATION (config key authentication) controls whether authentication is on at all. The login system is described as being for edit protection, which suggests the intended deployment is a publicly readable site where only writes are gated. That is a deliberate posture, not an oversight, but it means Raneto is not the tool for internal documentation that must not be readable without a login.

Configuration is environment-first, with config.js as the fallback

The README states that environment variables take the highest priority and override values set in config/config.js. That ordering matters for deployment: you can ship a config.js with sane defaults and override per environment without editing files inside a container image. The documented mapping is one variable per config key, with the exception of the admin credentials, where ADMIN_USERNAME and ADMIN_PASSWORD both map to credentials[0] and the README notes they must be set together.

A minimal production setup, based on the documented variables, looks like this:

SESSION_SECRET=$(openssl rand -base64 32) ADMIN_USERNAME=admin ADMIN_PASSWORD=<a password you choose> CONTENT_DIR=content/pages BASE_URL=https://docs.example.com SITE_TITLE=Engineering Handbook AUTHENTICATION=true ALLOW_EDITING=true ADDRESS=127.0.0.1 PORT=8080

The README gives openssl rand -base64 32 as the way to generate SESSION_SECRET and specifies a minimum of 32 characters. That is a hard constraint, not a suggestion. The default listen address is 127.0.0.1 and the default port is 8080, so out of the box the server is bound to loopback and expects a reverse proxy in front of it. HOST is documented as deprecated in favour of ADDRESS, which is worth knowing because older deployment guides and container recipes still reference it.

Two optional variables round out the surface: GOOGLE_ANALYTICS_ID takes a GA4 measurement ID such as G-XXXXXXXXXX, and LOCALE takes a locale code such as en or fr for UI translations. The README does not enumerate which locales ship with translations, so that is something to confirm against the repository rather than assume.

Where Raneto gets in the way

The single-admin credential model is the most consequential limitation in the supplied material. The environment variable table maps ADMIN_USERNAME and ADMIN_PASSWORD to credentials[0], an array entry, which suggests the config format supports more than one credential. The README does not document how to add a second one through environment variables, and it does not describe roles, groups, or per-page access. If your requirement is that the finance team sees one section and engineering sees another, Raneto as documented does not address it. Authentication here appears to be binary: authenticated or not.

Content that is publicly readable by default is the second constraint. Because the login system is framed as edit protection, a deployment that leaves AUTHENTICATION unset exposes every Markdown file in CONTENT_DIR to anyone who can reach the URL. That is fine for a public handbook and wrong for an internal runbook containing hostnames and credentials. The failure mode is silent: the site looks correct, and the content is simply public.

Search over file names and contents also has a scaling question the README does not answer. Nothing in the material describes an index format, a rebuild step, or a limit on the number of pages. A team with a few hundred files is clearly in scope. A team with tens of thousands of pages should treat search behaviour as unverified and measure it before relying on it.

Finally, the project is a single-maintainer repository with a long release gap in the visible history: 0.17.8 in February 2024, then 0.18.0 in September 2025, then 0.18.1 in March 2026. Sparse releases are not automatically a problem for a small file-serving application, but they do mean you should read the release notes for 0.18.0 and 0.18.1 before upgrading from a 0.17.x install, since the material does not describe what changed.

Alternatives, and the actual difference in approach

The closest well-known alternative is MkDocs with the Material theme. Both take Markdown in a directory and produce a browsable site. The difference is when the work happens. MkDocs is a static site generator: a build step renders Markdown to HTML, and the output is a set of files you can serve from any web server or object store. Raneto is a running Node.js process that serves pages and includes a browser editor and a login. That means Raneto can be edited in place without a rebuild and without a Git client, while MkDocs cannot. In exchange, MkDocs deployments have no session secret to manage, no admin credentials to rotate, and no application process to keep alive.

A second comparison is a database-backed wiki such as Wiki.js. The difference is where the canonical content lives. In Wiki.js the database holds the pages and Markdown is one storage format among several. In Raneto the Markdown files are the content and the application reads them. If your review process is pull requests and your backup strategy is Git, Raneto's model matches. If your contributors will never open a terminal, a database-backed wiki matches better, at the cost of an export step if you ever leave.

A third option worth naming is simply serving the Markdown directory with a static file server and a client-side renderer. That removes the application entirely but also removes search, the editor, and the login, which are the three features the README actually lists.

Licence, upkeep, and what upgrading costs

Raneto is MIT licensed, and the README carries a FOSSA licence report badge, which indicates the project tracks its dependency licences. MIT is permissive: you can use, modify, and redistribute the code, including in a commercial product, provided the copyright notice and licence text are preserved. That is a description of the licence text, not legal advice, and the FOSSA report is the right place to check the transitive dependency licences if your organisation has a policy against copyleft dependencies.

The maintenance cost is the cost of running a Node.js web application. You need a process supervisor or container runtime, a reverse proxy to terminate TLS in front of the default 127.0.0.1:8080 binding, and a rotation plan for SESSION_SECRET and the admin password. Because SESSION_SECRET signs sessions, changing it invalidates existing logins, which is the intended behaviour and worth knowing before you rotate it during an incident.

Upgrade cost is bounded by the environment variable surface. If you configure entirely through the variables in the README table, an upgrade is a version bump and a restart, and the variables listed are stable across the documented releases. If you have edited config/config.js directly, you carry a merge on every upgrade, which is the reason the environment-first ordering exists. The 0.18.0 and 0.18.1 releases are not described in the supplied material, so read their notes before moving a 0.17.x deployment forward.

Editorial conclusion

Adopt Raneto if your documentation is a folder of Markdown files that you already keep in Git and you want a read-only site with one admin login for occasional edits. Skip it if you need per-user permissions, a database, or a hosted product with a support contract. Before committing, verify that your Node.js version satisfies the engines field in package.json, that SESSION_SECRET is at least 32 characters, and that CONTENT_DIR points at the directory you actually intend to publish.

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. ryanlelek/Raneto on GitHub