docs(cookery): init introduction (#369)

README.md

@@ -16,97 +16,64 @@ $\textcolor{#2ecc40}{\textsf{server}}$ and $\textcolor{#0074d9}{\textsf{browser}
     <img width="100%" alt="Data Flow" src="https://github.com/Myriad-Dreamin/typst.ts/blob/main/github-pages/docs/data-flow-standalone.artifact.svg"/>
 </p>
 
-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 <ins>responsive</ins> 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)
+##### <ins>Incremental</ins> 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.
+##### <ins>Serverless</ins> 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 <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 <COMMAND>
-
-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.

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]

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

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

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 <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 <COMMAND>
+
+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
+```

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

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]

docs/cookery/templates/page.typ

@@ -8,13 +8,15 @@
 
 // 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"
 #let is-light-theme = not is-dark-theme
 
 #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
 }
 

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"

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,
 )