From b1f1b3d2ab9f908eb10e581686d1117dcc46ae97 Mon Sep 17 00:00:00 2001 From: Myriad-Dreamin Date: Wed, 1 Nov 2023 15:55:35 +0800 Subject: [PATCH] docs: complete guidance --- README.md | 4 +- docs/cookery/book.typ | 13 +- docs/cookery/get-started.typ | 67 +++++---- docs/cookery/guide/all-in-one.typ | 76 ++++++++-- docs/cookery/guide/compiler/service.typ | 192 +++++++++++++++++++++++- docs/cookery/guide/compiler/ts-cli.typ | 168 ++++++++++++++++++++- docs/cookery/guide/e2e-renderers.typ | 0 docs/cookery/guide/renderer/angular.typ | 82 ++++++++++ docs/cookery/guide/renderer/hexo.typ | 18 +++ docs/cookery/guide/renderer/pdfjs.typ | 23 +++ docs/cookery/guide/renderer/react.typ | 69 +++++++++ docs/cookery/guide/renderer/ts-lib.typ | 95 ++++++++++++ docs/cookery/guide/renderer/vue3.typ | 9 ++ docs/cookery/guide/renderers.typ | 13 ++ docs/cookery/guide/trouble-shooting.typ | 8 + docs/cookery/introduction.typ | 5 +- docs/cookery/term.typ | 6 + 17 files changed, 799 insertions(+), 49 deletions(-) delete mode 100644 docs/cookery/guide/e2e-renderers.typ create mode 100644 docs/cookery/guide/renderer/angular.typ create mode 100644 docs/cookery/guide/renderer/hexo.typ create mode 100644 docs/cookery/guide/renderer/pdfjs.typ create mode 100644 docs/cookery/guide/renderer/react.typ create mode 100644 docs/cookery/guide/renderer/ts-lib.typ create mode 100644 docs/cookery/guide/renderer/vue3.typ create mode 100644 docs/cookery/guide/renderers.typ create mode 100644 docs/cookery/term.typ diff --git a/README.md b/README.md index 51e1417c..c4b34893 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ `typst.ts` is a project dedicated to bring the power of [typst](https://github.com/typst/typst) to the world of JavaScript. In short, it provides an `typst::World` implementation and several exporters to help compile -and render your Typst document inside _Browser Environment_. In the scope of server-side rendering +and render your Typst document typically inside _Browser Environment_. In the scope of server-side rendering collaborated by $\textcolor{#3c9123}{\textsf{server}}$ and $\textcolor{#0074d9}{\textsf{browser}}$, there would be a data flow like this: @@ -44,7 +44,7 @@ The _Form2: Vector Format_ is developed specially for typst documents, and it ha

-So with _Form2_, you can continue rendeing the document in different ways: +So with _Form2_, you can continue rendering the document in different ways: ##### Static but responsive rendering diff --git a/docs/cookery/book.typ b/docs/cookery/book.typ index d3968161..efbf17ca 100644 --- a/docs/cookery/book.typ +++ b/docs/cookery/book.typ @@ -29,7 +29,7 @@ title: "reflexo-typst Documentation", summary: [ #prefix-chapter("introduction.typ")[Introduction] - = Quickstart + = Guidance - #chapter("get-started.typ", section: "1")[Get started] - #chapter("guide/all-in-one.typ", section: "1.1")[All-in-one JavaScript Library] - #chapter("guide/compilers.typ", section: "2")[Compilers] @@ -37,11 +37,12 @@ - #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/compiler/node.typ", section: "2.4")[Compiler for Node.js] - - #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] - - #chapter(none, section: "3.3")[Vue3 Library] - - #chapter(none, section: "3.4")[Hexo Plugin] + - #chapter("guide/renderers.typ", section: "3")[Renderers] + - #chapter("guide/renderer/ts-lib.typ", section: "3.1")[JavaScript/TypeScript Library] + - #chapter("guide/renderer/react.typ", section: "3.2")[React Library] + - #chapter("guide/renderer/angular.typ", section: "3.3")[Angular Library] + - #chapter("guide/renderer/vue3.typ", section: "3.4")[Vue3 Library] + - #chapter("guide/renderer/hexo.typ", section: "3.5")[Hexo Plugin] - #chapter("guide/trouble-shooting.typ", section: "4")[Trouble Shooting] = Advanced development - #chapter("guide/env-setup.typ", section: "5")[Environment Setup] diff --git a/docs/cookery/get-started.typ b/docs/cookery/get-started.typ index 0b357b05..3d609b72 100644 --- a/docs/cookery/get-started.typ +++ b/docs/cookery/get-started.typ @@ -1,4 +1,5 @@ #import "/docs/cookery/book.typ": book-page +#import "/docs/cookery/term.typ" as term #show: book-page.with(title: "Get Started") @@ -34,28 +35,44 @@ There are several ways to setup typst.ts. The difficulty of each approach is eva #let difficult-medium = text(fill: orange.darken(25%), "medium") #let difficult-hard = text(fill: hard_color, "hard") -- #box(link()[Approach 1]), difficulty: #difficult-easy - - Use a bundled javascript file along with wasm modules. +- #box(link()[Approach 1]) (Recommended) + start with the all-in-one JavaScript Library. -- #box(link()[Approach 2]), difficulty: #difficult-easy +- #box(link()[Approach 2]) + Use a bundled javascript file along with wasm modules. +- #box(link()[Approach 3]) Use typst.ts as a library in Node.js. -- #box(link()[Approach 3]), difficulty: #difficult-medium: - +- #box(link()[Approach 4]) Use typst.ts as a library in browser (for TypeScript users). -- #box(link()[Approach 4]), difficulty: #difficult-medium: - +- #box(link()[Approach 5]) Use typst.ts as a library in browser (for JavaScript users). -- #box(link()[Approach 5]), difficulty: #difficult-hard: - +- #box(link()[Approach 6]) Use typst.ts with customized renderer/compiler modules. #line(length: 100%) +=== Run the compiler or renderer with simplified APIs +#let easy-preview-example = link("https://github.com/Myriad-Dreamin/typst.ts/blob/main/packages/typst.ts/examples/all-in-one.html")[Single HTML file for real-time previewing typst document] + +Difficulty: #difficult-easy, Example: #easy-preview-example + +The most simple examples always work with the all-in-one JavaScript Library: + +```ts +import { $typst } from '@myriaddreamin/typst.ts/dist/esm/contrib/snippet.mjs'; +console.log((await $typst.svg({ + mainContent: 'Hello, typst!' })).length); +// :-> 7317 +``` + +See #link("https://myriad-dreamin.github.io/typst.ts/cookery/guide/all-in-one.html")[All-in-one (Simplified) JavaScript Library] for more example usage. + +Once you feel more conformtable, please continue to try other approaches. + === Use a bundled javascript file along with wasm modules. #let bundle-example = link("https://github.com/Myriad-Dreamin/typst.ts/blob/main/packages/typst.ts/index.html")[Single HTML file] @@ -180,21 +197,6 @@ const getModule = () => WebAssembly.instantiate(/* params */); const getModule = async () => {/* above four ways */}; ``` -== Run the compiler or renderer with simplified APIs - -The most simple examples always work with the all-in-one JavaScript Library: - -```ts -import { $typst } from '@myriaddreamin/typst.ts/dist/esm/contrib/snippet.mjs'; -console.log((await $typst.svg({ - mainContent: 'Hello, typst!' })).length); -// :-> 7317 -``` - -See #link("https://myriad-dreamin.github.io/typst.ts/cookery/guide/all-in-one.html")[All-in-one (Simplified) JavaScript Library] for more example usage. - -Once you feel more conformtable, please continue reading following sections. - == Configure and run compiler - Configure font resources @@ -203,12 +205,25 @@ Once you feel more conformtable, please continue reading following sections. - Configure package registry +See #link("https://github.com/Myriad-Dreamin/typst.ts/blob/main/packages/typst.ts/src/options.init.mts")[options.init.mts] for more details. + === Precompile with `typst-ts-cli` +See #term.ts-cli for more details. + === Build a compilation service in rust +See #link("https://myriad-dreamin.github.io/typst.ts/cookery/guide/compiler/service.html")[Compiler Service Library] for more details. + == Configure and run renderer - Configure font resources, same as compiler. -=== Full Code Listing +See #link("https://github.com/Myriad-Dreamin/typst.ts/blob/main/packages/typst.ts/src/options.init.mts")[options.init.mts] for more details. + +== Further reading + ++ #link("https://myriad-dreamin.github.io/typst.ts/cookery/guide/all-in-one.html")[All-in-one (Simplified) JavaScript Library] ++ #link("https://myriad-dreamin.github.io/typst.ts/cookery/guide/compilers.html")[Compilers] ++ #link("https://myriad-dreamin.github.io/typst.ts/cookery/guide/renderers.html")[Renderers] ++ #link("https://myriad-dreamin.github.io/typst.ts/cookery/guide/trouble-shooting.html")[Troble shooting] diff --git a/docs/cookery/guide/all-in-one.typ b/docs/cookery/guide/all-in-one.typ index 02fb3c26..66162422 100644 --- a/docs/cookery/guide/all-in-one.typ +++ b/docs/cookery/guide/all-in-one.typ @@ -5,7 +5,7 @@ = All-in-one (Simplified) JavaScript Library #let snippet-source = "https://github.com/Myriad-Dreamin/typst.ts/blob/main/packages/typst.ts/src/contrib/snippet.mts" -#let snippet-lib = link(snippet-source)[`snippet`] +#let snippet-lib = link(snippet-source)[`snippet.mts`] The most simple examples always work with #snippet-lib utility library, an all-in-one JavaScript Library with simplified API interfaces: @@ -41,15 +41,17 @@ because the compilation process may change the state of that. === Example: Create an instance of the utility class: ```typescript -// optional renderer instance -const renderer = enableRendering ?? (() => { - return createGlobalRenderer(createTypstRenderer, - undefined /* pdfJsLib */, initOptions); +const $typst = new TypstSnippet({ + // optional renderer instance + renderer: enableRendering ?? (() => { + return createGlobalRenderer(createTypstRenderer, + undefined /* pdfJsLib */, initOptions); + }), + compiler() => { + return createGlobalCompiler(createTypstCompiler, + initOptions); + } }); -const $typst = new TypstSnippet(() => { - return createGlobalCompiler(createTypstCompiler, - initOptions); -}, renderer); ``` === Example: get output from input @@ -149,6 +151,62 @@ await $typst.svg({ mainContent }); Note: There are more documentation about initialization in the *Import typst.ts to your project* section of #link("https://myriad-dreamin.github.io/typst.ts/cookery/get-started.html")[Get started with Typst.ts]. +== Configure snippet by the `use` API + +Specify address to a http server for filesystem backend (shadowed by the `addSource` and `mapShadow` api): + +```js +const cm = window.TypstCompileModule; +const fetchBackend = new cm.FetchAccessModel( + 'http://localhost:20810', +); +$typst.use( + TypstSnippet.withAccessModel(fetchBackend), +); +``` + +Specify a memory filesystem backend (shadowed by the `addSource` and `mapShadow` api): + +```js +const memoryAccessModel = new cm.MemoryAccessModel(); +$typst.use( + TypstSnippet.withAccessModel(memoryAccessModel), +); +``` + +Fetch package from remote registry: + +```js +const acessModel = cm.FetchAccessModel() or + cm.MemoryAccessModel() or others; +$typst.use( + TypstSnippet.fetchPackageRegistry(fetchBackend), +); +``` + == Specify extra render options See #link(snippet-source)[comments on source] for more details. + +== Configure dependencies of canvas export + +To display text layer of canvas, it needs pdf.js. + +#include "renderer/pdfjs.typ" + +=== Sample application: real-time preview document + +See #link("https://github.com/Myriad-Dreamin/typst.ts/blob/main/packages/typst.ts/examples/all-in-one.html")[Preview by all-in-one Library] by a single included file (`all-in-one.bundle.js`). + +See #link("https://github.com/Myriad-Dreamin/typst.ts/blob/main/packages/typst.ts/examples/all-in-one-lite.html")[Preview by all-in-one-lite Library] by the more pratical single included file (`all-in-one-lite.bundle.js`), which needs configure your frontend to have access to wasm module files: + +```js +$typst.setCompilerInitOptions({ + getModule: () => + '/path/to/typst_ts_web_compiler_bg.wasm', +}); +$typst.setRendererInitOptions({ + getModule: () => + '/path/to/typst_ts_renderer_bg.wasm', +}); +``` diff --git a/docs/cookery/guide/compiler/service.typ b/docs/cookery/guide/compiler/service.typ index cf1dda3a..8e501714 100644 --- a/docs/cookery/guide/compiler/service.typ +++ b/docs/cookery/guide/compiler/service.typ @@ -1,7 +1,197 @@ #import "/docs/cookery/book.typ": book-page +#import "/docs/cookery/term.typ" as term #show: book-page.with(title: "Compiler Service") = Compiler Service -Sample page +#let compile-middleware = ```rs trait CompileMiddleware``` +#let compiler-trait = ```rs trait Compiler``` +#let world-exporter = ```rs trait WorldExporter``` + +The compiler services help you build a precompiler CLI or an incremental compilation server Program for #term.vector-format. + +== Create and use a `TypstSystemWorld` instance +Note: The ```rs struct TypstSystemWorld``` implements ```rs trait typst::World```. + +Example: #link("https://github.com/Myriad-Dreamin/typst.ts/blob/main/cli/src/compile.rs#L17")[fn create_driver in compile.rs] + +```rs +let world = TypstSystemWorld::new(CompileOpts { + root_dir: workspace_dir.clone(), + font_paths: args.font.paths.clone(), + with_embedded_fonts: EMBEDDED_FONT.to_owned(), + ..CompileOpts::default() +}) +.unwrap_or_exit(); + +// usage +let mut tracer = Tracer::default(); +typst::compile(&world, tracer); +``` + +== Create and use a `CompileDriver` instance + +#[ + #set par(justify: false) + Note: The ```rs struct CompileDriver``` implements #compiler-trait. +] + +The compile driver holds more state for convenient usage. + +```rs +let compile_driver = CompileDriver { + world, + entry_file: entry_file_path.to_owned(), +} +``` + +=== Example: get main id of the current entry file + +```rs +let main_id = compile_driver.main_id(); +``` + +=== Example: compile document + +```rs +let document = compile_driver.compile().unwrap(); +``` + +=== Example: query document + +```rs +let selector = "figure".into_owned(); +let contents = compile_driver.query( + selector, document).unwrap(); +``` + +== Create and use a `CompileExporter` instance + +#[ + #set par(justify: false) + Note: The ```rs struct CompileExporter``` implements #compiler-trait. #linebreak() + Note: The ```rs struct CompileExporter``` implements #compile-middleware. #linebreak() + Note: The ```rs struct CompileExporter``` implements #world-exporter. +] + +Retrieve an exporter instance that is executed on each sucessful compilation (more useful for incremental compilation). + +```ts +let driver = CompileExporter::new(compiler_driver) + .with_exporter(exporter) +``` + +See #link("https://github.com/Myriad-Dreamin/typst.ts/blob/main/cli/src/export.rs")[exporter.rs] for usage of the exporter feature. + +Glance at current available exporters: + +```rs +type Ast = typst_ts_ast_exporter::AstExporter; +type Json = typst_ts_serde_exporter::JsonExporter; +type Pdf = typst_ts_pdf_exporter::PdfDocExporter; +type Rmp = typst_ts_serde_exporter::RmpExporter; +type Svg = typst_ts_svg_exporter::PureSvgExporter; +type SvgHtml = typst_ts_svg_exporter::SvgExporter; +type SIR = typst_ts_svg_exporter::SvgModuleExporter; +``` + +=== Example: use a lambda (closure) exporter + +Example: #link("https://github.com/Enter-tainer/typst-preview/blob/main/src/actor/typst.rs")[fn create_driver in compile.rs] + +```rs +let driver = CompileExporter::new(compiler_driver).with_exporter( + move |_world: &dyn World, doc: Arc| { + let _ = doc_sender.send(Some(doc)); // it is ok to ignore the error here + let _ = renderer_sender.send(RenderActorRequest::RenderIncremental); + Ok(()) + }, +); +``` + +== Create and use a `DynamicLayoutCompiler` instance + +#[ + #set par(justify: false) + Note: The ```rs struct CompileExporter``` implements #compiler-trait. #linebreak() + Note: The ```rs struct DynamicLayoutCompiler``` implements #compile-middleware. #linebreak() + Note: The ```rs struct DynamicLayoutCompiler``` implements #world-exporter. +] + +Enable dynamic layout based on a #compiler-trait. + +```rs +let driver = DynamicLayoutCompiler::new( + driver, output_dir) + .with_enable(true /* whether enabled dynamic layout */); +``` + +== Create and use a `CompileActor` instance + +Specifical for incremental compilation based on some #world-exporter instance. + +```rs +let driver = DynamicLayoutCompiler::new( + driver, output_dir).with_enable(true /* whether enabled */); +``` + +Example: #link("https://github.com/Enter-tainer/typst-preview/blob/main/src/actor/typst.rs")[struct TypstActor in typst.rs in typst-preview] + +```rs +let actor = CompileActor::new(driver, + root.as_ref().to_owned()).with_watch(true); +``` + +Example #link("https://github.com/Enter-tainer/typst-preview/blob/main/src/actor/typst.rs")[fn TypstActor::run in typst.rs in typst-preview] + +Watch input, compile incrementally, and response message: + +```rs +pub async fn run(self) { + let (server, client) = self.inner.split(); + + // spawn a watch compile thread + server.spawn().await; + + debug!("TypstActor: waiting for message"); + let mut client = wrap_client(self.client); + while let Some(mail) = client.mailbox.recv().await { + client.process_mail(mail).await; + } + + info!("TypstActor: exiting"); +} +``` + +== Create your owned compile middleware + +Example #link("https://github.com/Enter-tainer/typst-preview/blob/main/src/actor/typst.rs")[struct Reporter in typst.rs in typst-preview] + +```rs +impl CompileMiddleware for Reporter { + fn wrap_compile(&mut self) -> SourceResult> { + + // do someting before each compilation + // ... + + // trigger real compilation + let doc = self.inner_mut().compile(); + + // do someting after each compilation + // report compilation status + if let Err(err) = &doc { + let _ = self.sender.send(EditorActorRequest::CompileStatus( + CompileStatus::CompileError, + )); + log::error!("TypstActor: compile error: {:?}", err); + } else { + let _ = self.sender.send(EditorActorRequest::CompileStatus( + CompileStatus::CompileSuccess, + )); + } + + doc + } +} +``` diff --git a/docs/cookery/guide/compiler/ts-cli.typ b/docs/cookery/guide/compiler/ts-cli.typ index ffb42c5e..fc0c5be2 100644 --- a/docs/cookery/guide/compiler/ts-cli.typ +++ b/docs/cookery/guide/compiler/ts-cli.typ @@ -1,18 +1,180 @@ #import "/docs/cookery/book.typ": book-page +#import "/docs/cookery/term.typ" as term #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: +The unique feature of `typst-ts-cli` is that it precompiles typst documents into #term.vector-format files. It internally runs #link("https://github.com/typst/typst")[Typst compiler] with `typst.ts`'s exporters. + +```ts +// The './main.sir.in' could be obtained by `typst-ts-cli` +// Specifically, by `compile ... --format vector` +const vectorData: Uint8Array = await + fetch('./main.sir.in').into(); + +// into svg format +await $typst.svg({ vectorData }); +// into canvas operations +await $typst.canvas(div, { vectorData }); +``` + +For more usage of #term.vector-format files, please refer to #link("https://myriad-dreamin.github.io/typst.ts/cookery/guide/renderers.html")[Renderers] section. + +== Installation + +Install latest CLI of typst.ts via cargo: + +```shell +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). + +== The compile command + +=== Typical usage + +compile a document to a PDF file and a #term.vector-format file. ```bash -# Optional typst-ts-cli compile \ --workspace "fuzzers/corpora/math" \ --entry "fuzzers/corpora/math/main.typ" ``` +=== `-e,--entry` option, required + +Entry file. + +```bash +typst-ts-cli -e main.typ +``` + +=== `-w,--workspace` option, default: `.` + +Path to typst workspace. + +```bash +typst-ts-cli -w /repos/root/ -e main.typ +``` + +=== `--watch` option + +Watch file dependencies and compile the document. + +```bash +typst-ts-cli compile ... --watch +``` + +=== `--format` option + +compile a document to specific formats. + +```bash +# export nothing (dry compile) +typst-ts-cli compile ... --format nothing +# into vector format +typst-ts-cli compile ... --format vector +# into multiple formats at the same time +typst-ts-cli compile ... --format svg --format svg_html +``` + +=== `--dynamic-layout` option + +Please setup the #link("https://github.com/Myriad-Dreamin/typst.ts/tree/main/contrib/templates/variables")[variables] package before compilation. + +```bash +typst-ts-cli package link --manifest \ + repos/typst.ts/contrib/templates/variables/typst.toml +typst-ts-cli compile ... --dynamic-layout +``` + +=== `-o,--output` option + +Output to directory, default in the same directory as the entry file. + +```bash +typst-ts-cli compile ... -o dist +``` + +=== `--trace` option + +Comma seperated options to trace execution of typst compiler when compiling documents: + +```bash +# trace events at warning level +typst-ts-cli compile ... --trace=verbosity=0 +# trace events at info level +typst-ts-cli compile ... --trace=verbosity=1 +# trace events at debug level +typst-ts-cli compile ... --trace=verbosity=2 +# trace events at trace level +typst-ts-cli compile ... --trace=verbosity=3 +``` + +=== Example: compile a document with watching dependencies + +```bash +typst-ts-cli compile \ + -e "fuzzers/corpora/math/main.typ" + --watch +``` + +=== Example: compile a document into SVG + +```bash +typst-ts-cli compile \ + -e "fuzzers/corpora/math/main.typ" + --format svg +``` + +=== Example: compile a document into SVG wrapped with HTML + +```bash +typst-ts-cli compile \ + -e "fuzzers/corpora/math/main.typ" + --format svg_html +``` + +=== Example: compile a document into the #term.vector-format + +```bash +typst-ts-cli compile \ + -e "fuzzers/corpora/math/main.typ" + --format vector +``` + +=== Example: compile a document into the #term.vector-format containing responsive layouts + +```bash +typst-ts-cli compile \ + -e "fuzzers/corpora/math/main.typ" + --dynamic-layout +``` + +== Package commands + +=== Example: list packages in `@preview` namespace + +```bash +typst-ts-cli package list +``` + +=== Example: link a package to `@preview` namespace + +```bash +typst-ts-cli package link --manifest path/to/typst.toml +``` + +=== Example: unlink a package from `@preview` namespace + +```bash +typst-ts-cli package unlink --manifest path/to/typst.toml +``` + +== CLI Options + Help: ```bash @@ -31,7 +193,7 @@ Commands: Options: -V, --version Print Version - --VV Print Version in format [default: none] [possible values: none, short, full, json, json-plain] + --VV Print Version in format [default: none] [possible values: none, short, features, full, json, json-plain] -h, --help Print help ``` diff --git a/docs/cookery/guide/e2e-renderers.typ b/docs/cookery/guide/e2e-renderers.typ deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/cookery/guide/renderer/angular.typ b/docs/cookery/guide/renderer/angular.typ new file mode 100644 index 00000000..0e8e44a8 --- /dev/null +++ b/docs/cookery/guide/renderer/angular.typ @@ -0,0 +1,82 @@ +#import "/docs/cookery/book.typ": book-page +#import "/docs/cookery/term.typ" as term + +#show: book-page.with(title: "Angular Library") + += Angular Library + +Use #link("https://www.npmjs.com/package/@myriaddreamin/typst.angular")[`@myriaddreamin/typst.angular`]. + +Import the angular module containing the `typst-document` component. + +```typescript +/// component.module.ts +import { TypstDocumentModule } from '@myriaddreamin/typst.angular'; +``` + +And use directive `typst-document` in your template file. + +```html + +``` + +== The `typst-document` component + +=== Typical usage + +```html + + +``` + +=== `fill` property + +Fill document with color. + +```html + + +``` + +Note: Current typst.ts doesn't support a transparent background color in some browsers. + +=== `artifact` property + +Render the document with artifact from precompiler. + +```html + + +``` + +The artifact can be only in #term.vector-format to this time. + +To get `artifact` data, please refer to #term.ts-cli. + +#include "pdfjs.typ" + +=== Set renderer initialization option for `typst-document` + +Retrieve a #term.init-option for initializating the renderer for `typst-document` + +```ts +typst-document.setWasmModuleInitOptions({ + getModule: () => + 'http://localhost:20810/typst_ts_renderer_bg.wasm', +}); +``` + +The default value is: + +```ts +{ + beforeBuild: [], + getModule: () => '/assets/typst-ts-renderer/pkg/typst_ts_renderer_bg.wasm', +} +``` + +=== Example: show document + +See #link("https://github.com/Myriad-Dreamin/typst.ts/tree/main/packages/typst.angular/projects/demo")[typst.angular demo] for more details. diff --git a/docs/cookery/guide/renderer/hexo.typ b/docs/cookery/guide/renderer/hexo.typ new file mode 100644 index 00000000..e9cbdf5e --- /dev/null +++ b/docs/cookery/guide/renderer/hexo.typ @@ -0,0 +1,18 @@ +#import "/docs/cookery/book.typ": book-page + +#show: book-page.with(title: "Hexo Library") + += Hexo Library + +Add `"hexo-renderer-typst": "0"` to your `package.json` + +And run: + +``` +# serve files +hexo serve +# generate files +hexo generate +``` + +Currently, it could only render typst documents inside of `source/_posts` (Hexo Posts) and fix typst workspace (root directory) to the root of your blog project. diff --git a/docs/cookery/guide/renderer/pdfjs.typ b/docs/cookery/guide/renderer/pdfjs.typ new file mode 100644 index 00000000..a7626770 --- /dev/null +++ b/docs/cookery/guide/renderer/pdfjs.typ @@ -0,0 +1,23 @@ + +=== Provides the instance of pdf.js library + +Currently it is hardcoded by getting value of `window.pdfjsLib`. Example setup: + +```html + + + + + +``` + +We will remove dependency on pdf.js in future. diff --git a/docs/cookery/guide/renderer/react.typ b/docs/cookery/guide/renderer/react.typ new file mode 100644 index 00000000..ebec7457 --- /dev/null +++ b/docs/cookery/guide/renderer/react.typ @@ -0,0 +1,69 @@ +#import "/docs/cookery/book.typ": book-page +#import "/docs/cookery/term.typ" as term + +#show: book-page.with(title: "React Library") + += React Library + +Use #link("https://www.npmjs.com/package/@myriaddreamin/typst.react")[`@myriaddreamin/typst.react`]. + +```typescript +import { TypstDocument } from '@myriaddreamin/typst.react'; + +export const App = (artifact: Uint8Array) => { +return ( +
+

Demo: Embed Your Typst Document in React

+ +
+); +}; +``` + +=== `fill` property + +Fill document with color. + +```html + +``` + +Note: Current typst.ts doesn't support a transparent background color in some browsers. + +=== `artifact` property + +Render the document with artifact from precompiler. + +```html + +``` + +The artifact can be only in #term.vector-format to this time. + +To get `artifact` data, please refer to #term.ts-cli. + +#include "pdfjs.typ" + +=== Set renderer initialization option for `TypstDocument` + +Retrieve a #term.init-option for initializating the renderer for `TypstDocument` + +```ts +TypstDocument.setWasmModuleInitOptions({ + getModule: () => + 'http://localhost:20810/typst_ts_renderer_bg.wasm', +}); +``` + +The default value is: + +```ts +{ + beforeBuild: [], + getModule: () => '/node_modules/@myriaddreamin/typst-ts-renderer/pkg/typst_ts_renderer_bg.wasm', +} +``` + +=== Example: show document + +See #link("https://github.com/Myriad-Dreamin/typst.ts/tree/main/packages/typst.react/src/demo")[typst.react demo] for more details. diff --git a/docs/cookery/guide/renderer/ts-lib.typ b/docs/cookery/guide/renderer/ts-lib.typ new file mode 100644 index 00000000..e2e91f29 --- /dev/null +++ b/docs/cookery/guide/renderer/ts-lib.typ @@ -0,0 +1,95 @@ +#import "/docs/cookery/book.typ": book-page +#import "/docs/cookery/term.typ" as term + +#show: book-page.with(title: "JavaScript/TypeScript Library") + +#let renderer-source = "https://github.com/Myriad-Dreamin/typst.ts/blob/main/packages/typst.ts/src/renderer.mts" +#let renderer-lib = link(renderer-source)[`renderer.mts`] + += JavaScript/TypeScript Library + +Use #link("https://www.npmjs.com/package/@myriaddreamin/typst.ts")[`@myriaddreamin/typst.ts`]. + +== Use simplified APIs + +One may use simplified apis: + +```typescript +import { $typst } from '@myriaddreamin/typst.ts/dist/esm/contrib/snippet.mjs'; +const mainContent = 'Hello, typst!'; + +console.log(await $typst.svg({ mainContent })); +``` + +Specify correct path to the wasm modules if it complains. + +```typescript +$typst.setCompilerInitOptions({ getModule: ... }); +$typst.setRendererInitOptions({ getModule: ... }); +``` + +The path option is likely required in browser but not in node.js. + +See #link("https://myriad-dreamin.github.io/typst.ts/cookery/guide/all-in-one.html")[All-in-one (Simplified) JavaScript Library] for more details. + +== Use one-shot APIs + +See #renderer-lib for more details. + +=== Example: render a precompiled document inside of some `
` element + +Full example: #link("https://github.com/Myriad-Dreamin/typst.ts/blob/main/packages/typst.ts/index.html")[single-file] + +First, initialize the renderer inside browser: + +```js +let m = window.TypstRenderModule; +let plugin = m.createTypstRenderer(pdfjsLib); +plugin + .init({ + getModule: () => + '/path/to/typst_ts_renderer_bg.wasm', + }) +``` + +Please ensure that `/path/to/typst_ts_renderer_bg.wasm` is accessible to your frontend. + +Next, load the artifact in #term.vector-format from somewhere. For example, precompile your doucment by #term.ts-cli and load it by the `fetch` api: + +```ts +const artifactContent: Uint8Array = + await fetch('/main.white.artifact.sir.in') + .then(response => response.arrayBuffer()) + .then(buffer => new Uint8Array(buffer)); +``` + +Finally, call the `render` api to trigger rendering: + +```js +await plugin.init(args); +const artifactContent = await loadData(args); + +//
+const container = document.getElementById('typst-app'); + +await plugin.renderToCanvas({ + artifactContent, + container, + backgroundColor: '#343541', + pixelPerPt: 4.5, +}); +``` + +See the sample application #link("https://github.com/Myriad-Dreamin/typst.ts/blob/main/packages/typst.ts/index.html")[single-file] for more details. + +== Use `RenderSession` APIs + +Full exmaple: #link("https://github.com/Enter-tainer/typst-preview/tree/110c031d21e74f747f78fbf78934140d23fec267/addons/frontend")[typst-preview-frontend] + +See #renderer-lib for more details. + +== Configure dependencies of canvas export + +To display text layer of canvas, it needs pdf.js. + +#include "pdfjs.typ" diff --git a/docs/cookery/guide/renderer/vue3.typ b/docs/cookery/guide/renderer/vue3.typ new file mode 100644 index 00000000..58bb440c --- /dev/null +++ b/docs/cookery/guide/renderer/vue3.typ @@ -0,0 +1,9 @@ +#import "/docs/cookery/book.typ": book-page + +#show: book-page.with(title: "Compiler Service") + += Compiler Service + +Use `@myriaddreamin/typst.vue3` + +Coming soon. diff --git a/docs/cookery/guide/renderers.typ b/docs/cookery/guide/renderers.typ new file mode 100644 index 00000000..4293062d --- /dev/null +++ b/docs/cookery/guide/renderers.typ @@ -0,0 +1,13 @@ +#import "/docs/cookery/book.typ": book-page + +#show: book-page.with(title: "Renderers") + += Renderers + +See: + ++ #link("https://myriad-dreamin.github.io/typst.ts/cookery/guide/renderer/ts-lib.html")[JavaScript/TypeScript Library] ++ #link("https://myriad-dreamin.github.io/typst.ts/cookery/guide/renderer/react.html")[React Library] ++ #link("https://myriad-dreamin.github.io/typst.ts/cookery/guide/renderer/angular.html")[Angular Library] ++ #link("https://myriad-dreamin.github.io/typst.ts/cookery/guide/renderer/vue3.html")[Vue3 Library] ++ #link("https://myriad-dreamin.github.io/typst.ts/cookery/guide/renderer/hexo.html")[Hexo Plugin] diff --git a/docs/cookery/guide/trouble-shooting.typ b/docs/cookery/guide/trouble-shooting.typ index e69de29b..a87bec8d 100644 --- a/docs/cookery/guide/trouble-shooting.typ +++ b/docs/cookery/guide/trouble-shooting.typ @@ -0,0 +1,8 @@ +#import "/docs/cookery/book.typ": book-page + +#show: book-page.with(title: "Trouble shooting") + += Trouble shooting + +We are collecting questions and answers about the `typst.ts` project here. Feel free to ask questions in #link("https://github.com/Myriad-Dreamin/typst.ts/discussions")[Github Discussions]. + diff --git a/docs/cookery/introduction.typ b/docs/cookery/introduction.typ index 8829f08b..feac67cb 100644 --- a/docs/cookery/introduction.typ +++ b/docs/cookery/introduction.typ @@ -16,7 +16,7 @@ = Introduction -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 inside *Browser Environment*. In the scope of server-side rendering collaborated by #text(fill: rgb("#3c9123"), "server") and #text(fill: blue, "browser"), there would be a data flow like this basically: +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 typically inside *Browser Environment*. In the scope of server-side rendering collaborated by #text(fill: rgb("#3c9123"), "server") and #text(fill: blue, "browser"), there would be a data flow like this: #figure( { @@ -50,7 +50,7 @@ The #emph("Form2: Vector Format") is developed specially for typst documents, an // - Incremental Font Transfer -So with *Form2*, you can continue rendeing the document in different ways: +So with *Form2*, you can continue rendering the document in different ways: === Static but #underline("responsive") rendering @@ -92,3 +92,4 @@ Run the entire typst directly in browser, like #link("https://typst.app")[typst. == Further reading + #link("https://myriad-dreamin.github.io/typst.ts/cookery/get-started.html")[Get started with Typst.ts] ++ #link("https://myriad-dreamin.github.io/typst.ts/cookery/guide/trouble-shooting.html")[Troble shooting] diff --git a/docs/cookery/term.typ b/docs/cookery/term.typ new file mode 100644 index 00000000..d614a4fc --- /dev/null +++ b/docs/cookery/term.typ @@ -0,0 +1,6 @@ + +#let vector-format = link("https://github.com/Myriad-Dreamin/typst.ts/blob/main/docs/proposals/8-vector-representation-for-rendering.typ")[_Vector Format_] + +#let ts-cli = link("https://myriad-dreamin.github.io/typst.ts/cookery/guide/compiler/ts-cli.html")[Command Line Interface] + +#let init-option = link("https://github.com/Myriad-Dreamin/typst.ts/blob/main/packages/typst.ts/src/options.init.mts#L40")[`typst.InitOptions`]