| name | deploy-to-hf-spaces |
| description | Deploy the article to a Hugging Face Space. Use when the user asks to deploy, push, publish, or update their Space on Hugging Face. |
Deploy to Hugging Face Spaces
Guide for deploying and updating a research article on Hugging Face Spaces.
Prerequisites
- A Hugging Face account with an SSH key configured (
git@hf.co)
- Or HTTPS access with
huggingface-cli login
First deployment
1. Create the Space
Via CLI:
huggingface-cli repo create <username>/<space-name> --repo-type space --space_sdk docker
Or manually at https://huggingface.co/new-space (select Docker SDK).
2. Add the remote
git remote add space git@hf.co:spaces/<username>/<space-name>
3. Push
git push space main
The Space will build automatically using the included Dockerfile and nginx.conf. Build typically takes 3-5 minutes.
Updating an existing Space
git add -A
git commit -m "feat: describe your changes"
git push space main
Force push (when needed)
If the Space history has diverged (e.g., after a factory reset or manual edit on HF):
git push space main --force
Verifying deployment
- Go to
https://huggingface.co/spaces/<username>/<space-name>
- Check the Factory tab for build logs
- The build is complete when status shows "Running"
- If the page looks stale, append
?v=<timestamp> to the URL to bypass CDN cache
Cache busting
Hugging Face Spaces aggressively cache static assets. If changes don't appear after a successful build:
- Check that the CSS bundle hash has changed (view page source, look for
/_astro/*.css)
- If unchanged, the build used a stale cache - push an empty commit to force rebuild:
git commit --allow-empty -m "chore: trigger rebuild"
git push space main
- Wait for the new build to complete before checking again
Social share preview (OG image cache)
Social platforms (X/Twitter, LinkedIn, Slack, …) cache the share preview by
image URL and rarely re-fetch on their own. To force them to pick up a new
thumbnail, the OG image URL is fingerprinted with a short content hash:
…/thumb.auto.jpg?v=<hash>. The hash is derived from article.mdx, so the URL
only changes when the article changes.
-
App page (*.hf.space shares): handled automatically. src/pages/index.astro
computes the hash at build time, so og:image / twitter:image always carry the
current ?v=<hash>.
-
Space card (huggingface.co/spaces/... shares - this is what X scrapes when you
share the Space URL): driven by the thumbnail: field in README.md, which Hugging
Face reads from the committed file. Refresh it before deploying:
cd app && npm run og:sync
cd .. && git add README.md && git commit -m "chore: refresh OG cache token" && git push space main
Notes:
- This only affects new shares; previews already posted are frozen by the platform.
- LinkedIn/Facebook can be force-refreshed via their Post Inspector / Sharing Debugger.
X removed its Card Validator, so changing the URL (the
?v= bump) is the only reliable way.
README tag (critical)
The README.md YAML frontmatter must contain:
tags:
- research-article-template
NEVER remove this tag. It is used by the Research Article Gallery to list the article. Without it, the Space becomes invisible in the gallery.
README frontmatter reference
---
title: "Article Title"
emoji: 📝
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 8080
header: mini
pinned: false
tags:
- research-article-template
---
| Field | Description |
|---|
title | Displayed in the Space card |
emoji | Emoji shown on the Space card |
colorFrom / colorTo | Gradient colors for the card header |
sdk: docker | Required - uses the Dockerfile for build |
app_port: 8080 | Required - nginx serves on 8080 |
header: mini | Compact header (recommended for articles) |
tags | Must include research-article-template |
Troubleshooting
| Problem | Solution |
|---|
| Build fails | Check build logs in the Factory tab. Common issue: missing dependencies in package.json |
| CSS/layout looks wrong | Cache issue - force rebuild with empty commit |
| Images not showing | If using Git LFS, ensure LFS files are pushed. Otherwise check image paths |
| PDF not generated | Playwright is included in Docker build; check build logs for errors |
| Space shows old content | Wait 2-3 min after build completes for CDN propagation, then hard refresh |
