| 1 | # architecture |
| 2 | |
| 3 | markodown is implemented in rust using a fork of the markdown-it-rust create. we |
| 4 | fork it because they are unmaintained and we have hit bugs. the rust codebase is |
| 5 | compiled to wasm and then shipped as an NPM/JSR package for use in the web |
| 6 | ecosystem. |
| 7 | |
| 8 | ## `src/`: rust code |
| 9 | |
| 10 | the rust code in `src` implements most of markodown. it exports a cli for |
| 11 | testing. most of the tests are on the rust code. here are the relevant files |
| 12 | |
| 13 | - `src/lib.rs` - main library, primary function `transform` |
| 14 | - `src/wasm.rs` - binding for WASM |
| 15 | - `src/main.rs` - testing cli |
| 16 | - `src/typescript.rs` - wrappers around oxc parser to expose parsers for |
| 17 | different subsets of the ast, including a much more garbage-forgiving |
| 18 | expression parser. |
| 19 | - `src/marko.rs` - general marko tag parser |
| 20 | - `src/marko_ast.rs` - ast structure for the marko parser |
| 21 | - `src/plugin/` - `markdown-it` plugin and all rules |
| 22 | |
| 23 | markdown-it does not support failiable plugins, so instead errors are lowered |
| 24 | into `ErrorBlock` and then the errors are combined to form the final error list. |
| 25 | all the rules are essentially validations for the Marko syntax, and get |
| 26 | reprinted as text at the end. the set of rules: |
| 27 | |
| 28 | - block |
| 29 | - `frontmatter.rs` frontmatter |
| 30 | - `statement.rs` support top-level `import`, `static function`, and others |
| 31 | - `comment.rs` allow comments |
| 32 | - `tags.rs` parser for Marko tags at the block level |
| 33 | - inline |
| 34 | - `autolink.rs` custom autolink implementation to disambiguate |
| 35 | - `template.rs` template literals |
| 36 | - `inline_tags.rs` parser for Marko tags inline |
| 37 | |
| 38 | these rules are configured in `plugin/mod.rs` in `add_all`. |
| 39 | |
| 40 | ## `lib/`: javascript package |
| 41 | |
| 42 | published to jsr and then to npm. this is a thin wrapper on top of wasm-bindgen, |
| 43 | with plugins for the web ecosystem! you can build the wasm code with |
| 44 | `sh wasm.sh`. |
| 45 | |
| 46 | - `@clo/markodown` - primary import (`lib/mod.ts`) |
| 47 | - `@clo/markodown/rollup.ts` - rollup or vite plugin (`lib/rollup.ts`) |
| 48 | - `@clo/markodown/esbuild.ts` - esbuild or bun plugin (`lib/esbuild.ts`) |
| 49 | |
| 50 | these are tested with vitest: `cd lib && npx vitest` |