# The Homebrewery: Markdown Authoring for D&D Documents

> The Homebrewery turns Markdown into styled tabletop RPG homebrew, with a hosted editor and a self-hosted JavaScript application backed by MongoDB. It suits game designers who want editable source documents and Player's Handbook-like presentation without building a publishing system themselves.

**naturalcrit/homebrewery** — Create authentic looking D&D homebrews using only markdown

- Repository: https://github.com/naturalcrit/homebrewery
- Website: https://homebrewery.naturalcrit.com
- Stars: 1,368 · Forks: 387
- Language: JavaScript
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/naturalcrit-homebrewery

## Why The Homebrewery Exists for D&D Authors

The Homebrewery addresses a specific publishing gap between plain Markdown and finished tabletop RPG material. An author can write structured text in Markdown while relying on the project for D&D-oriented styling and an editing environment designed around documents such as adventures, characters, and rules. The target user is not someone seeking a general-purpose writing application. It is a designer, game master, or publisher who wants readable source files that can also produce a familiar, styled presentation.

The hosted option at `https://homebrewery.naturalcrit.com` is the README's recommended starting point. That matters because the project can be used without first operating a Node.js application or database. The open-source deployment path is available when code changes, local operation, or control of the hosting environment are important.

The repository also separates concerns that a static Markdown converter would combine. `client/`, `server/`, `shared/`, `themes/`, `config/`, and `vitePlugins/` indicate a JavaScript application with browser code, server code, shared logic, presentation themes, configuration, and build-time plugins. The repository layout supports a full web application rather than a single Markdown stylesheet, although the README excerpt does not describe each request or persistence path in detail.

The MIT license covers the project itself. The README separately warns that creators remain responsible for obtaining the rights to images and other resources they use. That distinction is practical for paid adventures: an MIT-licensed editor does not grant permission for every visual asset that an author inserts into a document.

## Markdown, Stylesheets, and the Homebrewery Rendering Path

The core authoring model is Markdown. That keeps content editable as text and avoids requiring authors to position every heading, box, or page element through a graphical layout program. The project adds the presentation layer needed for D&D content. Its standalone output is available as `phb.standalone.css`, described by the README as the generated stylesheet for pages that should look like they came from the Player's Handbook.

This separation creates two adoption modes. A writer can work through the web application, while a developer who only needs the visual treatment can use the standalone CSS instead of installing the full server. The latter is not a complete document hosting system, but it can be relevant when an existing publishing pipeline already handles Markdown and pages.

The repository's `themes/` directory and package scripts for theme and CSS tests indicate that rendering is not represented by one immutable design. `server.js` starts the application, while `vite.config.js`, `vitePlugins/`, and the `build` script place browser assets under a Vite-based build process. The documentation does not provide a complete request trace from Markdown input through database storage to print output, so a precise internal rendering sequence should not be assumed.

The test scripts offer more specific evidence about supported behavior. The repository defines tests for basic Markdown, variables, Mustache syntax, hard breaks, server themes, CSS generation, notifications, and content negotiation. These names show that parsing rules, template-like variables, and server responses form separate test areas. They do not establish compatibility with every Markdown implementation, so existing documents should be checked against the project's own syntax expectations.

## Self-Hosting on Node.js and MongoDB

The README says the easiest first use is the hosted website, but code changes require a local server. Its tutorial begins by installing Git, MongoDB Community, and Node.js, cloning the repository, and setting `NODE_ENV=local`. The README currently says Node.js v16 or higher, while `package.json` declares `"node": ">=26.4.0"` and npm `>=10.8 <12`. The package manifest is the stricter source for the current engine requirement.

Clone the repository with the command published in the README:

```bash
git clone https://github.com/naturalcrit/homebrewery.git
```

For a temporary setting on Linux or macOS, configure the documented environment variable:

```bash
export NODE_ENV=local
```

After installing Node.js, npm, and MongoDB, install the JavaScript dependencies and start the server from the repository:

```bash
npm install
npm start
```

The README says the first startup creates database indexes and that a new empty database should finish in seconds. Once startup completes, open `http://localhost:8000`. That address is the first concrete verification point: the browser should reach the locally running Homebrewery rather than the hosted site.

The Windows MongoDB preparation is more involved. The README calls for a `C:\data\db` directory, starts `mongod`, places the MongoDB `bin` directory on `path`, and uses the shell to select and seed the `homebrewery` database. Its seed command is:

```javascript
use homebrewery
db.brews.insertOne({"title":"test"})
```

The README says the second command should report `switched to db homebrewery`, followed by an acknowledged insert result. The exact `ObjectId` is generated and will differ. This procedure is documented specifically for Windows, while the environment variable examples also cover PowerShell, CMD, Linux, and macOS.

## Running The Homebrewery with Docker Compose

For an isolated local deployment, the repository contains a Dockerfile and `docker-compose.yml`. The Docker image is based on `node:26.4.0-alpine`, installs Git, sets `NODE_ENV=docker`, copies the package configuration, installs npm dependencies, builds the application with Vite, exposes port 8000, and starts it through `npm start`.

The Compose file defines two services: `mongodb` and `homebrewery`. MongoDB uses the `mongo:latest` image and stores database files in the named `mongodata` volume. The Homebrewery service connects through `MONGODB_URI: mongodb://mongodb/homebrewery` and maps container port 8000 to host port 8000.

It would be inappropriate to invent a command such as `docker compose up`, even though that is a common Docker workflow. The concrete configuration fact is that the intended topology consists of the application container and a separate MongoDB service connected by service name.

Using `mongo:latest` also makes the database image unpinned. That may simplify an initial deployment, but it gives the compose file no fixed MongoDB version to reproduce later. Organizations evaluating a deployment should compare that flexibility with their requirement for repeatable environments. The Node application image, by contrast, is pinned to `node:26.4.0-alpine`.

## Operational Limits, Data Ownership, and Upgrade Work

The first genuine limitation is documentation drift. The README's Node.js instruction says v16 or higher, but the current package manifest requires Node.js `>=26.4.0` and npm `>=10.8 <12`. A developer following only the README could select an incompatible runtime. The Dockerfile supports the manifest's direction by using Node 26.4.0, but the two sources should not be treated as interchangeable.

A second constraint is the system's data stack. Self-hosted use requires MongoDB, correct database initialization, and an application process. The compose file persists MongoDB data in a named volume, but the available documentation does not describe backup, restore, migration, or recovery procedures. The README also does not document rollback for application versions. Database and upgrade planning therefore cannot be reduced to restarting the Node.js process.

The project is not archived, and the last push was on 2026-10-15. Its listed releases include v3.21.0 on 2026-04-06, v3.20.0 on 2025-11-25, and v3.16.0 on 2024-10-13. These dates show recent release activity, but they do not specify migration complexity or compatibility between database collections and older releases. The package version is 3.24.1, which is newer than the latest listed release name.

The MIT license lowers licensing friction for use and modification, subject to its conditions. It does not resolve ownership of generated documents or third-party artwork. The README explicitly places responsibility for image and resource rights on the creator, particularly when content is sold or used for profit. Self-hosting also leaves the operator responsible for backups, access control, and database availability.

## Homebrewery Compared with Plain Markdown plus PHB CSS

The closest documented alternative is plain Markdown paired with `phb.standalone.css`. Both approaches can keep content in text and apply Player's Handbook-like presentation. The difference is scope. A Markdown converter or static-site pipeline can produce pages, but Homebrewery also provides a complete JavaScript application, server code, themes, editor-oriented files, and database-backed services.

That broader scope is useful when the hosted editing experience and server application are part of the goal. It is unnecessary when a writer needs only CSS presentation for an existing publishing stack. In that case, extracting the stylesheet avoids operating Node.js and MongoDB, although it also means taking responsibility for rendering, document storage, and export behavior outside Homebrewery.

Homebrewery is also the wrong choice for authors who require plain, portable Markdown with no Homebrewery-specific syntax or styling assumptions. The repository's tests for variables, Mustache syntax, and hard breaks indicate parsing behavior that deserves review when moving existing material. A generic editor may be simpler if the output needs to remain conventional Markdown rather than a styled tabletop document.

For evaluation, compare three concrete points: whether the hosted editor is sufficient, whether local control justifies running MongoDB, and whether the required stylesheet can be consumed without the full application. If the answer to the first is yes and the other two do not matter, the website is the least complex route. If data control or theme development is central, the repository provides more structure, with a corresponding maintenance burden.

## Conclusion

Adopt the hosted service for collaborative D&D drafting or self-host The Homebrewery when source-level control and local data matter. Do not choose it as a generic Markdown editor or as a ready-made commercial publishing package without confirming asset rights and export needs. Check the current Node.js engine requirement, MongoDB setup, and chosen print workflow first, because the README's local Node guidance conflicts with package.json.

## FAQ

### How do I run The Homebrewery locally?

Install MongoDB and a compatible Node.js release, set `NODE_ENV=local`, run `npm install` and `npm start`, then open `http://localhost:8000`. The current `package.json` requires Node.js `>=26.4.0`, despite the README saying v16 or higher.

### Does The Homebrewery require MongoDB?

Yes for the documented self-hosted setup. The README includes MongoDB database creation, while `docker-compose.yml` connects the Homebrewery service to `mongodb://mongodb/homebrewery`.

### Can I use The Homebrewery stylesheet without running the application?

The README provides `phb.standalone.css` for developers who only need the generated Player's Handbook-like styles. It does not present that file as a replacement for the full editor or server.

## Sources

- [License: MIT](https://github.com/naturalcrit/homebrewery/blob/master/LICENSE)
- [naturalcrit/homebrewery on GitHub](https://github.com/naturalcrit/homebrewery)
- [Project website](https://homebrewery.naturalcrit.com)
- [README](https://github.com/naturalcrit/homebrewery/blob/master/README.md)
- [Releases](https://github.com/naturalcrit/homebrewery/releases)

---

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