@vetala/vetala 0.1.0-beta

package/skill/typst-creator/references/scripting.md

@@ -0,0 +1,237 @@
+# Typst Scripting Reference
+
+Typst includes a built-in scripting language for logic and data manipulation.
+
+## Variables
+
+Variables store values for reuse throughout your document. All bindings are immutable by default but can be reassigned with `=`.
+
+### Let Bindings
+
+Use `let` to create named bindings. Variable names can contain letters, numbers, and hyphens but must start with a letter.
+
+```typst
+#let name = "Alice"
+#let count = 42
+#let ratio = 3.14
+#let active = true
+#let items = (1, 2, 3)
+#let person = (name: "Bob", age: 30)
+```
+
+### Destructuring
+
+Extract multiple values from arrays or dictionaries in a single statement. Pattern matching makes it easy to work with structured data.
+
+```typst
+#let (a, b) = (1, 2)
+#let (name: n, age: a) = (name: "Alice", age: 25)
+```
+
+## Data Types
+
+Typst is dynamically typed with these built-in types. Type checking happens at runtime.
+
+| Type | Example |
+|------|---------|
+| Integer | `42`, `-10` |
+| Float | `3.14`, `1e-5` |
+| String | `"hello"` |
+| Boolean | `true`, `false` |
+| Array | `(1, 2, 3)` |
+| Dictionary | `(key: "value")` |
+| Content | `[*bold*]` |
+| None | `none` |
+| Auto | `auto` |
+
+## Arrays
+
+Ordered collections of values. Arrays support functional methods like `map`, `filter`, and `fold` for data transformation.
+
+```typst
+#let arr = (1, 2, 3, 4, 5)
+
+arr.len()           // 5
+arr.first()         // 1
+arr.last()          // 5
+arr.at(2)           // 3
+arr.slice(1, 3)     // (2, 3)
+arr.contains(3)     // true
+arr.map(x => x * 2) // (2, 4, 6, 8, 10)
+arr.filter(x => x > 2)  // (3, 4, 5)
+arr.fold(0, (a, b) => a + b)  // 15
+arr.join(", ")      // "1, 2, 3, 4, 5"
+```
+
+## Dictionaries
+
+Key-value pairs for structured data. Access values using dot notation or the `at()` method. Keys are always strings.
+
+```typst
+#let dict = (name: "Alice", age: 25)
+
+dict.name           // "Alice"
+dict.at("age")      // 25
+dict.keys()         // ("name", "age")
+dict.values()       // ("Alice", 25)
+dict.pairs()        // (("name", "Alice"), ("age", 25))
+```
+
+## Functions
+
+Functions encapsulate reusable logic and can return both values and content. Define them with `let` and call them with parentheses.
+
+### Function Definition
+
+Basic functions use the arrow syntax. The expression after `=` becomes the return value.
+
+```typst
+#let greet(name) = [Hello, #name!]
+#let add(a, b) = a + b
+```
+
+### Default Parameters
+
+Provide fallback values with `:` syntax. Parameters with defaults become optional when calling the function.
+
+```typst
+#let greet(name, greeting: "Hello") = [#greeting, #name!]
+#greet("Alice")                    // Hello, Alice!
+#greet("Bob", greeting: "Hi")      // Hi, Bob!
+```
+
+### Named Parameters
+
+Use named arguments for clarity when calling functions with many parameters. Order doesn't matter for named arguments.
+
+```typst
+#let rect-area(width: 10, height: 5) = width * height
+#rect-area()                // 50
+#rect-area(width: 20)       // 100
+#rect-area(height: 10)      // 100
+```
+
+### Content Functions
+
+Functions that return styled content are the foundation of Typst templates. Use set rules inside to affect only the function's scope.
+
+```typst
+#let highlight(body) = {
+  set text(fill: red)
+  body
+}
+
+#highlight[Important text]
+```
+
+## Control Flow
+
+Control the execution flow with conditionals and loops. All control structures are expressions that return values.
+
+### Conditionals
+
+`if` expressions evaluate to their branch's value. Use for conditional content or computation.
+
+```typst
+#let x = 5
+
+#if x > 0 {
+  [Positive]
+} else if x < 0 {
+  [Negative]
+} else {
+  [Zero]
+}
+```
+
+### For Loops
+
+Iterate over arrays, ranges, or dictionary pairs. The loop body is evaluated for each element and results are joined.
+
+```typst
+#for i in range(5) {
+  [Item #i ]
+}
+
+#for (key, value) in (a: 1, b: 2) {
+  [#key: #value ]
+}
+
+#for item in ("apple", "banana", "cherry") {
+  list.item(item)
+}
+```
+
+### While Loops
+
+Repeat while a condition is true. Be careful to ensure the condition eventually becomes false to avoid infinite loops.
+
+```typst
+#let i = 0
+#while i < 3 {
+  [#i ]
+  i = i + 1
+}
+```
+
+## Operators
+
+Standard operators for arithmetic, comparison, and logical operations. Note that Typst uses `and`, `or`, `not` instead of symbols for logical operators.
+
+| Operator | Description |
+|----------|-------------|
+| `+`, `-`, `*`, `/` | Arithmetic |
+| `==`, `!=` | Equality |
+| `<`, `>`, `<=`, `>=` | Comparison |
+| `and`, `or`, `not` | Logical |
+| `in`, `not in` | Membership |
+| `+=` | Addition assignment |
+
+## String Operations
+
+Strings are immutable sequences of characters. Methods return new strings rather than modifying in place.
+
+```typst
+#let s = "Hello, World!"
+
+s.len()             // 13
+s.contains("World") // true
+s.starts-with("He") // true
+s.ends-with("!")    // true
+s.replace("World", "Typst")  // "Hello, Typst!"
+s.split(", ")       // ("Hello", "World!")
+s.trim()            // removes whitespace
+upper(s)            // "HELLO, WORLD!"
+lower(s)            // "hello, world!"
+```
+
+## Import and Modules
+
+Organize code across files using imports. Import specific items or use `*` to import everything from a module.
+
+```typst
+// Import from file
+#import "template.typ": conf, title
+
+// Import all
+#import "utils.typ": *
+
+// Import with alias
+#import "math.typ": formula as f
+```
+
+## Context
+
+The `context` keyword provides access to document state that depends on location, such as page numbers, counters, and current styles. Required for introspection queries.
+
+```typst
+// Access current location/state
+#context {
+  let current-page = counter(page).get()
+  [Page: #current-page.first()]
+}
+
+// Access set rule values
+#set text(lang: "ko")
+#context text.lang  // "ko"
+```

package/skill/typst-creator/references/styling.md

@@ -0,0 +1,217 @@
+# Typst Styling Reference
+
+Typst uses set rules and show rules for styling documents.
+
+## Function Parameters
+
+These tables document the key styling functions. Use them with set rules to configure defaults or directly for inline styling.
+
+### `text` Function
+
+Controls typography including font family, size, color, and language settings. This is the most fundamental styling function for text appearance.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `font` | str \| array | `"libertinus serif"` | Font family or priority list |
+| `size` | length | `11pt` | Font size |
+| `fill` | color | `black` | Text color |
+| `weight` | int \| str | `"regular"` | `"thin"`, `"light"`, `"regular"`, `"medium"`, `"bold"`, or 100-900 |
+| `style` | str | `"normal"` | `"normal"`, `"italic"`, `"oblique"` |
+| `lang` | str | `"en"` | Language code (e.g., `"ko"`, `"ja"`, `"zh"`) |
+| `region` | str \| none | `none` | Region code (e.g., `"KR"`, `"US"`) |
+| `hyphenate` | auto \| bool | `auto` | Enable hyphenation |
+| `tracking` | length | `0pt` | Letter spacing |
+| `spacing` | relative | `100%` | Word spacing |
+| `baseline` | length | `0pt` | Baseline shift |
+| `body` | content | required | Text content |
+
+### `par` Function
+
+Controls paragraph-level formatting including line spacing, justification, and indentation. Essential for achieving professional document layouts.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `leading` | length | `0.65em` | Line spacing (between lines) |
+| `spacing` | length | `1.2em` | Paragraph spacing (between paragraphs) |
+| `justify` | bool | `false` | Justify text |
+| `linebreaks` | auto \| str | `auto` | `"simple"`, `"optimized"` |
+| `first-line-indent` | length | `0pt` | First line indentation |
+| `hanging-indent` | length | `0pt` | Hanging indent for subsequent lines |
+| `body` | content | required | Paragraph content |
+
+### `block` Function
+
+Creates block-level containers with visual styling options like backgrounds, borders, and padding. Use for callout boxes, code blocks, or any content that needs visual separation.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `width` | auto \| relative | `auto` | Block width |
+| `height` | auto \| relative | `auto` | Block height |
+| `fill` | none \| color | `none` | Background color |
+| `stroke` | none \| stroke | `none` | Border stroke |
+| `radius` | relative \| dict | `(:)` | Corner radius |
+| `inset` | relative \| dict | `(:)` | Inner padding |
+| `outset` | relative \| dict | `(:)` | Outer expansion |
+| `spacing` | relative | `1.2em` | Spacing around block (sets above & below) |
+| `above` | auto \| relative | `auto` | Spacing above |
+| `below` | auto \| relative | `auto` | Spacing below |
+| `breakable` | bool | `true` | Allow page breaks |
+| `clip` | bool | `false` | Clip overflow content |
+| `sticky` | bool | `false` | Stick to next block |
+| `body` | content | `none` | Block content |
+
+## Set Rules
+
+Set rules apply default property values to all instances of an element within a scope. They cascade like CSS and are the primary mechanism for consistent document styling.
+
+### Syntax
+
+```typst
+#set element(property: value)
+```
+
+### Common Set Rules
+
+These examples show the most frequently used set rules for document configuration. Set rules can be placed at the document start for global effect or within content blocks for local scope.
+
+```typst
+// Text styling
+#set text(font: "New Computer Modern", size: 11pt)
+#set text(lang: "ko")  // Korean language
+
+// Paragraph styling
+#set par(justify: true, leading: 0.65em, first-line-indent: 1em)
+
+// Page setup
+#set page(paper: "a4", margin: 2cm)
+#set page(numbering: "1")
+
+// Heading numbering
+#set heading(numbering: "1.1")
+
+// List styling
+#set list(marker: [•])
+#set enum(numbering: "1.a)")
+```
+
+### Scoped Set Rules
+
+Wrap content in `#[...]` to create a scope where set rules only apply locally. This is useful for applying temporary styles without affecting the rest of the document.
+
+```typst
+// Apply only within block
+#[
+  #set text(fill: blue)
+  This text is blue.
+]
+This text is default color.
+```
+
+## Show Rules
+
+Show rules transform how elements are displayed. Unlike set rules which configure properties, show rules can completely redefine an element's appearance using custom logic.
+
+### Basic Show Rule
+
+The basic form takes an element type and a transformation function. The `it` parameter receives the matched element.
+
+```typst
+// Transform all headings
+#show heading: it => {
+  set text(fill: blue)
+  it
+}
+
+// Transform specific element
+#show "typst": [*Typst*]
+```
+
+### Show-Set Rule
+
+A shorthand syntax that combines show rules with set rules. Use when you want to apply set rules only to specific elements without custom transformation logic.
+
+```typst
+// Apply set rule to specific element
+#show heading: set text(fill: navy)
+#show raw: set text(font: "Fira Code")
+```
+
+### Show with Function
+
+For complex transformations, define a function that receives the element and returns modified content. Access element properties through the `it` parameter.
+
+```typst
+#show heading.where(level: 1): it => {
+  pagebreak(weak: true)
+  set text(size: 18pt)
+  block(it.body)
+}
+```
+
+### Selector Types
+
+Selectors determine which elements a show rule matches. Use `.where()` to filter by specific property values.
+
+| Selector | Example |
+|----------|---------|
+| Element | `#show heading: ...` |
+| Text | `#show "word": ...` |
+| Regex | `#show regex("\d+"): ...` |
+| Label | `#show <label>: ...` |
+| Where | `#show heading.where(level: 1): ...` |
+
+## Document Setup Pattern
+
+A typical document preamble combines set rules and show rules to establish consistent styling. Place these at the document start before any content.
+
+```typst
+// Typical document setup
+#set document(
+  title: "Document Title",
+  author: "Author Name",
+)
+
+#set page(
+  paper: "a4",
+  margin: (x: 2.5cm, y: 3cm),
+  header: [
+    #set text(8pt)
+    Document Title
+    #h(1fr)
+    #context counter(page).display()
+  ],
+)
+
+#set text(
+  font: "Noto Sans KR",
+  size: 10pt,
+  lang: "ko",
+)
+
+#set par(
+  justify: true,
+  leading: 0.8em,
+)
+
+#set heading(numbering: "1.1")
+#show heading.where(level: 1): set text(size: 16pt)
+#show heading.where(level: 2): set text(size: 14pt)
+```
+
+## LaTeX-like Styling
+
+To achieve a classic academic paper appearance similar to LaTeX defaults, use these settings with Computer Modern fonts. Adjust margins and spacing to match your target style.
+
+```typst
+// Achieve LaTeX look
+#set page(margin: 1.75in)
+#set par(
+  leading: 0.55em,
+  spacing: 0.55em,
+  first-line-indent: 1.8em,
+  justify: true,
+)
+#set text(font: "New Computer Modern")
+#show raw: set text(font: "New Computer Modern Mono")
+#show heading: set block(above: 1.4em, below: 1em)
+```

package/skill/typst-creator/references/syntax.md

@@ -0,0 +1,234 @@
+# Typst Syntax Reference
+
+Typst has three syntactical modes: Markup, Math, and Code.
+
+## Function Parameters
+
+These tables provide quick reference for the most commonly used markup functions and their configurable options.
+
+### `heading` Function
+
+Defines document structure with hierarchical sections. The number of `=` signs determines the heading level.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `level` | auto \| int | `auto` | Heading level (1-6), auto-detected from `=` count |
+| `depth` | int | - | (read-only) Nesting depth relative to `offset` |
+| `offset` | int | `0` | Starting level offset for numbering |
+| `numbering` | none \| str \| func | `none` | Number format: `"1."`, `"1.1"`, `"I.a"` |
+| `supplement` | auto \| none \| content | `auto` | Reference prefix (e.g., "Section") |
+| `outlined` | bool | `true` | Include in outline |
+| `bookmarked` | auto \| bool | `auto` | Include in PDF bookmarks |
+| `hanging-indent` | auto \| length | `auto` | Indent for wrapped lines |
+| `body` | content | required | Heading text |
+
+### `list` Function (Bullet List)
+
+Creates unordered lists with customizable bullet markers. Use `-` in markup mode for quick list creation.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `tight` | bool | `true` | Reduce spacing between items |
+| `marker` | content \| array \| func | `[•]` | Bullet marker(s) per level |
+| `indent` | length | `0pt` | Indent from left |
+| `body-indent` | length | `0.5em` | Gap between marker and text |
+| `spacing` | auto \| relative | `auto` | Space between items |
+| `children` | content | required | List items |
+
+### `enum` Function (Numbered List)
+
+Creates ordered lists with automatic numbering. Use `+` in markup mode. Supports various numbering formats including letters and roman numerals.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `tight` | bool | `true` | Reduce spacing between items |
+| `numbering` | str \| func | `"1."` | Number format: `"1."`, `"a)"`, `"(i)"` |
+| `start` | int | `1` | Starting number |
+| `full` | bool | `false` | Show full numbering (e.g., "1.1.1") |
+| `indent` | length | `0pt` | Indent from left |
+| `body-indent` | length | `0.5em` | Gap between number and text |
+| `spacing` | auto \| relative | `auto` | Space between items |
+| `children` | content | required | List items |
+
+### `raw` Function (Code Block)
+
+Displays text exactly as written without interpretation. Use backticks in markup mode for inline code or triple backticks for code blocks with syntax highlighting.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `text` | str | required | Raw text content |
+| `block` | bool | `false` | Display as block (true for fenced blocks) |
+| `lang` | none \| str | `none` | Language for syntax highlighting |
+| `align` | alignment | `start` | Text alignment |
+| `syntaxes` | str \| array | `()` | Additional syntax definition files |
+| `theme` | auto \| str \| none | `auto` | Syntax highlighting theme |
+| `tab-size` | int | `2` | Tab width in spaces |
+
+### `link` Function
+
+Creates clickable hyperlinks to URLs, labels, or document locations. URLs are automatically detected in markup mode.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `dest` | str \| label \| location \| dict | required | URL, label, or location |
+| `body` | auto \| content | `auto` | Link text (auto shows URL) |
+
+### `ref` Function
+
+Creates cross-references to labeled elements like headings, figures, or equations. Use `@label` syntax in markup mode.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `target` | label | required | Target label |
+| `supplement` | auto \| none \| content | `auto` | Reference prefix |
+
+## Mode Switching
+
+Typst has three syntactical modes that you can switch between at any point. Understanding mode transitions is essential for combining text, math, and logic.
+
+| New Mode | Syntax | Example |
+|----------|--------|---------|
+| Code | Prefix with `#` | `Number: #(1 + 2)` |
+| Math | Surround with `$...$` | `$-x$ is the opposite of $x$` |
+| Markup | Surround with `[..]` | `let name = [*Typst!*]` |
+
+## Markup Mode Syntax
+
+Markup mode is the default in a Typst document. It provides lightweight syntax for common document elements, with each shorthand corresponding to a function.
+
+| Element | Syntax | Function |
+|---------|--------|----------|
+| Paragraph break | Blank line | `parbreak` |
+| Strong emphasis | `*strong*` | `strong` |
+| Emphasis | `_emphasis_` | `emph` |
+| Raw text | `` `code` `` | `raw` |
+| Link | `https://typst.app/` | `link` |
+| Label | `<intro>` | `label` |
+| Reference | `@intro` | `ref` |
+| Heading | `= Heading` | `heading` |
+| Bullet list | `- item` | `list` |
+| Numbered list | `+ item` | `enum` |
+| Term list | `/ Term: description` | `terms` |
+| Line break | `\` | `linebreak` |
+| Smart quote | `'single'` or `"double"` | `smartquote` |
+| Comment | `/* block */` or `// line` | - |
+
+### Heading Levels
+
+The number of `=` signs determines the heading depth. Add more `=` for deeper nesting levels.
+
+```typst
+= Level 1 Heading
+== Level 2 Heading
+=== Level 3 Heading
+```
+
+### Lists
+
+Typst supports bullet lists (`-`), numbered lists (`+`), and term/definition lists (`/`). Indent with spaces for nested items.
+
+```typst
+- Bullet item 1
+- Bullet item 2
+  - Nested item
+
++ Numbered item 1
++ Numbered item 2
+
+/ Term: Definition of the term
+/ Another: Its definition
+```
+
+## Math Mode Syntax
+
+Math mode is entered by wrapping equations in `$` characters. The equation becomes a block if it has spaces after `$` and before the closing `$`; otherwise it renders inline.
+
+| Element | Syntax | Example |
+|---------|--------|---------|
+| Inline math | `$...$` (no spaces) | `$x^2$` |
+| Block math | `$ ... $` (with spaces) | `$ x^2 $` |
+| Subscript | `_` | `$x_1$` |
+| Superscript | `^` | `$x^2$` |
+| Fraction | `/` | `$(a+b)/5$` |
+| Alignment | `&` | `$x &= 2 \ &= 3$` |
+| Line break | `\` | `$x \ y$` |
+
+### Math Examples
+
+These examples demonstrate common mathematical notation patterns including inline equations, block equations, matrices, and aligned multi-line equations.
+
+```typst
+// Inline equation
+The formula $a^2 + b^2 = c^2$ is famous.
+
+// Block equation
+$ sum_(i=1)^n i = (n(n+1))/2 $
+
+// Matrix
+$ mat(1, 2; 3, 4) $
+
+// Aligned equations
+$ x &= 2 + 3 \
+    &= 5 $
+```
+
+## Code Mode Syntax
+
+Code mode lets you use Typst's scripting features. Prefix with `#` to enter code mode from markup. Once in code mode, you don't need additional hashes until switching back.
+
+| Element | Syntax |
+|---------|--------|
+| Variable binding | `#let x = 1` |
+| Function call | `#func(arg)` |
+| Code block | `#{ ... }` |
+| Content block | `#[ ... ]` |
+| Conditional | `#if cond { } else { }` |
+| Loop | `#for x in items { }` |
+
+### Code Examples
+
+These examples show variable definitions, loops, and conditionals. Content blocks `[...]` are used to return markup from code.
+
+```typst
+#let title = "My Document"
+#let items = (1, 2, 3)
+
+#for item in items {
+  [Item: #item]
+}
+
+#if items.len() > 0 {
+  [Has items]
+} else {
+  [Empty]
+}
+```
+
+## Escape Sequences
+
+Use backslash to escape special characters that would otherwise be interpreted as markup syntax.
+
+| Character | Escape |
+|-----------|--------|
+| `\` | `\\` |
+| `#` | `\#` |
+| `*` | `\*` |
+| `_` | `\_` |
+| `$` | `\$` |
+| `<` | `\<` |
+| `>` | `\>` |
+| `@` | `\@` |
+
+## Symbol Shorthands
+
+Typst provides convenient shortcuts for commonly used typographic symbols. These work in both markup and math modes.
+
+| Symbol | Shorthand |
+|--------|-----------|
+| Non-breaking space | `~` |
+| Em dash | `---` |
+| En dash | `--` |
+| Ellipsis | `...` |
+| Arrow right | `->` |
+| Arrow left | `<-` |
+| Double arrow | `<->` |