| name | upload-post-image |
| description | Use when adding or migrating non-thumbnail images for a Hugging Face Blog post. Uploads body images to the Hugging Face documentation-images dataset, updates the Markdown, and verifies the new links. |
| metadata | {"short-description":"Upload blog post images"} |
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.svgdashboard-screenshot.pngmodel-comparison-chart.jpgdemo-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:
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.
- 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.
- 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.
