A written description of a UI interaction takes a paragraph and still loses to ten seconds of footage. That is why every good project README eventually grows a demo video, and every internal wiki collects screen recordings. But developers have specific requirements most video platforms ignore: embeddable links that render in Markdown, files that do not rot when a free tier changes, and workflows that fit a repo.

Here is the developer's guide to hosting demo and documentation video.

What developers actually need

Direct, stable URLs

Markdown renderers on GitHub, GitLab, and most wikis display images and video from raw URLs. The host must serve stable links that do not expire, do not wrap content in landing pages, and ideally do not require session cookies.

Markdown-friendly embedding

GitHub READMEs will render video files added to the repo itself, and link out to platform pages otherwise. The ideal host gives you both options: a clean watch page for humans, and a direct or embeddable asset for docs.

Zero ceremony

Demo videos are created in the middle of debugging, not planned. Upload friction kills the habit; anything requiring an account dance or a manual transcoding step gets skipped.

Option 1: Put the video in the repository

For small demos tied to the code, the repo is the most durable host in existence: versioned with the project, reviewed in PRs, mirrored in every clone.

The caveats are size and scope. Repos should stay lean; a 40 MB screen recording in a docs folder bloats every clone forever. Reasonable guideline: under 10 MB per video, and only for footage that documents the repo itself. Use Git LFS if you must exceed that, and understand LFS quotas before you depend on them.

Option 2: Video platforms with clean pages

Short-form platforms work well for demo clips. Upload the screen recording, get a watch page with an HLS player, and paste the link into your README or issue. Because the platform transcodes to adaptive streaming, the demo plays instantly for a colleague on a train, which raw repo files cannot promise. Platforms like s.pub are built for exactly this quick-share use case: upload, link, done.

For public-facing project pages, a platform link also gives you view counts and a shareable URL that survives repo reorganizations.

Option 3: Object storage plus CDN

The professional option for teams: encode your demo to a reasonable MP4 or HLS ladder, drop it in a bucket, serve via CDN. Pennies per gigabyte, full control, links that live as long as you pay the bill. The costs are setup time and the discipline to encode before uploading, since raw uploads are served as-is.

A minimal FFmpeg encode for docs video:

ffmpeg -i raw.mp4 -c:v libx264 -crf 23 -preset medium -vf "scale=-2:720" -c:a aac -b:a 96k -movflags +faststart demo.mp4

Screen recordings compress extremely well at CRF 23, often to a tenth of the raw capture.

Option 4: Issue trackers and wikis as accidental hosts

Attaching video to GitHub issues works and is quietly one of the most durable free options: issue attachments have outlived several dedicated video services. It is clunky for README use, but for "here is the bug reproducing," an attached or drag-dropped clip into the issue is the lowest-friction answer that exists.

Recording demos worth hosting

Ten seconds of tight footage beats three minutes of wandering:

Crop to the window

Record the app window, not the whole desktop. Taskbars and unrelated tabs are noise.

Script the motion

Know the exact interaction you are showing and do only that. Every extra second of hesitation is file size and viewer attention spent for nothing.

Pause typing fumbles

Restart the take when you mistype. Editing out two seconds is faster than re-recording, and even a free editor trims painlessly.

Prefer shorter loops

If the demo is cyclical, loop it cleanly and let it run 8 to 10 seconds rather than 40 one-way.

A pragmatic stack

Personal projects: repo for tiny loops, platform links for everything else. Team docs: object storage with a naming convention, plus issue attachments for bug reports. Public projects: a platform watch page linked from the README, with a repo-resident loop for the impatient.

The right host is the one your future self will still find working in three years, and for developers, that usually means the one closest to the code.