Skip to content

Workspace configuration

Hard build config lives in vyasac.toml. Language (aliases, entities, extra commands) lives in context.vy. `annotate, `note, and `frame are in the standard library. Shared catalog metadata lives in publisher.toml. Unknown keys in vyasac.toml tables that use deny_unknown_fields are pack/load errors.

Walkthrough: Packing and publishing. Stream identity: Streams and the URN spine. Edition, extent holes, and `note kinds: Edition identity and gaps.

FieldRole
idStable publication id (pack filename, catalog id). Prefer this over name for files.
nameWorkspace name; filename fallback if id is omitted. Required (no empty default).
titlePublication title. Required for view / vyir pack (HTML <title> and manifest.edition.title). No "Untitled" fallback.
descriptionRequired for view / vyir pack (edition.description).
versionOptional
authorsOptional list
FieldRole
schemeURN template, e.g. urn:vyasa:bg:{chapter}:{verse}
publisher / corpusUsed when scheme / prefix are omitted
prefixAlternate scheme builder with hierarchy
hierarchyRelative-path levels (["chapter", "verse"])
extentOptional declared id ranges for non-leaf levels; missing members become absent :0 containers. See Edition identity and gaps.
path_schemaOptional
bit_layoutOptional bit widths for packed sequence ids

[urn.extent] values are mixed: a top-level start..end on the first hierarchy name, or a parent-keyed table on the second hierarchy name only. A leaf name as a key is a pack error. Inclusive integers, span < 10000. A packed file outside the extent is a pack error. Omit extent for no synthetic holes.

Legacy: top-level urn_scheme string still works if [urn] is absent.

Each immediate folder under content/ is one stream. Packed id is the folder name. There is no [streams] table in vyasac.toml (that key is a load error).

FieldRequiredRole
languageyesBCP 47 shape (sa, en, sa-Latn). Syntax-checked only; not a language registry.
scriptyesOpaque writing-system token. Prefer ISO 15924 (Deva, Latn, Mlym); IAST / ISO15919 for Sanskrit romanization.
kindyesOpaque layer token. Recommended: source, commentary, translation. Value primary is a pack error (collides with the URN-spine alias).
primarynotrue on exactly one stream: the URN spine. Default false.
segment_separatornoInserted between SegmentBreak splits when weaving this stream

Do not set kind = "primary" to mark the spine. Nested content/transliteration/iast packs as stream transliteration. Annotations and vocabulary are not content streams.

content/mula/stream.toml
language = "sa"
script = "Deva"
kind = "source"
primary = true

Profile name default is what vyasac pack uses unless --profile is set. target defaults to view.

FieldRole
streamsOptional packed-name allow-list. Omit unless excluding folders. Do not list the alias primary unless the folder is named primary. Unknown ids fail pack.
targetview (default), zip, sqlite, vyir
layoutStructural layout (sequence, …)
publicationOptional publication label
enable_markdownOptional
cssCSS files relative to the workspace root. Missing file → pack error. No ...
publisher_cssCSS files relative to [publish] publisher_dir. Packed before css. Requires publisher_dir.
content_themesOptional override of publisher theme slugs. Non-empty; each slug must exist as html.theme-{slug} in packed CSS.
FieldRole
publisher_dirDirectory containing publisher.toml (and shared CSS for publisher_css)
FieldRole
typeCopied to catalog.json (e.g. work)
languageCopied to catalog.json
licenseRequired for view / vyir pack (edition.license). Also copied to catalog.json.
sourceRequired for view / vyir (edition.source) — where this impression came from
source_rootRequired for view / vyir (edition.source_root) — work title or path at the source
snapshotRequired for view / vyir (edition.snapshot). Must be YYYY-MM-DD.

zip / sqlite targets do not require these edition fields. Catalog id, title, vyviewUrl, and updated are always written on publish; see Packing and publishing. Why edition lives on the pack: Edition identity and gaps.

Named table of other packed works to merge at pack time:

[dependencies.bg]
package = "vedabase-bg"

package is the sibling directory name. vyasac ATTACHes that .vyview and copies streams as dependency.<key>.<stream> plus their HTML blocks. It does not replace this work’s spine content or merge graphs. Details: Dependencies and localization.

Resolved from [publish] publisher_dir/publisher.toml, or publisher.toml in the workspace root if that file exists.

[publisher]
identifier = "vysamples"
title = "Vyasa Samples"
description = "…"
homepage = "https://…"
content_themes = ["light", "dark"] # required for view pack; [0] = default
[org]
id = "vysamples"
title = "Vyasa Samples"
homepage = "https://…"
FieldRole
[publisher] identifierCatalog / publisher id used by vyasac publish
[publisher] content_themesAdvertised paper/ink slugs inherited by every work
[org]Optional org block copied into catalog.json

content_themes slugs must match [a-z0-9]+(?:-[a-z0-9]+)* and appear in concatenated CSS as html.theme-{slug} (comments do not count). An empty array is a pack error. If both publisher and [build.*] content_themes are omitted, pack fails until a list is declared.

Written by vyasac pack for the viewer; inspect with vyasav inspect --table manifest.

KeyMeaning
primary_streamPacked spine id (folder), not the word primary unless that is the folder
content_themesJSON array of theme slugs
css_files / publisher_css_filesSheets that were packed
streams_configPacked-name stream allow-list (when [build.*] streams is set)
streams_metaJSON object keyed by packed name: { language, script, kind }
stream_separatorsPer packed-name segment separators
editionJSON object on view / vyir packs: title, description, license, source, source_root, snapshot
work_notesJSON array of { kind, content, detail?, href? } from `note { scope="work" } (omitted if empty)