crates_io_og_image

A Rust crate for generating Open Graph images for crates.io packages.

[!NOTE] This crate is maintained by the crates.io team, primarily for use by crates.io and docs.rs, and not intended for external use. This crate may make major changes to its APIs or be deprecated without warning.

Overview

crates_io_og_image is a specialized library for generating visually appealing Open Graph images for Rust crates. These images are designed to be displayed when crates.io links are shared on social media platforms, providing rich visual context about the crate including its name, description, authors, and key metrics.

The generated images include:

• Crate name and description
• Tags/keywords
• Author information with avatars (when available)
• Key metrics (releases, latest version, license, lines of code, size)
• Consistent crates.io branding

Requirements

• The Fira Sans font must be installed on your system (or configured via the TYPST_FONT_PATH environment variable).
• The Noto CJK font may optionally be installed for CJK character support.
• The Noto Color Emoji font may optionally be installed for Emoji support.

Usage

Basic Example

use crates_io_og_image::{OgImageData, OgImageGenerator, OgImageAuthorData, OgImageError};

#[tokio::main]
async fn main() -> Result<(), OgImageError> {
    // Create a generator instance
    let generator = OgImageGenerator::default();

    // Define the crate data
    let data = OgImageData {
        name: "example-crate",
        version: "1.2.3",
        description: Some("An example crate for testing OpenGraph image generation"),
        license: Some("MIT/Apache-2.0"),
        tags: &["example", "testing", "og-image"],
        authors: &[
            OgImageAuthorData::with_url(
                "Turbo87",
                "https://avatars.githubusercontent.com/u/141300",
            ),
        ],
        lines_of_code: Some(2000),
        crate_size: 75,
        releases: 5,
    };

    // Generate the image
    let image = generator.generate(data).await?;

    // `image` contains the raw PNG bytes
    println!("Generated image: {} bytes", image.len());

    Ok(())
}

Configuration

The following environment variables can be used to configure the image generation:

• TYPST_FONT_PATH - Additional font directory

Cargo Features

• oxipng (enabled by default) - Bundles the oxipng library for lossless PNG file size optimization. Disable it with default-features = false. When enabled, call OgImageGenerator::with_oxipng() to optimize generated images.

Development

Running Tests

cargo test

Example

The crate includes an example that demonstrates how to generate an image:

cargo run --example test_generator

This will generate a test image in the current directory

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.