The Space API provides functions for interacting with pages, documents, and files in the space.
space.collidingBasenames()
Returns every basename carried by more than one file, with the files carrying it.
space.createRevisionSnapshot()
Commits everything outstanding as a revision now, rather than waiting for the automatic commit. False if there was nothing to commit.
space.deleteDocument(name)
Deletes a document from the space.
space.deleteFile(name)
Deletes an arbitrary file from the space.
space.deletePage(name)
Deletes a page from the space.
space.fileExists(name)
Checks whether an arbitrary file exists in the space.
space.getAttachmentMeta(name)
Deprecated: Use space.getDocumentMeta instead.
Deprecated alias for space.getDocumentMeta.
space.getDocumentMeta(name)
Returns metadata for a document.
space.getFileMeta(name)
Returns metadata for an arbitrary space file.
space.getGitConflictVersion(id, generation, side)
Downloads one original side of an unresolved Git conflict.
space.getGitConflicts()
Lists unresolved Git conflicts with saved content versions.
space.getGitSyncStatus()
Reads Git sync status and its last successful check.
space.getPageMeta(name)
Returns metadata for a page.
space.getRevision(path, rev, parent?)
Reads the text of a file as it was at a given revision, or at that revision's parent.
space.getRevisionDiff(path, rev?)
Reads a unified diff of a revision's own change (vs its parent), or of the uncommitted change when no revision is given.
space.getSpaceLog(before?, q?)
Lists the space-wide commit log. Each commit's files — and the uncommitted list — are tables of {path, status}, where status is added, modified, deleted or renamed.
space.getActivity(since?, filesSince?, top?)
Summarizes revision activity. Returns {commits, topFiles, authors}: commits is a list of commit timestamps (unix seconds) since since, topFiles lists the most frequently changed files since filesSince as {path, count}, and authors lists the commit count per author name since filesSince as {name, count}, most active first. All arguments are optional unix times in seconds (and top a count); omitted ones use the server defaults. Fails if revisions are not enabled for the space.
Example:
local activity = space.getActivity(os.time() - 7 * 86400, nil, 5)
for _, f in ipairs(activity.topFiles) do
print(f.path .. ": " .. f.count)
end
space.lint()
space.lint(page)
space.lint(pages)
Lints pages the way the editor does — frontmatter and data block YAML, space-lua syntax, object validation against tag schemas, anchors — and also renders each ${...} directive and Lua code widget, reporting those that fail. Without an argument, lints every page outside Library/ and Repositories/.
Parameters:
pages? — A page name or a list of page names; omit to lint all pages outside Library/ and Repositories/.Returns:
table — A list of {page, line, column, severity, message, source}, ordered by page then position. line and column are 1-based; severity is error, warning, info or hint; source names what reported it: the linter's own name (yaml, lua, objects and anchors for the built-in ones) or else its editor:lint listener, widget (a failing directive or code widget), or page (the page could not be read). hint diagnostics, such as the X-Ray lens, are left out.Examples:
space.lint("Projects/Launch")
for _, d in ipairs(space.lint()) do
print(d.page .. ":" .. d.line .. ": " .. d.message)
end
space.listAttachments()
Deprecated: Use space.listDocuments instead.
Deprecated alias for space.listDocuments.
space.listDocuments()
Lists all non-page documents in the space.
space.listFiles()
Lists every file in the space.
space.listPages()
Lists all pages in the space.
space.listPlugs()
Lists all plug files in the space.
space.listRevisions(path, before?)
Lists the revision history of a file.
space.lookupPaths(paths)
Looks up, for each path, whether it exists exactly and which files share its basename.
space.mergeText(base, local, remote)
Three-way merges local and remote against their common base on the server, without writing anything. Overlapping changes are kept as conflict markers. Returns nil when the texts can't be merged (one already contains conflict markers, or is too large).
Parameters:
base (string) — Common ancestor of both versions.local (string) — Local version.remote (string) — Remote version.Returns:
status ("clean" or "conflicted") and the merged text, or nil when not mergeable.Example:
local merged = space.mergeText("a\nb\n", "A\nb\n", "a\nB\n")
if merged then
print(merged.status, merged.text)
end
space.pageExists(name)
Checks whether a page exists in the space.
space.readAttachment(name)
Deprecated: Use space.readDocument instead.
Deprecated alias for space.readDocument.
space.readDocument(name)
Reads a document as binary data.
space.readFile(name)
Reads an arbitrary space file as binary data.
space.readFileWithMeta(name)
Reads an arbitrary space file together with its metadata.
space.readPage(name)
Reads a page and returns its Markdown text.
space.readPageWithMeta(name)
Reads a page and returns both its Markdown text and metadata.
space.readRef(ref)
Reads the text addressed by a page, header, or position reference.
space.resolveGitConflict(id, generation, contentRevision, action)
Resolves a Git conflict if the merge and saved content still match.
space.syncGitNow()
Requests sync on the existing Git connection.
space.writeDocument(name, data)
Writes binary document data and returns its metadata.
space.writeFile(name, data)
Writes an arbitrary binary file and returns its metadata.
space.writePage(name, text)
Writes Markdown text to a page and returns its metadata.