minimal documentation for engine extensions

_quarto.yml

@@ -477,6 +477,7 @@ website:
             - text: "Metadata Extensions"
               href: docs/extensions/metadata.qmd
             - docs/extensions/brand.qmd
+            - docs/extensions/engine.qmd
 
     - id: reference
       title: "Reference"

docs/extensions/brand.qmd

@@ -4,12 +4,6 @@ title: "Brand Extensions"
 
 Brand extensions are Quarto extensions that provide a [brand.yml](../authoring/brand.qmd) file and its assets.
 
-::: callout-important
-
-Currently, brand extensions merge project-level metadata, so they can only be used with a `_quarto.yml` [project](../projects/quarto-projects.qmd) present in the place where they are installed. This limitation may be lifted in the future.
-
-:::
-
 ### Quick Start
 
 Here we'll describe how to create a simple brand extension. We'll use the `quarto create` command to do this. If you are using VS Code, Positron, or RStudio you should execute `quarto create` within their respective integrated Terminal panes. 
@@ -68,7 +62,7 @@ color:
     dark: "#fff"
 ```
 
-This is just enough `brand.yml` to enable dark mode. If you preview the `example.qmd` provided in the root of your brand extension
+This uses [light and dark colors](../authoring/brand.qmd#light-and-dark-colors) to enable dark mode. If you preview the `example.qmd` provided in the root of your brand extension
 
 ```bash
 quarto preview example.qmd
@@ -85,15 +79,7 @@ project:
   type: default
 ```
 
-::: {.callout-note}
-
-The example brand.yml is using the unified light and dark brand feature. Documentation for this feature is on the way.
-
-Any color in the color or typography sections of [brand.yml](https://posit-dev.github.io/brand-yml/) can be specified with `light` and `dark` components or as a string. If a string, the value is used for both light and dark modes.
-
-This works for colors only.
-
-:::
+The example brand.yml is to demonstrate dark mode. 
 
 ## How Brand Extensions Work
 

docs/extensions/engine.qmd

@@ -0,0 +1,112 @@
+---
+title: "Engine Extensions"
+---
+
+Engine extensions are Quarto extensions that provide an execution engine for running code blocks and capturing their output in Quarto documents.
+
+::: callout-important
+
+Currently there is one execution engine per Quarto document, so you can't have some code blocks executed by an engine extension and other code blocks executed by e.g. `jupyter` or `knitr`.
+
+Engine extensions do not allow control over the cell language handlers for [diagrams](/docs/authoring/diagrams.qmd) like `mermaid` and `dot`.
+
+This is likely to improve in the future.
+:::
+
+### Quick Start
+
+Here we'll describe how to create a basic engine extension. We'll use the `quarto create` command to do this. If you are using VS Code, Positron, or RStudio you should execute `quarto create` within their respective integrated Terminal panes. 
+
+To get started, execute `quarto create extension engine` within the parent directory where you'd like the engine extension to be created:
+
+```{.bash filename="Terminal"}
+$ quarto create extension engine
+? Extension Name › my-language-engine
+? Default cell language name (my-language-engine) › my-language
+```
+
+As shown above, you'll be prompted for an engine name and a cell language name for cells, e.g.
+
+````markdown
+```{my-language}
+x = 42
+```
+````
+
+The language name will default to the engine name. Type each name and press Enter---the engine extension is then created:
+
+```bash
+? Extension Name › my-prerender-scripts
+Creating extension at /Users/gordon/src/my-language-engine:
+  - Created example.qmd
+  - Created README.md
+  - Created _extensions/my-language-engine/_extension.yml
+  - Created .gitignore
+  - Created src/my-language-engine.ts
+? Open With
+❯ positron
+  vscode
+  rstudio
+  (don't open)
+```
+
+If you are running within VS Code, Positron, or RStudio a new window will open with the extension project. 
+
+## Contents of Engine Extensions
+
+The `quarto create extension engine` command has created an `_extensions` directory, which is what gets installed for users of your extension, and a `src` directory containing the TypeScript source.
+
+The `_extensions/my-language-engine/` directory will contain a Quarto extension configuration like this:
+
+``` {.yaml filename="_extensions/my-language-engine/_extension.yml"}
+title: My-language-engine
+author: Gordon Woodhull
+version: 1.0.0
+quarto-required: ">=1.9.0"
+contributes:
+  engines:
+    - path: my-language-engine.js
+```
+
+To generate the JavaScript bundle this points to, run
+
+```bash
+quarto call build-ts-extension
+```
+
+This builds the TypeScript source `src/my-language-engine.ts` against the types and import map distributed with Quarto, and outputs `_extensions/my-language-engine/my-language-engine.js`.
+
+## How Engine Extensions Work
+
+The `ExecutionEngineDiscovery` interface specifies
+
+* an `init` method providing the **Quarto API**[The **Quarto API** is not documented yet. See the Typescript types in [quarto-types](https://github.com/quarto-dev/quarto-cli/tree/main/packages/quarto-types)]{.aside} to the engine
+* methods used in determining which engine to use
+* a `launch` method which takes the `EngineProjectContext` and provides methods for executing cells and capturing output, and returns an `ExecutionEngineInstance`.
+
+The `ExecutionEngineInstance.execute` method processes the entire markdown of the document after includes and embeds, and before cell language handlers and Pandoc.
+
+For the languages that it claims, it should replace each code block with:
+
+1.  If `options.format.execute.echo` is true, the same code block in non-executable syntax. 
+
+    E.g. if the input is
+
+    ````markdown
+    ```{{python}}
+    ```
+    ````
+
+    Then the output should be
+
+    ````markdown
+    ``` {.python}
+    ```
+    ````
+
+    adding other classes and attributes as appropriate.
+
+    If `echo` is false, the code should not be output.
+2.  Any outputs from executing the code block, depending on `options.format.execute.output`
+
+See [Execution Options](/docs/computations/execution-options.qmd) for more information on execution options.

docs/extensions/metadata.qmd

@@ -6,7 +6,9 @@ Metadata extensions are Quarto extensions that provide metadata (YAML objects) t
 
 ::: callout-important
 
-Currently, metadata extensions only merge project-level metadata. This limitation will be lifted in the future.
+Currently, metadata extensions only merge project-level metadata. (If there is no project, a temporary default project is created in memory.) 
+
+This limitation will be lifted in the future.
 
 :::
 
@@ -60,6 +62,8 @@ Quarto projects using metadata extensions do not need to change their project ty
 
 ::: callout-note
 
-As noted above, metadata extensions only merge project-level metadata in the `project` key. This limitation will be lifted in the future.
+As noted above, metadata extensions only merge project-level metadata in the `project` key (empty if there is no project). 
+
+This limitation will be lifted in the future.
 
 :::

docs/prerelease/1.9/_highlights.qmd

@@ -2,4 +2,13 @@ Quarto 1.9 includes the following new features:
 
 - [Privacy-first cookie consent](/docs/websites/website-tools.qmd#cookie-consent): The default for cookie consent has changed to `type: express`, providing opt-in consent that blocks cookies until users explicitly agree. This privacy-conscious default is designed with modern privacy regulations in mind.
 
-- [`aria-label` for videos](/docs/authoring/videos.qmd#accessibility-label): Improve accessibility of embedded videos by providing custom descriptive labels for screen readers instead of the default "Video Player" label.
+- [`aria-label` for videos](/docs/authoring/videos.qmd#accessibility-label): Improve accessibility of embedded videos by providing custom descriptive labels for screen readers instead of the default "Video Player" label.
+
+- Metadata and brand extensions now work without a `_quarto.yml` project. A temporary default project is created in memory.
+
+- [Engine extensions](/docs/extensions/engine.qmd) allow replacement of the execution engine:
+  - Julia is now a bundled extension instead of being built-in.
+  - **quarto-marimo** will soon change from a filter extension to an engine extension.
+  - New `quarto create extension engine` command.
+  - New `quarto call build-ts-extension` command.
+  - New **Quarto API** for engine extensions to use. (This is in flux and will not be documented for the next few releases, but there will be a dev blog post about it.)