Workspace configuration
Workspace configuration
Section titled “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.
vyasac.toml
Section titled “vyasac.toml”[workspace]
Section titled “[workspace]”| Field | Role |
|---|---|
id | Stable publication id (pack filename, catalog id). Prefer this over name for files. |
name | Workspace name; filename fallback if id is omitted. Required (no empty default). |
title | Publication title. Required for view / vyir pack (HTML <title> and manifest.edition.title). No "Untitled" fallback. |
description | Required for view / vyir pack (edition.description). |
version | Optional |
authors | Optional list |
| Field | Role |
|---|---|
scheme | URN template, e.g. urn:vyasa:bg:{chapter}:{verse} |
publisher / corpus | Used when scheme / prefix are omitted |
prefix | Alternate scheme builder with hierarchy |
hierarchy | Relative-path levels (["chapter", "verse"]) |
extent | Optional declared id ranges for non-leaf levels; missing members become absent :0 containers. See Edition identity and gaps. |
path_schema | Optional |
bit_layout | Optional 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.
content/<folder>/stream.toml
Section titled “content/<folder>/stream.toml”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).
| Field | Required | Role |
|---|---|---|
language | yes | BCP 47 shape (sa, en, sa-Latn). Syntax-checked only; not a language registry. |
script | yes | Opaque writing-system token. Prefer ISO 15924 (Deva, Latn, Mlym); IAST / ISO15919 for Sanskrit romanization. |
kind | yes | Opaque layer token. Recommended: source, commentary, translation. Value primary is a pack error (collides with the URN-spine alias). |
primary | no | true on exactly one stream: the URN spine. Default false. |
segment_separator | no | Inserted 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.
language = "sa"script = "Deva"kind = "source"primary = true[build.<profile>]
Section titled “[build.<profile>]”Profile name default is what vyasac pack uses unless --profile is set. target defaults to view.
| Field | Role |
|---|---|
streams | Optional packed-name allow-list. Omit unless excluding folders. Do not list the alias primary unless the folder is named primary. Unknown ids fail pack. |
target | view (default), zip, sqlite, vyir |
layout | Structural layout (sequence, …) |
publication | Optional publication label |
enable_markdown | Optional |
css | CSS files relative to the workspace root. Missing file → pack error. No ... |
publisher_css | CSS files relative to [publish] publisher_dir. Packed before css. Requires publisher_dir. |
content_themes | Optional override of publisher theme slugs. Non-empty; each slug must exist as html.theme-{slug} in packed CSS. |
[publish]
Section titled “[publish]”| Field | Role |
|---|---|
publisher_dir | Directory containing publisher.toml (and shared CSS for publisher_css) |
[catalog]
Section titled “[catalog]”| Field | Role |
|---|---|
type | Copied to catalog.json (e.g. work) |
language | Copied to catalog.json |
license | Required for view / vyir pack (edition.license). Also copied to catalog.json. |
source | Required for view / vyir (edition.source) — where this impression came from |
source_root | Required for view / vyir (edition.source_root) — work title or path at the source |
snapshot | Required 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.
[dependencies]
Section titled “[dependencies]”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.
publisher.toml
Section titled “publisher.toml”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://…"| Field | Role |
|---|---|
[publisher] identifier | Catalog / publisher id used by vyasac publish |
[publisher] content_themes | Advertised 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.
Packed manifest keys (selected)
Section titled “Packed manifest keys (selected)”Written by vyasac pack for the viewer; inspect with vyasav inspect --table manifest.
| Key | Meaning |
|---|---|
primary_stream | Packed spine id (folder), not the word primary unless that is the folder |
content_themes | JSON array of theme slugs |
css_files / publisher_css_files | Sheets that were packed |
streams_config | Packed-name stream allow-list (when [build.*] streams is set) |
streams_meta | JSON object keyed by packed name: { language, script, kind } |
stream_separators | Per packed-name segment separators |
edition | JSON object on view / vyir packs: title, description, license, source, source_root, snapshot |
work_notes | JSON array of { kind, content, detail?, href? } from `note { scope="work" } (omitted if empty) |