{"id":29487260,"url":"https://github.com/ranrar/marco","last_synced_at":"2026-03-13T13:01:41.240Z","repository":{"id":313094202,"uuid":"1021071368","full_name":"Ranrar/Marco","owner":"Ranrar","description":"Marco — a lightweight Markdown Composer and Viewer","archived":false,"fork":false,"pushed_at":"2026-02-11T22:23:50.000Z","size":20444,"stargazers_count":46,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-02-12T07:17:54.924Z","etag":null,"topics":["editor","gtk-rs","linux","markdown","rust","webkit","windows","wry"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ranrar.png","metadata":{"files":{"readme":"README.md","changelog":"changelog/core.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"Ranrar"}},"created_at":"2025-07-16T20:47:22.000Z","updated_at":"2026-02-11T22:23:54.000Z","dependencies_parsed_at":"2025-09-03T22:21:59.514Z","dependency_job_id":"fc20ec25-7a9e-4ecd-acff-56eee184ee9d","html_url":"https://github.com/Ranrar/Marco","commit_stats":null,"previous_names":["ranrar/marco"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/Ranrar/Marco","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ranrar%2FMarco","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ranrar%2FMarco/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ranrar%2FMarco/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ranrar%2FMarco/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ranrar","download_url":"https://codeload.github.com/Ranrar/Marco/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ranrar%2FMarco/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30467783,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-13T11:00:43.441Z","status":"ssl_error","status_checked_at":"2026-03-13T11:00:23.173Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["editor","gtk-rs","linux","markdown","rust","webkit","windows","wry"],"created_at":"2025-07-15T09:01:03.921Z","updated_at":"2026-03-13T13:01:41.230Z","avatar_url":"https://github.com/Ranrar.png","language":"Rust","readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/Ranrar/marco/refs/heads/main/documentation/user_guide/Logo_marco_and_polo.png\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Platform-Linux%20|%20Windows-blue?style=for-the-badge\u0026logo=windows\u0026logoColor=white\" alt=\"Cross-Platform: Linux \u0026 Windows\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/CommonMark-100%25-brightgreen?style=for-the-badge\u0026logo=markdown\u0026logoColor=white\" alt=\"100% CommonMark Compliant\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/International-Characters-blue?style=for-the-badge\u0026logo=translate\u0026logoColor=white\" alt=\"International Characters Support\" /\u003e\n  \u003cbr/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Language-Rust-orange?style=for-the-badge\u0026logo=rust\u0026logoColor=white\" alt=\"Written in Rust\" /\u003e\n  \u003cimg src=\"https://img.shields.io/github/license/Ranrar/Marco?style=for-the-badge\" alt=\"License\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Version-0.20.0-blue?style=for-the-badge\" alt=\"Version 0.20.0\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Channel-Beta-orange?style=for-the-badge\" alt=\"Beta Channel\" /\u003e\n\u003c/p\u003e\n\n**Marco** is a fast, cross-platform Markdown editor built in Rust with live preview, syntax extensions, and a custom parser for technical documentation.\n\n**Polo**, its companion viewer, lets you open and read Markdown documents with identical rendering and minimal resource use.  \n\nBoth 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**.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"documentation/Screenshot/marco.png\" alt=\"Marco Editor\" /\u003e\n  \u003cbr/\u003e\n  \u003cem\u003eMarco - Full-featured Markdown editor with live preview\u003c/em\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"documentation/Screenshot/polo.png\" alt=\"Polo Viewer\" /\u003e\n  \u003cbr/\u003e\n  \u003cem\u003ePolo - Lightweight Markdown viewer\u003c/em\u003e\n\u003c/p\u003e\n\n\u003ca href=\"documentation/Screenshot\"\u003eView more screenshots\u003c/a\u003e\n\n## Quickstart\n\nReady to try Marco? Installation is simple and takes less than a minute:\n\n| Linux | Windows |\n|-------|---------|\n| **Beta (current release channel)** | **Beta (current release channel)** |\n| Download the latest Beta `.deb` from the **Release (Beta)** page:\u003cbr\u003ehttps://github.com/Ranrar/Marco/releases/tag/release | Download the latest Beta `.zip` from the **Release (Beta)** page:\u003cbr\u003ehttps://github.com/Ranrar/Marco/releases/tag/release |\n| **Asset:** `marco-suite_\u003cversion\u003e_linux_amd64.deb` | **Asset:** `marco-suite_\u003cversion\u003e_windows_amd64.zip` |\n| **Install (Debian/Ubuntu):**\u003cbr\u003e1. Download the `*.deb` asset for your architecture (typically `amd64`)\u003cbr\u003e2. Install with your package manager (e.g. `dpkg`), then resolve any missing dependencies if prompted | **Install:**\u003cbr\u003e1. Download the `.zip` asset\u003cbr\u003e2. Extract to any location (e.g., `C:\\Program Files\\Marco`)\u003cbr\u003e3. Run `marco.exe` or `polo.exe`\u003cbr\u003e4. Settings are stored in the extracted folder (portable mode) |\n\n## Welcome screen (first run)\n\nOn first launch, Marco shows a short **welcome assistant** (non-blocking) to help you get started:\n\n- A quick overview of key features\n- **Language selection** (saved to your settings)\n- A telemetry page (currently a placeholder; telemetry stays disabled)\n\n## Why Marco?\n\nI started building Marco because I couldn't find a simple, reliable Markdown editor for Linux.  \nAs an IT systems manager, I've always preferred **local software** — fast, safe, and running entirely on my own machine, not in the cloud.  \nIn 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.\n\nThat 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.\n\n---\n\nMost Markdown editors focus on simplicity. Marco focuses on **precision**.\n\nIt's built for developers, engineers, and writers who need:\n- **Native performance** — no login, no cloud, your documents stay on your machine\n- **Structured documents** — full control over headings, blocks, and formatting  \n- **Custom Markdown grammar** — hand-crafted parser for extensibility and AST-level control  \n- **Seamless preview** — rendered with WebKit and perfectly synced with the editor  \n\nWhether you're writing technical docs, tutorials, or long-form text, Marco turns Markdown into a professional writing tool — fast, clear, and extensible.\n\n## Marco Markdown Functions\n\nMarco aims for **100% CommonMark compliance** (currently 652/652 spec tests passing), plus a growing set of carefully-scoped extensions.\n\n| Markdown / Syntax feature | Status | Notes |\n|---|---|---|\n| 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. |\n| International text (Unicode) | ✅ Supported | Works with non-Latin scripts (e.g. 日本語, العربية) and emoji. |\n| Heading IDs (`# Title {#id}`) | ✅ Supported | Extension for stable anchors/links. |\n| Autolinks (`\u003chttps://…\u003e` / `\u003cuser@…\u003e`) | ✅ Supported | CommonMark autolinks (email becomes `mailto:`). |\n| GFM-style autolink literals (`https://…`, `www.…`, `user@…`) | ✅ Supported | Rendered as links when detected in text. |\n| Reference-style links (`[text][label]`, `[label][]`, `[label]`) | ✅ Supported | Resolved against `[label]: url` definitions (supports forward definitions). |\n| 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`. |\n| Tables (GFM pipe tables) | ✅ Supported | Header/body separation + per-column alignment. |\n| 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 `\u003ctbody\u003e` only. |\n| Strikethrough (`~~text~~` / `--text--`) | ✅ Supported | GFM extension (`~~text~~`). Also supports Marco's dash-style alternative (`--text--`); both render as `\u003cs\u003e…\u003c/s\u003e`. |\n| Admonitions / callouts | ✅ Supported | GitHub-style alerts (e.g. Note/Tip/Important/Warning/Caution) plus an extended custom-header form: `\u003e [:joy: Happy Header]` (quote-styled with a custom emoji/icon + title). |\n| Footnotes (`[^a]` + `[^a]: …`) | ✅ Supported | Rendered as an end-of-document footnotes section. |\n| Inline footnotes (`^[...]`) | ✅ Supported | Marco extension: inline footnote content is defined at the reference point and rendered into the same footnotes section. |\n| Highlight/mark (`==text==`) | ✅ Supported | Rendered as `\u003cmark\u003e…\u003c/mark\u003e`. |\n| Superscript (`^text^`) / subscript (`~text~`) | ✅ Supported | Marco extensions. Rendered as `\u003csup\u003e…\u003c/sup\u003e` / `\u003csub\u003e…\u003c/sub\u003e`. Subscript also accepts the arrow-style delimiter `˅text˅` (U+02C5) as an alternative. |\n| Emoji shortcodes (`:joy:`) | ✅ Supported | Only recognized shortcodes convert; unknown ones stay literal text. |\n| 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. |\n| Inline checkboxes mid-paragraph (`... [x] ...`) | ✅ Supported | Marco extension: `[ ]` / `[x]` / `[X]` markers are recognized inside normal text (with conservative parsing to avoid breaking link syntax). |\n| Tab blocks (`:::tab` + `@tab`) | ✅ Supported | Marco extension: `:::tab` container with `@tab \u003ctitle\u003e` headers; renders as a no-JS tab UI in the HTML preview (radio+label panels). Nested tab blocks are intentionally not supported. |\n| 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. |\n| YouTube embeds | Not implemented yet | Planned (URLs render as links today; embed would be opt-in). |\n| Math (KaTeX / LaTeX) | ✅ Supported | Inline (`$...$`) and display (`$$...$$`) math rendering via KaTeX. Supports standard LaTeX math syntax. |\n| 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). |\n\n## Future functions in pipeline\n\n- **Executable code blocks** — run Bash, Python, or shell snippets directly in the preview\n- **Document navigation** — TOC and cross-file links  \n- **Structured formatting** — semantic elements for headings, notes, and exports  \n- **Export to PDF** - Export into PDF in A4 or US Letter\n- **Templates** — start from predefined markdown templates (README, runbook, etc.)\n\n## AI-assisted development\n\nThis project is developed with occasional help from AI tools (for example, Copilot-style code suggestions). AI can speed up prototyping and refactors, but:\n\n- Changes are still reviewed by a human.\n- Tests and linting are expected to pass before merging.\n- 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.\n\n## Architecture \u0026 internals\n\nMarco uses a **Cargo workspace** with three crates:\n\n- **`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.\n- **`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`.\n- **`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`.\n- **`assets/`** — Centralized workspace assets: themes, fonts, icons, settings.\n\n**Key technologies:**\n\n- **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.\n\n- **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.\n\n- **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.\n\n- **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.\n\n- **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.\n\n- **KaTeX** (`katex-rs`) - Rust re-implementation of the KaTeX rendering engine for mathematical expressions. Provides fast, native math rendering without JavaScript dependencies.\n\n- **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.\n\n- **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).\n\n**Current development focus:**\n- Maintaining **100% CommonMark compliance** while adding extensions\n- Fine-tuning the **parser grammar** for comprehensive markdown support\n- Polishing the **AST builder** and **HTML renderer** components\n- Refining **Markdown intelligence**: completion, hover accuracy, and diagnostic catalog coverage\n- Implement robust error handling and edge-case coverage\n- Optimizing **parser performance** and **caching** with Moka\n\n## Roadmap\n\n### Core Parser \u0026 Language Features\n- [x] Syntax highlighting in editor (via intelligence engine)\n- [x] Diagnostic underlines — issue detection with hover details and footer panel\n- [x] Hover insights — Markdown element info and diagnostic details at cursor\n- [ ] Completion (in-progress: Markdown completions available; refinement ongoing)\n- [ ] Enhanced AST validation and error reporting\n- [ ] Optimize parser performance and caching\n\n### Editor Features (Marco)\n- [x] Multiple layout modes: editor+preview, editor only, preview only, detachable preview\n- [x] Scroll sync between editor and preview\n- [x] Intelligent search\n- [x] Context menus \u0026 toolbar: Quick access to formatting and actions\n- [x] Syntax highlighting in editor\n- [x] Diagnostics (issue underlines, footer panel, hover details, reference dialog)\n- [x] Markdown hover insights\n- [ ] Multi-cursor editing support\n- [ ] LSP protocol for language server integration\n\n### Viewer Fetures (Polo)\n- [x] Same viewer engine as Marco\n- [ ] Search function\n- [ ] Mouse over link information \n\n### Document Features\n- [x] Smart code blocks with programming languages syntax\n- [x] Math rendering: KaTeX support for equations and formulas (inline `$...$` and display `$$...$$`)\n- [x] Diagram support: Mermaid for flowcharts, sequence diagrams, class diagrams, and 20+ other diagram types\n- [ ] Export to PDF\n- [ ] Page size presets for export (A4, US Letter, etc.)\n- [ ] Document navigation: TOC sidebar\n- [X] Document navigation: bookmarks\n- [ ] Document navigation: cross-file links\n\n### Advanced Features\n- [x] Language plugin system via. `assets/language/xx*.toml` files\n- [ ] Local AI-assisted tools: writing suggestions, grammar checking, content improvement\n- [ ] Collaborative editing (Yjs/CRDT): shared document model, multi-cursor, presence awareness\n- [ ] Built in terminal to run code blocks in editor\n\n### Distribution \u0026 Platform\n- [x] Cross-platform support: Linux and Windows builds\n- [x] Linux packaging: .deb packages\n- [x] Windows packaging: Portable .zip packages\n- [ ] Additional packaging: Snap, .MSI installer\n\n### Opt-in Telemetry\n- [ ] Privacy-first telemetry (opt-in, disabled by default)\n  - **Privacy guarantees**: No personal data, no file content, no tracking cookies\n  - **User control**: First-run dialog, settings toggle, can be disabled anytime\n  - **Data collected** (anonymous, minimal):\n    - App launch events (to understand active user count)\n    - OS type (Linux/Windows) and app version\n    - Anonymous session ID (random UUID per session, not tied to user)\n    - Feature usage patterns (which menu items, view modes, export formats)\n    - Error/crash reports (stack traces only, no user content)\n    - Timestamp and timezone offset\n  - **Purpose**: Prioritize development on most-used features, fix critical bugs faster\n  - **Transmission**: Lightweight HTTPS endpoint, 3-second timeout, non-blocking\n\n\n## Contributing\n\nWe welcome contributions of all sizes. Short workflow:\n\n1. Open an issue describing the change or bug you plan to address.\n2. Fork the repository and create a feature branch.\n3. Add tests where appropriate and keep changes small and focused.\n4. Run `cargo build` and `cargo test` locally.\n5. Open a pull request referencing the issue and describe the change.\n\nCode style \u0026 expectations:\n\n- Keep UI code in `marco/src/ui/` and business logic in `core/src/logic/`.\n- Follow Rust idioms (use `Result\u003cT, E\u003e`, avoid panics in library code).\n- Add unit tests and integration tests in `tests/` when applicable.\n\n### High-value contributions\n\nIf you'd like to make a high-impact contribution, consider one of these areas — open an issue first so we can coordinate:\n\n- 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.\n- 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.\n\n### Component docs \u0026 assets\n\nReference locations for contributors working on components and translations:\n\n- [marco/src/components/ai/README.md](marco/src/components/ai/README.md) — AI component guidance and interface notes\n- [marco/src/components/collab/README.md](marco/src/components/collab/README.md) — Collaboration integration notes and references\n- [documentation/language.md](documentation/language.md) — Localization provider contract and workflow\n- [assets/language/language_matrix.md](assets/language/language_matrix.md) — language implementation matrix\n","funding_links":["https://github.com/sponsors/Ranrar"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Franrar%2Fmarco","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Franrar%2Fmarco","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Franrar%2Fmarco/lists"}