{"id":50965679,"url":"https://github.com/harehare/mq-exec","last_synced_at":"2026-06-18T20:01:57.281Z","repository":{"id":359707755,"uuid":"1246686903","full_name":"harehare/mq-exec","owner":"harehare","description":"Executable Markdown — embed mq queries inside Markdown code blocks and replace them with live results.","archived":false,"fork":false,"pushed_at":"2026-05-23T02:57:26.000Z","size":279,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T04:28:39.594Z","etag":null,"topics":["documentation","markdown","mq","scripting-language"],"latest_commit_sha":null,"homepage":"https://mqlang.org","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/harehare.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2026-05-22T12:55:05.000Z","updated_at":"2026-05-23T02:57:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/harehare/mq-exec","commit_stats":null,"previous_names":["harehare/mq-exec"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/harehare/mq-exec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harehare%2Fmq-exec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harehare%2Fmq-exec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harehare%2Fmq-exec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harehare%2Fmq-exec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/harehare","download_url":"https://codeload.github.com/harehare/mq-exec/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/harehare%2Fmq-exec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34505423,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-18T02:00:06.871Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["documentation","markdown","mq","scripting-language"],"created_at":"2026-06-18T20:01:55.241Z","updated_at":"2026-06-18T20:01:57.275Z","avatar_url":"https://github.com/harehare.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003emq-exec\u003c/h1\u003e\n\n**Executable Markdown** — embed [mq](https://mqlang.org) queries inside Markdown code blocks and replace them with live results.\n\n![demo](assets/demo.gif)\n\n````markdown\n## Pending tasks\n\n```mq { exec: true, render: \"list\", input: \"tasks.md\" }\n.todo | .value\n```\n````\n\nRunning `mq-exec process report.md` rewrites the block in-place:\n\n```markdown\n## Pending tasks\n\n- Implement user authentication\n- Create API endpoints\n- Configure deployment\n```\n\n---\n\n## Contents\n\n- [Concept](#concept)\n- [Installation](#installation)\n- [CLI usage](#cli-usage)\n- [Code block syntax](#code-block-syntax)\n- [Input methods](#input-methods)\n- [Render formats](#render-formats)\n- [Library API](#library-api)\n- [Wasm / custom loaders](#wasm--custom-loaders)\n- [Architecture](#architecture)\n\n---\n\n## Concept\n\nStatic Markdown is great for documentation, but keeping data sections (task lists, reports, summaries) up to date is manual work.  \n`mq-exec` adds a thin **execution layer**: code blocks tagged with `exec: true` are treated as mq queries, evaluated at render time, and their fenced block is replaced with the query output — leaving the rest of the document untouched.\n\nUse cases:\n\n- **Dynamic documentation** — auto-inject filtered data from companion files\n- **Living reports** — regenerate progress summaries from task files\n- **AI context generation** — produce token-optimised context by selecting only the relevant Markdown nodes\n\n---\n\n## Installation\n\n```sh\n# From source (requires Rust ≥ 1.70)\ngit clone https://github.com/harehare/mq-exec\ncd mq-exec\ncargo install --path .\n```\n\n---\n\n## CLI usage\n\n```\nmq-exec \u003cCOMMAND\u003e\n\nCommands:\n  process   Process a Markdown file once and write the result\n  watch     Watch a Markdown file and re-process on changes\n  demo      Run the built-in demo\n```\n\n### process\n\n```sh\n# Print result to stdout\nmq-exec process report.md\n\n# Write to a separate file\nmq-exec process report.md -o output.md\n\n# Overwrite the source file\nmq-exec process report.md --in-place\n```\n\n### watch\n\nWatches the input file and its sibling directory.  \nRe-processes automatically whenever any `.md` file changes.\n\n```sh\n# Stream results to stdout on every change\nmq-exec watch report.md\n\n# Write to output file on every change\nmq-exec watch report.md -o output.md\n```\n\n### demo\n\nRuns an end-to-end demo using in-memory mock files (no filesystem access needed).\n\n```sh\nmq-exec demo\n```\n\n---\n\n## Code block syntax\n\nMark a fenced code block with language `mq` and a JSON-like attribute object:\n\n````markdown\n```mq { exec: true, render: \"list\", input: \"tasks.md\" }\n.todo | .value\n```\n````\n\n| Attribute | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `exec` | `true` | ✅ | Marks this block as executable |\n| `render` | string | — | Output format (default: `\"markdown\"`) |\n| `input` | string \\| string[] | — | File(s) to load as mq input |\n\nBlocks without `exec: true` are left untouched, so ordinary code samples are safe.\n\n---\n\n## Input methods\n\n### 1 — `input:` attribute (Wasm-compatible)\n\nThe runtime reads the file(s) via the injected `FileLoader` before the query runs.  \nThis works in any environment, including WebAssembly, because no filesystem call happens inside the engine.\n\n````markdown\n```mq { exec: true, render: \"list\", input: \"tasks.md\" }\n.todo | .value\n```\n````\n\nMultiple files are concatenated in order:\n\n````markdown\n```mq { exec: true, render: \"list\", input: [\"tasks.md\", \"backlog.md\"] }\n.todo | .value\n```\n````\n\n### 2 — `load_markdown()` inside the query (native only)\n\nUses mq's built-in `load_markdown(path)` function (`read_file | to_markdown`).  \nRequires the `file-io` feature and direct filesystem access.\n\n````markdown\n```mq { exec: true, render: \"list\" }\nload_markdown(\"tasks.md\") | .list | .value\n```\n````\n\n---\n\n## Render formats\n\n| `render` value | Output |\n|----------------|--------|\n| `\"markdown\"` (default) | Raw mq output, blank-line separated |\n| `\"list\"` | Unordered list: `- value` |\n| `\"ol\"` / `\"numbered_list\"` | Ordered list: `1. value` |\n| `\"table\"` | Single-column Markdown table |\n| `\"code\"` | Fenced code block |\n\n### Useful mq query patterns\n\n```mq\n# Text of unchecked task items\n.todo | .value\n\n# Text of checked task items\n.done | .value\n\n# All list item text\n.list | .value\n\n# First-level headings\n.h1 | .value\n\n# All headings\n.h | .value\n```\n\n---\n\n## Library API\n\n```rust\nuse mq_exec::{ExecMarkdownRuntime, LocalFileLoader, MockFileLoader};\n\n// Native — reads files from disk\nlet runtime = ExecMarkdownRuntime::new(LocalFileLoader);\nlet output = runtime.process(\u0026source)?;\n\n// Mock — inject content in-memory (tests, Wasm)\nlet mut loader = MockFileLoader::new();\nloader.insert(\"tasks.md\", \"- [ ] Implement auth\\n- [x] Design schema\\n\");\nlet runtime = ExecMarkdownRuntime::new(loader);\nlet output = runtime.process(\u0026source)?;\n```\n\n---\n\n## Wasm / custom loaders\n\nThe `FileLoader` trait decouples I/O from the engine so the runtime can run in any host environment:\n\n```rust\npub trait FileLoader {\n    fn load(\u0026self, path: \u0026str) -\u003e Result\u003cString, LoadError\u003e;\n}\n```\n\nImplement it to serve content from IndexedDB, a network fetch, a bundled asset, or any other source.\n\n```rust\nstruct FetchLoader;\n\nimpl FileLoader for FetchLoader {\n    fn load(\u0026self, path: \u0026str) -\u003e Result\u003cString, LoadError\u003e {\n        // e.g. call JS fetch() via wasm-bindgen\n        todo!()\n    }\n}\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharehare%2Fmq-exec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fharehare%2Fmq-exec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fharehare%2Fmq-exec/lists"}