Skip to content
Docs-as-Code Blueprint

Managing Media & Assets

Visuals, screenshots, and architecture diagrams play an essential role in helping readers comprehend technical documentation quickly. Sveltia CMS includes a built-in Media Library that streamlines uploading and managing graphical assets while maintaining our repository standards.

The Sveltia Media Library

Section titled “The Sveltia Media Library”

You can access the asset manager at any time from the left navigation bar by clicking Media, or directly within any document editor by clicking the Insert Image toolbar icon.

Upload Assets

Drag and drop image files from your computer directly into the media window, or click Upload to browse your local filesystem.

Visual File Browser

Browse existing screenshots and diagrams already committed to the project. Search and filter by filename to avoid uploading duplicates.

Direct Insertion

Click on any uploaded asset to insert it directly into your current document at your cursor location.

Safe Deletions

You can remove unused images from the media library. Sveltia commits the deletion directly to Git.

How Sveltia Handles Images Behind the Scenes

Section titled “How Sveltia Handles Images Behind the Scenes”

In many static site setups, uploading an image places raw, uncompressed files directly into a public folder, leading to sluggish page loads.

In our Docs-as-Code Blueprint:

  1. Target Directory: Sveltia automatically places uploaded assets into src/assets/images/.
  2. Astro Optimization Pipeline: During the site build, Astro scans all referenced images, converts them into modern, lightweight WebP format, generates responsive display sizes for mobile and retina displays, and caches them globally.
  3. Zero Configuration for Writers: You simply upload your screenshot, and the build pipeline handles all compression and performance engineering automatically.

Essential: Writing Accessibility Alt Text

Section titled “Essential: Writing Accessibility Alt Text”

Every image inserted into our documentation must include meaningful Alternative Text (alt). Alt text serves three vital functions:

  • Screen Reader Accessibility: Enables visually impaired colleagues and readers using assistive technology to understand the graphic.
  • Network Fallbacks: Displays if a reader experiences a slow or interrupted network connection.
  • Search Discoverability: Allows search engines and internal search to index diagram context.
  • alt="Sveltia CMS editor displaying the + Insert menu with Aside and Tabs options highlighted"
  • alt="Architecture diagram showing Git commit triggering GitHub Actions CI pipeline"
  • alt="GitHub OAuth login prompt requesting write access to docs-as-code repository"

Step-by-Step: Inserting an Image in Sveltia

Section titled “Step-by-Step: Inserting an Image in Sveltia”
  1. Place Your Cursor:
    Click inside the editor where you want the graphic to appear.
  2. Click Insert Image:
    Select the Image icon in the rich text toolbar.
  3. Choose or Upload:
    Select an existing asset from the media library, or click Upload to add a new file from your desktop.
  4. Enter Descriptive Alt Text:
    When prompted, enter a concise, descriptive alt text phrase.
  5. Confirm Insertion:
    Click Insert. The image will render immediately in your rich text editor and live preview pane.

Image Best Practices

Section titled “Image Best Practices”

Use Kebab-Case Filenames

Name files descriptively using lowercase and hyphens (e.g., sveltia-insert-menu.png rather than Screen Shot 2026-09-10 at 4.21.32 PM.png).

Crop to the Focal Point

Avoid uploading full 4K desktop captures. Crop your screenshot tightly to the relevant dialog, button, or workflow step.

Avoid Text Inside Images

Whenever possible, convey information in Markdown prose rather than embedding text inside an image where it cannot be translated, copied, or searched.

Supported Formats

Use PNG for screenshots, software UIs, and line art; use JPEG/WebP for photographic content; use SVG for vector icons and logos.