diff --git a/_quarto.yml b/_quarto.yml index 92c73a8bb..c9d26b734 100644 --- a/_quarto.yml +++ b/_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" diff --git a/docs/extensions/brand.qmd b/docs/extensions/brand.qmd index 78f87e6c7..bea89fa30 100644 --- a/docs/extensions/brand.qmd +++ b/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 diff --git a/docs/extensions/engine.qmd b/docs/extensions/engine.qmd new file mode 100644 index 000000000..0bbdaf515 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/extensions/metadata.qmd b/docs/extensions/metadata.qmd index 1e3ecb20a..4f679aef0 100644 --- a/docs/extensions/metadata.qmd +++ b/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. ::: \ No newline at end of file diff --git a/docs/prerelease/1.9/_highlights.qmd b/docs/prerelease/1.9/_highlights.qmd index 763f977ec..bac833cd9 100644 --- a/docs/prerelease/1.9/_highlights.qmd +++ b/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. \ No newline at end of file +- [`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.)