Online help pipeline

The editor shows help for every field at four levels. This page explains where the texts come from, how they reach the editor and how the editor picks the text for a field. For how to write help texts, see Help texts.

The four levels

Level	Key	Where it shows	Content
1	tooltip	On hover or focus of the (?) icon	One line
2	short	Under the field	What to fill in
3	extended	Help panel (right)	Why the field matters, how to fill it in well
4	details	Help panel, under More: examples and details (closed by default)	Examples (good and to avoid), notes, links, export mappings, plus field rules derived from the schema

Where the texts live

schemas repo
  help/help.schema.json          format of a help file (the contract)
  help/docs.<profile>.json       hand-maintained help, one file per profile, keyed by x-sidedoc id
  GenJSONSchema/postprocess_docs_schema.py
                                 keeps help/ in step with the schema (adds new ids, refreshes
                                 label/path), adds generated details.mapping, writes output/
  scripts/lint_help.py           validates help files, warns on duplicate or missing texts
        |
        |  build.sh -> output/docs.<profile>.json -> published at sidedoc.app/schemas/<version>/
        v
monorepo
  app/sidedoc-frontend/public/schemas/<version>/docs.<profile>.json   committed copy the app serves

The Google Sheet defines the schema structure only. It does not hold help texts.

Each field entry is keyed by the field's x-sidedoc.id (for example ds:f00100). label and path are copied from the schema by the build; do not edit them by hand.

Loading

app/sidedoc-frontend/src/components/editor/help/helpPayload.js loads and merges help files. loadHelpPayload(schemaNode, { mode }) starts from help embedded in the schema (x-sidedoc-help, set by the backend's loadProfileFromSchemaUrls, which also marks synthesized entries with isFallback: true) and merges the candidate files in order, later files winning per language:

Mode	Used by	Files
full	help panel (EditorPanel.vue via useFieldHelp)	docs.type-library.json, help files of $ref'd schemas, legacy help-texts.json and example-data.json, then the profile's own file
profile	inline short help (WorkspaceEditorView.vue, getFieldHelpShort)	the profile's own file, docs.type-library.json, help-texts.json
own	backend demo (BackendDemo.vue)	the profile's own file

The profile's own file is x-sidedoc.docsSchemaUrl (or helpTextsUrl) on the schema root, else docs.<schema file name> next to the schema.

details merges per part: notes per language, examples, links and mappings as a whole list.

Resolving a field

useFieldHelp(props, editorCtx) (help/useFieldHelp.js) maps the focused element's DOM id (pathToFieldId) to a field in the schema, then looks up its entry by schema path, x-sidedoc id, key name and label, in that order. It takes the first entry with real text. When nothing matches, it uses a curated text for common keys (HELP_FALLBACK_BY_KEY) or a generic one derived from the schema shape, and flags the result isFallback; the panel then says No documentation available for this field.

resolveHelpDetailsForFieldId returns level 4:

• authored: the entry's details, localised (helpDetails.js, resolveAuthoredDetails). Examples with a lang only show in that editor language.
• facts: field rules derived from the schema (deriveSchemaFacts): required or optional, repeatable, multilingual, format (uiHint), validation pattern in words (known patterns are listed in KNOWN_PATTERNS; others are shown verbatim), identifier types (allowedSchemas), and the vocabulary binding from editorCtx.getVocabularyBindingForPath. Scheme labels are fetched from the vocabulary service when the panel opens.

FieldHelpDetails.vue renders level 4 as a native <details>/<summary> disclosure, so it works with keyboard and screen readers without extra ARIA. The open state is kept while the user moves between fields. It links to the field's entry in the generated profile reference on this site.

Adding a new help level or key

1. Add it to help/help.schema.json in the schemas repo and to the lint script.
2. Pass it through mergeHelpEntry in helpPayload.js (unknown keys survive merges only if listed there).
3. Resolve and render it in useFieldHelp.js / FieldHelpDetails.vue.
4. Add it to the profile reference generator (scripts/gen_profile_docs.py) so the docs show it too.
5. Extend src/components/editor/help/__tests__/help.test.ts.

Known limitations

• The lookup by name and label (with fuzzy matching) exists for old help files that had no ids. With all profiles now keyed by id, it can be removed once every profile's help file is complete.
• The unversioned files in public/schemas/ (docs.datasheet.json, help-texts.json, example-data.json) are legacy. full mode still reads them; the profile's own versioned file is merged last and wins.