Skip to content

feat(opf): ship examples, docs, and upstream README in the npm package#3

Merged
michaeljgrimm merged 1 commit into
mainfrom
feat/package-examples-docs-readme
May 21, 2026
Merged

feat(opf): ship examples, docs, and upstream README in the npm package#3
michaeljgrimm merged 1 commit into
mainfrom
feat/package-examples-docs-readme

Conversation

@michaeljgrimm

Copy link
Copy Markdown
Contributor

Adds three new subpath exports for downstream sites that currently have to clone OpenPresentation/opf or hit GitHub at request time to read content the package doesnt yet ship.

  • @openpresentation/opf/examples bundles every .opf.json under examples/ at build time, exposes them as ExampleRecord[] + GalleryRecord[] (with the parsed Presentation deck), plus convenience lookups: getExample, getGallery, getExamplesByGallery, getExamplesByCategory. Each deck is validated against the presentation schema during smoke tests.
  • @openpresentation/opf/docs bundles the top-level docs/*.md reference pages (schema-reference, catalog-schema-reference, content-payloads, content-item-design-overrides, examples) and exposes them as DocRecord[] with getDoc. The BACKLOG and docs/migrations/, docs/plans/ subdirectories are intentionally excluded because they change too quickly to pin inside a release.
  • @openpresentation/opf/repo-readme exposes the upstream README.md as a raw markdown string so consumer sites can mirror the canonical README without a network fetch.

Implementation:

  • New scripts/generate-content.mjs walks examples/, docs/, and README.md at build time and emits src/generated/{examples,docs,repo-readme}.ts; wired into the generate / build pipeline alongside the existing schema, catalog, spec-files, and previews generators.
  • New facade modules src/examples.ts, src/docs.ts, src/repo-readme.ts re-export the generated data with the public type surface.
  • tsup config gains three entries; package.json gets three new exports.
  • Smoke test asserts every shipped deck validates, that gallery indexing is consistent, that docs metadata is non-empty, and that the repo README is present and non-trivial.
  • README and CHANGELOG document the new entry points.

Pack stays at one tarball; size grows from ~1 MB to ~1.7 MB (unpacked 13.5 MB) which is acceptable for the convenience of removing the GitHub source sync from downstream consumers.

Adds three new subpath exports for downstream sites that currently have to
clone OpenPresentation/opf or hit GitHub at request time to read content the
package doesnt yet ship.

- @openpresentation/opf/examples bundles every .opf.json under examples/ at
  build time, exposes them as ExampleRecord[] + GalleryRecord[] (with the
  parsed Presentation deck), plus convenience lookups: getExample,
  getGallery, getExamplesByGallery, getExamplesByCategory. Each deck is
  validated against the presentation schema during smoke tests.
- @openpresentation/opf/docs bundles the top-level docs/*.md reference pages
  (schema-reference, catalog-schema-reference, content-payloads,
  content-item-design-overrides, examples) and exposes them as DocRecord[]
  with getDoc. The BACKLOG and docs/migrations/, docs/plans/ subdirectories
  are intentionally excluded because they change too quickly to pin inside a
  release.
- @openpresentation/opf/repo-readme exposes the upstream README.md as a raw
  markdown string so consumer sites can mirror the canonical README without
  a network fetch.

Implementation:

- New scripts/generate-content.mjs walks examples/, docs/, and README.md at
  build time and emits src/generated/{examples,docs,repo-readme}.ts; wired
  into the generate / build pipeline alongside the existing schema, catalog,
  spec-files, and previews generators.
- New facade modules src/examples.ts, src/docs.ts, src/repo-readme.ts
  re-export the generated data with the public type surface.
- tsup config gains three entries; package.json gets three new exports.
- Smoke test asserts every shipped deck validates, that gallery indexing is
  consistent, that docs metadata is non-empty, and that the repo README is
  present and non-trivial.
- README and CHANGELOG document the new entry points.

Pack stays at one tarball; size grows from ~1 MB to ~1.7 MB (unpacked
13.5 MB) which is acceptable for the convenience of removing the GitHub
source sync from downstream consumers.
@michaeljgrimm michaeljgrimm merged commit 868899c into main May 21, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant