Docs: pre-release model pages

docs/hub/_toctree.yml

@@ -105,6 +105,8 @@
     title: Leaderboard Data
   - local: models-gated
     title: Gated Models
+  - local: models-release-announcements
+    title: Pre-Release Model Pages
   - local: models-uploading
     title: Uploading Models
   - local: models-downloading

docs/hub/model-cards.md

@@ -22,7 +22,7 @@ Model Cards on the Hub have two key parts, with overlapping information:
 
 ## Model card metadata
 
-A model repo will render its `README.md` as a model card. The model card is a [Markdown](https://en.wikipedia.org/wiki/Markdown) file, with a [YAML](https://en.wikipedia.org/wiki/YAML) section at the top that contains metadata about the model. 
+A model repo will render its `README.md` as a model card. The model card is a [Markdown](https://en.wikipedia.org/wiki/Markdown) file, with a [YAML](https://en.wikipedia.org/wiki/YAML) section at the top that contains metadata about the model.
 
 The metadata you add to the model card supports discovery and easier use of your model. For example:
 
@@ -40,7 +40,7 @@ There are a few different ways to add metadata to your model card including:
 - Directly editing the YAML section of the `README.md` file
 - Via the [`huggingface_hub`](https://huggingface.co/docs/huggingface_hub) Python library, see the [docs](https://huggingface.co/docs/huggingface_hub/guides/model-cards#update-metadata) for more details.
 
-Many libraries with [Hub integration](./models-libraries) will automatically add metadata to the model card when you upload a model. 
+Many libraries with [Hub integration](./models-libraries) will automatically add metadata to the model card when you upload a model.
 
 #### Using the metadata UI
 
@@ -60,7 +60,7 @@ You can also directly edit the YAML section of the `README.md` file. If the mode
 
 ```yaml
 ---
-language: 
+language:
   - "List of ISO 639-1 code for your language"
   - lang1
   - lang2
@@ -95,14 +95,14 @@ tags:
 - flair
 ```
 
-If it's not specified, the Hub will try to automatically detect the library type. However, this approach is discouraged, and repo creators should use the explicit `library_name` as much as possible. 
+If it's not specified, the Hub will try to automatically detect the library type. However, this approach is discouraged, and repo creators should use the explicit `library_name` as much as possible.
 
 1. By looking into the presence of files such as `*.nemo` or `*.mlmodel`, the Hub can determine if a model is from NeMo or CoreML.
 2. In the past, if nothing was detected and there was a `config.json` file, it was assumed the library was `transformers`. For model repos created after August 2024, this is not the case anymore, so you need to set `library_name: transformers` explicitly.
 
 ### Specifying a base model
 
-If your model is a fine-tune, an adapter, or a quantized version of a base model, you can specify the base model in the model card metadata section. This information can also be used to indicate if your model is a merge of multiple existing models. Hence, the `base_model` field can either be a single model ID, or a list of one or more base_models (specified by their Hub identifiers). 
+If your model is a fine-tune, an adapter, or a quantized version of a base model, you can specify the base model in the model card metadata section. This information can also be used to indicate if your model is a merge of multiple existing models. Hence, the `base_model` field can either be a single model ID, or a list of one or more base_models (specified by their Hub identifiers).
 
 ```yaml
 base_model: HuggingFaceH4/zephyr-7b-beta
@@ -157,21 +157,31 @@ The Hub will infer the type of relationship from the current model to the base m
 
 ### Specifying a new version
 
-If a new version of your model is available in the Hub, you can specify it in a `new_version` field.  
+If a new version of your model is available in the Hub, you can specify it in a `new_version` field.
 
 For example, on `l3utterfly/mistral-7b-v0.1-layla-v3`:
 
 ```yaml
 new_version: l3utterfly/mistral-7b-v0.1-layla-v4
 ```
 
-This metadata will be used to display a link to the latest version of a model on the model page. If the model linked in `new_version` also has a `new_version` field, the very latest version will always be displayed. 
+This metadata will be used to display a link to the latest version of a model on the model page. If the model linked in `new_version` also has a `new_version` field, the very latest version will always be displayed.
 
 <div class="flex justify-center">
    <img class="block dark:hidden" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/new_version.png"/>
    <img class="hidden dark:block" src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/hub/new_version-dark.png"/>
 </div>
 
+### Announcing an upcoming release
+
+Organizations on an Enterprise plan or above can announce an upcoming model before its weights are public. Adding a `release_date` field to the model card metadata of a **private** model turns the model page into a [pre-release page](./models-release-announcements) with a countdown and a **Like and Notify on release** button. Making the model public releases it:
+
+```yaml
+release_date: 2026-07-27
+```
+
+The field accepts a YAML date or a quoted ISO 8601 timestamp (e.g. `"2026-07-27T15:00:00Z"`). See the [Pre-Release Model Pages](./models-release-announcements) documentation for more details.
+
 ### Specifying a dataset
 
 You can specify the datasets used to train your model in the model card metadata section. The datasets will be displayed on the model page and users will be able to filter models by dataset. You should use the Hub dataset identifier, which is the same as the dataset's repo name as the identifier:
@@ -202,7 +212,7 @@ For `transformers` models, the pipeline tag is automatically inferred from the m
 
 You can specify the license in the model card metadata section. The license will be displayed on the model page and users will be able to filter models by license. Using the metadata UI, you will see a dropdown of the most common licenses.
 
-If required, you can also specify a custom license by adding `other` as the license value and specifying the name and a link to the license in the metadata. 
+If required, you can also specify a custom license by adding `other` as the license value and specifying the name and a link to the license in the metadata.
 
 ```yaml
 # Example from https://huggingface.co/coqui/XTTS-v1
@@ -287,7 +297,7 @@ Yes, you can add custom tags to your model by adding them to the `tags` field in
 
 ### How can I indicate that my model is not suitable for all audiences
 
-You can add a `not-for-all-audiences` tag to your model card metadata. When this tag is present, a message will be displayed on the model page indicating that the model is not for all audiences. Users can click through this message to view the model card. 
+You can add a `not-for-all-audiences` tag to your model card metadata. When this tag is present, a message will be displayed on the model page indicating that the model is not for all audiences. Users can click through this message to view the model card.
 
 ### How can I display different images for dark and light mode?
 
@@ -336,5 +346,3 @@ $$
 $$
 
 $$ E=mc^2 $$
-
-

docs/hub/models-release-announcements.md

@@ -0,0 +1,65 @@
+# Pre-Release Model Pages
+
+> [!WARNING]
+> This feature is available to organizations on an <a href="https://huggingface.co/enterprise">Enterprise</a> plan or above — or <a href="https://huggingface.co/contact/sales?from=enterprise" target="_blank">contact us</a>.
+
+Pre-release model pages let your organization announce an upcoming model while it is still private. Instead of a 404 page, visitors see a dedicated announcement page with a live countdown to the release date and a **Like and Notify on release** button, so they can be notified by email the moment your model is out. When you make the model public, it is considered released and the announcement page is replaced with the model card.
+
+## Eligibility
+
+- Your organization must be subscribed to an [Enterprise](https://huggingface.co/enterprise) plan or above.
+- The model repository must live under the **organization namespace** (e.g. `my-org/my-upcoming-model`). User-owned repositories are not eligible.
+- The model repository must be **private**. Making the model public releases it (see [below](#notify-your-subscribers-on-release)).
+
+## Announce your model
+
+To turn a **private** model's page into a pre-release page, add a `release_date` field to the model card metadata (the YAML section at the top of the repo's `README.md`):
+
+```yaml
+---
+release_date: 2026-07-27
+description: "A short tagline shown on the pre-release page"
+---
+```
+
+The `release_date` field accepts either a YAML date, or a quoted ISO 8601 timestamp if you want to target a specific time:
+
+```yaml
+release_date: "2026-07-27T15:00:00Z"
+```
+
+Invalid values are rejected by the metadata validator and ignored. A few more things to know:
+
+- The optional `description` metadata field is used as the hero tagline of the pre-release page.
+- The markdown body of your model card is rendered as the content of the page, so you can use it to describe what's coming.
+- Metadata changes can take up to a minute to propagate.
+
+## What visitors see
+
+While the model is private and `release_date` is set (and your organization is eligible), visitors see the pre-release page instead of a 404 page:
+
+- A live **countdown** to the release date, along with your tagline and the model card content.
+- A sidebar showing the number of users waiting for the release, the expected release date, and your organization's latest models.
+- A **Like and Notify on release** button: clicking it likes the repo and subscribes the user to an email notification for the release. Unliking the model unsubscribes.
+- The social-share thumbnail of the page also gets an "Upcoming release" treatment.
+
+Members with **write access** to the repository always see the regular model page instead, so they can keep managing files and settings while the announcement is up.
+
+When the countdown reaches zero, the page shows **"Coming very soon"** — the pre-release page stays up until you make the model public.
+
+## Notify your subscribers on release
+
+When you're ready to release:
+
+1. Push the model files to the repository.
+2. Make the model **public**. This releases the model: the pre-release page becomes a regular model page — no need to remove the `release_date` field.
+3. Repo members with write access will see a banner reading "N users are waiting to be notified about this release", with a **Send release notifications** button.
+4. Click **Send release notifications** to email each subscriber that your model is now available on Hugging Face.
+
+Notifications respect each user's notification preferences.
+
+## Things to keep in mind
+
+- **The page stays up past the date**: reaching the release date does not automatically take the pre-release page down; make the model public to release it and switch back to the regular model page.
+- **Making the model public is the release**: release notifications can only be sent once the model is public.
+- **Making the model private again** (while `release_date` is still set) turns the pre-release page back on.