Upload Post Image

Upload Post Image

Use this skill when a blog post needs an image in the article body.

Do not use this skill for thumbnails. Blog thumbnails stay in this repository under assets/<post-slug>/ and are referenced from frontmatter with /blog/assets/<post-slug>/<thumbnail-file>.

Body images, diagrams, screenshots, GIFs, and videos should live in the Hugging Face Documentation Images dataset:

huggingface/documentation-images

Use a mirrored folder under:

blog/<post-slug>/

This keeps the blog repository small while still making images stable and public.

Workflow

• Identify the post slug.

Use the Markdown filename without .md unless the user asks for a different folder.

For my-post.md, use:

blog/my-post/

• Identify the image role.

If the image is the post thumbnail, keep it in this repo under:

assets/<post-slug>/

If the image appears inside the article body, upload it to:

huggingface/documentation-images

• Choose a descriptive filename.

Use a short filename that describes the image's role in the post.

Good examples:

• architecture-diagram.svg
• dashboard-screenshot.png
• model-comparison-chart.jpg
• demo-output.gif

Avoid temporary names, source-site names, hashes, timestamps, and names tied to a one-off migration.

• Download or prepare the image locally.

For a remote image, download the direct image URL into /tmp:

mkdir -p /tmp/<post-slug>-images
curl -L --fail --silent --show-error "<direct-image-url>" -o /tmp/<post-slug>-images/<descriptive-file-name>

Use a direct image URL, not an album page or webpage.

• Inspect the local file.

Confirm the file type, dimensions, and size:

file /tmp/<post-slug>-images/<descriptive-file-name>
du -h /tmp/<post-slug>-images/<descriptive-file-name>

Keep files reasonably small. Compress large PNG/JPEG files before upload when possible.

• Confirm Hugging Face authentication.

hf auth whoami

If this fails, ask the user to authenticate before uploading.

• Upload the image to the documentation-images dataset.

hf upload huggingface/documentation-images \
  /tmp/<post-slug>-images/<descriptive-file-name> \
  blog/<post-slug>/<descriptive-file-name> \
  --repo-type dataset

• Use the resolver URL in the blog post.

The public URL has this shape:

https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/blog/<post-slug>/<descriptive-file-name>

Markdown image:

![Clear alt text](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/blog/<post-slug>/<descriptive-file-name>)

HTML figure with caption:

<figure class="image text-center">
  <img class="mx-auto" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/blog/<post-slug>/<descriptive-file-name>" alt="Clear alt text" width="70%">
  <figcaption>Short caption.</figcaption>
</figure>

• Verify the new URL resolves.

curl -I --fail --silent --show-error "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/blog/<post-slug>/<descriptive-file-name>"

A redirect to Hugging Face storage is expected.

10. Update the Markdown and check for stale links.

Search for the old host or path:

rg -n "<old-host-or-file-name>|documentation-images/resolve/main/blog/<post-slug>" <post-slug>.md

Make sure the article no longer depends on temporary hosts for body images.

11. Commit only the blog repo changes.

The dataset upload creates its own commit in huggingface/documentation-images.

In this repository, commit the Markdown change that points at the new image URL.

Use a clear Conventional Commit message, for example:

git commit -m "docs: move post images to documentation dataset"

Notes

• Preserve meaningful alt text.
• Keep captions short and factual.
• Prefer lowercase filenames with hyphens.
• Avoid spaces in filenames.
• Do not upload private, sensitive, or uncleared copyrighted images.
• Do not move the post thumbnail to the dataset repo.