{"id":51441718,"url":"https://github.com/elementmerc/alt-markdown","last_synced_at":"2026-07-05T12:30:26.485Z","repository":{"id":363675859,"uuid":"1236688464","full_name":"elementmerc/alt-markdown","owner":"elementmerc","description":"Design sketch for an AI-pair-programmed plain-text authoring format. Pure design; no implementation yet.","archived":false,"fork":false,"pushed_at":"2026-06-09T23:13:32.000Z","size":268,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T23:15:25.563Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/elementmerc.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"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}},"created_at":"2026-05-12T13:32:59.000Z","updated_at":"2026-06-09T22:48:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/elementmerc/alt-markdown","commit_stats":null,"previous_names":["elementmerc/alt-markdown"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/elementmerc/alt-markdown","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elementmerc%2Falt-markdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elementmerc%2Falt-markdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elementmerc%2Falt-markdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elementmerc%2Falt-markdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elementmerc","download_url":"https://codeload.github.com/elementmerc/alt-markdown/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elementmerc%2Falt-markdown/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35154748,"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-07-05T02:00:06.290Z","response_time":100,"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":[],"created_at":"2026-07-05T12:30:24.372Z","updated_at":"2026-07-05T12:30:26.468Z","avatar_url":"https://github.com/elementmerc.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# alt-markdown\n\n\u003e \"Basically an overengineered synthesis of markdown built for the modern era.\"\n\nA strict superset of CommonMark that renders rich, interactive graphics in the\nbrowser with no build step, and still reads as ordinary markdown when the\nruntime is not there.\n\n\n## What it is\n\nPlain markdown, plus a small curated set of components (callouts, tabs,\naccordions, charts, maths, tables, diagrams, a table of contents). Each\ncomponent is declarative and carries a static fallback, so three things hold at\nonce:\n\n- **A true CommonMark superset.** All 652 spec examples pass, plus the GitHub\n  extensions (tables, task lists, strikethrough, autolinks, footnotes).\n- **Safe by default.** Untrusted input cannot inject a script, an event handler,\n  or a dangerous URL. Diagrams render in a script-disabled, origin-isolated iframe.\n- **No build step.** Load the runtime and the components light up; remove it and\n  the document still reads as markdown.\n\n## How it compares\n\n| Property | alt-markdown | markdown-it | marked | MDX | Markdoc |\n|---|:--:|:--:|:--:|:--:|:--:|\n| True CommonMark superset | 🟩 | 🟩 | 🟨 | 🟥 | 🟥 |\n| Safe by default | 🟩 | 🟩 | 🟥 | 🟩 | 🟩 |\n| No build step | 🟩 | 🟩 | 🟩 | 🟥 | 🟩 |\n| Renders rich components | 🟩 | 🟥 | 🟥 | 🟩 | 🟩 |\n| Degrades to plain markdown | 🟩 | 🟩 | 🟩 | 🟥 | 🟨 |\n| One core, browser and native | 🟩 | 🟥 | 🟥 | 🟥 | 🟥 |\n\n🟩 yes · 🟨 partial · 🟥 no. Each tool in its default configuration.\n\n## The cost of richness\n\nThe same one-page spec, three ways, measured in real Claude tokens:\n\n| Form | Tokens | Content (vs scaffolding) | Charts, diagrams, maths | Safe by default |\n|---|--:|:--:|:--:|:--:|\n| Plain Markdown | 606 | 77% | 🟥 | 🟨 |\n| **alt-markdown** | **637** | **70%** | 🟩 | 🟩 |\n| Self-contained HTML | 3,247 | 15% | 🟩 | 🟥 |\n\nalt-markdown costs about 5% more tokens than plain markdown but renders what\nmarkdown cannot. The equivalent self-contained HTML costs about 5x the tokens,\nis only 15% reading content, and turns any ingested string into a possible\nexploit.\n\n## Why a format, and not just HTML?\n\n| | Plain Markdown | Raw HTML | alt-markdown |\n|---|:--:|:--:|:--:|\n| Rich tables, charts, diagrams | 🟨 | 🟩 | 🟩 |\n| Reads as plain text | 🟩 | 🟥 | 🟩 |\n| Safe by default | 🟨 | 🟥 | 🟩 |\n| Easy for a person to review | 🟩 | 🟥 | 🟩 |\n| Easy for a model to rewrite | 🟩 | 🟨 | 🟩 |\n| Renders with no adoption | 🟥 | 🟩 | 🟨 |\n| Arbitrary bespoke UI | 🟥 | 🟩 | 🟥 |\n\nalt-markdown keeps plain markdown's readability and review-ability (the middle\nrows), adds the richness of HTML, and stays safe by default. The one trade is\nthat, like a plain `.md` file, a `.alt` file needs its runtime to render; the\nlast row is a deliberate scope choice, not a missing feature.\n\n## See it\n\n**[Try it live](https://elementmerc.github.io/alt-markdown/):** type alt-markdown\non the left, watch it render on the right, and share what you make with a link.\n\nOr browse the gallery: a security deep dive, a literary essay, a data-heavy piece,\nand an adversarial-Unicode stress test. Each is a plain `.alt` file that tries hard\nto break the format, in a light and a Notion-style dark theme.\n\nPrefer local? `cd js \u0026\u0026 python3 -m http.server 8000`, then open\n`http://localhost:8000/demo/`. Turn JavaScript off and every article still reads as\nordinary markdown.\n\n## Use it from the command line\n\n```\naltmd render doc.alt              # component-aware HTML\naltmd render --standalone doc.alt # one self-contained HTML file, themed\naltmd render --commonmark doc.alt # pure CommonMark HTML\naltmd fmt doc.alt                 # normalise the source\naltmd ast doc.alt                 # print the parsed AST as JSON\naltmd check doc.alt               # validate and report a diagnostic\n```\n\n`--standalone` writes a single portable file: the document reads correctly with\nno runtime, and the graphics light up when the runtime is reachable.\n\n## How it works\n\nOne Rust core compiles to WebAssembly for the browser and to a native binary for\nthe CLI, so the same grammar runs everywhere. In the browser, a small runtime\n(about 14 KB compressed) loads the core, renders the document, and upgrades each\ncomponent in place; the heavy graphics libraries (uPlot, KaTeX, Mermaid) load\nonly when a document needs them. The renderer is safe by construction: text is\nescaped, URLs are scheme-filtered, raw HTML is sanitised against an allowlist,\nand anything that could carry an exploit renders in a sandboxed iframe.\n\n## Project layout\n\n```\ncrates/\n  altmd-ast        the syntax tree and the parser/serializer traits\n  altmd-parser     comrak-backed parser, the component grammar, the serializer\n  altmd-sanitize   the raw-HTML allowlist sanitiser\n  altmd-core       the public facade: parse, render, serialise\n  altmd-wasm       the WebAssembly bindings\n  altmd-cli        the altmd command-line tool\njs/\n  packages/runtime the browser runtime that upgrades components\n  demo             the live gallery\ndocs/              the spec and the architecture guide\n```\n\n## Documentation\n\n- [docs/spec.md](docs/spec.md): the grammar and safety model.\n- [docs/architecture.md](docs/architecture.md): how the pieces fit together.\n- [CONTRIBUTING.md](CONTRIBUTING.md): how to build, test, and contribute.\n\n## Licence\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felementmerc%2Falt-markdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felementmerc%2Falt-markdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felementmerc%2Falt-markdown/lists"}