### Install Dependencies

Source: https://github.com/quarto-dev/quarto/blob/main/packages/ojs/external-observablehq-runtime/CONTRIBUTING.md

Run this command to install project dependencies before development.

```bash
yarn
```

--------------------------------

### Install @quarto/mapped-string

Source: https://github.com/quarto-dev/quarto/blob/main/packages/mapped-string/README.md

Install the library using npm.

```bash
npm install @quarto/mapped-string
```

--------------------------------

### Install Dependencies and Run VS Code Extension

Source: https://github.com/quarto-dev/quarto/blob/main/README.md

Use these commands to install project dependencies and run a development version of the VS Code extension. Ensure you have Node.js and Yarn installed.

```bash
yarn             # install dependencies
yarn dev-vscode  # run development/debug version of extension
```

--------------------------------

### Import Cell Example

Source: https://github.com/quarto-dev/quarto/blob/main/packages/ojs/external-observablehq-parser/README.md

Demonstrates an import cell and its AST representation.

```javascript
import {foo} from "module"
```

```json
{
  "type": "Cell",
  "id": null,
  "async": false,
  "generator": false,
  "body": {
    "type": "ImportDeclaration",
    "specifiers": [
      {
        "type": "ImportSpecifier",
        "view": false,
        "imported": {
          "type": "Identifier",
          "name": "foo"
        },
        "local": {
          "type": "Identifier",
          "name": "foo"
        }
      }
    ],
    "source": {

```

--------------------------------

### initQuartoContext

Source: https://context7.com/quarto-dev/quarto/llms.txt

Locates and initializes a Quarto CLI installation, returning a context object with helpers for running Quarto and Pandoc commands.

```APIDOC
## initQuartoContext — Locate and initialize a Quarto CLI installation

Probes the system for a Quarto binary using a prioritized strategy: user-configured path → system PATH → known OS-specific install locations → caller-supplied additional search paths. Returns a `QuartoContext` with helpers to invoke `quarto` and `pandoc` as child processes.

### Method Signature

```typescript
initQuartoContext(
  quartoPath?: string,
  workspaceDir?: string,
  additionalSearchPaths?: string[],
  showWarning?: (msg: string) => void,
  options?: { logger?: (msg: string) => void; source?: QuartoSource }
): QuartoContext;
```

### Parameters

- **quartoPath** (string, Optional): The explicit path to the Quarto binary.
- **workspaceDir** (string, Optional): The workspace folder to consider.
- **additionalSearchPaths** (string[], Optional): Additional paths to search for the Quarto binary.
- **showWarning** ((msg: string) => void, Optional): A callback function to display warnings.
- **options** ({ logger?: (msg: string) => void; source?: QuartoSource }, Optional): Additional options, including a logger and source information.

### Returns

A `QuartoContext` object containing information about the Quarto installation and methods to run Quarto and Pandoc commands.

### Request Example

```typescript
import { initQuartoContext, QuartoContext } from "quarto-core";

// Minimal usage — auto-discover Quarto on PATH / known locations
const ctx: QuartoContext = initQuartoContext();

if (!ctx.available) {
  console.error("Quarto CLI not found");
  process.exit(1);
}

console.log(`Quarto ${ctx.version} at ${ctx.binPath}`);

// Run a quarto sub-command synchronously
const result = ctx.runQuarto({ encoding: "utf8" }, "--version");
console.log(result); 

// Run pandoc directly
const pandocVersion = ctx.runPandoc({ encoding: "utf8" }, "--version");
console.log(pandocVersion); 

// Explicit path + workspace folder + Positron-style additional search paths
const explicit = initQuartoContext(
  "/opt/custom-quarto/bin/quarto",
  "/home/user/project",
  ["/path/to/positron/quarto/bin"],
  (msg) => console.warn(msg),         // showWarning callback
  { logger: console.log, source: "setting" }
);
```
```

--------------------------------

### Absolute Path Example in Templates

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Demonstrates how to construct absolute paths for source files within a Quarto template.

```lua
$curdir$/$sourcefile$
```

--------------------------------

### Pandoc Numbered Example Lists Syntax

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Employ the '@' marker for sequentially numbered examples. Numbering continues across lists. Labels can be added for cross-referencing.

```markdown
(@)  My first example will be numbered (1).
(@)  My second example will be numbered (2).

Explanation of examples.

(@)  My third example will be numbered (3).
```

```markdown
(@good)  This is a good example.

As (@good) illustrates, ...
```

--------------------------------

### Pandoc Command for Highlighting Styles

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Example of using pandoc to list supported syntax highlighting styles.

```bash
pandoc --list-highlight-styles
```

--------------------------------

### Install Development Version of Extension

Source: https://github.com/quarto-dev/quarto/blob/main/apps/vscode/CONTRIBUTING.md

Install the development version of the extension directly into VS Code or Positron. This allows for testing the latest changes without publishing.

```sh
yarn install-vscode
```

```sh
yarn install-positron
```

--------------------------------

### Markdown Blockquote Example

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Demonstrates a basic blockquote with multiple lines and a list inside. Each line must start with '> '.

```markdown
> This is a block quote. This
> paragraph has two lines.
>
> 1. This is a list inside a block quote.
> 2. Second item.
```

--------------------------------

### Pandoc Command for Highlighting Styles

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Example of using pandoc to list supported syntax highlighting languages.

```bash
pandoc --list-highlight-languages
```

--------------------------------

### Print Default Custom Reader Example

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

This command prints the default Lua script for the Creole reader, serving as an example for custom readers.

```bash
pandoc --print-default-data-file creole.lua
```

--------------------------------

### Pandoc Command with Custom Highlight Style

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Example of using a custom highlight style file with pandoc.

```bash
pandoc --highlight-style my.theme
```

--------------------------------

### Initialize Quarto Context

Source: https://context7.com/quarto-dev/quarto/llms.txt

Automatically discovers the Quarto CLI installation or allows explicit path configuration. Provides helpers to run Quarto and Pandoc commands.

```typescript
import { initQuartoContext, QuartoContext } from "quarto-core";

// Minimal usage — auto-discover Quarto on PATH / known locations
const ctx: QuartoContext = initQuartoContext();

if (!ctx.available) {
  console.error("Quarto CLI not found");
  process.exit(1);
}

console.log(`Quarto ${ctx.version} at ${ctx.binPath}`);
// e.g. "Quarto 1.5.57 at /usr/local/bin"

// Run a quarto sub-command synchronously
const result = ctx.runQuarto({ encoding: "utf8" }, "--version");
console.log(result); // "1.5.57"

// Run pandoc directly
const pandocVersion = ctx.runPandoc({ encoding: "utf8" }, "--version");
console.log(pandocVersion); // "pandoc 3.1.11 ..."

// Explicit path + workspace folder + Positron-style additional search paths
const explicit = initQuartoContext(
  "/opt/custom-quarto/bin/quarto",
  "/home/user/project",
  ["/path/to/positron/quarto/bin"],
  (msg) => console.warn(msg),         // showWarning callback
  { logger: console.log, source: "setting" }
);
```

--------------------------------

### Expression Cell Example

Source: https://github.com/quarto-dev/quarto/blob/main/packages/ojs/external-observablehq-parser/README.md

Demonstrates a simple expression cell and its corresponding AST representation.

```javascript
1 + 2
```

```json
{
  "type": "Cell",
  "id": null,
  "async": false,
  "generator": false,
  "body": {
    "type": "BinaryExpression",
    "left": {
      "type": "Literal",
      "value": 1,
      "raw": "1"
    },
    "operator": "+",
    "right": {
      "type": "Literal",
      "value": 2,
      "raw": "2"
    }
  }
}
```

--------------------------------

### Pandoc Specify Input and Output Formats

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Explicitly set input and output formats using -f/--from and -t/--to options. This example converts Markdown to LaTeX.

```bash
pandoc -f markdown -t latex hello.txt
```

--------------------------------

### QuartoContext

Source: https://context7.com/quarto-dev/quarto/llms.txt

The runtime context interface returned by `initQuartoContext`, providing access to Quarto installation details and execution helpers.

```APIDOC
## QuartoContext — Runtime context interface

The central value object returned by `initQuartoContext`. Carries binary locations, version, workspace information, and synchronous execution helpers.

### Interface Definition

```typescript
interface QuartoContext {
  available: boolean;        // false → all other fields are empty strings
  version: string;           // semver string, e.g. "1.5.57"
  binPath: string;           // directory containing the quarto executable
  resourcePath: string;      // Quarto's built-in resource directory
  pandocPath: string;        // full path to the bundled pandoc binary
  workspaceDir?: string;     // resolved workspace folder
  useCmd: boolean;           // true on Windows for older Quarto (quarto.cmd)
  source?: QuartoSource;     // how Quarto was found
  runQuarto(options, ...args): string;
  runPandoc(options, ...args): string;
}
```

### Properties

- **available** (boolean): Indicates if Quarto is available. If `false`, other fields are empty.
- **version** (string): The semver string of the Quarto version (e.g., "1.5.57").
- **binPath** (string): The directory containing the Quarto executable.
- **resourcePath** (string): The path to Quarto's built-in resource directory.
- **pandocPath** (string): The full path to the bundled Pandoc binary.
- **workspaceDir** (string, Optional): The resolved workspace folder.
- **useCmd** (boolean): `true` on Windows for older Quarto versions using `quarto.cmd`.
- **source** (QuartoSource, Optional): Information on how Quarto was found.

### Methods

- **runQuarto(options, ...args): string**: Executes a Quarto sub-command synchronously.
- **runPandoc(options, ...args): string**: Executes the Pandoc binary synchronously.

### Example Usage

```typescript
import { QuartoContext, quartoContextUnavailable } from "quarto-core";

// Create a safely usable "not available" context (all fields empty)
const safe: QuartoContext = quartoContextUnavailable();
console.log(safe.available); // false
console.log(safe.runQuarto({}, "--version")); // ""
```
```

--------------------------------

### Run Pandoc as a Web Server

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Rename or symlink the pandoc executable to 'pandoc-server' to start a web server with a JSON API for Pandoc's conversion functionality.

```bash
pandoc-server
```

--------------------------------

### EPUB Body Structure Example

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Illustrates the resulting HTML structure for EPUB output when using `epub:type` attributes, showing body and section types.

```html
<body epub:type="frontmatter">
  <section epub:type="prologue">
    <h1>My chapter</h1>
```

--------------------------------

### Build Project

Source: https://github.com/quarto-dev/quarto/blob/main/packages/ojs/external-observablehq-runtime/CONTRIBUTING.md

Use this command to build the project, typically before publishing.

```bash
yarn prepublishOnly
```

--------------------------------

### Fenced Code Block Example

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Demonstrates a fenced code block using three or more tildes. The starting and ending tilde rows must be at least as long as each other. Blank lines are required around the block.

```plaintext
~~~~~~~
if (a > 3) {
  moveShip(5 * gravity, DOWN);
}
~~~~~~~
```

--------------------------------

### Configure KaTeX Rendering (Command Line)

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Use the --katex flag to enable KaTeX rendering for HTML output.

```bash
--katex
```

--------------------------------

### Configure KaTeX Rendering (Defaults File)

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Set 'html-math-method:
  method: katex' in your _quarto.yml for KaTeX.

```yaml
html-math-method:
  method: katex
```

--------------------------------

### YAML Metadata Block Example

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

A basic YAML metadata block demonstrating title, author list, keywords, and a multi-paragraph abstract using literal block scalar.

```yaml
---
title:  'This is the title: it contains a colon'
author:
- Author One
- Author Two
keywords: [nothing, nothingness]
abstract: |
  This is the abstract.

  It consists of two paragraphs.
...
```

--------------------------------

### Configure GladTeX Rendering (Command Line)

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Use the --gladtex flag to enable GladTeX rendering for HTML output.

```bash
--gladtex
```

--------------------------------

### `LspInitializationOptions`

Source: https://context7.com/quarto-dev/quarto/llms.txt

Options passed from the VS Code extension client to the LSP server during initialization to control the Quarto binary and log verbosity.

```APIDOC
## `LspInitializationOptions` — LSP server startup options

Passed from the VS Code extension client to the LSP server process during `initialize`, controlling the Quarto binary to use and the log verbosity.

```typescript
import { LspInitializationOptions } from "quarto-core";

// In the extension host (apps/vscode/src/lsp/client.ts)
const initOptions: LspInitializationOptions = {
  quartoBinPath: "/usr/local/bin",   // directory containing quarto binary
  logLevel: "warn",                  // "trace" | "debug" | "info" | "warn" | "error"
};

// Passed as initializationOptions in LanguageClientOptions
const clientOptions: LanguageClientOptions = {
  documentSelector: [{ language: "quarto" }, { language: "markdown" }],
  initializationOptions: initOptions,
};
```
```

--------------------------------

### Indented Code Block Example

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

An example of an indented code block, which requires four spaces or one tab before each line of code. The indentation is removed in the output.

```plaintext
    if (a > 3) {
      moveShip(5 * gravity, DOWN);
    }
```

--------------------------------

### Initialize LSP Server Options

Source: https://context7.com/quarto-dev/quarto/llms.txt

Configure the Quarto Language Server Protocol (LSP) client by specifying the Quarto binary path and log level. This is passed during the client's initialization phase.

```typescript
import { LspInitializationOptions } from "quarto-core";

// In the extension host (apps/vscode/src/lsp/client.ts)
const initOptions: LspInitializationOptions = {
  quartoBinPath: "/usr/local/bin",   // directory containing quarto binary
  logLevel: "warn",                  // "trace" | "debug" | "info" | "warn" | "error"
};

// Passed as initializationOptions in LanguageClientOptions
const clientOptions: LanguageClientOptions = {
  documentSelector: [{ language: "quarto" }, { language: "markdown" }],
  initializationOptions: initOptions,
};
```

--------------------------------

### now

Source: https://github.com/quarto-dev/quarto/blob/main/packages/ojs/external-observablehq-stdlib/README.md

Get the current timestamp.

```APIDOC
## now

### Description
The current value of Date.now().

### API Reference
- `now()`
```

--------------------------------

### width

Source: https://github.com/quarto-dev/quarto/blob/main/packages/ojs/external-observablehq-stdlib/README.md

Get the current page width.

```APIDOC
## width

### Description
The current page width.

### API Reference
- `width()`
```

--------------------------------

### Configure WebTeX Rendering (Command Line)

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Use the --webtex flag to enable WebTeX rendering for HTML output.

```bash
--webtex
```

--------------------------------

### Empty Cell Example

Source: https://github.com/quarto-dev/quarto/blob/main/packages/ojs/external-observablehq-parser/README.md

Shows an empty cell, where the body is null, and its AST.

```javascript

```

```json
{
  "type": "Cell",
  "id": null,
  "async": false,
  "generator": false,
  "body": null
}
```

--------------------------------

### Configure GladTeX Rendering (Defaults File)

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Set 'html-math-method:
  method: gladtex' in your _quarto.yml for GladTeX.

```yaml
html-math-method:
  method: gladtex
```

--------------------------------

### Block Cell Example

Source: https://github.com/quarto-dev/quarto/blob/main/packages/ojs/external-observablehq-parser/README.md

Illustrates a block cell, which contains a BlockStatement, and its AST.

```javascript
{
  return 1 + 2;
}
```

```json
{
  "type": "Cell",
  "id": null,
  "async": false,
  "generator": false,
  "body": {
    "type": "BlockStatement",
    "body": [
      {
        "type": "ReturnStatement",
        "argument": {
          "type": "BinaryExpression",
          "left": {
            "type": "Literal",
            "value": 1,
            "raw": "1"
          },
          "operator": "+",
          "right": {
            "type": "Literal",
            "value": 2,
            "raw": "2"
          }
        }
      }
    ]
  }
}
```

--------------------------------

### Named Block Cell Example

Source: https://github.com/quarto-dev/quarto/blob/main/packages/ojs/external-observablehq-parser/README.md

Illustrates a named block cell with an identifier and its AST.

```javascript
foo = {
  return 42;
}
```

```json
{
  "type": "Cell",
  "id": {
    "type": "Identifier",
    "name": "foo"
  },
  "async": false,
  "generator": false,
  "body": {
    "type": "BlockStatement",
    "body": [
      {
        "type": "ReturnStatement",
        "argument": {
          "type": "Literal",
          "value": 42,
          "raw": "42"
        }
      }
    ]
  }
}
```

--------------------------------

### Enable Listings

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Use `--listings` on the command line or `listings: true` in the defaults file to enable the inclusion of source code listings.

```bash
--listings
```

```yaml
listings: true
```

--------------------------------

### Named Expression Cell Example

Source: https://github.com/quarto-dev/quarto/blob/main/packages/ojs/external-observablehq-parser/README.md

Demonstrates a named expression cell with an identifier and its AST.

```javascript
foo = 42
```

```json
{
  "type": "Cell",
  "id": {
    "type": "Identifier",
    "name": "foo"
  },
  "async": false,
  "generator": false,
  "body": {
    "type": "Literal",
    "value": 42,
    "raw": "42"
  }
}
```

--------------------------------

### Mapping Command Line to Defaults File (Single Input)

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Demonstrates how a single input file specified on the command line maps to the 'input-file' field in a defaults file.

```yaml
input-file: foo.md
```

--------------------------------

### Viewof Expression Cell Example

Source: https://github.com/quarto-dev/quarto/blob/main/packages/ojs/external-observablehq-parser/README.md

Illustrates a viewof expression cell, where the id is a ViewExpression, and its AST.

```javascript
viewof x = DOM.range()
```

```json
{
  "type": "Cell",
  "id": {
    "type": "ViewExpression",
    "id": {
      "type": "Identifier",
      "name": "x"
    }
  },
  "async": false,
  "generator": false,
  "body": {
    "type": "CallExpression",
    "callee": {
      "type": "MemberExpression",
      "object": {
        "type": "Identifier",
        "name": "DOM"
      },
      "property": {
        "type": "Identifier",
        "name": "range"
      },
      "computed": false
    },
    "arguments": []
  }
}
```

--------------------------------

### Observable Runtime Hello World

Source: https://github.com/quarto-dev/quarto/blob/main/packages/ojs/external-observablehq-runtime/test/hello-world.html

Initializes the Observable Runtime, defines an input for a name, and displays a reactive greeting. Use this to set up a basic interactive element with Observable.

```javascript
import {Runtime, Inspector, Library} from "/dist/runtime.js";
var runtime = new Runtime(new Library),
    module = runtime.module();
module.variable(new Inspector(document.querySelector("#name"))).define("viewof name", ["DOM"], DOM => DOM.input());
module.variable().define("name", ["Generators", "viewof name"], (Generators, view) => Generators.input(view));
module.variable(new Inspector(document.querySelector("#hello"))).define(["name"], name => `Hello, ${name || "anonymous"}!`);
```

--------------------------------

### Generator Expression Cell Example

Source: https://github.com/quarto-dev/quarto/blob/main/packages/ojs/external-observablehq-parser/README.md

Demonstrates a generator expression cell, where generator is true, and its AST.

```javascript
yield* [1, 2, 3]
```

```json
{
  "type": "Cell",
  "id": null,
  "async": false,
  "generator": true,
  "body": {
    "type": "YieldExpression",
    "delegate": true,
    "argument": {
      "type": "ArrayExpression",
      "elements": [
        {
          "type": "Literal",
          "value": 1,
          "raw": "1"
        },
        {
          "type": "Literal",
          "value": 2,
          "raw": "2"
        },
        {
          "type": "Literal",
          "value": 3,
          "raw": "3"
        }
      ]
    }
  }
}
```

--------------------------------

### Asynchronous Expression Cell Example

Source: https://github.com/quarto-dev/quarto/blob/main/packages/ojs/external-observablehq-parser/README.md

Shows an asynchronous expression cell and its AST, where async is true.

```javascript
2 * await value
```

```json
{
  "type": "Cell",
  "id": null,
  "async": true,
  "generator": false,
  "body": {
    "type": "BinaryExpression",
    "left": {
      "type": "Literal",
      "value": 2,
      "raw": "2"
    },
    "operator": "*",
    "right": {
      "type": "AwaitExpression",
      "argument": {
        "type": "Identifier",
        "name": "value"
      }
    }
  }
}
```

--------------------------------

### Configure WebTeX Rendering (Defaults File)

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Set 'html-math-method:
  method: webtex' in your _quarto.yml for WebTeX.

```yaml
html-math-method:
  method: webtex
```

--------------------------------

### Mapping Command Line to Defaults File (Multiple Inputs)

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Shows how multiple input files specified on the command line map to the 'input-files' list in a defaults file.

```yaml
input-files:
  - foo.md
  - bar.md
```

--------------------------------

### Configure MathML Rendering (Command Line)

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Use the --mathml flag to enable MathML rendering for HTML output.

```bash
--mathml
```

--------------------------------

### Enable HTML Q Tags

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Use `--html-q-tags` on the command line or `html-q-tags: true` in the defaults file to enable the use of HTML <q> tags.

```bash
--html-q-tags
```

```yaml
html-q-tags: true
```

--------------------------------

### Enable Reference Links

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Use `--reference-links` on the command line or `reference-links: true` in the defaults file to enable the generation of reference-style links.

```bash
--reference-links
```

```yaml
reference-links: true
```

--------------------------------

### Get File Attachment URL

Source: https://github.com/quarto-dev/quarto/blob/main/packages/ojs/external-observablehq-stdlib/README.md

Retrieve the URL for a file attachment. This is useful for embedding or referencing the file externally.

```javascript
const url = await FileAttachment("file.txt").url();
```

--------------------------------

### Get Pandoc Capabilities

Source: https://context7.com/quarto-dev/quarto/llms.txt

Use `getCapabilities` to fetch Pandoc version information and a list of supported output formats.

```typescript
// getCapabilities — Pandoc version info and supported formats
const caps = await pandocServer.getCapabilities();
// caps.version => "3.1.11"
// caps.output_formats => "html,pdf,docx,..."
```

--------------------------------

### Enable Incremental Rendering

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Use `--incremental` on the command line or `incremental: true` in the defaults file to enable incremental rendering for presentations.

```bash
--incremental
```

```yaml
incremental: true
```

--------------------------------

### Metadata Configuration (Command Line)

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Set metadata key-value pairs directly on the command line.

```bash
--metadata key=value \
 --metadata key2
```

--------------------------------

### ATX-style Headings

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Create headings using '#' symbols. The number of '#' at the start determines the level. Inline formatting is supported.

```markdown
## A level-two heading
```

```markdown
### A level-three heading ###
```

```markdown
# A level-one heading with a [link](/url) and *emphasis*
```

--------------------------------

### YAML Metadata with Structured Authors

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Example of a YAML metadata block with structured author information, including name and affiliation.

```yaml
---
title: The document title
author:
- name: Author One
  affiliation: University of Somewhere
- name: Author Two
  affiliation: University of Nowhere
...
```

--------------------------------

### Configure MathML Rendering (Defaults File)

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Set 'html-math-method:
  method: mathml' in your _quarto.yml for MathML.

```yaml
html-math-method:
  method: mathml
```

--------------------------------

### Nested Blockquote Example

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Illustrates how to nest blockquotes by using an additional '>' character. A blank line is required before the nested quote.

```markdown
> This is a block quote.
>
> > A block quote within a block quote.
```

--------------------------------

### Pandoc Template Syntax: Delimiters

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Examples of delimiters used for variables and control structures in Pandoc templates. Literal '$' can be escaped with '$$'.

```template
$...$
```

```template
${...}
```

```template
$$ 
```

--------------------------------

### Wrapper Script Options

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Command-line options for wrapper scripts and their corresponding defaults file settings.

```bash
--dump-args
```

```yaml
dump-args: true
```

```bash
--ignore-args
```

```yaml
ignore-args: true
```

--------------------------------

### Viewof Reference in Expression Cell Example

Source: https://github.com/quarto-dev/quarto/blob/main/packages/ojs/external-observablehq-parser/README.md

Shows a viewof reference within an expression cell's body and its AST.

```javascript
viewof x.tagName
```

```json
{
  "type": "Cell",
  "id": null,
  "async": false,
  "generator": false,
  "body": {
    "type": "MemberExpression",
    "object": {
      "type": "ViewExpression",
      "id": {
        "type": "Identifier",
        "name": "x"
      }
    },
    "property": {
      "type": "Identifier",
      "name": "tagName"
    },
    "computed": false
  }
}
```

--------------------------------

### Print Hello World in Python

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

A basic Python code snippet to print 'hello' to standard output.

```python
print("hello")
```

--------------------------------

### Resolve the URL for an npm package

Source: https://github.com/quarto-dev/quarto/blob/main/packages/ojs/external-observablehq-stdlib/README.md

Use `require.resolve` to get the resolved URL for a module, which can be useful for debugging or direct linking.

```javascript
require.resolve("d3-array") // "https://cdn.jsdelivr.net/npm/d3-array@2.0.3/dist/d3-array.min.js"
```

--------------------------------

### `diagnostics` (custom.ts)

Source: https://context7.com/quarto-dev/quarto/llms.txt

Get YAML diagnostics from Quarto CLI by calling `quarto.getYamlDiagnostics` for an `EditorContext` and returns structured lint items.

```APIDOC
## `diagnostics` (custom.ts)

### Description
Get YAML diagnostics from Quarto CLI by calling `quarto.getYamlDiagnostics` for an `EditorContext` and returns structured lint items.

### Usage
```typescript
import { diagnostics } from "./custom"; // apps/lsp/src/custom.ts
import { EditorContext } from "./service/quarto";
import { LintItem } from "editor-types";

const context: EditorContext = {
  filepath: "/home/user/project/analysis.qmd",
  language: "yaml",
  code: "title: Hello\noutput: html_docment\n", // note typo
  position: { row: 0, column: 0 },
  formats: ["html"],
  trigger: undefined,
  explicit: false,
};

const items: LintItem[] | null = await diagnostics(quarto, context);
// items[0] => {
//   "start.row": 1, "start.column": 8,
//   "end.row": 1,   "end.column": 20,
//   text: "Unknown key 'html_docment'",
//   type: "error"
// }
```
```

--------------------------------

### Create PowerPoint Slide Show

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Command to convert Markdown to a PowerPoint presentation file.

```bash
pandoc habits.txt -o habits.pptx
```

--------------------------------

### Pandoc Table Captions

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Add a caption to any table by preceding it with a paragraph starting with 'Table:', 'table:', or ':'. The caption text will be stripped.

```markdown
Table:

| Header 1 | Header 2 |
|---|---|
| Cell 1 | Cell 2 |
| Cell 3 | Cell 4 |
```

--------------------------------

### Configure MathJax Rendering (Defaults File)

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Set 'html-math-method:
  method: mathjax' in your _quarto.yml for MathJax.

```yaml
html-math-method:
  method: mathjax
```

--------------------------------

### Markdown Source for Slide Show

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Example Markdown content demonstrating structure for a slide show, including title, sections, and content.

```markdown
% Habits
% John Doe
% March 22, 2005

# In the morning

## Getting up

- Turn off alarm
- Get out of bed

## Breakfast

- Eat eggs
- Drink coffee

# In the evening

## Dinner

- Eat spaghetti
- Drink wine

------------------

![picture of spaghetti](images/spaghetti.jpg)

## Going to sleep

- Get in bed
- Count sheep
```

--------------------------------

### Template Selection: Command Line vs. Defaults File

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Specify a custom template with --template command-line flag or template: <name> in the defaults file.

```bash
--template letter
```

```yaml
template: letter
```

--------------------------------

### Including Raw LaTeX in Header

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Example of using `header-includes` with the `raw_attribute` extension to insert raw LaTeX code into the document header.

```yaml
header-includes:
- | 
  ```{=latex}
  \let\oldsection\section
  \renewcommand{\section}[1]{\clearpage\oldsection{#1}}
  ```
```

--------------------------------

### Configure MathJax Rendering (Command Line)

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Use the --mathjax flag to enable MathJax rendering for HTML output.

```bash
--mathjax
```

--------------------------------

### Lazy Blockquote Example

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Shows the 'lazy' form of blockquotes where '>' is only required on the first line of each paragraph. Lists still require '>' on each line.

```markdown
> This is a block quote. This
paragraph has two lines.

> 1. This is a list inside a block quote.
2. Second item.
```

--------------------------------

### Basic Pipe Usage in Quarto

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Demonstrates the basic application of pipes to transform variable values within loops and directly. Use pipes to modify data before rendering.

```quarto
$for(name)$
$name/uppercase$
$endfor$
```

```quarto
$for(metadata/pairs)$
- $it.key$: $it.value$
$endfor$
```

```quarto
$employee:name()/uppercase$
```

--------------------------------

### Get YAML Diagnostics in Editor

Source: https://github.com/quarto-dev/quarto/blob/main/apps/overview.md

Retrieves diagnostics for YAML front matter in the editor. Requires editor context and behavior context.

```typescript
const diagnostics = await getDiagnostics(cellContext, behaviorContext);
if (!diagnostics) return;

for (const error of diagnostics) {
  underline(
    cmView,
    rowColumnToIndex(code, [error[kStartColumn], error[kStartRow]]),
    rowColumnToIndex(code, [error[kEndColumn], error[kEndRow]]),
    error.text,
  );
}
```

--------------------------------

### Pipes with Parameters for Table Formatting

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Shows how pipes like 'left' and 'right' can be used with parameters to format text for table alignment. Ensure parameters are correctly quoted and ordered.

```quarto
|----------------------|------------|
$for(employee)$
$it.name.first/uppercase/left 20 "| "$$it.name.salary/right 10 " | " " |"$
$endfor$
|----------------------|------------|
```

--------------------------------

### Define multiple aliases for require

Source: https://github.com/quarto-dev/quarto/blob/main/packages/ojs/external-observablehq-stdlib/README.md

Define multiple module aliases in a single object for use with `require.alias`. This allows for a more organized setup.

```javascript
r = require.alias({
  "react": "react@16/umd/react.production.min.js",
  "react-dom": "react-dom@16/umd/react-dom.production.min.js",
  "semiotic": "semiotic@1"
})
```

--------------------------------

### Get Zip Archive Filenames - JavaScript

Source: https://github.com/quarto-dev/quarto/blob/main/packages/ojs/external-observablehq-stdlib/README.md

Access the list of filenames within a zip archive. Requires the zip archive to be loaded as a FileAttachment.

```javascript
const archive = await FileAttachment("archive.zip").zip();
console.log(archive.filenames);
```

--------------------------------

### Configure Citation Processing (Defaults File)

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Set 'citeproc: true' in your _quarto.yml (or equivalent) to enable citation processing.

```yaml
citeproc: true
```

--------------------------------

### Set Numbering Offset

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Use `--number-offset=1,4` on the command line or `number-offset: [1,4]` in the defaults file to set the starting number for sections.

```bash
--number-offset=1,4
```

```yaml
number-offset: [1,4]
```

--------------------------------

### Specify Bibliography File (Defaults File)

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Define the bibliography file under the 'metadata' section in your _quarto.yml.

```yaml
metadata:
  bibliography: logic.bib
```

--------------------------------

### Generate integers from 0 to 99

Source: https://github.com/quarto-dev/quarto/blob/main/packages/ojs/external-observablehq-stdlib/README.md

Generators.range creates a generator that yields an arithmetic progression. This example shows how to iterate over integers from 0 up to (but not including) 100.

```javascript
i = {
  for (const i of Generators.range(0, 100, 1)) {
    yield i;
  }
}
```

--------------------------------

### Enable Sandbox Mode via Command Line

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Use the `--sandbox` argument to enable sandbox mode, which restricts file access.

```bash
--sandbox
```

--------------------------------

### List Pandoc Extensions for a Format

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Use this command to see which extensions are supported for a given format and which are enabled by default. Replace FORMAT with the desired format name.

```bash
pandoc --list-extensions=FORMAT
```

--------------------------------

### Enable Sandbox Mode in Defaults File

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Configure sandbox mode using the `sandbox: true` setting in a YAML defaults file.

```yaml
sandbox: true
```

--------------------------------

### Pandoc Command: Convert Docx to Markdown (No Styles)

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Example of converting a docx file to markdown without enabling the 'styles' extension. This will not preserve custom styles.

```bash
$ pandoc test/docx/custom-style-reference.docx -f docx -t markdown
```

--------------------------------

### Enable List Tables

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Use `--list-tables` on the command line or `list-tables: true` in the defaults file to enable the rendering of tables within lists.

```bash
--list-tables
```

```yaml
list-tables: true
```

--------------------------------

### Standalone Mode: Command Line vs. Defaults File

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Configure standalone output using the --standalone command-line flag or the standalone: true setting in the defaults file.

```bash
--standalone
```

```yaml
standalone: true
```

--------------------------------

### Backtick Code Block Example

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

An alternative to tilde-fenced code blocks, using three or more backticks to delimit the code. Requires blank lines around the block.

```plaintext
```
if (a > 3) {
  moveShip(5 * gravity, DOWN);
}
```
```

--------------------------------

### Highlight Style (Specific): Command Line vs. Defaults File

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Set a specific highlight style using --highlight-style on the command line or highlight-style: <name> in the defaults file.

```bash
--highlight-style kate
```

```yaml
highlight-style: kate
```

--------------------------------

### Get the first element from an iterator

Source: https://github.com/quarto-dev/quarto/blob/main/packages/ojs/external-observablehq-stdlib/README.md

Generators.valueAt retrieves a specific element from an iterator by its index. Note that this method assumes a synchronous iterator and does not wait for promises to resolve.

```javascript
first = Generators.valueAt(iterator, 0)
```

--------------------------------

### Configure Geometry Package Options

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Set page margins and other layout options using the 'geometry' package. Repeat the 'geometry' key for multiple options.

```yaml
---
geometry:
- top=30mm
- left=20mm
- heightrounded
...
```

--------------------------------

### Get Zotero Library Names

Source: https://context7.com/quarto-dev/quarto/llms.txt

Use `getLibraryNames` to retrieve a list of available Zotero library names for the authenticated user. Check the `status` property of the result.

```typescript
// Get library names available to the user
const namesResult: ZoteroResult = await zoteroServer.getLibraryNames();
if (namesResult.status === "ok") {
  console.log(namesResult.message); // => ["My Library", "Group: Lab Papers"]
}
```

--------------------------------

### Get YAML Diagnostics from Quarto CLI

Source: https://context7.com/quarto-dev/quarto/llms.txt

Calls `quarto.getYamlDiagnostics` for an `EditorContext` to retrieve structured lint items. Ensure the `diagnostics` function and `EditorContext` type are imported.

```typescript
import { diagnostics } from "./custom"; // apps/lsp/src/custom.ts
import { EditorContext } from "./service/quarto";
import { LintItem } from "editor-types";

const context: EditorContext = {
  filepath: "/home/user/project/analysis.qmd",
  language: "yaml",
  code: "title: Hello\noutput: html_docment\n", // note typo
  position: { row: 0, column: 0 },
  formats: ["html"],
  trigger: undefined,
  explicit: false,
};

const items: LintItem[] | null = await diagnostics(quarto, context);
// items[0] => {
//   "start.row": 1, "start.column": 8,
//   "end.row": 1,   "end.column": 20,
//   text: "Unknown key 'html_docment'",
//   type: "error"
// }
```

--------------------------------

### Create a default standard library

Source: https://github.com/quarto-dev/quarto/blob/main/packages/ojs/external-observablehq-stdlib/README.md

Instantiate the `Library` class to create a default standard library object. This object provides access to various Observable symbols.

```javascript
const library = new Library();
const canvas = library.DOM.canvas(960, 500);
```

--------------------------------

### Blank Line Before Header Extension

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Pandoc requires a blank line before a heading, unlike some Markdown implementations. This prevents accidental heading creation from lines starting with '#'.

```markdown
I like several of their flavors of ice cream:
#22, for example, and #5.
```

--------------------------------

### Trace (Command Line)

Source: https://github.com/quarto-dev/quarto/blob/main/apps/writer/public/content/MANUAL-FULL.md

Enable tracing output with the `--trace` command-line flag.

```bash
--trace
```