Setting up social cards

Social cards, also known as social sharing image, are images that are displayed when a link to your project documentation is shared on social media. Material for nbdev enables you to easily create attractive social media share images for your project.

By default, mkdocs.yml is configured to use the social sharing image generated by GitHub’s Open Graph image service for your project.

For viewing the default social share image for our project nbdev_mkdocs_tutorial, navigate to the URL below in your preferred browser.

Info

In the following URL:

• Replace {user} with your github username
• If you have used a different name for your repo, replace nbdev_mkdocs_tutorial with it.

https://opengraph.githubassets.com/some-random-stuff-to-refresh-or-timestamp/{user}/nbdev_mkdocs_tutorial

Generating new social cards

For customizing and generating a new social share image for your project, you can use the nbdev_mkdocs social-image generate CLI command. For viewing the current configuration options, please run the following command in the terminal.

nbdev_mkdocs social-image generate --help

 Usage: nbdev_mkdocs social-image generate [OPTIONS]

 Generate a custom social share image

╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --root-path         TEXT           Project's root path. [default: .]         │
│ --generator         [file|dall_e]  Generator to use to create the social     │
│                                    image. Valid options are: 'file' and      │
│                                    'dall_e'. Choose 'file' if you want to    │
│                                    use an existing image from your local     │
│                                    machine in the social share image.        │
│                                    [default: file]                           │
│ --prompt            TEXT           The prompt to use for generating the      │
│                                    image.                                    │
│                                    [default: Cute animal wearing hoodie      │
│                                    sitting in high chair in purple room,     │
│                                    browsing computer, 3d render]             │
│ --image-path        TEXT           Image file path to use in the social      │
│                                    share image. Use images with a 1:1 aspect │
│                                    ratio and at least 512x512 pixels for the │
│                                    best results. If None, then the default   │
│                                    image will be used.                       │
│                                    [default: None]                           │
│ --help                             Show this message and exit.               │
╰──────────────────────────────────────────────────────────────────────────────╯

The above command generates the custom social share image using the playwright library. Please run the following command to install the required browser for the playwright plugin before generating a custom social share image:

playwright install chromium

Generating using AI

The nbdev_mkdocs social-image generate CLI command can be configured to use DALL-E, an OpenAI model to create stunning social share images for your project.

Here’s an example of how to use DALL-E to create a custom social share image based on a description.

Note

The OpenAI API uses API keys for authentication. Please create one and set it in the OPENAI_API_KEY environment variable before running the below command.

nbdev_mkdocs social-image generate \
    --generator "dall_e" \
    --prompt "Cute panda browsing computer in purple room. 3d render."

The generated image will be saved as social_image.png in the mkdocs/docs_overrides/images directory. You can make multiple versions of the image by experimenting with the text prompts. Each version will be saved to the same directory, with a version number added to the suffix. For example, the most recently generated image is saved as social_image.png, the first version will be saved as social_image_1.png, the second version will be saved as social_image_2.png, and so on. This allows you to easily experiment and compare different versions of the image to find the one that looks best.

Generating from an existing image

You can also make a custom social share image from an existing image. This can be an excellent way to maintain your brand’s visual style while also making it stand out on social media. Here’s an example of how to do so:

Tip

Use images with a 1:1 aspect ratio and at least 512x512 pixels for the best results.

Info

Replace {path-to-image} in the following command with the image path you want to use in the social share image

nbdev_mkdocs social-image generate \
    --image-path {path-to-image}

You can also choose not to pass the --image-path parameter in the above command, in which case the default image will be used.