Knowledge Media Flow

Knowledge Media Flow

This guide defines how screenshots, diagrams, poster images, and externally hosted video captures move from fast authoring mode into the canonical knowledge base without breaking the Static Site Generator (SSG) or bloating the repo.

Goals

• One rule-based drop zone for every capture so you can stay in flow.
• Zero duplication between /md (Markdown) and /www (HTML) trees for repo-managed assets.
• Deterministic paths so SSG → HTML keeps poster/image URLs and public video URLs untouched.
• Copy-friendly structure for S3 + CloudFront deploys without committing large video binaries.

Directory Layout

knowledge/
  public/
    md/                 # Markdown truth source
    assets/
      inbox/            # raw capture drops
      library/
        img/            # curated PNG/JPG/SVG poster and UI assets
        js/             # repo-managed page scripts
        vendor/         # third-party frontend assets
    www/                # generated HTML (prod)
    draft/www/          # generated HTML (preview)

Only the library is referenced by Markdown for repo-managed assets. Inbox folders are temporary holding pens. Canonical MP4/WebM files are uploaded outside git to their public object keys under https://www.idialogue.app/assets/video/....

Authoring Workflow

1. Capture fast

   • Save screenshots or local video working files directly into knowledge/public/assets/inbox/<date>-<slug>/.
   • Use any naming while capturing; the inbox never ships.
   • Common video formats are git-ignored, so local MP4/WebM working copies can live here without entering the repo.

2. Curate repo-managed assets

   • Move polished posters, screenshots, and diagrams into the library and mirror the Markdown route:
     • Markdown: knowledge/public/md/support/cases/escalation.md
     • Asset folder: knowledge/public/assets/library/img/support/cases/escalation/
   • Keep filenames lowercase, hyphen-separated, and sequential when order matters (step-01.png).
   • Trim, blur, or crop before moving so the library always represents the final poster/image artifact.

3. Publish canonical videos outside git

   • Upload the final MP4/WebM directly to the website bucket/object key instead of committing it under knowledge/public/assets/library.
   • Prefer route-mirrored public keys:
     • Markdown: knowledge/public/md/product/ai-memory.md
     • Video URL: https://www.idialogue.app/assets/video/product/ai-memory/ai-memory-overview.mp4
     • Poster image: knowledge/public/assets/library/img/product/ai-memory/ai-memory-overview-poster.jpg
   • Avoid a flat /assets/video/ namespace unless the asset is explicitly short-lived. Route-mirrored keys make retention, cleanup, and ownership easier.

4. Reference from Markdown

   • Use root-relative links for repo-managed assets so the SSG emits the same URLs:
     • ![Escalation Settings](/assets/img/support/cases/escalation/step-01.png)
   • Use a full public URL for canonical videos:
     • <video controls src="https://www.idialogue.app/assets/video/support/cases/escalation/demo.mp4"></video>
   • For front-matter-driven embeds:
     • videoSrc: "https://www.idialogue.app/assets/video/product/ai-memory/ai-memory-overview.mp4"
     • videoPoster: "/assets/img/product/ai-memory/ai-memory-overview-poster.jpg"
   • Always include alt text or captions for accessibility.

5. Sync repo-managed assets into /www

   • Run ./scripts/knowledge_media_sync.sh after adding or updating posters, images, scripts, or vendor assets.
   • The script mirrors assets/library → public/www/assets via rsync.
   • Video binaries are intentionally excluded from this sync, and stale /www/assets/video/... copies are deleted so the deploy tree does not package canonical videos by accident.

6. Generate HTML + Deploy

   • Execute the usual SSG build (Markdown → HTML). Root-relative /assets/img/... URLs stay intact and absolute videoSrc URLs remain unchanged.
   • If a page bypasses the SSG (for example, CMS-provided HTML), check it directly into /knowledge/public/www and point it at the same poster/image paths plus the canonical public video URL.
   • Deploy the knowledge/public/www tree to the public bucket.
   • Upload canonical videos as a separate prerequisite; this repo does not include a video-upload script.
   • Invalidate CloudFront so cached pages pick up the new HTML + shared assets.

Naming & Organization Rules

• Group posters and images by audience or feature (support/, kb/, platform/) to keep diffs scoped.
• Prefer PNG for UI, SVG for diagrams, and root-relative /assets/img/... references for repo-managed visuals.
• Prefer route-mirrored public video keys such as /assets/video/product/ai-memory/ai-memory-overview.mp4 over flat /assets/video/demo.mp4.
• Keep large final videos out of git. Use the public bucket as the source of truth for canonical MP4/WebM files.
• Remove sensitive data before capturing; inbox folders should be cleaned once the curated poster/image assets exist.
• Never place deployable media beside Markdown files. Use /assets/img/... for repo-managed visuals and https://www.idialogue.app/assets/video/... for canonical videos.

Translating to HTML

• Because posters and images use root-relative /assets/... URLs, the SSG writes the same value into <img src> attributes.
• Because canonical videos use absolute public URLs, dlog build --html preserves those values verbatim in data-video-src, <source src>, or raw <video src> output.
• During deployment the /assets subtree inside /knowledge/public/www contains repo-managed posters/images/scripts only. Canonical videos must already exist at their public object keys.
• Any future SSG theme or template only needs to ensure the <base href> remains / so root-relative poster/image links resolve correctly.
• When you add CMS-ready or bespoke HTML directly under /knowledge/public/www, treat it as authoritative, keep the /assets/... poster/image references intact, and use the same canonical public video URL strategy.

Checklist Before Pushing

• Inbox folder is empty or cleaned for the feature you touched.
• All new posters and images live under knowledge/public/assets/library/....
• Canonical videos have been uploaded to their final public https://www.idialogue.app/assets/video/... object keys.
• Markdown references /assets/... for repo-managed assets and a full public URL for videoSrc.
• ./scripts/knowledge_media_sync.sh has been run (rerun if unsure).
• mvn test (or the relevant SSG command) succeeds and HTML renders the expected posters/images while preserving the external video URLs.
• S3 sync + CloudFront invalidation steps are documented in the PR when deploying public docs.