Gramax: a WYSIWYG editor for Markdown kept in your own Git repository

An editor that writes Markdown into a repository you control

Gramax is described as a free, open-source application for creating, editing and publishing docs as code. The defining constraint is where the bytes live. All data is stored locally in Markdown format, which means the files stay readable in any text editor, and the app integrates with Git for version control and collaboration.

That single decision is what separates Gramax from a hosted documentation product. The README positions it explicitly as an alternative to GitBook, Mintlify and typical static site generators, and it also lists import support for Confluence and Notion with preserved formatting and hierarchy. The target reader is a technical writer or a developer who has to hand docs to people who will not type raw Markdown, but who does not want to hand over the repository to a vendor either.

The homepage is gram.ax, the web editor is reachable at app.gram.ax, and desktop builds for Windows, Mac and Linux are downloaded from the same site. The primary language is TypeScript, the licence is GPL-3.0, and the default branch is master.

One phrase in the README deserves scepticism. The description says the app integrates with Git and stores data locally, and the usage steps confirm that the catalog is linked to a Git repository, but the README does not document how conflicts are detected, how authentication against private remotes is handled, or whether a catalog can live outside a local working copy. Those are the questions to ask before pointing it at a production repository.

Catalog, articles, and the five step loop

The usage section is short, and each step maps to a distinct piece of the system.

The first step is to create a catalog inside a workspace, which is the container for articles. The second is to edit articles in the Markdown editor, which adds tabs, tables and multimedia to what is otherwise plain Markdown. The third is to connect to Git, linking a catalog to a repository for collaboration. The fourth is to synchronize changes, pulling and pushing updates through built-in Git commands and resolving conflicts as needed. The fifth is to publish, sharing a catalog to the documentation portal.

The ordering matters more than it looks. A catalog can exist without a remote, so a writer can start on a single machine, and Git integration is a later, separable step. Publishing is also independent of both, which means the portal is one possible output of a catalog rather than the reason to create it.

The phrase "resolving conflicts as needed" is the thinnest part of the documentation. The README does not say what conflict tooling is provided, whether a merge UI exists, or what happens to a file that was edited outside the app while the editor had it open. A team that reviews documentation through pull requests should establish its own merge expectations before several people write in the same catalog at once.

One core, several front ends: desktop, web, portal and CLI

The repository layout shows a product with a single core and multiple shells. The Yarn workspace list in `package.json` names the members: the Tauri desktop app, a web app, the documentation portal, a Next based app, the CLI, the plugin SDK and example plugins, plus the end to end Playwright suite and a build package under `.ci/build`.

The Rust side mirrors that shape. The Cargo workspace lists `crates/git`, `crates/fs`, `crates/core` and `crates/test-utils` as default members, and adds a Tauri plugin for the Gramax core, a plugin for browser sessions, one for mail, one for OpenTelemetry context, a WebAssembly crate named `gramax-wasm` under the web app, a Next specific core crate, and a `crates/spa` crate.

Two design details are worth reading closely because they explain the product's character. The Git and filesystem crates are workspace default members, which says that file and repository handling are the foundation rather than a plugin. And `serde_json` is pulled in with the `preserve_order` feature, with a comment in the manifest explaining that the scan hands article frontmatter to the frontend as JSON and the frontend writes it back verbatim, so an alphabetising map would rewrite every file it touches.

That single dependency choice is the clearest statement of the project's intent. Gramax goes out of its way not to reorder your YAML frontmatter when it round-trips a document through the editor, because for a docs-as-code workflow an unexpected reordering is a diff that reviewers have to read.

Working with the source: bun workspaces, cargo members, biome

The root `package.json` is a private workspace manifest with a small set of scripts, and it is the clearest map of the developer workflow.

	"scripts": {
		"tauri": "cargo +nightly -Z unstable-options -C apps/tauri tauri dev",
		"web": "bun --cwd apps/web run dev",
		"lint": "tsc --incremental false && biome ci",

The `tauri` script runs the desktop app in development mode using a nightly Cargo with unstable options, and the `web` script starts the web app with bun from inside `apps/web`. The `lint` script is two checks in one: a full TypeScript compile with incremental caching switched off, then `biome ci` for formatting and lint rules. The `biome.jsonc` file at the top level is where those rules live.

The Rust workspace is declared separately, and the default member list shows which crates are what a plain `cargo` invocation at the root will build.

[workspace]
resolver = "2"
default-members = [
  "crates/git",
  "crates/fs",
  "crates/core",
  "crates/test-utils",
]

The workspace itself also sets shared metadata and pins the edition, and the lints table denies duplicate crate versions, which is a strict setting for a workspace of this size.

[workspace.package]
version = "0.0.0"
authors = ["gram.ax"]
description = "Gramax"
edition = "2021"

The test scripts are split by kind, which tells you how the project is tested: `bun ./scripts/run-tests.ts` runs the suite, and the same runner takes `int`, `unit` and `ges` arguments for integration, unit and end to end suites, with a separate script that restricts runs to database tests.

The dependency list in the manifest also names the editor stack. Tiptap appears through a diff utility package, and the Monaco editor is present, alongside drag and drop helpers and a tree view component for arranging pages, which matches the described drag and drop editing experience.

Publishing the documentation portal on your own server

The portal is the publishing half of the product, and the README gives two deployment routes. The first is Docker, using a `docker-compose.yaml` file fetched from gram.ax. The second is a static site build, which the README describes in two commands.

   1.   `npm install -g cli`.
   2.  `cli build --source ./content --destination ./output`.

The CLI reads a content directory and writes an output directory, and the `cli` package is one of the Yarn workspaces in the repository, so a contributor can build it from source rather than installing the published package. The static route means the portal output can be served by any web server, or hosted as plain files, with no Gramax process involved in serving traffic.

The Docker route is the one that implies an operating commitment, since the compose file is pulled from a URL rather than described in the repository. The README points to a setup page, Setting Up the Documentation Portal, for the instructions, and to the official documentation under gram.ax/resources/docs/en for the rest of the usage detail.

The gap worth naming is that the README does not state what the portal needs at runtime beyond the compose file, whether the portal requires the editor service to function, or how authentication is handled for a private portal. A self-hosted knowledge base is exactly the kind of deployment where those details decide whether a team can run it unattended.

Editor features, seventeen languages, and Confluence migration

The feature list is the strongest part of the README, and it explains who finds Gramax useful. Beyond plain Markdown editing, the visual editor supports tabs, tables, video embedding, code blocks, diagrams through Mermaid, Excalidraw and Diagrams.net, and Swagger API descriptions, so a page can hold an interactive API reference without leaving the document.

Multilingual support covers 17 languages, including English and Spanish, which matters for teams that publish the same catalog in several locales. Styling is customizable for both the app and the portal, so the documentation can carry a brand rather than a default theme.

Migration is the feature that distinguishes Gramax from a plain editor. Import from Confluence and Notion is supported with preserved formatting and hierarchy, which addresses the most common reason teams stay on those tools: the content already exists and nobody wants to retype it. The README states this as a feature but does not document which Confluence export formats are accepted, how page trees are mapped onto catalogs, or whether attachments survive the import. An import that drops images silently is a common failure, and the documentation here does not let a reader predict it.

For readers who want the full detail, the README points to the official documentation, and the project's support channels are an email address at [email protected], a Telegram community chat and the GitHub issues page.

What to check before you deploy, and what the repository does not tell you

The repository is a monorepo with an unusual amount of machinery for a documentation tool: Tauri plugins for browser sessions, mail and OpenTelemetry context, a Bugsnag crate, a vector search dependency set, an Elasticsearch interactions package, Trivy configuration for both vulnerabilities and secrets, a GitLab CI file alongside a GitHub workflow directory, and a `CLAUDE.md` at the root. There is also a `devenv` style setup through `scripts/`, a `renovate` style dependency surface implied by the lock files, and a `bun.lock` next to `Cargo.lock`.

That tells you the product is built by a team with real release engineering, not a weekend script. It also tells you that running it yourself is not a zero operation: the Docker route pulls a compose file from the website, and the dependency set includes a vector search stack and an Elasticsearch client, so a self-hosted deployment has a footprint that a static Markdown repository does not.

Two concrete gaps remain. First, the repository has no GitHub releases, so there is no published version to pin, and the workspace version is the placeholder `0.0.0` with releases presumably produced by the `releaser` workspace. The last push was on 2026-10-06. Second, the licence is GPL-3.0, which is a copyleft licence with real obligations for anyone modifying the code and distributing it, and for anyone exposing a modified version as a service. That is worth reading in the licence file itself before a team plans to run a modified instance internally, and this is not legal advice.

The pragmatic test is small. Point the app at one catalog in a scratch repository, edit with two people, publish once through the static build, and only then consider the Docker deployment and a full Confluence import.

Editorial conclusion

Gramax is a reasonable fit for a team whose documentation already lives as Markdown in Git and whose writers want a visual editor, plus a portal they host themselves; it is a poor fit for anyone who needs the Confluence feature set the README only summarises, or for people who want a hosted service with no server to maintain. Before adopting it, check the version you would deploy, because the repository has no GitHub releases, and read the GPL-3.0 licence terms for the code you plan to run as a service, since the project is a copyleft codebase rather than a permissive one. If you try it, start with a single catalog and one Git remote before migrating a whole documentation set.

Frequently asked questions

Official sources

1. Gram-ax/gramax on GitHub
2. Issues
3. License: GPL-3.0
4. Project website
5. README