Open-source project
huggingface/blog avatar
huggingface/blog

huggingface/blog: the repository behind the Hugging Face blog, and how to publish in it

Public repo for HF blog posts

3,563 stars1,067 forksJupyter NotebookLicense varies

At a glance

What is it?
The huggingface/blog repository holds the markdown sources for posts on hf.co/blog. This is a walkthrough of its contribution workflow, its asset split, and the cases where a community blog is the better route.
Who is it for?
Adopt huggingface/blog if you are writing a collaboration post with Hugging Face and want it to appear on hf.co/blog, since merging the pull request is what publishes it. Do not open a pull request here for an independent post: the README directs external contributors whose post is not a collaboration to create a community blog instead.
Can I use it commercially?
Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
Is it still maintained?
Yes. The repository last received commits 2 days ago.
What is it written in?
Mainly Jupyter Notebook, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • huggingface/blog3,563 ★ · +30
Star history
Repository2026-09-242026-11-15
huggingface/blog3.5k3.6k

30 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What problem the huggingface/blog repository solves

The repository is the source of truth for the posts published at hf.co/blog. Each article is a markdown file at the top level of the repository, named after the post itself, and the README states that the file name becomes the blog post's URL. That single detail explains most of the layout: the long list of top-level .md files is not a docs tree, it is a flat directory of published posts, from 1_58_llm_extreme_quantization.md to more recent entries.

The intended user is a person writing a post that Hugging Face is publishing, either as staff or as a collaborator. The README is explicit about the boundary: if your blog post is not a collaboration post with Hugging Face, it asks you to consider creating a community blog instead, and notes that community posts appear on the blog's main page just like the ones in this repository. That sentence is the most useful thing in the README for an outsider, because it tells you which door to use before you spend time on a pull request that will be redirected.

What the repository is not: it is not a site generator you install, and it is not a template you deploy. There is no build step described for local rendering. The publishing happens on the Hub side, and the README describes the merge as the trigger.

How an article moves from a branch to a published URL

The workflow in the README is a numbered list, and the order matters. You create a branch named YourName/Title, then create the markdown file with a short file name, because that name becomes the URL. A title like "Introduction to Deep Reinforcement Learning" is given the file name intro-rl.md in the example. Short names are not a style preference here, they are the public address of the post.

Assets are split across two locations, and this is the part contributors get wrong. The assets folder in this repository holds the thumbnail only, in a subfolder named after the markdown file, optionally with a numerical prefix such as 123_intro-rl. Everything else goes into a mirrored folder in the HuggingFace Documentation Images dataset repository. The README gives the reason plainly: to reduce bloat in the GitHub base repo when cloning and pulling. A repository with hundreds of posts and their full image sets would be painful to clone, so only the thumbnail stays.

The front matter carries the title, the thumbnail path, and an authors list of Hub user names. The README shows the shape of it, including the thumbnail path pointing into /blog/assets/ and authors entries of the form user: your_hf_user. After that comes the body in markdown, and then a separate step: modifying _blog.yml to register the post. That file is the index, and a post that is not listed there is not wired into the site even if the markdown exists.

Publishing is described as automatic on merge. The README also states that the Hub inserts a "Published on [date]" line, an "Update on GitHub" button, and author avatars right after the main header, so those elements are not something you write yourself.

Writing your first post: branch, front matter, thumbnail

The README's first step is creating a branch named YourName/Title, and the second is creating a markdown file with a short name, because the file name becomes the blog post's URL. In the README's own example, a post titled "Introduction to Deep Reinforcement Learning" gets the file name intro-rl.md.

Create that markdown file at the repository root, then open it with the front matter block the README provides. Keep the keys exactly as shown; the thumbnail path points at the assets subfolder, and each author is a Hub user name.

yaml
---
title: "PUT YOUR TITLE HERE"
thumbnail: /blog/assets/101_decision-transformers-train/thumbnail.gif
authors:
- user: your_hf_user
- user: your_coauthor
---

Below that block comes the article body, starting with a single # heading. The README notes that the Hub inserts the publication date, the "Update on GitHub" button and the author avatars immediately after that first heading, so you should not add them yourself.

For the thumbnail itself, the README asks for a 1300x650 image and points at a template SVG in the repository's assets folder, or a Figma template. It also asks for small files, suggesting tinypng.com or iloveimg.com for compression, with the stated goal of avoiding a slow loading experience. The thumbnail goes in an assets subfolder named after the markdown file; the remaining images go in the mirrored folder in the documentation-images dataset repository.

Finally, register the post by editing _blog.yml, then open a pull request. The README states the article is published automatically when the pull request is merged.

LaTeX, captions and embedded Spaces in a post

The README documents a few rendering features that are not obvious from plain markdown. Inline math uses escaped parentheses rather than dollar signs, so the source reads with double backslashes around the expression. The README's example, Q(S_t, A_t), renders as a typeset formula.

code
\\(your_latex_here\\)

Figure captions have two documented approaches: a Markdown table, with a link to a post that uses it, or HTML, with a link to another post. The README does not prescribe one over the other, which means caption style is effectively whatever the reviewers of your pull request accept. That is a small but real inconsistency: two posts can caption figures in visibly different ways.

Embedding a Gradio Space is done with a script tag and a custom element, both shown in the README with a specific Gradio version in the script URL and a space attribute naming the Space. Highlight boxes exist as well, but the README points to a pull request as the example and adds "This is to be used sparingly" with a smiley, which is the closest the documentation comes to a style rule.

For contributors who find the markdown fiddly, the README names two helpers: a community blog editor at huggingface.co/new-blog with a preview function, and an assistant Space that helps render tricky blocks such as caption figures with image tables, tip formatting, and clickable references. Neither is required.

Where this repository is the wrong tool

The clearest limitation is stated by the project itself. If your post is not a collaboration with Hugging Face, the README asks you to consider a community blog instead. The community route is not a lesser version of the same thing: the README says those posts appear on the blog's main page just like the posts in this repository. So the practical failure mode is spending an afternoon formatting front matter and thumbnails for a pull request that should have been a community submission.

A second limit is that the repository is not self-contained. The markdown lives here, but the images that make a post readable mostly live in a separate dataset repository, and the rendered site lives on the Hub. Cloning huggingface/blog gives you the text and the thumbnails, not a working preview of the blog. The README does not document a local preview command, and it does not document rollback if a merged post needs to be pulled back down.

There is also no release process to speak of. The repository has no published GitHub releases, which is consistent with what it is: a content repository where the merge is the deploy. If you need versioned artifacts or a changelog for the thing you are publishing, this is the wrong shape of project.

The repository's primary language is listed as Jupyter Notebook, which is a quirk of how the content is counted rather than a signal about the workflow. The contribution path described in the README is markdown and YAML, plus a pull request.

Community blog versus a pull request in this repository

The real alternative is the community blog route the README names, and the difference is not cosmetic. A pull request against huggingface/blog goes through the repository's index file and its asset conventions, and the README frames it as the path for collaboration posts. A community blog is created through the Hub's own flow, and per the README its output appears on the blog's main page alongside repository posts. Same surface, different gatekeeping and different tooling.

If your goal is simply to publish a technical writeup under your own name, the community route removes the two most annoying constraints here: the mirrored image repository and the _blog.yml edit. If your goal is a post that reads as an official Hugging Face publication, with the injected publication date and "Update on GitHub" button, then this repository is the only path described.

A second reference point is the community blog editor at huggingface.co/new-blog, which the README offers as a way to write with a preview. It is not a competing platform so much as a different entry point into the same publishing surface, and the README presents it as assistance rather than a replacement for the pull request workflow.

Maintenance, licence and what to check before contributing

The repository is not archived, and its last push was on 2026-09-23, so it is being updated. That matters for a content repository in a specific way: the posts at the top level change constantly, and the README's conventions can drift from what recent posts actually do. The README already shows this drift. It says the numerical prefix on the assets subfolder is no longer required, and it says the folder number is mostly for rough ordering and that collisions between concurrent articles are no big deal. Read the README as guidance, then read two or three recent posts to see the current practice.

The repository metadata lists no licence. That is worth stating plainly rather than guessing: the repository does not identify a licence, so anyone planning to reuse the markdown or the assets outside the blog should treat the terms as unconfirmed and check the repository before doing so. This is a factual gap, not legal advice.

The upgrade cost is low in the usual sense, since there is nothing to install or version. The cost sits in the contribution loop instead: a short file name you can live with, a thumbnail at 1300x650, a mirrored image folder elsewhere, and an entry in _blog.yml. Get any of those wrong and the pull request comes back. The README does not describe a validation step that catches these before review, so the review itself is the check.

Editorial conclusion

Adopt huggingface/blog if you are writing a collaboration post with Hugging Face and want it to appear on hf.co/blog, since merging the pull request is what publishes it. Do not open a pull request here for an independent post: the README directs external contributors whose post is not a collaboration to create a community blog instead. Before you start, verify three things in the repository: the exact front matter keys in a current post, the entries in _blog.yml, and whether your images belong in the mirrored documentation-images folder rather than assets.

Frequently asked questions

What is huggingface/blog?

It is the public repository holding the markdown sources for posts on the Hugging Face blog at hf.co/blog. Articles are markdown files at the top level, with a thumbnail in assets and an entry in _blog.yml.

How do I publish a post in the huggingface/blog repository?

The README's steps are: create a branch named YourName/Title, create a short-named markdown file with title, thumbnail and authors front matter, add the thumbnail under assets, modify _blog.yml, and open a pull request. The README states the article is published automatically when the pull request is merged.

Can I contribute a post if it is not a collaboration with Hugging Face?

The README asks external contributors whose post is not a collaboration with Hugging Face to consider creating a community blog instead, and notes that community posts appear on the blog's main page just like the posts in this repository.

Where do images for a huggingface/blog post go?

Only the thumbnail goes in the repository's assets folder, in a subfolder named after the markdown file. The README says the rest of your files go in a mirrored folder in the HuggingFace Documentation Images repository, to reduce bloat when cloning and pulling the GitHub repo.

What thumbnail size does huggingface/blog expect?

The README asks for a 1300x650 image and points to a template SVG in the repository's assets folder or a Figma template. It also asks for compressed, small files to avoid a slow loading experience.

Official sources

  1. huggingface/blog on GitHub
  2. Issues
  3. Project website
  4. README

Was this useful?