Videos and Tabs in DocC Documentation

Beyond Basic Markdown in DocC

Most developers know DocC supports standard markdown, but there are two powerful directives that are surprisingly underused: video embedding and tabbed content. Both work in Xcode’s documentation viewer and on hosted DocC websites.

Embedding Videos

Adding a video to your documentation is a single directive:

@Video(source: "setup-walkthrough.mp4")

Place the video file in your documentation catalog’s Resources folder. This renders an inline video player directly in the documentation, which is far more effective than linking to an external URL or describing a visual process in text. It works well for setup guides, UI walkthroughs, or demonstrating animations.

Tabbed Content with TabNavigator

When you need to show alternative approaches or platform-specific instructions, tabs keep things organized without overwhelming the reader:

@TabNavigator {
   @Tab("SwiftUI") {
      Use the `.environment` modifier to inject dependencies.
   }
   @Tab("UIKit") {
      Override `viewDidLoad` and configure your dependencies there.
   }
}

This renders as a proper tabbed interface where readers can switch between sections. It is especially useful for documentation that covers multiple platforms, API versions, or configuration approaches.

Practical Advice

I updated my Contributing guide to use both of these features, and the result is noticeably more approachable than a wall of text. The video shows the setup process that would take paragraphs to describe, and the tabs separate platform-specific steps cleanly.

These directives are documented in Apple’s DocC documentation but rarely mentioned in tutorials. If you maintain an open-source Swift package, consider adding them to your documentation catalog – they make a real difference in how people experience your docs.