Skip to main content

Introduction

Readma is a workspace-compatible README generator for Deno, pnpm/npm and Cargo projects. It reads the project files you already maintain — deno.json, package.json, Cargo.toml, pnpm-workspace.yaml — and renders a complete, well-structured README.md with:

  • a centered logo, title and description header,
  • a row of relevant shields.io badges,
  • a collapsible table of contents with GitHub-compatible anchors,
  • your own markdown in the standard sections (features, installation, usage, roadmap, contributing, acknowledgments…),
  • a workspace members table on the root readme,
  • a repobeats analytics footer (optional).
deno run -A jsr:@readma/cli gen

Why Readma?​

Hand-written READMEs rot: badges point to dead URLs, installation snippets drift from the actual package names, and monorepo members each need their own copy-pasted boilerplate. Readma treats your README like build output:

Hand-written READMEReadma
Badges copied from other repos14 built-in badges derived from your files
Install commands maintained by handDerived from language + registry
One README per package, manuallyOne config, N readmes (root + members)
Stale docs discovered in reviewgen --check fails CI before review
Config without validationvalidate lints config and file refs

Design principles​

  1. Your content stays yours. Readma owns the scaffolding — badges, table of contents, section layout — while every section body is plain markdown you write in one typed config file.
  2. Detect, don't ask. Language, package registry, workspace members, license, git branch and even your GitHub username are inferred from local files, not from interactive prompts.
  3. Pure rendering. All environment-dependent values (branch, license, issue template URLs) are resolved once into a context, then rendering is a pure function — which is what makes --check and --dry-run trivial to support.
  4. Quality gate. 100% test coverage, deno lint and oxlint --deny-warnings in pedantic mode with zero suppressions.

Quick start: five minutes​

1. Prerequisites​

  • Deno 2.0 or higher
  • A git repository (branch and license are auto-detected)

2. Scaffold a config​

deno run -A jsr:@readma/cli init

This detects your git remote, workspace layout and license, then writes a readma.config.ts at the root:

import type * as types from "@readma/core";

const config: types.ReadmeTemplateArgs = {
  language: "ts",
  title: "My project",
  author: "me",
  githubUsername: "me",
  repoName: "my-project",
  xHandle: "me",
  domain: "gmail",
  email: "me",
  images: { logo: "images/logo.png" },
  sections: {
    features: "\n- Fast\n- Small",
    projectDescription: "A short description",
    about: "About the project",
    installation: "```sh\ndeno add my-project\n```",
    acknowledgments: "\n- [Best README](https://github.com/othneildrew/Best-README-Template)",
    gettingStarted: "Clone and run",
    usage: "deno task start",
    roadmap: "\n- [x] Ship",
  },
  template: {
    bugReport: "bug-report.yml",
    featRequest: "feature-request.yml",
  },
  backToTop: true,
};

export default config;

3. Generate​

# Preview without writing
deno run -A jsr:@readma/cli gen --dry-run

# Write README.md at the root and inside every workspace member
deno run -A jsr:@readma/cli gen
warning

gen overwrites README.md files. Commit your work first, or start with --dry-run.

4. Keep it green in CI​

- name: Check readmes are in sync
  run: deno run -A jsr:@readma/cli gen --check

--check re-renders every readme in memory and exits with code 2 when a file would change. Add --offline to skip every network call.

Where to go next​