Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/ranrar/marco

Marco — a lightweight Markdown Composer and Viewer
https://github.com/ranrar/marco

editor gtk-rs linux markdown rust webkit windows wry

Last synced: about 8 hours ago
JSON representation

Marco — a lightweight Markdown Composer and Viewer

Awesome Lists containing this project

README 

          


  






  Cross-Platform: Linux & Windows

  100% CommonMark Compliant

  International Characters Support

  


  Written in Rust

  License

  Version 0.20.0

  Beta Channel




**Marco** is a fast, cross-platform Markdown editor built in Rust with live preview, syntax extensions, and a custom parser for technical documentation.



**Polo**, its companion viewer, lets you open and read Markdown documents with identical rendering and minimal resource use.  



Both run natively on **Linux and Windows**, built with **GTK4 and Rust**, designed for speed, clarity, and modern technical writing — with features like **executable code blocks**, **document navigation**, and **structured formatting**.





  Marco Editor

  


  Marco - Full-featured Markdown editor with live preview






  Polo Viewer

  


  Polo - Lightweight Markdown viewer




View more screenshots



## Quickstart



Ready to try Marco? Installation is simple and takes less than a minute:



| Linux | Windows |

|-------|---------|

| **Beta (current release channel)** | **Beta (current release channel)** |

| Download the latest Beta `.deb` from the **Release (Beta)** page:
https://github.com/Ranrar/Marco/releases/tag/release | Download the latest Beta `.zip` from the **Release (Beta)** page:
https://github.com/Ranrar/Marco/releases/tag/release |

| **Asset:** `marco-suite__linux_amd64.deb` | **Asset:** `marco-suite__windows_amd64.zip` |

| **Install (Debian/Ubuntu):**
1. Download the `*.deb` asset for your architecture (typically `amd64`)
2. Install with your package manager (e.g. `dpkg`), then resolve any missing dependencies if prompted | **Install:**
1. Download the `.zip` asset
2. Extract to any location (e.g., `C:\Program Files\Marco`)
3. Run `marco.exe` or `polo.exe`
4. Settings are stored in the extracted folder (portable mode) |



## Welcome screen (first run)



On first launch, Marco shows a short **welcome assistant** (non-blocking) to help you get started:



- A quick overview of key features

- **Language selection** (saved to your settings)

- A telemetry page (currently a placeholder; telemetry stays disabled)



## Why Marco?



I started building Marco because I couldn't find a simple, reliable Markdown editor for Linux.  

As an IT systems manager, I've always preferred **local software** — fast, safe, and running entirely on my own machine, not in the cloud.  

In my daily work, I write a lot of **technical documentation and manuals**, so I needed a tool that could handle complex documents efficiently and reliably.



That idea became a personal challenge: to create a complete Markdown editor from the ground up — with a **custom-built parser** and a design focused on performance, clarity, and long-term potential.



---



Most Markdown editors focus on simplicity. Marco focuses on **precision**.



It's built for developers, engineers, and writers who need:

- **Native performance** — no login, no cloud, your documents stay on your machine

- **Structured documents** — full control over headings, blocks, and formatting  

- **Custom Markdown grammar** — hand-crafted parser for extensibility and AST-level control  

- **Seamless preview** — rendered with WebKit and perfectly synced with the editor  



Whether you're writing technical docs, tutorials, or long-form text, Marco turns Markdown into a professional writing tool — fast, clear, and extensible.



## Marco Markdown Functions



Marco aims for **100% CommonMark compliance** (currently 652/652 spec tests passing), plus a growing set of carefully-scoped extensions.



| Markdown / Syntax feature | Status | Notes |

|---|---|---|

| CommonMark core (block + inline) | ✅ Supported | Includes ATX + Setext headings, paragraphs, blockquotes, thematic breaks, lists, code spans/blocks, links, images, HTML blocks/inlines, hard/soft breaks, and entity references. |

| International text (Unicode) | ✅ Supported | Works with non-Latin scripts (e.g. 日本語, العربية) and emoji. |

| Heading IDs (`# Title {#id}`) | ✅ Supported | Extension for stable anchors/links. |

| Autolinks (`` / ``) | ✅ Supported | CommonMark autolinks (email becomes `mailto:`). |

| GFM-style autolink literals (`https://…`, `www.…`, `user@…`) | ✅ Supported | Rendered as links when detected in text. |

| Reference-style links (`[text][label]`, `[label][]`, `[label]`) | ✅ Supported | Resolved against `[label]: url` definitions (supports forward definitions). |

| Task lists (`- [ ]` / `- [x]`) | ✅ Supported | Rendered with themed checkbox icons. Also supports checklist-style paragraph markers (`[ ]` / `[x]` / `[X]`) and mid-paragraph markers like `Do this [ ] today`. |

| Tables (GFM pipe tables) | ✅ Supported | Header/body separation + per-column alignment. |

| Headerless pipe tables (delimiter-first, no header row) | ✅ Supported | Marco extension: the first line is the delimiter row, followed by 1+ body rows; renders as a normal table with `` only. |

| Strikethrough (`~~text~~` / `--text--`) | ✅ Supported | GFM extension (`~~text~~`). Also supports Marco's dash-style alternative (`--text--`); both render as `…`. |

| Admonitions / callouts | ✅ Supported | GitHub-style alerts (e.g. Note/Tip/Important/Warning/Caution) plus an extended custom-header form: `> [:joy: Happy Header]` (quote-styled with a custom emoji/icon + title). |

| Footnotes (`[^a]` + `[^a]: …`) | ✅ Supported | Rendered as an end-of-document footnotes section. |

| Inline footnotes (`^[...]`) | ✅ Supported | Marco extension: inline footnote content is defined at the reference point and rendered into the same footnotes section. |

| Highlight/mark (`==text==`) | ✅ Supported | Rendered as `…`. |

| Superscript (`^text^`) / subscript (`~text~`) | ✅ Supported | Marco extensions. Rendered as `…` / `…`. Subscript also accepts the arrow-style delimiter `˅text˅` (U+02C5) as an alternative. |

| Emoji shortcodes (`:joy:`) | ✅ Supported | Only recognized shortcodes convert; unknown ones stay literal text. |

| User mentions (`@name[platform]`) | ✅ Supported | Marco extension: renders as a profile link when `(platform, username)` maps to a stable public profile URL; otherwise renders as non-link text. |

| Inline checkboxes mid-paragraph (`... [x] ...`) | ✅ Supported | Marco extension: `[ ]` / `[x]` / `[X]` markers are recognized inside normal text (with conservative parsing to avoid breaking link syntax). |

| Tab blocks (`:::tab` + `@tab`) | ✅ Supported | Marco extension: `:::tab` container with `@tab ` headers; renders as a no-JS tab UI in the HTML preview (radio+label panels). Nested tab blocks are intentionally not supported. |

| Slideshow decks (`@slidestart` / `@slideend`) | ✅ Supported | Marco extension: author slide decks inside Markdown using `@slidestart[:tN]` … `@slideend`. Use `---` for horizontal slide breaks and `--` for vertical breaks (stored as metadata). Renders as an interactive slideshow in the preview (controls + dots); adds autoplay when a timer is provided. |

| YouTube embeds | Not implemented yet | Planned (URLs render as links today; embed would be opt-in). |

| Math (KaTeX / LaTeX) | ✅ Supported | Inline (`$...$`) and display (`$$...$$`) math rendering via KaTeX. Supports standard LaTeX math syntax. |

| Diagrams (Mermaid) | ✅ Supported | Flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, pie charts, Gantt charts, and more. Uses `mermaid-rs-renderer` (pure Rust, 100-1400x faster than mermaid-cli). |



## Future functions in pipeline



- **Executable code blocks** — run Bash, Python, or shell snippets directly in the preview

- **Document navigation** — TOC and cross-file links  

- **Structured formatting** — semantic elements for headings, notes, and exports  

- **Export to PDF** - Export into PDF in A4 or US Letter

- **Templates** — start from predefined markdown templates (README, runbook, etc.)



## AI-assisted development



This project is developed with occasional help from AI tools (for example, Copilot-style code suggestions). AI can speed up prototyping and refactors, but:



- Changes are still reviewed by a human.

- Tests and linting are expected to pass before merging.

- If something looks "too magical to be true", please open an issue — bugs don't get a free pass just because a robot wrote the first draft.



## Architecture & internals



Marco uses a **Cargo workspace** with three crates:



- **`core/`** — Pure Rust library with hand-crafted parser, AST builder, HTML renderer, dianostics features, and core logic (buffer management, settings, paths, cache, logging). No GTK dependencies.

- **`marco/`** — Full-featured editor binary with GTK4 UI, SourceView5 text editing, and platform-specific HTML preview (WebKit6 on Linux, WebView2 on Windows via `wry`). Depends on `core`.

- **`polo/`** — Lightweight viewer binary with GTK4 UI and platform-specific HTML preview (WebKit6 on Linux, WebView2 on Windows via `wry`). No SourceView5. Depends on `core`.

- **`assets/`** — Centralized workspace assets: themes, fonts, icons, settings.



**Key technologies:**



- **GTK4-RS** (`gtk4`, `glib`, `gio`) - Cross-platform GUI framework providing the main application window, widgets, and event handling. Used for the editor interface, menus, toolbars, and all user interactions.



- **SourceView5** (`sourceview5`) - Advanced text editor component with syntax highlighting and code editing features. Provides the main markdown editing area with features like line numbers, search/replace, and text formatting.



- **WebKit6 / WebView2** - Platform-specific web engines for HTML rendering and preview. Linux uses `webkit6` (GTK4-native WebKit), Windows uses `wry` (WebView2/Chromium wrapper). Both display the live markdown preview with support for local images, custom CSS themes, and JavaScript interactions like scroll synchronization.



- **nom** (`nom`) - Parser combinator library for building the custom markdown grammar. nom uses **recursive descent parsing** where you write Rust functions that parse pieces of input and compose them together. This approach provides total control, incremental parsing capability, and native Rust performance. The parser lives in `core/src/grammar/` and generates an AST for fine-grained control over rendering and extensibility.



- **RON** (`ron`) - Rusty Object Notation for configuration files. Used for settings storage, theme definitions, and user preferences with a human-readable format that's easy to edit and version control.



- **KaTeX** (`katex-rs`) - Rust re-implementation of the KaTeX rendering engine for mathematical expressions. Provides fast, native math rendering without JavaScript dependencies.



- **Mermaid** (`mermaid-rs-renderer` / `mmdr`) - Pure Rust implementation by [Jeremy Huang](https://github.com/1jehuang/mermaid-rs-renderer). Renders diagrams 100-1400x faster than mermaid-cli by eliminating browser overhead. Supports 23 diagram types including flowcharts, sequence diagrams, class diagrams, and more.



- **markdownlint** - A respected Markdown/CommonMark linting reference by David Anson that inspired Marco's **MD*** baseline diagnostics model. Project: [DavidAnson/markdownlint](https://github.com/DavidAnson/markdownlint).



**Current development focus:**

- Maintaining **100% CommonMark compliance** while adding extensions

- Fine-tuning the **parser grammar** for comprehensive markdown support

- Polishing the **AST builder** and **HTML renderer** components

- Refining **Markdown intelligence**: completion, hover accuracy, and diagnostic catalog coverage

- Implement robust error handling and edge-case coverage

- Optimizing **parser performance** and **caching** with Moka



## Roadmap



### Core Parser & Language Features

- [x] Syntax highlighting in editor (via intelligence engine)

- [x] Diagnostic underlines — issue detection with hover details and footer panel

- [x] Hover insights — Markdown element info and diagnostic details at cursor

- [ ] Completion (in-progress: Markdown completions available; refinement ongoing)

- [ ] Enhanced AST validation and error reporting

- [ ] Optimize parser performance and caching



### Editor Features (Marco)

- [x] Multiple layout modes: editor+preview, editor only, preview only, detachable preview

- [x] Scroll sync between editor and preview

- [x] Intelligent search

- [x] Context menus & toolbar: Quick access to formatting and actions

- [x] Syntax highlighting in editor

- [x] Diagnostics (issue underlines, footer panel, hover details, reference dialog)

- [x] Markdown hover insights

- [ ] Multi-cursor editing support

- [ ] LSP protocol for language server integration



### Viewer Fetures (Polo)

- [x] Same viewer engine as Marco

- [ ] Search function

- [ ] Mouse over link information 



### Document Features

- [x] Smart code blocks with programming languages syntax

- [x] Math rendering: KaTeX support for equations and formulas (inline `$...$` and display `$$...$$`)

- [x] Diagram support: Mermaid for flowcharts, sequence diagrams, class diagrams, and 20+ other diagram types

- [ ] Export to PDF

- [ ] Page size presets for export (A4, US Letter, etc.)

- [ ] Document navigation: TOC sidebar

- [X] Document navigation: bookmarks

- [ ] Document navigation: cross-file links



### Advanced Features

- [x] Language plugin system via. `assets/language/xx*.toml` files

- [ ] Local AI-assisted tools: writing suggestions, grammar checking, content improvement

- [ ] Collaborative editing (Yjs/CRDT): shared document model, multi-cursor, presence awareness

- [ ] Built in terminal to run code blocks in editor



### Distribution & Platform

- [x] Cross-platform support: Linux and Windows builds

- [x] Linux packaging: .deb packages

- [x] Windows packaging: Portable .zip packages

- [ ] Additional packaging: Snap, .MSI installer



### Opt-in Telemetry

- [ ] Privacy-first telemetry (opt-in, disabled by default)

  - **Privacy guarantees**: No personal data, no file content, no tracking cookies

  - **User control**: First-run dialog, settings toggle, can be disabled anytime

  - **Data collected** (anonymous, minimal):

    - App launch events (to understand active user count)

    - OS type (Linux/Windows) and app version

    - Anonymous session ID (random UUID per session, not tied to user)

    - Feature usage patterns (which menu items, view modes, export formats)

    - Error/crash reports (stack traces only, no user content)

    - Timestamp and timezone offset

  - **Purpose**: Prioritize development on most-used features, fix critical bugs faster

  - **Transmission**: Lightweight HTTPS endpoint, 3-second timeout, non-blocking



## Contributing



We welcome contributions of all sizes. Short workflow:



1. Open an issue describing the change or bug you plan to address.

2. Fork the repository and create a feature branch.

3. Add tests where appropriate and keep changes small and focused.

4. Run `cargo build` and `cargo test` locally.

5. Open a pull request referencing the issue and describe the change.



Code style & expectations:



- Keep UI code in `marco/src/ui/` and business logic in `core/src/logic/`.

- Follow Rust idioms (use `Result`, avoid panics in library code).

- Add unit tests and integration tests in `tests/` when applicable.



### High-value contributions



If you'd like to make a high-impact contribution, consider one of these areas — open an issue first so we can coordinate:



- Collaborative editing (Yjs / CRDT): add a `marco/src/components/collab/` backend that implements a `CollabBackend` trait and provide in-process tests for concurrent patches and cursor sync.

- AI-assisted tools: add a `marco/src/components/ai/` interface for suggestions/edits; keep adapters off the UI thread and provide a small example implementation.



### Component docs & assets



Reference locations for contributors working on components and translations:



- [marco/src/components/ai/README.md](marco/src/components/ai/README.md) — AI component guidance and interface notes

- [marco/src/components/collab/README.md](marco/src/components/collab/README.md) — Collaboration integration notes and references

- [documentation/language.md](documentation/language.md) — Localization provider contract and workflow

- [assets/language/language_matrix.md](assets/language/language_matrix.md) — language implementation matrix