Overture docs update by MitchellShiell · Pull Request #448 · overture-stack/lectern

MitchellShiell · 2026-07-30T13:53:45Z

Documentation for the Overture docs site. No source code changes; the only non-docs/ change is adding .DS_Store to .gitignore.

docs/04-lecternViewer.md becomes a three-page section, docs/04-viewer/, written against packages/ui as it stands on main.

File	Sidebar label	URL
`docs/04-viewer/index.md`	Overview	`/develop/Lectern/viewer/`
`docs/04-viewer/01-setup.md`	Viewer Setup	`/develop/Lectern/viewer/setup`
`docs/04-viewer/02-reference.md`	Viewer Reference	`/develop/Lectern/viewer/reference`

Other changes

docs/01-overview.md: Lyric links repointed; repository tree corrected (common removed, ui added); components table de-indented so it renders, and the Dictionary/Validation npm badges and paths fixed, both having pointed at the client package.
docs/02-Setup.md: documents the optional MONGO_URL, which takes precedence over MONGO_HOST/MONGO_PORT/MONGO_DB.
READMEs: links into the deleted develop branch repointed at main, and docs/important-concepts.md#testresult repointed at pendingDocs/glossary.md#testresult.
"Need Help?" blocks repointed to /community/support; docs/assets/submission-system.svg updated.

Rebased onto `main`

Current with main, no conflicts. 43 commits absorbed, with one conflict in README.md where both sides had repointed the same stale link; this branch's /develop/Lectern/overview was kept over main's older docs/core-software/ scheme. main's reformat of docs/03-dictionaryReference.md and its displayName additions are untouched. The viewer pages were re-checked against the rebased packages/ui: entry points, DictionaryTableProps, CustomColumnConfig and MetaValueRenderer all match.

Known issues, not fixed here

Screenshots predate #416: Table View Styling Updates. Recapturable from Storybook, but not needed for this pass.
packages/ui/src/index.ts aliases SchemaTable and Toolbar to the same default export as DictionaryTable, so all three resolve to DictionaryViewerPage. Also in the published 1.0.0 types. The Reference page routes readers to the /dictionary-table subpath instead, and notes the caveat.
Columns/DataType.tsx renders Array in place of the value type, so array-of-string and array-of-integer look identical.
packages/ui/README.md and packages/ui/docs/README.md still advertise the removed LecternThemeProvider/LecternTheme names.

Broken code fence fixed

docs/03-dictionaryReference.md had an unclosed four-backtick fence in the "Display Name Example" block, which arrived with the displayName work on main. It swallowed the ## Field Restrictions heading and everything after it into a code block, so the #field-restrictions anchor stopped existing and the Docusaurus build failed on two broken anchors: the field-properties table on this page, and the docs site's /use/administration/building-dictionaries page.

Originally flagged here as out of scope, then fixed once it broke the site build, since this branch already owns the file.

CI

The Jenkins failure is unrelated to this branch, which changes no build inputs. The shared pipeline runs npx --yes pnpm install, which resolves to pnpm 11, requiring Node >= 22.13; the agent runs Node 18.16.1. main fails identically.

…diagram Lyric has graduated from under-development to core software, so the two Overview cross-links now point at …/build/core-software/Lyric/overview instead of the old …/docs/under-development/lyric/ path. Also commits the in-flight submission-system.svg diagram update (light/dark styling).

Bring the Lectern Viewer (@overture-stack/lectern-ui) into the Lectern component docs as 04-lecternViewer.md, moved out of the docs site's under-development section. Content pulled from packages/ui (README + docs): the DictionaryTableView and DictionaryEntityRelationshipView components, Storybook quick start, and theming, with the full contributor walkthrough cross-linked to packages/ui/docs rather than duplicated. Screenshots added under docs/assets/.

Lectern has no `develop` branch any more — only `main` — so every `blob/develop/...` link 404s. Retarget them at `main`; LICENSE, apps/server/README.md and generated/DictionaryMetaSchema.json all still exist at those paths. `docs/important-concepts.md` also no longer exists: #299 moved it to pendingDocs/glossary.md, which still carries the four anchors the validation README deep-links to (#dictionary, #schema, #testresult, Also repoints the README's site links, which had gone stale the same way as every other component README.

The block opened with four backticks and was never closed, so the ## Field Restrictions heading and all its prose rendered inside a code block, and the #field-restrictions anchor stopped existing. Docusaurus reported it as two broken anchors: the field-properties table on this page links to #field-restrictions, and the site's /use/administration/building-dictionaries page links to /develop/Lectern/dictionaryReference#field-restrictions. Arrived on main with the displayName work; fixed here because this branch already owns this file and the docs site build is failing on it.

joneubank · 2026-08-04T19:29:31Z

+
+- **React 19.** The package declares `react` and `react-dom` `^19.1.0`.
+- **A dictionary source.** Either a running [Lectern server](../02-Setup.md), a dictionary JSON file served over HTTP, or dictionary objects already in your application.
+- **Emotion.** Components style themselves with `@emotion/react`, which ships as a dependency. Applications using a different CSS-in-JS library can still mount the components, but theming goes through Emotion.


This is not a prerequisite, its just a dependency that the developer is going to have to work with. Not sure it should be here or in a later section on "theming"

Moved into the theming section.

joneubank · 2026-08-04T19:35:21Z

+## Run Storybook
+
+The library is developed with [Storybook](https://storybook.js.org/), which renders each component in isolation. It is the fastest way to explore the components before wiring them into an application — every component has stories covering its states, including loading, error, and empty-dictionary cases.
+
+1. Clone the [Lectern repository](https://github.com/overture-stack/lectern) and install dependencies from the repository root:
+
+   ```sh
+   pnpm install
+   ```
+
+2. Start Storybook:
+
+   ```sh
+   pnpm --filter @overture-stack/lectern-ui storybook
+   ```
+
+Storybook runs on port `6006` by default: [http://localhost:6006/](http://localhost:6006/).
+
+Stories render under a `themeDecorator`, and a theme selector in the Storybook toolbar applies an alternate theme to every story that uses it — useful for checking that a component reads the theme rather than hard-coding values.
+
+![Storybook theme selector in the toolbar](../assets/global-theme-selector.png)
+
+For the full walkthrough — adding themes to the selector, wiring the decorator, and editing stories — see the [Lectern UI developer docs](https://github.com/overture-stack/lectern/blob/main/packages/ui/docs/README.md) in the repository.


Place the storybook section after the intro or install sections since it is the reference documentation?

We should consider running the storybook on a publicly hosted URL so that devs can see whats available before going through the install.

Moved to just after the intro. Hosted Storybook will likely be needed, its relevant and can be linked into the dictionary viewer paper i am currently writing too

joneubank · 2026-08-04T19:37:53Z

Impressive documentation. IMO its the storybook that is responsible for documenting the components available but its nice having this reference as well. As per usual, my concern is that it will be a challenge to maintain both to same standard and that leads to reduced trust in the library.

agreed maybe once we have the storybook hosted and linked then we can revisit these docs and how much of it we want to keep/maintain

joneubank · 2026-08-04T19:39:13Z

+
+## Hooks
+
+Both hooks throw when called outside their provider.


This should be like an Important! callout. It should probably live, in duplicate, in each of the hook sections and not here.

Done. One callout per hook section, each naming its own provider.

joneubank · 2026-08-04T19:39:53Z

+## Theming
+
+| Export | Type | Description |
+| --- | --- | --- |
+| `ThemeProvider` | Component | Supplies a theme. Takes an optional `theme` prop, deep-merged into the active theme, so partial overrides are valid. |
+| `defaultTheme` | `Theme` | The theme used when no provider is present. |
+| `useThemeContext` | `(overrides?: PartialTheme) => Theme` | Reads the active theme, optionally merging per-call overrides. |
+| `Theme` | Type | The full theme: `colors`, `typography`, `dimensions`, `shadow`, and `icons`. |
+| `PartialTheme` | Type | A recursively partial `Theme`, for passing to `ThemeProvider`. |


Do we document what are the properties available in the theme and what htey control? don't NEED to add that to this PR, its a very lofty goal, but would be sweet.

Added a table with the five theme groups, what each controls, w/ link to source

Co-authored-by: Jon Eubank <joneubank@gmail.com>

MitchellShiell mentioned this pull request Jul 30, 2026

Overture docs V2 update overture-stack/docs#48

Open

5 tasks

MitchellShiell added 7 commits July 30, 2026 13:44

remove .DS_Store

7fe2167

usage > reference

133c10b

docs update

c5ab8ec

lectern viewer update

36fa352

MitchellShiell force-pushed the overtureDocsUpdate branch from 484c097 to 66a2331 Compare July 30, 2026 17:45

MitchellShiell requested a review from joneubank July 30, 2026 17:54

MitchellShiell added 2 commits July 30, 2026 14:17

docs: use full docs.overture.bio URLs for cross-repo links

9d60fd0

joneubank requested changes Aug 4, 2026

View reviewed changes

MitchellShiell and others added 6 commits August 4, 2026 17:02

update viewer docs with images used for publication

938a0cd

clean up old images

f8af3a0

removed quickstart references from readme

5e638da

[Contributing Guide](./CONTRIBUTING.md)

3f220d9

Update docs/01-overview.md

d4f6eb2

Co-authored-by: Jon Eubank <joneubank@gmail.com>

docs: address viewer docs review feedback

5355c8c

MitchellShiell requested a review from joneubank August 5, 2026 18:34

joneubank previously approved these changes Aug 5, 2026

View reviewed changes

Comment thread docs/04-viewer/02-reference.md Outdated

Update docs/04-viewer/02-reference.md

ecaa24d

Co-authored-by: Jon Eubank <joneubank@gmail.com>

MitchellShiell dismissed joneubank’s stale review via ecaa24d August 5, 2026 20:16

Navigation Menu

Uh oh!

Overture docs update - #448

Overture docs update#448
MitchellShiell wants to merge 16 commits into
mainfrom
overtureDocsUpdate

MitchellShiell commented Jul 30, 2026 •

edited

Loading

Uh oh!

joneubank Aug 4, 2026

Uh oh!

MitchellShiell Aug 5, 2026

Uh oh!

joneubank Aug 4, 2026

Uh oh!

MitchellShiell Aug 5, 2026 •

edited

Loading

Uh oh!

joneubank Aug 4, 2026

Uh oh!

MitchellShiell Aug 5, 2026

Uh oh!

joneubank Aug 4, 2026

Uh oh!

MitchellShiell Aug 5, 2026

Uh oh!

joneubank Aug 4, 2026

Uh oh!

MitchellShiell Aug 5, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants


		## Hooks

		Both hooks throw when called outside their provider.

Uh oh!

Conversation

MitchellShiell commented Jul 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Other changes

Rebased onto main

Known issues, not fixed here

Broken code fence fixed

CI

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MitchellShiell Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

MitchellShiell commented Jul 30, 2026 •

edited

Loading

Rebased onto `main`

MitchellShiell Aug 5, 2026 •

edited

Loading