Skip to main content

Workflow

WORKFLOWS.md — OnCue Support Site (Current State)

This document describes “who does what” and which tools to use for common tasks.

1. Choose your workflow​

A) Developer workflow (most accurate)​

Use when:

  • you are adding new features, blocks, styles, or fixing rendering issues

Steps:

  1. Edit MDX directly in site/docs/...
  2. Run npm run site:dev
  3. Validate output in the real MDX runtime
  4. Commit

B) Author/editor workflow (Decap CMS)​

Use when:

  • you want a form-based UI and structured collections

Steps:

  1. Run npm run site:dev
  2. Go to /admin
  3. Edit/create content
  4. Use Preview for approximate rendering
  5. Save changes (writes MDX into site/docs/...)

Notes:

  • The editor may show MDX components as text; the Preview renders them via a custom renderer.

C) Page-building workflow (Streamlit)​

Use when:

  • you want a guided way to assemble pages with common block patterns

Steps:

  1. Run streamlit run src/support_page_builder.py
  2. Build page content
  3. Copy generated MDX into site/docs/...
  4. Validate with npm run site:dev
  5. Commit

2. Where different types of changes live​

Content changes (new pages, text edits)​

  • site/docs/.../*.mdx

Images/media​

  • stored in: site/static/img
  • referenced as: /img/...

Sidebar/navigation structure​

  • site/sidebars.js

Site-wide styling​

  • Docusaurus custom CSS: site/src/css/custom.css
  • Blocks shared CSS: site/static/shared/oncue-blocks.css

Blocks (layout components)​

  • Runtime React blocks: site/src/components/blocks/index.tsx
  • MDX registration (generated): site/src/theme/MDXComponents.js
  • Preview registry + renderers:
  • site/static/shared/blocks-config.generated.js (generated)
  • site/static/shared/blocks-renderers.js (hand-written)
  • site/static/shared/blocks-config.js (glue)
  • site/static/admin/preview-templates.js (parser/renderer)

3. Validation checklist before committing​

For content-only changes:

  • npm run site:dev shows correct rendering
  • Images load from /img/...
  • Sidebar placement is acceptable (autogenerated behavior)

For block/styling changes:

  • Docusaurus runtime rendering is correct
  • Decap Preview still renders blocks correctly (/admin)
  • Streamlit preview (if used) still visually matches expectations
  • Tables in TwoCol layouts render correctly (no broken widths)