Resource path resolution broken in Typst format extension

[mcanouil]

I have:

• searched the issue tracker for similar issues
• installed the latest version of Quarto CLI
• formatted my issue following the Bug Reports guide

Bug description

Path resolution of resources for Typst format is broken.

Reproducible example: https://github.com/mcanouil/quarto-issues-experiments/tree/main/quarto-cli-13917

git clone --filter=blob:none --sparse https://github.com/mcanouil/quarto-issues-experiments.git
cd quarto-issues-experiments
git sparse-checkout set quarto-cli-13917

.
├── _extensions
│   └── issue
│       ├── _extension.yml
│       └── quarto-icon.svg
├── _quarto.yml
└── sub
    ├── template_files
    │   └── mediabag
    ├── template.qmd
    └── template.typ

5 directories, 5 files

cd quarto-cli-13917/
quarto render sub/template.qmd

pandoc 
  to: typst
  output-file: template.typ
  standalone: true
  shift-heading-level-by: -1
  default-image-extension: svg
  wrap: none
  citeproc: false
  variables: {}
  
metadata
  logo: ../_extensions/issue/quarto-icon.svg
  title: Untitled
  
[typst]: Compiling template.typ to template.pdf...error: failed to load file (access denied)
    ┌─ sub/template.typ:287:63
    │
287 │ #set page(background: align(left+top, box(inset: 0.75in, image("../../_extensions/issue/quarto-icon.svg", width: 1.5in))))
    │                                                                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    │
    = hint: cannot read file outside of project root
    = hint: you can adjust the project root with the --root argument

Unless the Quarto document lives next to _quarto.yml, paths get resolved incorrectly.

This makes the use of custom Typst formats inside projects almost impossible.

When template.qmd is at the root of the project:

quarto render template.qmd

pandoc 
  to: typst
  output-file: template.typ
  standalone: true
  shift-heading-level-by: -1
  default-image-extension: svg
  wrap: none
  citeproc: false
  variables: {}
  
metadata
  logo: _extensions/issue/quarto-icon.svg
  title: Untitled
  
[typst]: Compiling template.typ to template.pdf...DONE

Output created: template.pdf

The Typst intermediate file:

#set page(background: align(left+top, box(inset: 0.75in, image("_extensions/issue/quarto-icon.svg", width: 1.5in))))

---

Related discussions:

• https://github.com/orgs/quarto-dev/discussions/13742
• https://github.com/orgs/quarto-dev/discussions/12638

Possibly related if not the same issue as:

• In custom typst format extension, relative or project relative font-paths not working #13745

Quarto check output

Quarto 99.9.9
[✓] Checking environment information...
      Quarto cache location: /Users/mcanouil/Library/Caches/quarto
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.8.3: OK
      Dart Sass version 1.87.0: OK
      Deno version 2.4.5: OK
      Typst version 0.14.2: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 99.9.9
      commit: 5e05270460a1830ef38031b6a93c1a0432933ac4
      Path: /Users/mcanouil/Projects/quarto-dev/quarto-cli/package/dist/bin

[✓] Checking tools....................OK
      TinyTeX: v2026.01
      Chromium: (not installed)

[✓] Checking LaTeX....................OK
      Using: TinyTex
      Path: /Users/mcanouil/Library/TinyTeX/bin/universal-darwin
      Version: 2025

[✓] Checking Chrome Headless....................OK
      Using: Chrome found on system
      Path: /Applications/Brave Browser.app/Contents/MacOS/Brave Browser
      Source: QUARTO_CHROMIUM

[✓] Checking basic markdown render....OK

(/) Checking R installation...........ℹ R version 4.5.2 (2025-10-31)
! Config '~/.Rprofile' was loaded!
[✓] Checking R installation...........OK
      Version: 4.5.2
      Path: /Library/Frameworks/R.framework/Resources
      LibPaths:
        - /Library/Frameworks/R.framework/Versions/4.5-arm64/Resources/library
      knitr: 1.50
      rmarkdown: 2.30

[✓] Checking Knitr engine render......OK

[✓] Checking Python 3 installation....OK
      Version: 3.14.2
      Path: /opt/homebrew/opt/python@3.14/bin/python3.14
      Jupyter: (None)

      Jupyter is not available in this Python installation.
      Install with python3 -m pip install jupyter

[✓] Checking Julia installation...

[mcanouil]

Funnily, there are twice ../ as the document is nested.
See also the difference between "metadata" and what ends up in the intermediate Typst file.

quarto render subsub/sub/template.qmd

pandoc 
  to: typst
  output-file: template.typ
  standalone: true
  shift-heading-level-by: -1
  default-image-extension: svg
  wrap: none
  citeproc: false
  variables: {}
  
metadata
  logo: ../../_extensions/issue/quarto-icon.svg
  title: Untitled
  
[typst]: Compiling template.typ to template.pdf...error: failed to load file (access denied)
    ┌─ subsub/sub/template.typ:287:63
    │
287 │ #set page(background: align(left+top, box(inset: 0.75in, image("../../../../_extensions/issue/quarto-icon.svg", width: 1.5in))))
    │                                                                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    │
    = hint: cannot read file outside of project root
    = hint: you can adjust the project root with the --root argument

[mcanouil]

It seems the project offset is prepended twice: probably in TypeScript during extension processing (toInputRelativePaths) and in Lua (according to DeepWiki: typst-brand-yaml.lua).

This could be a side effect of:

• typst brand yaml: resolve logo paths via project directory #13297

I would say imageFilename:sub(1, 3) ~= "../" is missing as you probably don't want to add project offset to a path with ../.

if imageFilename[1] ~= "/" and imageFilename:sub(1, 3) ~= "../" and _quarto.projectOffset() ~= "." then

• quarto-cli/src/resources/filters/quarto-post/typst-brand-yaml.lua

  Lines 323 to 326 in 5e05270

  	if imageFilename[1] ~= "/" and _quarto.projectOffset() ~= "." then
  	local offset = _quarto.projectOffset()
  	imageFilename = pandoc.path.join({offset, imageFilename})
  	end

[gordonwoodhull]

Thanks @mcanouil!

I'm dismayed that there is yet another kind of path that I didn't understand before.

I think both fixes are correct and minimal, but I find this situation confusing and hope that in the future we'll have properly typed paths and known stages of path resolution.

I'm pasting Claude's analysis of the two bugs and fixes below.

Brand vs Extension Path Resolution in Typst

Overview

Quarto has two different path resolution systems with different semantics that must be handled correctly when rendering Typst documents from project subdirectories.

The Two Path Systems

1. Brand paths (from _brand.yml)

• Resolved by: Brand.resolvePath() in src/core/brand/brand.ts:246-257
• Semantics: Paths are PROJECT-relative (relative to projectDir)
• Example: If brand is at _brand/ with logo images/logo.png, the resolved path is _brand/images/logo.png

// brand.ts:246-257
resolvePath(entry: BrandLogoResource) {
  const pathPrefix = relative(this.projectDir, this.brandDir);
  if (typeof entry === "string") {
    return { path: isExternalPath(entry) ? entry : join(pathPrefix, entry) };
  }
  // ...
}

2. Extension paths (from _extension.yml)

• Resolved by: toInputRelativePaths() in src/project/project-shared.ts:137-206
• Semantics: Paths are INPUT-relative (relative to the document being rendered)
• Example: For a doc at sub/doc.qmd using extension at _extensions/foo/, paths become ../_extensions/foo/resource.svg

// project-shared.ts:147-157
const fixup = (value: string) => {
  // if this is a valid file, then transform it to be relative to the input path
  if (!existsCache.has(value)) {
    const projectPath = join(baseDir, value);
    if (existsSync(projectPath)) {
      existsCache.set(value, pathWithForwardSlashes(join(offset!, value)));
    }
  }
  return existsCache.get(value);
};

The Fundamental Issue

When rendering Typst from a subdirectory, the two path types require different handling:

Path Type	Original Path	Needs Adjustment?	Reason
Brand paths	_brand/logo.png (project-relative)	YES	Need projectOffset() to become ../_brand/logo.png for doc in subdirectory
Extension paths	../_extensions/foo/logo.svg (input-relative)	NO	Already correct for the document's location

The Two Bugs

Bug #1: Font paths (Issue #13745 / PR #13902)

• Location: src/command/render/output-typst.ts
• Problem: Extension font-paths passed to typst compile weren't being found because Typst runs from project root (via --root flag)
• Root cause: All relative font paths were being passed as-is, but extension paths needed resolution relative to input directory
• Fix: Detect extension paths (contain _extensions or start with ..) and resolve them to absolute paths before passing to Typst

// PR #13902 fix in output-typst.ts
const fontPaths = asArray(format.metadata?.[kFontPaths]).map((p) => {
  const fontPath = p as string;
  if (isAbsolute(fontPath)) {
    return fontPath;
  }
  // Extension-resolved paths need to be resolved relative to input file
  if (fontPath.includes("_extensions") || fontPath.startsWith("..")) {
    return join(inputDir, fontPath);
  }
  // Other relative paths (like .quarto/...) stay relative to working dir
  return fontPath;
});

Bug #2: Logo paths (Issue #13917)

• Location: src/resources/filters/quarto-post/typst-brand-yaml.lua
• Problem: Commit 533784522 added projectOffset() for brand logos, but it incorrectly also applies to extension logos
• Root cause: The code doesn't distinguish between brand paths (project-relative, need offset) and extension paths (input-relative, already correct)
• Symptom: Logo path ../_extensions/issue/logo.svg becomes ../../_extensions/issue/logo.svg (double-prefixed), causing "access denied" from Typst

Buggy code:

-- typst-brand-yaml.lua:323-326 (introduced in 533784522)
if imageFilename[1] ~= "/" and _quarto.projectOffset() ~= "." then
  local offset = _quarto.projectOffset()
  imageFilename = pandoc.path.join({offset, imageFilename})
end

Fix: Same pattern as PR #13902 - detect extension paths and skip the offset:

if imageFilename[1] ~= "/" and _quarto.projectOffset() ~= "." then
  local is_extension_path = string.find(imageFilename, "_extensions") or
    string.sub(imageFilename, 1, 2) == ".."
  if not is_extension_path then
    local offset = _quarto.projectOffset()
    imageFilename = pandoc.path.join({offset, imageFilename})
  end
end

The Common Detection Pattern

Both fixes use the same heuristic to detect extension-resolved paths:

path.includes("_extensions") || path.startsWith("..")

This works because:

• Extension paths always contain _extensions in the path
• Extension paths from documents in subdirectories start with .. (parent directory traversal)
• Brand paths never match either pattern (they're things like _brand/images/logo.png or brand/logo.svg)

Git History

Commit	Date	Description
533784522	Aug 28, 2025	"typst brand yaml: resolve logo paths via project directory" - introduced #13917 bug
b586e72c4	Jan 16, 2026	"fix relative font-paths in typst extensions (#13745)" - fixed font-paths with extension detection

Test Cases

Extension logo from subdirectory (Issue #13917)

project/
├── _quarto.yml
├── _extensions/
│   └── myformat/
│       ├── _extension.yml  # contains: logo: icon.svg
│       └── icon.svg
└── sub/
    └── doc.qmd             # uses format: myformat-typst

When rendering sub/doc.qmd:

• Extension resolves logo to ../_extensions/myformat/icon.svg (input-relative) ✓
• Typst template should use this path as-is
• Bug: projectOffset() incorrectly changes it to ../../_extensions/myformat/icon.svg

Brand logo from subdirectory (existing behavior, should continue working)

project/
├── _quarto.yml
├── _brand.yml              # contains: logo: images/logo.png
├── images/
│   └── logo.png
└── sub/
    └── doc.qmd

When rendering sub/doc.qmd:

• Brand resolves logo to images/logo.png (project-relative)
• projectOffset() correctly changes it to ../images/logo.png (input-relative) ✓

Recommendations

1. Merge PR fix: resolve relative font-paths in typst extensions (#13745) #13902 to fix font-paths issue
2. Apply similar fix to typst-brand-yaml.lua for logo paths (issue Resource path resolution broken in Typst format extension #13917)
3. Consider centralizing the extension path detection logic if more cases emerge
4. Add tests for both brand and extension paths from subdirectories

[mcanouil]

My current workaround to avoid the project offset to be prepended:

filters:
  - at: post-render
    path: filters/normalise-extension-paths.lua

--[[
# MIT License
# Copyright (c) 2026 Mickaël Canouil
]]

--- @module normalise-extension-paths
--- @brief Normalises .*_extensions/ to /_extensions/ in logo and orcid-icon paths.
---
--- NOTE: This is a workaround for Quarto's path resolution in Typst output.
--- When rendering from subdirectories, paths to extension assets include
--- relative prefixes (e.g., ../../_extensions/). This filter normalises
--- these paths to use absolute references (/_extensions/) for portability.
--- See: https://github.com/quarto-dev/quarto-cli/issues/13917

local KEYS = { 'logo', 'logo-light', 'logo-dark', 'orcid-icon' }

local function normalise(value)
  local t = pandoc.utils.type(value)
  if t == 'string' then
    return (value:gsub("^.*_extensions/", "/_extensions/"))
  elseif t == 'Inlines' then
    return pandoc.Inlines({ pandoc.Str((pandoc.utils.stringify(value):gsub("^.*_extensions/", "/_extensions/"))) })
  elseif t == 'List' then
    local r = {}
    for i, v in ipairs(value) do r[i] = normalise(v) end
    return r
  elseif t == 'table' or t == 'MetaMap' then
    local r = {}
    for k, v in pairs(value) do r[k] = normalise(v) end
    return r
  end
  return value
end

local function get(tbl, path)
  local cur = tbl
  for p in path:gmatch("[^.]+") do
    local t = pandoc.utils.type(cur)
    if t ~= 'table' and t ~= 'MetaMap' and t ~= 'Meta' then return nil end
    cur = cur[p]
  end
  return cur
end

local function Meta(meta)
  if not quarto.doc.is_format('typst') then return meta end

  -- Normalise top-level keys
  for _, k in ipairs(KEYS) do
    if meta[k] then meta[k] = normalise(meta[k]) end
  end

  -- Set logo.path from appropriate variant based on brand-mode
  local mode = meta['brand-mode'] and pandoc.utils.stringify(meta['brand-mode']) or 'light'
  local src = get(meta, 'logo-' .. mode .. '.path')
  if src and meta['logo'] then
    meta['logo']['path'] = normalise(src)
  end

  return meta
end

return { { Meta = Meta } }