include

.include path:{String} sandbox:{ContextSandbox = ContextSandbox.SHARE} -> Any

This function has three behaviors:

  • Reads a Quarkdown file and includes its parsed content in the current document, using the specified sandbox strategy to determine what information is shared between the main context and the included file's context.

  • Loads a library into the current context and includes its parsed content in the current document. Loadable libraries are fetched from the library folder (--libs CLI option). sandbox is ignored in this case.

  • Resolves a package reference in the @scope/name:version form (e.g. @atoms/cowsay:1.0.0), installing the package on first use, and includes its entry point. The included file's working directory is the package root. sandbox applies as for files.

The context of the included file is always inherited from the main file, with an updated working directory that matches the included file's location. sandbox defines, instead, what information is shared back to the main file's context, and how. The following modes are listed in ascending order of isolation:

  • share (default): exchanges information bi-directionally. Changes made in the included file's context are reflected in the main file's context, and vice versa, allowing for full sharing of variables, functions and other declarations. This is represented by SharedContext.

  • scope: like share, but the included file's context does not share new declarations (functions and variables) back to the main file's context. This is the behavior used within lambda blocks, such as forEach, and is represented by ScopeContext.

  • subdocument: no information is shared back to the main file's context, only inherited from it. This also applies to the document info (metadata, title, etc.), This is the behavior used for subdocuments, and is represented by SubdocumentContext.

Return

the content of the file as a node if a file is included, or nothing if a library is loaded

Parameters

path

either a path (relative or absolute with extension) to the file to include, the name of a loadable library, or a package reference

sandbox

relationship between the main context and the included file's context

Values

Throws

if the file does not exist or the loaded Quarkdown source cannot be evaluated

if a package reference is malformed, or the package cannot be retrieved or installed

if a package reference is used in an environment without package support

Permissions

project-read
to include files located in the project directory, including installed packages
global-read
to include files located outside the project directory
package-install
to download a referenced package that is not installed yet

Wiki page

including-other-quarkdown-files