deploy-to-hf-spaces

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 ([e-mail])
• 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 [e-mail]: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

1. Go to https://huggingface.co/spaces/<username>/<space-name>
2. Check the Factory tab for build logs
3. The build is complete when status shows "Running"
4. 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:

1. Check that the CSS bundle hash has changed (view page source, look for /_astro/*.css)
2. 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
   

3. 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   # rewrites README thumbnail: with ?v=<hash>
  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