diff --git a/README.md b/README.md index b3408117..4fb666e1 100644 --- a/README.md +++ b/README.md @@ -16,97 +16,64 @@ $\textcolor{#2ecc40}{\textsf{server}}$ and $\textcolor{#0074d9}{\textsf{browser} Data Flow

-Specifically, it provides several typical approaches: +Specifically, it first typically presents a typst document in three forms: -- Provides a render to export typst document as browser-friendly SVG documents. +- [Form1](https://myriad-dreamin.github.io/typst.ts/cookery/guide/compiler/ts-cli.html): Render to SVG and then embed it as a high-quality vectored image directly. -- Arrange typst documents to a compressed artifact, which then get realized in client side. +- [Form2](https://myriad-dreamin.github.io/typst.ts/cookery/guide/compiler/ts-cli.html): Preprocessed to a Vector Format artifact. -- Provide a world implementation suitable for NodeJs or Browser environments, to bind typst's compiler to Javascript. +- [Form3](https://myriad-dreamin.github.io/typst.ts/cookery/guide/compiler/serverless.html): Manipulate a canvas element directly. -Visualized Feature: +The _Form2: Vector Format_ is developed specially for typst documents, and it has several fancy features: Todo: Visualized Feature: -- Artifact Streaming +- Data Sharing across multiple layouts. -- Incremental Rendering +- Artifact Streaming. -- Incremental Font Transfer +- Incremental Rendering. -### Application +So with _Form2_, you can continue rendeing the document in different ways: -- [A Website built with Typst.ts](https://myriad-dreamin.github.io/typst.ts/) +##### Static but responsive rendering -- [Instant VSCode Preview Plugin](https://github.com/Enter-tainer/typst-preview-vscode) +Example Application: [single-file](https://github.com/Myriad-Dreamin/typst.ts/blob/main/packages/typst.ts/index.html), [typst-book](https://github.com/Myriad-Dreamin/typst-book) and [hexo-renderer-typst](https://github.com/Myriad-Dreamin/typst.ts/tree/main/packages/hexo-renderer-typst) -- [typst-book - A simple tool for creating modern online books in pure typst.](https://github.com/Myriad-Dreamin/typst-book) +A compressed artifact containing data for different theme and screen settings. The bundle size of artifacts is optimized for typst documents. -- [Renderer Plugin for Hexo, a Blog-aware Static Site Generator](https://www.npmjs.com/package/hexo-renderer-typst) +##### Incremental server-side rendering -- Renderer/Component Library for [JavaScript](https://www.npmjs.com/package/@myriaddreamin/typst.ts), [React](https://www.npmjs.com/package/@myriaddreamin/typst.react), and [Angular](https://www.npmjs.com/package/@myriaddreamin/typst.angular) +Example Application: [typst-preview](https://github.com/Enter-tainer/typst-preview-vscode) -### Prerequisite +Build a server for compilation with [Compiler Service](https://myriad-dreamin.github.io/typst.ts/cookery/guide/compiler/service.html), streaming the artifact, and render it incrementally. -- The font assets for Typst.ts are not included in this repository. See [Download Font Assets](./docs/download-font-assets.md) for more information. +##### Serverless client-side rendering -### Installation +Example Application: [single-file](https://github.com/Myriad-Dreamin/typst.ts/blob/main/packages/typst.ts/examples/compiler.html) -Install latest precompiler via cargo: +Run the entire typst directly in browser, like [typst.app](https://typst.app). -```shell -cargo install --locked --git https://github.com/Myriad-Dreamin/typst.ts typst-ts-cli -``` +### Application -Or Download the latest release from [GitHub Releases](https://github.com/Myriad-Dreamin/typst.ts/releases). +- [A Website built with Typst.ts](https://myriad-dreamin.github.io/typst.ts/) -### CLI +- [Instant VSCode Preview Plugin](https://github.com/Enter-tainer/typst-preview-vscode) -Run [Typst compiler](https://github.com/typst/typst) with `typst.ts`'s exporters (renderers) Example: +- [typst-book - A simple tool for creating modern online books in pure typst.](https://github.com/Myriad-Dreamin/typst-book) -```shell -typst-ts-cli compile --workspace "fuzzers/corpora/math" --entry "fuzzers/corpora/math/main.typ" -``` +- [Renderer Plugin for Hexo, a Blog-aware Static Site Generator](https://www.npmjs.com/package/hexo-renderer-typst) -Help: +- Renderer/Component Library for [JavaScript](https://www.npmjs.com/package/@myriaddreamin/typst.ts), [React](https://www.npmjs.com/package/@myriaddreamin/typst.react), and [Angular](https://www.npmjs.com/package/@myriaddreamin/typst.angular) -```shell -$ typst-ts-cli --help -The cli for typst.ts. - -Usage: typst-ts-cli [OPTIONS] [COMMAND] - -Commands: - compile Run compiler. [aliases: c] - completion Generate shell completion script - env Dump Client Environment. - font Commands about font for typst. - help Print this message or the help of the given subcommand(s) - package Commands about package for typst. - -Options: - -V, --version Print Version - --VV Print Version in format [default: none] [possible values: none, short, full, json, json-plain] - -h, --help Print help -``` +### Installation -Package Help: +Install latest CLI of typst.ts via cargo: ```shell -$ typst-ts-cli package --help -Commands about package for typst. - -Usage: typst-ts-cli package - -Commands: - doc Generate documentation for a package - help Print this message or the help of the given subcommand(s) - link Link a package to local data path - list List all discovered packages in data and cache paths - unlink Unlink a package from local data path - -Options: - -h, --help Print help +cargo install --locked --git https://github.com/Myriad-Dreamin/typst.ts typst-ts-cli ``` +Or Download the latest release from [GitHub Releases](https://github.com/Myriad-Dreamin/typst.ts/releases). + ### Example: Render Typst document in browser (build from source with/without wasm-pack) Note: see [Troubleshooting WASM Build](docs/troubleshooting-wasm-build.md) for (especially) **Arch Linux** users. diff --git a/docs/cookery/book.typ b/docs/cookery/book.typ index 362fa9d5..e25c4cff 100644 --- a/docs/cookery/book.typ +++ b/docs/cookery/book.typ @@ -29,9 +29,10 @@ = Quickstart - #chapter("get-started.typ", section: "1")[Get started] - #chapter(none, section: "1.1")[All-in-one JavaScript Library] - - #chapter("guide/precompilers.typ", section: "2")[Precompilers] - - #chapter(none, section: "2.1")[Command Line Interface] - - #chapter(none, section: "2.2")[Compiler Service Library] + - #chapter("guide/compilers.typ", section: "2")[Compilers] + - #chapter("guide/compiler/ts-cli.typ", section: "2.1")[Command Line Interface] + - #chapter("guide/compiler/service.typ", section: "2.2")[Compiler Service Library] + - #chapter("guide/compiler/serverless.typ", section: "2.3")[Serverless (In-browser) Compiler] - #chapter("guide/e2e-renderers.typ", section: "3")[End-to-end Renderers] - #chapter(none, section: "3.1")[React Library] - #chapter(none, section: "3.2")[Angular Library] diff --git a/docs/cookery/guide/compiler/serverless.typ b/docs/cookery/guide/compiler/serverless.typ new file mode 100644 index 00000000..c1ddc475 --- /dev/null +++ b/docs/cookery/guide/compiler/serverless.typ @@ -0,0 +1,7 @@ +#import "/docs/cookery/book.typ": book-page + +#show: book-page.with(title: "Serverless Compiler") + += Serverless Compiler + +Sample page diff --git a/docs/cookery/guide/compiler/service.typ b/docs/cookery/guide/compiler/service.typ new file mode 100644 index 00000000..cf1dda3a --- /dev/null +++ b/docs/cookery/guide/compiler/service.typ @@ -0,0 +1,7 @@ +#import "/docs/cookery/book.typ": book-page + +#show: book-page.with(title: "Compiler Service") + += Compiler Service + +Sample page diff --git a/docs/cookery/guide/compiler/ts-cli.typ b/docs/cookery/guide/compiler/ts-cli.typ new file mode 100644 index 00000000..ffb42c5e --- /dev/null +++ b/docs/cookery/guide/compiler/ts-cli.typ @@ -0,0 +1,55 @@ +#import "/docs/cookery/book.typ": book-page + +#show: book-page.with(title: "Command Line Interface") + += Command Line Interface + +Run #link("https://github.com/typst/typst")[Typst compiler] with `typst.ts`'s exporters (renderers) Example: + +```bash +# Optional +typst-ts-cli compile \ + --workspace "fuzzers/corpora/math" \ + --entry "fuzzers/corpora/math/main.typ" +``` + +Help: + +```bash +$ typst-ts-cli --help +The cli for typst.ts. + +Usage: typst-ts-cli [OPTIONS] [COMMAND] + +Commands: + compile Run compiler. [aliases: c] + completion Generate shell completion script + env Dump Client Environment. + font Commands about font for typst. + help Print this message or the help of the given subcommand(s) + package Commands about package for typst. + +Options: + -V, --version Print Version + --VV Print Version in format [default: none] [possible values: none, short, full, json, json-plain] + -h, --help Print help +``` + +Package Help: + +```bash +$ typst-ts-cli package --help +Commands about package for typst. + +Usage: typst-ts-cli package + +Commands: + doc Generate documentation for a package + help Print this message or the help of the given subcommand(s) + link Link a package to local data path + list List all discovered packages in data and cache paths + unlink Unlink a package from local data path + +Options: + -h, --help Print help +``` diff --git a/docs/cookery/guide/compilers.typ b/docs/cookery/guide/compilers.typ new file mode 100644 index 00000000..8f641240 --- /dev/null +++ b/docs/cookery/guide/compilers.typ @@ -0,0 +1,7 @@ +#import "/docs/cookery/book.typ": book-page + +#show: book-page.with(title: "Compilers") + += Compilers + +Sample page diff --git a/docs/cookery/guide/precompilers.typ b/docs/cookery/guide/precompilers.typ deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/cookery/introduction.typ b/docs/cookery/introduction.typ index 488eda5e..8f8c8df3 100644 --- a/docs/cookery/introduction.typ +++ b/docs/cookery/introduction.typ @@ -1,7 +1,78 @@ #import "/docs/cookery/book.typ": book-page +#import "/github-pages/docs/data-flow.typ": data-flow-graph #show: book-page.with(title: "Introduction") = Introduction -Sample page +Typst.ts is a project dedicated to bring the power of #link("https://github.com/typst/typst")[Typst] to the world of JavaScript. In short, it composes ways to compile and render your Typst document. In the scope of server-side rendering collaborated by #text(fill: green, "server") and #text(fill: blue, "browser"), there would be a data flow like this basically: + +#figure( + { + set text(size: 12pt) + data-flow-graph() + }, + caption: [Browser-side module needed: $dagger$: compiler; $dagger.double$: renderer. ], + numbering: none, +) + +Specifically, it first typically presents a typst document in three forms: + +- #link("https://myriad-dreamin.github.io/typst.ts/cookery/guide/compiler/ts-cli.html")[Form1]: Render to SVG and then embed it as a high-quality vectored image directly. + +- #link("https://myriad-dreamin.github.io/typst.ts/cookery/guide/compiler/ts-cli.html")[Form2]: Preprocessed to a Vector Format artifact. + +- #link("https://myriad-dreamin.github.io/typst.ts/cookery/guide/compiler/serverless.html")[Form3]: Manipulate a canvas element directly. + +The #emph("Form2: Vector Format") is developed specially for typst documents, and it has several fancy features: Todo: Visualized Feature: + +- Data Sharing across multiple layouts. + +- Artifact Streaming. + +- Incremental Rendering. + +// - Incremental Font Transfer + +So with *Form2*, you can continue rendeing the document in different ways: + +=== Static but #underline("responsive") rendering + +Example Application: #link("https://github.com/Myriad-Dreamin/typst.ts/blob/main/packages/typst.ts/index.html")[single-file], #link("https://github.com/Myriad-Dreamin/typst-book")[typst-book] and #link("https://github.com/Myriad-Dreamin/typst.ts/tree/main/packages/hexo-renderer-typst")[hexo-renderer-typst] + +A compressed artifact containing data for different theme and screen settings. The bundle size of artifacts is optimized for typst documents. + +=== #underline("Incremental") server-side rendering + +Example Application: #link("https://github.com/Enter-tainer/typst-preview-vscode")[typst-preview] + +Build a server for compilation with #link("https://myriad-dreamin.github.io/typst.ts/cookery/guide/compiler/service.html")[Compiler Service], streaming the artifact, and render it incrementally. + +=== #underline("Serverless") client-side rendering + +Example Application: #link("https://github.com/Myriad-Dreamin/typst.ts/blob/main/packages/typst.ts/examples/compiler.html")[single-file] + +Run the entire typst directly in browser, like #link("https://typst.app")[typst.app]. + +// Typst.ts allows you to independently run the Typst compiler and exporter (renderer) in your browser. + +// You can: + +// - locally run the compilation via `typst-ts-cli` to get a precompiled document, +// - or use `typst-ts-compiler` to build your backend programmatically. +// - build your frontend using the lightweight TypeScript library `typst.ts`. +// - send the precompiled document to your readers' browsers and render it as HTML elements. + +== Application + +- #link("https://myriad-dreamin.github.io/typst.ts/")[A Website built with Typst.ts] + +- #link("https://github.com/Enter-tainer/typst-preview-vscode")[Instant VSCode Preview Plugin] + +- #link("https://www.npmjs.com/package/hexo-renderer-typst")[Renderer Plugin for Hexo, a Blog-aware Static Site Generator] + +- Renderer/Component Library for #link("https://www.npmjs.com/package/@myriaddreamin/typst.ts")[JavaScript], #link("https://www.npmjs.com/package/@myriaddreamin/typst.react")[React], and #link("https://www.npmjs.com/package/@myriaddreamin/typst.angular")[Angular] + +== Further reading + ++ #link("https://myriad-dreamin.github.io/typst.ts/cookery/get-started.html")[Get started with Typst.ts] diff --git a/docs/cookery/templates/page.typ b/docs/cookery/templates/page.typ index 00a001cf..ac83c02c 100644 --- a/docs/cookery/templates/page.typ +++ b/docs/cookery/templates/page.typ @@ -8,6 +8,7 @@ // todo: move theme style parser to another lib file #let theme-target = if target.contains("-") { target.split("-").at(1) } else { "light" } +// #let theme-target = "ayu" #let theme-style = toml("theme-style.toml").at(theme-target) #let is-dark-theme = theme-style.at("color-scheme") == "dark" @@ -15,6 +16,7 @@ #let main-color = rgb(theme-style.at("main-color")) #let dash-color = rgb(theme-style.at("dash-color")) +#let background-color = rgb(theme-style.at("background-color")) #let main-font = ( "Charter", @@ -75,6 +77,7 @@ numbering: none, number-align: center, width: page-width, + // fill: background-color, ) // remove margins for web target @@ -138,6 +141,12 @@ // Main body. set par(justify: true) + if is-web-target { + link("https://github.com/Myriad-Dreamin/typst.ts/commits/main/docs/cookery")[Edition History] + + v(-.5em) + } + body } diff --git a/docs/cookery/templates/theme-style.toml b/docs/cookery/templates/theme-style.toml index 5690bcce..ef211ead 100644 --- a/docs/cookery/templates/theme-style.toml +++ b/docs/cookery/templates/theme-style.toml @@ -3,28 +3,33 @@ color-scheme = "light" main-color = "#000" dash-color = "#20609f" +background-color = "#ffffff" code-theme = "" [rust] color-scheme = "light" main-color = "#262625" dash-color = "#2b79a2" +background-color = "#e1e1db" code-theme = "" [coal] color-scheme = "dark" main-color = "#98a3ad" dash-color = "#2b79a2" +background-color = "#131516" code-theme = "/github-pages/assets/tokyo-night.tmTheme" [navy] color-scheme = "dark" main-color = "#bcbdd0" dash-color = "#2b79a2" +background-color = "#161923" code-theme = "/github-pages/assets/tokyo-night.tmTheme" [ayu] color-scheme = "dark" main-color = "#c5c5c5" dash-color = "#0096cf" +background-color = "#0f141a" code-theme = "/github-pages/assets/tokyo-night.tmTheme" diff --git a/github-pages/docs/data-flow-standalone.typ b/github-pages/docs/data-flow-standalone.typ index 524031db..9227d658 100644 --- a/github-pages/docs/data-flow-standalone.typ +++ b/github-pages/docs/data-flow-standalone.typ @@ -1,11 +1,11 @@ #import "data-flow.typ": data-flow-graph -#set page(height: auto, width: auto, margin: 0.5em) +#set page(height: auto, width: auto, margin: 0.5em, fill: white) #show link: underline #figure( - data-flow-graph, + data-flow-graph(), caption: [Browser-side module needed: $dagger$: compiler; $dagger.double$: renderer. ], numbering: none, ) diff --git a/github-pages/docs/data-flow.typ b/github-pages/docs/data-flow.typ index b28ad848..9fc8b7d6 100644 --- a/github-pages/docs/data-flow.typ +++ b/github-pages/docs/data-flow.typ @@ -1,7 +1,11 @@ #import "/contrib/typst/diagram.typ": node, arr, commutative_diagram +#import "/docs/cookery/templates/page.typ": main-color, background-color -#let data-flow-graph = commutative_diagram( +#let arr = arr.with(stroke: main-color) + +#let data-flow-graph() = commutative_diagram( node_padding: (70pt, 50pt), + bg-color: background-color, node((0, 0), [ Typst Documents ]), @@ -9,7 +13,7 @@ Preprocessed Artifact ]), node((1, 1), [ - #link("https://developer.mozilla.org/en-US/docs/Web/SVG")[Svg Document] ( `` ) + #link("https://developer.mozilla.org/en-US/docs/Web/SVG")[SVG Document] ( `` ) ]), node((2, 1), [ #link("https://developer.mozilla.org/en-US/docs/Web/HTML/Element/canvas")[Canvas] ( `` ) diff --git a/github-pages/docs/readme-draft.typ b/github-pages/docs/readme-draft.typ index e2b4f2a4..cee963a9 100644 --- a/github-pages/docs/readme-draft.typ +++ b/github-pages/docs/readme-draft.typ @@ -53,7 +53,7 @@ Typst.ts is a project dedicated to bring the power of #link("https://github.com/typst/typst")[Typst] to the world of JavaScript. In short, it composes ways to compile and render your Typst document. In the scope of server-side rendering collaborated by #text(fill: green, "server") and #text(fill: blue, "browser"), there would be a data flow like this: #figure( - data-flow-graph, + data-flow-graph(), caption: [Browser-side module needed: $dagger$: compiler; $dagger.double$: renderer. ], numbering: none, ) diff --git a/github-pages/docs/readme.typ b/github-pages/docs/readme.typ index 4cd18ce4..515d7322 100644 --- a/github-pages/docs/readme.typ +++ b/github-pages/docs/readme.typ @@ -60,10 +60,6 @@ The Typst.ts application is designed to be fast due to the following reasons: - The renderer has a small code size. - Typst itself has great performance. -== Prerequisite - -- The font assets for Typst.ts are not included in this repository. See [Download Font Assets](./docs/download-font-assets.md) for more information. - == CLI Run Compiler Example: diff --git a/package.json b/package.json index 8bd9f3bc..d4c0afcb 100644 --- a/package.json +++ b/package.json @@ -22,6 +22,7 @@ "packages/templates/*" ], "scripts": { + "book": "typst-book serve --font-path assets/fonts -w . docs/cookery", "build:core": "yarn workspace @myriaddreamin/typst.ts build", "bump-packages": "python scripts/bump_version.py", "prepublish-packages": "turbo run prepublish",