nowline
Create and edit your roadmaps in a plain-text format.
Open source Open in the app JSON README (API)
About
Create and edit your roadmaps in a plain-text format.
Details
- Kind
- Plugins
- Topic
- No topic detected
- Publisher
- lolay
- Origin
- gemini
- Category
- ferramentas
- Version
- 0.8.5
- Last push
- 2026-09-04T06:30:17Z
- Repository state
- ativo
- Language
- TypeScript
- License
- Apache-2.0
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
lolay/nowline
README
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./branding/logo-dark.svg" />
<img src="./branding/logo.svg" alt="Nowline" width="360" />
</picture>
</p>
<p align="center">
Roadmaps as code. For everyone.<br />
<strong>Human readable roadmaps, built for AI.</strong><br />
Plain <code>.nowline</code> text files. Version-controlled. Render to SVG, PNG, PDF, HTML, Mermaid, XLSX, and MS Project XML.
</p>
---
## What is Nowline?
Nowline is a text-first DSL for describing product and engineering roadmaps — human readable and machine readable. You write plain `.nowline` text files — indented, keyword-driven, diff-friendly — and tooling renders them as timelines, validates them, and composes them.
[`examples/minimal.nowline`](./examples/minimal.nowline):
```nowline
nowline v1
roadmap minimal "Starter" start:2026-01-05 scale:2w author:"Jane Doe"
swimlane engineering "Engineering"
item research "Research" duration:3w status:done
item design "Design" duration:2w status:in-progress remaining:5d
item build "Build" duration:3w status:planned
```
Renders to:
<p align="center">
<img src="./docs/screenshots/minimal.png" alt="Minimal roadmap rendered with light theme and now-line on 2026-02-09" width="720" />
</p>
## Why Nowline?
- **Text, not a Gantt chart.** Version-controlled, diffable, reviewable in a PR.
- **Indentation, not XML.** Roadmaps read like outlines, because that's how people think about them.
- **Strict enough to catch mistakes.** 30+ validation rules, clear error messages with line and column numbers.
- **Composable.** `include` other files with explicit `merge` / `ignore` / `isolate` semantics.
## Quick start
Install the CLI from your package manager:
```bash
brew trust lolay/tap # macOS / Linux / WSL (one-time)
brew install lolay/tap/nowline
```
Debian/Ubuntu and Windows users can grab the latest `.deb` or `.exe` from [GitHub Releases](https://github.com/lolay/nowline/releases/latest). See [`packages/cli/README.md`](./packages/cli/README.md#install) for the full install matrix (including `man nowline` setup).
## Toolchain
Two-tier Node policy: **Node ≥ 22** to **consume** `@nowline/*` packages (`engines.node` on every published package), **Node 26** (`.nvmrc`) to **develop**. CI tests both versions on every PR. See [Toolchain & Supported Versions](./CONTRIBUTING.md#toolchain--supported-versions) for the full policy and bump procedure.
Render your first roadmap:
```bash
nowline examples/minimal.nowline # writes ./minimal.svg
nowline --version
```
Or scaffold a brand-new file from a template:
```bash
nowline --init my-project # ./my-project.nowline
nowline --init my-project -t teams # ./my-project.nowline (teams template)
```
For the VS Code / Cursor / VSCodium extension, search **Nowline** on the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=nowline.vscode-nowline) or [Open VSX](https://open-vsx.org/extension/nowline/vscode-nowline).
> **`0.x` versioning.** `nowline` is on `0.x.y` while we settle the embed surface and IDE expansion. Public APIs may change between minor versions; full SemVer guarantees apply once we ship `1.0`. See [`specs/releasing.md`](./specs/releasing.md) for the version contract.
To run from a checkout for local development (`pnpm install && pnpm build`), see [`CONTRIBUTING.md`](./CONTRIBUTING.md).
## Use the CLI
`nowline` is **verbless**: rendering is the default. Other operations are flags on the same command.
### Render (default)
```bash
nowline roadmap.nowline # writes ./roadmap.svg
nowline roadmap.nowline -f png # writes ./roadmap.png
nowline roadmap.nowline -f pdf # writes ./roadmap.pdf
nowline roadmap.nowline -f html # writes ./roadmap.html
nowline roadmap.nowline -f mermaid # writes ./roadmap.md
nowline roadmap.nowline -f xlsx # writes ./roadmap.xlsx
nowline roadmap.nowline -f msproj # writes ./roadmap.xml
nowline roadmap.nowline -o roadmap.pdf # format inferred from extension
nowline roadmap.nowline -o - # SVG to stdout
nowline roadmap.nowline --theme dark --now 2026-03-15
nowline roadmap.nowline --now - --asset-root ./brand --no-links --strict
nowline roadmap.nowline -f pdf --page-size a4 --orientation landscape --margin 0.5in
cat roadmap.nowline | nowline - # stdin → ./roadmap.svg
```
The render pipeline is `@nowline/core` parse → `@nowline/layout` layout → `@nowline/renderer` SVG → format-specific exporter. Output is byte-for-byte deterministic for the same input, theme, and `--now`. A single `nowline` binary ships every format — see [`packages/cli/README.md`](./packages/cli/README.md#install) for install details.
### Validate (`--dry-run`)
Run the full pipeline (parse + validate + layout + format) without writing. Exits `0` on success, `1` if any errors are emitted.
```bash
nowline roadmap.nowline --dry-run
nowline roadmap.nowline -n # short alias
cat roadmap.nowline | nowline - --dry-run # read stdin
nowline roadmap.nowline -n --diagnostic-format json # machine-readable output
```
### Convert text ↔ JSON
Convert is just `-f json` (or `-f nowline` to go the other way). Input format is inferred from the extension; `--input-format` overrides for unusual filenames.
```bash
nowline roadmap.nowline -f json -o roadmap.json # text → JSON
nowline roadmap.json -f nowline -o roadmap.nowline # JSON → text (canonical)
nowline roadmap.nowline -f json -o - | jq '.ast.roadmapDecl.name'
```
The emitted JSON carries a top-level `"$nowlineSchema": "1"` so downstream tools can detect schema changes. Comments are not preserved across round-trips — see [`packages/cli/README.md`](./packages/cli/README.md) for the canonical printer rules.
### Serve (`--serve`)
Run a live-reload preview in the browser. Great while authoring.
```bash
nowline roadmap.nowline --serve # http://127.0.0.1:4318
nowline roadmap.nowline --serve -p 4400 -t dark --open
nowline roadmap.nowline --serve -o latest.svg # rewrite latest.svg on each rebuild
```
The server re-parses, re-validates, re-lays-out, and re-renders on every file change; connected clients refresh automatically via Server-Sent Events. Validation errors are displayed as an overlay on top of the most recent successful render.
### Init (`--init`)
Scaffold a new `.nowline` file in cwd. The positional argument is the **project name**, not a file path. `.nowline` is auto-appended.
```bash
nowline --init # ./roadmap.nowline (default name)
nowline --init my-project # ./my-project.nowline
nowline --init my-plan.nowline # ./my-plan.nowline (literal)
nowline --init my-project --template=teams # use the teams template
```
`minimal`, `teams`, and `product` correspond to the files under [`examples/`](./examples). Existing files are silently overwritten.
### Exit codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Validation error (parse failure, invalid reference) |
| 2 | Usage error (missing input, bad flags, unsupported format, file not found, binary→TTY refusal) |
| 3 | Output error (cannot write to destination) |
### Manual
After any package-manager install (`brew install lolay/tap/nowline`, `npm install -g @nowline/cli`, or the `.deb` from GitHub Releases), `man nowline` shows the CLI manual and `man 5 nowline` shows the full DSL reference. Both man pages also ship as standalone assets on every [GitHub Release](https://github.com/lolay/nowline/releases) — see [`packages/cli/man/`](./packages/cli/man/) for the mdoc sources.
## Language at a glance
### File structure
```nowline
nowline v1 // 1. version directive (optional, must be first)
include "shared/teams.nowline" // 2. includes
include "brand.nowline" config:isolate
config // 3. config section (optional)
scale
name: weeks
style enterprise
bg: blue
fg: navy
roadmap r "My Roadmap" // 4. roadmap section
swimlane platform
item x "Work item" duration:1w status:done
```
### Entities
| Keyword | Purpose |
|---|---|
| `roadmap` | The top-level roadmap declaration. At most one per file. |
| `swimlane` | A horizontal lane of work. |
| `item` | A unit of work inside a swimlane. |
| `parallel` | A block whose children run concurrently. |
| `group` | A logical grouping of items, rendered together. |
| `anchor` | A named date on the timeline. |
| `milestone` | A point-in-time marker that depends on work. |
| `footnote` | A callout anchored to one or more entities. |
| `person`, `team` | Ownership references. |
| `style`, `label`, `status`, `duration`, `scale`, `calendar`, `default` | Config and declaration entries. |
### Properties
```nowline
item auth "Auth refactor"
duration: 2w // duration literal: d, w, m, q, y
status: in-progress // builtin or custom from config
owner: sam // id reference (person or team)
after: kickoff // dependency (single)
after: [kickoff, approvals] // dependency (list)
remaining: 30% // percentage
labels: [security, p0] // list of label ids
link: https://… // URL (bare, no quotes)
```
### Roadmap start date
A `roadmap` may carry an optional `start:YYYY-MM-DD` that anchors the timeline baseline:
```nowline
roadmap platform-2026 "Platform 2026" start:2026-01-06
```
- If the roadmap contains any `anchor`, or any `milestone` with a `date:` property, `start:` is **required**.
- Every such date must be on or after `start:`.
- A pure-relative roadmap (built from `duration:` and `after:` only) does not need `start:`.
- Across `include`s that don't use `roadmap:ignore`, the parent and any included roadmap must agree on `start:` — both absent, or both present with the same value. Mismatches are errors, not silent overrides.
### Includes
```nowline
include "teams.nowline" // merge everything (default)
include "snippet.nowline" config:ignore // skip child config
include "partner.nowline" roadmap:isolate // render child as a separate region
```
- `merge` — default: child content is merged; parent definitions win on collision.
- `ignore` — child content of that kind is discarded.
- `isolate` — child roadmap is preserved as a self-contained region (requires a `roadmap` in the child).
For the full grammar reference, see [`specs/dsl.md`](./specs/dsl.md).
## Examples
Progressively-richer examples are included:
- [`examples/minimal.nowline`](./examples/minimal.nowline) — smallest complete file.
- [`examples/capacity.nowline`](./examples/capacity.nowline) — lane and item `capacity:` with on-call support taking a quarter of team bandwidth; lane utilization underline.
- [`examples/sizing.nowline`](./examples/sizing.nowline) — T-shirt `size:` entries plus shortening calendar span with `capacity:` (parallel work).
- [`examples/teams.nowline`](./examples/teams.nowline) — persons, teams, anchors, milestones, footnotes.
- [`examples/product.nowline`](./examples/product.nowline) — full config, styles, labels, parallels, groups, descriptions.
- [`examples/long.nowline`](./examples/long.nowline) — stress test: eight swimlanes, ~160 items, parallels, groups, anchors, milestones, footnotes, cross-cutting labels. Used for layout/render perf.
- [`examples/nested.nowline`](./examples/nested.nowline) + [`examples/nested/`](./examples/nested) — parent Security swimlane plus five isolated per-team roadmap includes (iOS, Android, Web, Platform, Data). Demonstrates `roadmap:isolate`.
## Editor support
A TextMate grammar lives at [`grammars/nowline.tmLanguage.json`](./grammars/nowline.tmLanguage.json). It works in any editor that supports TextMate grammars (VS Code, Sublime Text, Zed, IntelliJ via third-party plugins, etc.). A first-class LSP server and VS Code extension are tracked in [`packages/lsp/`](./packages/lsp) and [`packages/vscode-extension/`](./packages/vscode-extension).
## Use as a library
`@nowline/core` is a pure-TypeScript parser, typed AST, and validator built on [Langium](https://langium.org/). Everything the CLI does on top of parsing is itself built against this library. See [`packages/core/README.md`](./packages/core/README.md) for the API and a usage example.
## Status
Nowline is on `v0.x` — published to Homebrew, npm, the VS Code Marketplace, Open VSX, and GitHub Releases. The parser, validator, layout, renderer, every export format (SVG, PNG, PDF, HTML, Markdown+Mermaid, XLSX, MS Project XML), and the verbless CLI (`--dry-run`, `--init`, `--serve`) are usable today. Breaking changes may land between `0.x` minor versions while the embed surface and IDE expansion settle; full SemVer guarantees kick in at `1.0`. The release-by-release roadmap lives in [`specs/milestones.md`](./specs/milestones.md).
## Contributing
Bug reports, feature requests, and pull requests are welcome. Start with [`CONTRIBUTING.md`](./CONTRIBUTING.md) for setup, build/test commands, and the expected workflow. Before opening an issue, please check the templates under [`.github/ISSUE_TEMPLATE/`](./.github/ISSUE_TEMPLATE). Security issues should follow [`SECURITY.md`](./SECURITY.md). All participation is governed by our [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md).
Design specs for the DSL, renderer, CLI, IDE integrations, and OSS milestones live under [`specs/`](./specs) — start there to understand how Nowline is shaped before touching code.
## License
Apache 2.0 — see [`LICENSE`](./LICENSE).