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

> Raneto turns a directory of .md files into a searchable wiki with an optional browser editor. It is simple by design, and that simplicity is also the limit of what it does.

**ryanlelek/Raneto** — Markdown powered Knowledgebase Wiki for Node.js

- Repository: https://github.com/ryanlelek/Raneto
- Website: https://raneto.com
- Stars: 2,902 · Forks: 439
- Language: JavaScript
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/ryanlelek-raneto

## The problem Raneto solves, and who it is actually for

Most wiki software stores pages in a database and gives you a web form to edit them. That is convenient until you want the documentation to live beside the code, be reviewed in a pull request, or be restored from a backup you already trust. Raneto takes the other position. The README states that all content is file-based, and the repository ships a content/ directory at the top level. Pages are Markdown files on disk. The application reads them, renders them, and serves them.

That makes Raneto a reasonable fit for engineering teams that already treat documentation as source. It is also a fit for anyone who wants a small self-hosted site rather than a hosted product. The package.json lists express, helmet, express-session and express-rate-limit as dependencies, so the runtime is a conventional Express application, not a static site generator. The distinction matters: a static generator writes HTML at build time, while Raneto resolves pages on each request and can therefore offer search across file names and contents plus an in-browser editor. The README lists both under Top Features.

The audience is narrow on purpose. If your writers expect a rich text editor, comments, or page-level access control, Raneto does not offer those. If your writers are comfortable with Markdown and a directory tree, the file-based model removes an entire category of problems: there is no export step, no database dump, and no migration when you change hosting.

## How Raneto loads and serves Markdown files

The entry point is server.js at the repository root, and package.json maps the start script to node server.js. The application module is app/index.js, declared as both main and exports, and the package is marked type: module, so the codebase is ESM rather than CommonJS. Configuration is read from config/config.js, and the README is explicit that environment variables take the highest priority and override values set in that file. That ordering is worth remembering: if a setting appears to be ignored, an environment variable is the first place to look.

Content resolution is driven by CONTENT_DIR, which the README documents as the path to the content directory containing .md files, defaulting to content/pages. The server listens on ADDRESS, default 127.0.0.1, and PORT, default 8080. Because the default address is loopback, a fresh install is reachable only from the machine it runs on until you change ADDRESS or put a reverse proxy in front of it. The bundled Dockerfile sets HOST=0.0.0.0 and PORT=8080, which is why the container is reachable from outside while a bare npm start may not be.

The rendering stack is visible in the dependency list. Markdown parsing, table-of-contents generation via @fixhq/markdown-toc, YAML front matter through js-yaml, and file globbing through glob. The theme is a separate package, @raneto/theme-default, pinned at 0.9.0. Two security-relevant dependencies are present by default: helmet for response headers and express-rate-limit for request throttling. Neither is mentioned in the README feature list, but both appear in package.json, so they are part of the default surface rather than optional add-ons.

## Installing Raneto and serving your first page

The engines field in package.json requires Node.js 23.14.0 or newer and npm 11.9.0 or newer. Check that before anything else, because an older runtime will fail rather than degrade. The Makefile provides a default target that cleans node_modules and then runs npm install, but the plain npm route is equivalent.

```bash
npm install
npm start
```

The start script runs node server.js. With no environment variables set, the server binds to 127.0.0.1 on port 8080, so open http://127.0.0.1:8080 in a browser on the same machine. If nothing renders, confirm that your Markdown files sit under content/pages, since that is the default CONTENT_DIR.

To run it in a container instead, the Makefile defines a build and a run target that wrap the Dockerfile. The image is based on node:24.14.0-alpine, runs as user 1000, and exposes 8080.

```bash
docker build -t raneto-local:latest .
docker run --rm -it -p 8080:8080 raneto-local:latest
```

The container sets HOST=0.0.0.0, so the port mapping is reachable from the host. For a real deployment, set the environment variables the README documents. SESSION_SECRET is required for session signing and must be at least 32 characters; the README suggests generating one with openssl rand -base64 32. ADMIN_USERNAME and ADMIN_PASSWORD must be set together, and AUTHENTICATION and ALLOW_EDITING are booleans that default to off. The README's environment variable table lists SESSION_SECRET, ADMIN_USERNAME, ADMIN_PASSWORD, CONTENT_DIR, BASE_URL, SITE_TITLE, GOOGLE_ANALYTICS_ID, LOCALE, AUTHENTICATION, ALLOW_EDITING, ADDRESS and PORT, and notes that HOST is deprecated in favour of ADDRESS. With AUTHENTICATION and ALLOW_EDITING enabled, the login system protects editing and the browser editor becomes available. Leave ALLOW_EDITING unset and Raneto is a read-only site, which is the safer default for anything public.

## Where Raneto stops being the right tool

The README describes a single login system for edit protection. It does not describe roles, groups, or per-page permissions. If your knowledge base needs one team's pages hidden from another team, Raneto as documented does not provide that. You would be relying on network-level access control or a reverse proxy instead, and that is a different kind of problem.

Search is also file-based. The README lists search across file names and contents, which implies the server walks the content directory rather than querying an index. For a few hundred pages that is fine. The documentation does not state a page count at which search becomes slow, and no benchmark is published, so treat large-corpus performance as something you would have to measure yourself rather than something the project claims.

The version requirements are a real constraint. Node.js 23.14.0 is a recent line, and teams pinned to an older LTS release cannot run the current package without upgrading. The Dockerfile sidesteps this by pinning node:24.14.0-alpine, which is the pragmatic path for anyone whose host Node is older.

Finally, the project is not a documentation generator in the static-site sense. The Makefile's build target literally echoes "REMOVED", so there is no build step producing deployable HTML. If you want a CDN-hosted static site with no Node process running, Raneto is the wrong shape.

## Raneto compared with MkDocs and Docusaurus

The nearest alternative in spirit is MkDocs, which also reads Markdown from a directory. The difference is what happens next. MkDocs renders a static site at build time; you deploy the output and no application server runs. Raneto runs an Express server that resolves pages per request, which is what allows the login system and the in-browser editor to exist at all. A static site cannot offer an authenticated edit form without a separate backend.

Docusaurus takes a third position. It is a React-based static site generator with versioned docs, sidebars defined in JavaScript, and a plugin ecosystem. It produces a static bundle too, but the authoring model assumes a build pipeline and a deployment step. Raneto's authoring model assumes you save a .md file and refresh the browser.

That difference cuts both ways. Raneto gives you editing without a build, but you inherit a running Node process to patch, monitor and restart. MkDocs and Docusaurus give you a static artifact that is cheap to host and trivial to roll back, but they give up the live editor. If your authors are engineers who already commit to Git, the static route is usually less to operate. If your authors want to fix a typo in a browser without cloning anything, Raneto's editor is the reason to pick it.

## Maintenance, upgrades and the MIT licence

The last push to the default branch was on 2026-03-18, and the most recent release, 0.18.1, was tagged on 2026-03-11. The release before that, 0.18.0, dates to 2025-09-15, and 0.17.8 to 2024-02-22. The cadence is irregular: roughly a year and a half between 0.17.8 and 0.18.0, then six months to 0.18.1. The repository is not archived, so the project has not been formally retired, but the spacing between releases means you should not expect fixes on a short schedule.

Upgrade cost is dominated by the Node version floor. Because package.json requires Node.js 23.14.0 and the dependency set includes Express 5, helmet 8 and express-rate-limit 8, staying current means tracking major versions of several packages at once. The test script runs unit tests, ESLint and a Prettier check, so the project does hold itself to a lint and formatting standard; a fork that drifts from that will diverge from upstream quickly.

Licensing is straightforward. package.json declares MIT, and the LICENSE file is at the repository root. MIT permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are retained. That is a summary of what the licence text says, not legal advice; if you are redistributing Raneto inside a product, have your own counsel read the LICENSE file. One practical note: the theme is a separate package, @raneto/theme-default, published under the @raneto scope. If you fork or replace it, check that package's own licence rather than assuming it matches the server.

## Conclusion

Raneto fits teams that want documentation to live as .md files in a repository they already back up, and that can run Node.js 23.14.0 or newer. It is the wrong tool if you need per-page permissions, a database-backed review workflow, or non-technical authors who will not touch a file tree. Before adopting it, confirm three things: that your Node version satisfies the engines field, that SESSION_SECRET is set to at least 32 characters if you enable authentication, and that CONTENT_DIR points at the directory you intend to serve, since the default is content/pages.

## FAQ

### What is Raneto?

It is an MIT-licensed, Markdown-powered knowledge base for Node.js. Content lives as .md files on disk, and the README lists file-based content, search across file names and contents, a browser Markdown editor, a login system for edit protection, and a lightweight footprint as its top features.

### How do I install Raneto?

Install Node.js 23.14.0 or newer and npm 11.9.0 or newer, then run npm install followed by npm start, which executes node server.js. A Dockerfile is also included, and the Makefile wraps it with docker build -t raneto-local:latest . and docker run --rm -it -p 8080:8080 raneto-local:latest.

### Where does Raneto keep its content files?

In the directory named by CONTENT_DIR, which defaults to content/pages. The README documents CONTENT_DIR as the path to the content directory containing .md files, and environment variables override anything set in config/config.js.

### Does Raneto support user accounts and editing permissions?

The README describes a login system for edit protection, controlled by the AUTHENTICATION and ALLOW_EDITING booleans, plus ADMIN_USERNAME and ADMIN_PASSWORD which must be set together. It does not document roles, groups or per-page permissions.

### What port does Raneto run on?

Port 8080 by default, configurable through the PORT environment variable. The default ADDRESS is 127.0.0.1, so a plain npm start is only reachable locally; the Dockerfile sets HOST=0.0.0.0 instead.

### Is Raneto still maintained?

The repository is not archived. The last push was on 2026-03-18, and the most recent release, 0.18.1, was tagged on 2026-03-11, following 0.18.0 in September 2025 and 0.17.8 in February 2024.

## Sources

- [License: MIT](https://github.com/ryanlelek/Raneto/blob/main/LICENSE)
- [Project website](https://raneto.com)
- [README](https://github.com/ryanlelek/Raneto/blob/main/README.md)
- [Releases](https://github.com/ryanlelek/Raneto/releases)
- [ryanlelek/Raneto on GitHub](https://github.com/ryanlelek/Raneto)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ryanlelek-raneto