---
source: https://iinventedlight.com/library/notes/hf-model-cards.md
title: "Hugging Face model cards: README.md plus YAML metadata"
license: CC-BY-4.0
license_url: https://creativecommons.org/licenses/by/4.0/
source_license: "Apache-2.0 (huggingface/hub-docs); restated in our own words"
attribution: "Summary by iinventedlight (AI-assisted). Sources: Hugging Face, Hub docs: Model Cards, Apache-2.0 (huggingface/hub-docs); Hugging Face, Annotated Model Card Template, Apache-2.0 (huggingface/hub-docs)."
author: "iinventedlight (synthesis of cited sources); text drafted with AI assistance"
date: 2026-11-04
status: published
checked_on: 2026-11-05
as_of: 2026-11-05
confidence: medium
untested: "No card was published; only the fetched Hub docs page was read."
category: huggingface-datasets
topic_area: "hf: documenting models on the Hub"
tags: huggingface, hub, model-cards, documentation
sources:
  - id: S1
    title: "Hub docs: Model Cards"
    publisher: Hugging Face
    url: https://huggingface.co/docs/hub/model-cards
    accessed: 2026-11-05
    license: "Apache-2.0 (huggingface/hub-docs)"
  - id: S2
    title: "Annotated Model Card Template"
    publisher: Hugging Face
    url: https://huggingface.co/docs/hub/model-card-annotated
    accessed: 2026-11-05
    license: "Apache-2.0 (huggingface/hub-docs)"
    license: "Apache-2.0 (huggingface/hub-docs)"
---
# Hugging Face model cards

## Short answer
A model card is the README.md that describes a model, its intended uses, and limits. Cards are Markdown with extra metadata and help with discoverability. [S1]

## Points
- You can find a model card as README.md in any model repo. [S1]
- Evaluation results can be stored in model card metadata. [S2]
- The Hub parses that metadata into a widget on the model page. [S2]

## Claims
- id: C1
  claim: Model cards are Markdown files with metadata.
  source: S1
  evidence: "model cards are simple Markdown files with additional metadata"
- id: C2
  claim: A model card is the README.md in a model repo.
  source: S1
  evidence: "find a model card as the README.md file in any model repo"
- id: C3
  claim: Evaluation results can go in model card metadata.
  source: S2
  evidence: "evaluation results in a structured way in the model card metadata"
- id: C4
  claim: Hub parses metadata for a widget on the model page.
  source: S2
  evidence: "Results are parsed by the Hub and displayed in a widget on the model page"

## Sources
- [S1] Hub docs: Model Cards. Hugging Face. https://huggingface.co/docs/hub/model-cards . License: Apache-2.0 (huggingface/hub-docs). Accessed 2026-11-05.
- [S2] Annotated Model Card Template. Hugging Face. https://huggingface.co/docs/hub/model-card-annotated . License: Apache-2.0 (huggingface/hub-docs). Accessed 2026-11-05.

License: this note is CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Summary by iinventedlight (AI-assisted).

Source notice: Hugging Face Hub docs, Apache License 2.0 (https://github.com/huggingface/hub-docs/blob/main/LICENSE).