lean

README

Lean

A lightweight, open-source document engine written in Go.

Lean is building a shared document representation for parsing, transforming, and exporting standard document formats without binding an application to one editor.

Direction

Lean is working toward this architecture:

Markdown ──┐                              ┌──→ Markdown
HTML ──────┤                              ├──→ HTML
.docx ─────┤    ┌────────────────┐        ├──→ .docx
ODT (v1.1) ┤───→│  Document IR   │───────→├──→ ODT (v1.1)
Plain text ─┘    └────────────────┘        ├──→ Typst → PDF / PNG / SVG
                        ↕                  └──→ EPUB (planned)
                  Operation Model
                 (edit, undo, redo)

The first alpha opens and saves a conservative DOCX profile through a typed document representation. The editable profile covers document metadata, page and section layout, text and paragraph formatting, tables, links, numbering, named styles, and embedded images. A fidelity report keeps unsupported documents read only instead of silently changing them.

Lean also imports and exports CommonMark and HTML. It exports Typst for PDF, PNG, and SVG rendering. Tracked changes, fields, comments, headers, footers, footnotes, and mutation APIs remain outside the editable alpha profile.

Native Markdown files

Use OpenMarkdownSource to open a UTF-8 Markdown file without converting its canonical source into the document representation. Bytes returns a copy of the original bytes, including a byte order mark, newline conventions, frontmatter, comments, reference links, and unsupported syntax.

RenderHTML renders CommonMark with tables, task lists, strikethrough, and autolinks. Raw HTML is sanitized; scripts, inline styles, and dangerous links are removed. Rendering does not rewrite the source. Applications must isolate previews and control external resource loading and navigation.

RenderSyntaxHTML(CommonMark) and RenderSyntaxHTML(GitHubFlavoredMarkdown) return syntax output for conversion and conformance checking. This output can contain unsafe HTML and must be sanitized before browser display. The CommonMark dialect follows 0.31.2; GFM adds the five published 0.29 extensions. The older GFM base examples are not the CommonMark 0.31.2 contract.

The existing Markdown parser and exporter remain conversion APIs. Applications must not use their normalized output as a lossless save of the original file. A visual editor needs source-preserving edits and a declared feature profile before it can replace native source editing.

Quick Start

go get github.com/lean-docs/lean@v0.1.0-alpha.2

Building from Source

git clone https://github.com/lean-docs/lean.git
cd lean
go build ./...

# Test the released DOCX surface
go test -race -count=1 . ./pkg/ir ./pkg/export/ooxml

Project Layout

lean/
├── cmd/lean/              CLI binary
├── pkg/
│   ├── ir/                Document model
│   ├── parser/            Markdown, HTML, OOXML readers
│   ├── export/            Markdown, HTML, OOXML, Typst writers
│   ├── hittest/           Coordinate → document position mapping
│   ├── selection/         Selection geometry
│   └── font/              Font loading and metrics
├── testdata/              Fixtures and golden files
├── ARCHITECTURE.md        Design decisions and rationale
└── SRS.md                 Requirements and test specification

Status

Alpha software. The public API and document fidelity guarantees can change before v1.0. See CHANGELOG.md for the implemented scope. Release notes are kept in docs/releases. Maintainers can publish a release by following RELEASING.md.

License

Lean is MIT licensed. See THIRD_PARTY_NOTICES.md for the licenses that cover imported conformance fixtures.

Documentation

Overview

Package lean is a lightweight document rendering engine.

It provides parsing, layout, rendering, and export of documents through a clean internal intermediate representation (IR).

Index

• Variables
• func Version() string
• type FidelityReport
  • func OpenDOCX(input []byte) (*ir.Document, FidelityReport, error)
  • func SaveDOCX(document *ir.Document) ([]byte, FidelityReport, error)
• type MarkdownDialect
• type MarkdownSource
  • func OpenMarkdownSource(source []byte) (*MarkdownSource, error)
  • func (document *MarkdownSource) Bytes() []byte
  • func (document *MarkdownSource) RenderHTML() ([]byte, error)
  • func (document *MarkdownSource) RenderSyntaxHTML(dialect MarkdownDialect) ([]byte, error)

Variables

var ErrInvalidMarkdown = errors.New("lean: Markdown must contain valid UTF-8 text")

var ErrUnsupportedDocument = errors.New("lean: document contains unsupported features")

Functions

func Version

func Version() string

Version returns the current semantic version of the lean engine.

Types

type FidelityReport

type FidelityReport struct {
	Format      string   `json:"format"`
	Editable    bool     `json:"editable"`
	Preserved   []string `json:"preserved"`
	Unsupported []string `json:"unsupported"`
}

func OpenDOCX

func OpenDOCX(input []byte) (*ir.Document, FidelityReport, error)

func SaveDOCX

func SaveDOCX(document *ir.Document) ([]byte, FidelityReport, error)

type MarkdownDialect

type MarkdownDialect string

const (
	CommonMark             MarkdownDialect = "commonmark"
	GitHubFlavoredMarkdown MarkdownDialect = "gfm"
)

type MarkdownSource

type MarkdownSource struct {
	// contains filtered or unexported fields
}

func OpenMarkdownSource

func OpenMarkdownSource(source []byte) (*MarkdownSource, error)

func (*MarkdownSource) Bytes

func (document *MarkdownSource) Bytes() []byte

func (*MarkdownSource) RenderHTML

func (document *MarkdownSource) RenderHTML() ([]byte, error)

func (*MarkdownSource) RenderSyntaxHTML

func (document *MarkdownSource) RenderSyntaxHTML(dialect MarkdownDialect) ([]byte, error)