Filesystem

Extension Discovery Module

Extension discovery from the filesystem.

Scans the _extensions directory to find installed Quarto extensions.

Interfaces

Variables

Functions

Manifest Parsing Module

Manifest parsing for _extension.yml files.

Provides functions to read, parse, and write Quarto extension manifests.

Interfaces

Variables

Functions

Quarto Ignore Module

Reading and matching .quartoignore patterns.

.quartoignore lists paths a repository keeps out of Quarto’s view, most commonly a documentation website that ships its own _quarto.yml and _extensions/. Tooling that scans a repository for Quarto projects should skip those paths.

Variables

Functions

Directory Walking Module

Directory walking and file collection utilities.

Provides recursive directory traversal and file copying operations.

Interfaces

Type Aliases

Functions

collectFiles

TypeScript
function collectFiles(directory): Promise<string[]>;

Defined in: packages/core/src/filesystem/walk.ts:62

Collect all file paths in a directory recursively.

Parameters

Parameter Type Description
directory string Directory to walk

Returns

Promise<string[]>

Array of file paths

copyDirectory

TypeScript
function copyDirectory(sourceDir, targetDir): Promise<string[]>;

Defined in: packages/core/src/filesystem/walk.ts:99

Copy a directory recursively.

Parameters

Parameter Type Description
sourceDir string Source directory
targetDir string Target directory

Returns

Promise<string[]>

Array of created file paths

discoverInstalledExtensions

TypeScript
function discoverInstalledExtensions(projectDir, options?): Promise<InstalledExtension[]>;

Defined in: packages/core/src/filesystem/discovery.ts:82

Discover all installed extensions in a project.

Scans the _extensions directory for extensions in both formats:

  • _extensions/owner/name/_extension.yml (with owner)
  • _extensions/name/_extension.yml (without owner)

Parameters

Parameter Type Description
projectDir string Project root directory
options DiscoveryOptions Discovery options

Returns

Promise<InstalledExtension[]>

Array of installed extensions

Example

TypeScript
const extensions = await discoverInstalledExtensions("./my-project");
for (const ext of extensions) {
  console.log(`${ext.id.owner ?? ""}/${ext.id.name}: ${ext.manifest.version}`);
}

discoverInstalledExtensionsSync

TypeScript
function discoverInstalledExtensionsSync(projectDir, options?): InstalledExtension[];

Defined in: packages/core/src/filesystem/discovery.ts:99

Synchronous version of discoverInstalledExtensions.

Parameters

Parameter Type Description
projectDir string Project root directory
options DiscoveryOptions Discovery options

Returns

InstalledExtension[]

Array of installed extensions

findInstalledExtension

TypeScript
function findInstalledExtension(projectDir, extensionId): Promise<
  | InstalledExtension
| null>;

Defined in: packages/core/src/filesystem/discovery.ts:203

Find a specific installed extension by ID.

Parameters

Parameter Type Description
projectDir string Project root directory
extensionId ExtensionId Extension ID to find

Returns

Promise< | InstalledExtension | null>

InstalledExtension or null if not found

findManifestFile

TypeScript
function findManifestFile(directory): string | null;

Defined in: packages/core/src/filesystem/manifest.ts:38

Find the manifest file in a directory.

Parameters

Parameter Type Description
directory string Directory to search

Returns

string | null

Path to manifest file or null if not found

getExtensionInstallPath

TypeScript
function getExtensionInstallPath(projectDir, extensionId): string;

Defined in: packages/core/src/filesystem/discovery.ts:239

Get the installation path for an extension.

Parameters

Parameter Type Description
projectDir string Project root directory
extensionId ExtensionId Extension ID

Returns

string

Path where the extension should be installed

getExtensionsDir

TypeScript
function getExtensionsDir(projectDir): string;

Defined in: packages/core/src/filesystem/discovery.ts:48

Get the extensions directory path for a project.

Parameters

Parameter Type Description
projectDir string Project root directory

Returns

string

Path to _extensions directory

hasExtensionsDir

TypeScript
function hasExtensionsDir(projectDir): boolean;

Defined in: packages/core/src/filesystem/discovery.ts:58

Check if an extensions directory exists.

Parameters

Parameter Type Description
projectDir string Project root directory

Returns

boolean

True if _extensions directory exists

hasManifest

TypeScript
function hasManifest(directory): boolean;

Defined in: packages/core/src/filesystem/manifest.ts:135

Check if a directory contains a manifest file.

Parameters

Parameter Type Description
directory string Directory to check

Returns

boolean

True if manifest exists

isInside

TypeScript
function isInside(parent, child): boolean;

Defined in: packages/core/src/filesystem/walk.ts:140

Check whether a path is parent itself or lives below it.

Parameters

Parameter Type Description
parent string Ancestor directory
child string Path to test

Returns

boolean

True when child is parent or is contained by it

isQuartoIgnored

TypeScript
function isQuartoIgnored(patterns, relativePath): boolean;

Defined in: packages/core/src/filesystem/quartoignore.ts:75

Check whether a path is covered by .quartoignore patterns.

Every ancestor of relativePath is tested, so an ignored directory also hides everything below it. Patterns containing no separator are additionally matched against each individual segment, so _site matches at any depth; patterns containing a separator stay anchored to the directory holding the .quartoignore.

Parameters

Parameter Type Description
patterns readonly string[] Normalised patterns from readQuartoIgnore
relativePath string POSIX-separated path relative to the directory holding the ignore file

Returns

boolean

True when the path is ignored

Example

TypeScript
isQuartoIgnored(["docs"], "docs/_extensions/mcanouil/gitlink"); // true

parseManifestContent

TypeScript
function parseManifestContent(content, sourcePath?): ExtensionManifest;

Defined in: packages/core/src/filesystem/manifest.ts:85

Parse manifest content from a YAML string.

Parameters

Parameter Type Description
content string YAML content
sourcePath? string Source path for error messages (optional)

Returns

ExtensionManifest

Parsed manifest

Throws

ManifestError if parsing fails

parseManifestFile

TypeScript
function parseManifestFile(manifestPath): ExtensionManifest;

Defined in: packages/core/src/filesystem/manifest.ts:73

Parse a manifest file from a path.

Parameters

Parameter Type Description
manifestPath string Full path to the manifest file

Returns

ExtensionManifest

Parsed manifest

Throws

ManifestError if parsing fails

pathExists

TypeScript
function pathExists(filePath): Promise<boolean>;

Defined in: packages/core/src/filesystem/walk.ts:83

Async check whether a path exists on disk.

Prefer this over fs.existsSync in async code paths to avoid blocking the event loop.

Parameters

Parameter Type Description
filePath string Path to check

Returns

Promise<boolean>

True if the path exists

quartoIgnoreGlobs

TypeScript
function quartoIgnoreGlobs(patterns): string[];

Defined in: packages/core/src/filesystem/quartoignore.ts:104

Convert .quartoignore patterns into globs matching the ignored paths and their contents.

isQuartoIgnored is a predicate over one path; consumers that hand patterns to a glob matcher need the same semantics expressed as globs instead. Each pattern yields the path itself and everything below it, plus depth-independent variants for unanchored patterns.

Parameters

Parameter Type Description
patterns readonly string[] Normalised patterns from readQuartoIgnore

Returns

string[]

Glob patterns covering the ignored paths and their descendants

Example

TypeScript
quartoIgnoreGlobs(["docs"]); // ["docs", "docs/**", "**/docs", "**/docs/**"]

readManifest

TypeScript
function readManifest(directory):
  | ManifestReadResult
  | null;

Defined in: packages/core/src/filesystem/manifest.ts:112

Read a manifest from a directory.

Parameters

Parameter Type Description
directory string Directory containing the manifest

Returns

| ManifestReadResult | null

ManifestReadResult or null if no manifest found

readQuartoIgnore

TypeScript
function readQuartoIgnore(dir): string[];

Defined in: packages/core/src/filesystem/quartoignore.ts:35

Read and normalise the patterns declared in a directory’s .quartoignore.

Comments (#), blank lines, and surrounding whitespace are stripped, as are leading ./ and / and trailing /, so docs/, /docs and docs are equivalent. Negation (!) is not part of Quarto’s format and such lines are dropped.

Parameters

Parameter Type Description
dir string Directory holding the .quartoignore file

Returns

string[]

Normalised patterns, or an empty array when the file is absent or unreadable

Example

TypeScript
const patterns = readQuartoIgnore("./my-extension");
// [".scratch", "docs"]

toRelativePosixPath

TypeScript
function toRelativePosixPath(basePath, fsPath): string;

Defined in: packages/core/src/filesystem/walk.ts:129

Express fsPath relative to basePath using POSIX separators.

Path comparison and pattern matching both work on forward slashes, so callers on Windows need this normalisation before handing a path to a matcher or to a display label.

Parameters

Parameter Type Description
basePath string Directory the result is relative to
fsPath string Path to express relatively

Returns

string

POSIX-separated relative path, empty when the two paths are equal

updateManifestSource

TypeScript
function updateManifestSource(
   manifestPath,
   source,
   sourceType?): void;

Defined in: packages/core/src/filesystem/manifest.ts:298

Record the source of an installed extension in its manifest.

Patches the source and source-type lines in place instead of re-serialising the document, so comments, key order, quoting style, and any keys the extension author added are preserved. A file without a trailing newline gains one when a key is appended.

Parameters

Parameter Type Description
manifestPath string Path to the manifest file
source string New source value
sourceType? SourceType Type of source (github, url, local, registry)

Returns

void

Throws

ManifestError if the manifest cannot be read or patched

walkDirectory

TypeScript
function walkDirectory(directory, callback): Promise<void>;

Defined in: packages/core/src/filesystem/walk.ts:37

Walk a directory recursively, calling the callback for each entry.

Parameters

Parameter Type Description
directory string Directory to walk
callback WalkCallback Callback for each entry

Returns

Promise<void>

DiscoveryOptions

Defined in: packages/core/src/filesystem/discovery.ts:37

Options for extension discovery.

Properties

Property Type Description Defined in
includeInvalid? boolean Include extensions without valid manifests. packages/core/src/filesystem/discovery.ts:39

InstalledExtension

Defined in: packages/core/src/filesystem/discovery.ts:23

An installed extension discovered on the filesystem.

Properties

Property Type Description Defined in
directory string Full path to the extension directory. packages/core/src/filesystem/discovery.ts:31
id ExtensionId Extension identifier. packages/core/src/filesystem/discovery.ts:25
manifest ExtensionManifest Parsed manifest data. packages/core/src/filesystem/discovery.ts:27
manifestPath string Full path to the manifest file. packages/core/src/filesystem/discovery.ts:29

ManifestReadResult

Defined in: packages/core/src/filesystem/manifest.ts:23

Result of reading a manifest file.

Properties

Property Type Description Defined in
filename string Filename used (e.g., “_extension.yml”). packages/core/src/filesystem/manifest.ts:29
manifest ExtensionManifest Parsed manifest data. packages/core/src/filesystem/manifest.ts:25
manifestPath string Full path to the manifest file. packages/core/src/filesystem/manifest.ts:27

WalkEntry

Defined in: packages/core/src/filesystem/walk.ts:16

Entry information for directory walking.

Properties

Property Type Description Defined in
isDirectory boolean Whether entry is a directory. packages/core/src/filesystem/walk.ts:22
name string Entry name (basename). packages/core/src/filesystem/walk.ts:20
path string Full path to the entry. packages/core/src/filesystem/walk.ts:18

WalkCallback

TypeScript
type WalkCallback = (entry) => boolean | void | Promise<boolean | void>;

Defined in: packages/core/src/filesystem/walk.ts:29

Callback for directory walking. Return false to skip processing children of a directory.

Parameters

Parameter Type
entry WalkEntry

Returns

boolean | void | Promise<boolean | void>

EXTENSIONS_DIR

TypeScript
const EXTENSIONS_DIR: "_extensions" = "_extensions";

Defined in: packages/core/src/filesystem/discovery.ts:18

Name of the extensions directory.

MANIFEST_FILENAMES

TypeScript
const MANIFEST_FILENAMES: readonly ["_extension.yml", "_extension.yaml"];

Defined in: packages/core/src/filesystem/manifest.ts:18

Supported manifest file names.

QUARTOIGNORE_FILENAME

TypeScript
const QUARTOIGNORE_FILENAME: ".quartoignore" = ".quartoignore";

Defined in: packages/core/src/filesystem/quartoignore.ts:17

Name of the ignore file.

Back to top