Repository navigation
docs(compose): split compose into a group of learn and reference pages - #100
Merged
Merged
Conversation
The page taught the pre-release timeline: per-clip `color`, `blur`, `chromaKey` and `filter` fields, `animateTo` for movement, shapes that placed themselves with their own `position`, `size` and `anchor`, and `output.frameTime` for a still. Ten of the twelve complete examples on it used at least one field that has moved. It now teaches one `effects` list on a clip, a track or the timeline, keyframes with 33 easings on anything that moves, and one `transform` that places every clip including text and shapes. New sections cover timers, subtitles from cues or an .srt file, Lottie animations, masks and LUTs, the `engine` entry, `output.range`, a transparent background, and the free `validate` endpoint. The transition table carries all six kinds, with wipes by shape or by your own greyscale map. Every JSON example was run through the API's own validator: 30 of them, no refusals, no warnings, nothing left in the old shape. That caught three examples I had written wrong, including an engine parameter that takes a number and a transparent background on mp4, which has no alpha.
Both ship with the compose release: a free dry run of a compose submit, and reading one effect's parameters instead of the whole reference.
…reference One page of 970 lines becomes eleven learn pages and thirteen generated reference pages, matching how Creatomate and JSON2Video both organise this: one reference page per asset kind. jobs/compose stays the overview so every existing link to it still works. The reference pages are generated from the schema the API validates with, so a field table cannot drift from what a render accepts. Effect and transition demos play the before and after clips already on the CDN. Both groups are marked expanded, so opening a reference page no longer folds the rest of the section away.
The before and after pair on that page was the engine escape-hatch demo, which renders frei0r.cartoon, captioned as a keyframed scale. That is why the result looked flat and low quality: it was a cartoon filter, not a Ken Burns push. No keyframe demo exists in the showcase set, so the page teaches from the JSON until one is rendered. A wrong clip is worse than no clip. Also removes a lead that repeated the section's own opening line.
These pages are for a quick explanation and a look at the result, not a second reference. Three of them carried no picture at all. Motion gets a real Ken Burns demo, rendered through the compiler a job uses: a still photograph scaled 1 to 1.15 with easeInOutSine, beside the untouched still. Text gets the timer, subtitles and Lottie clips, which were already rendered and sitting unused. Timeline gets a diagram of the music-bed example, because length "end" is the hardest thing on that page to picture from prose.
fonts proves the claim it makes: a display family on the headline, Arabic and Devanagari shaping through the bundled fallbacks with no font file uploaded. output gains the fit comparison, a wide photograph in a phone-shaped box, which is the framing question readers actually get wrong.
A vertical render with the title clipped at the top and the caption jammed at the bottom, beside the same two lines inside the safe area. The last learn page without a picture now has one.
Position, anchor, scale, size, rotate, flip, crop, rounded corners, corner pin, opacity and speed, each one before and after on the same shot. Twelve fields were documented in a table and shown nowhere.
The page was mixing six clips from an older prefix that nothing validates with two from the drift-tested demo set. Every clip on it now comes from the demo set, and all seven kinds join the same two shots so they can be compared.
Stroke, shadow and a box, ordered by how much each changes the look, plus alignment and an entrance. Five fields that were described and never shown.
Kinds, gradient, outline with a real hole, radius, softness, shadow and paths. Thirteen clips from the drift-tested demo set, beside the six composed pattern examples the page already had.
…transition shape The page described a transition field on a clip and showed JSON for it. No such field exists: a transition is a clip placed between the two it joins, and the property is transition rather than kind. Corrected on the page, in the example and in the generated reference.
Every media block on every compose page now comes from the drift-tested demo set. The four transition clips on the overview, four colour clips on effects, one on output and one on text all duplicated demos that now exist, and the shapes lead's row of six became a lower third and a progress bar of their own.
Twenty-five always-visible entries was too many. The twelve learn pages stay open and the thirteen generated reference pages sit behind one line. Mintlify opens a collapsed group when the active page is inside it, so landing on a reference page still shows its siblings.
…nce entry
Two halves of the same nav bug. Clicking the Compose parent did nothing and
selecting a child never held its highlight.
`jobs/compose` is now the group's `root`, so the parent row opens the overview
the way the Captions group does. The structural validator counted only `pages`
entries, so a group with a `root` reported its own landing page as an orphan;
it now counts `root` as a nav entry.
The generated reference entries had labels identical to the learn pages above
them ("Timeline" twice, "audio" twice). Mintlify highlights by label, so one
group with two identical entries reads as a single selection. Each one now says
what it lists. The regen also picks up the reworded `textStyle.animate`
description from the schema.
The rulebook bans "not just X" as an AI rhetorical tell. The sentence reads stronger without it.
a-essawy
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Do not merge until the compose release ships. These pages document the timeline shape on
feat/compose-revampin the monorepo, which is not onmainand not deployed. Merging early would publish docs for an API that is not live.What changed
jobs/compose.mdxwas one page of 970 lines and 44 sections, the largest on the site by a factor of three, and the page a migrating Shotstack customer lands on. It is now a group: an overview, 11 learn pages, and 13 reference pages generated from the schema the API validates with. The docs went from 35 pages to 59.The learn pages teach the shape the next release ships, which the old page did not: one ordered
effectslist on a clip, a track or the timeline; keyframes as their own section with all 33 easings; onetransformthat places every clip including text and shapes; timers, subtitles, Lottie, masks, LUTs,output.range, a transparent background and the freevalidateendpoint; all six transitions.Every feature is shown, not described
93 video clips across the group, 77 of them before-and-after pairs, one for each compose feature. They are rendered locally through the same melt image the render lane runs, uploaded to
cdn.rendobar.com/compose/showcase/, and pinned by a drift test in the monorepo that fails if a demo is edited without a re-render or if a demo request contains anything the render would ignore.The eleven sound demos cannot be judged by eye, so they were verdicted by measurement (
ebur128andastats, before and after) against what each one claims. That caught a compressor that was not compressing at its documented defaults.Verification
validateComposeDocument: no refusals, no warnings, nothing in the old shape. It caught a documentedtransitionfield on an ordinary clip that does not exist.Nav
The Compose group uses
root: "jobs/compose", so clicking the parent opens the overview the way the Captions group does, and each generated reference entry is labelled by what it lists rather than repeating the learn page's label above it.scripts/validate-nav-and-redirects.mjsnow counts a group'srootas a nav entry; it previously reported that page as an orphan.Still owed, separately
Nothing on this page set. The MCP page already carries
validate_composeand theeffectargument onlist_job_types(mcp-server.mdx, in this PR). Notes for bringing the other 34 pages up to this standard are in the monorepo atdocs/plans/docs-revamp-all.md.Merges only once the compose API is live, after
rendobar/rendobar#792.