source
this is a rendered mirror of the normative spec at github.com/declared-md/spec. in case of conflict, the source repository wins.
whatis.md: specification v1.0
the specification for project identity profiles in the declared-md family.
see shared rules for encoding, file location, filename, and common validation rules.
purpose
whatis.md is a self-published identity file for open-source projects, protocols, libraries, applications, CLIs, and other software projects that maintain a public GitHub repository.
file location rules
| priority | location |
|---|---|
| 1 | root of the project's primary public repository |
| 2 | root of <owner>/declared repo |
| 3 | .github/whatis.md in any public repo the owner controls |
frontmatter schema
required fields
| field | type | rules |
|---|---|---|
declared | string | must be "1.0" |
kind | string | must be "whatis" |
name | string | project name. at least 1 character. |
handle | string | URL slug. must match ^[a-z0-9-]{2,39}$. |
recommended fields
| field | type | rules |
|---|---|---|
headline | string | one-line description. at most 120 characters. |
kind_of_project | string | one of: library, framework, application, cli, service, protocol, dataset, documentation |
links | object | see links schema. links.repo must be present. |
optional fields
| field | type | rules |
|---|---|---|
status | string | one of: experimental, alpha, beta, stable, mature, archived |
license | string | SPDX license identifier. examples: MIT, Apache-2.0. |
language | string[] | primary programming languages. |
stack | string[] | frameworks and major dependencies. |
maintained_by | string[] | GitHub handles of active maintainers. |
sponsored_by | string[] | GitHub handles or org names of sponsors. |
tags | string[] | free-form tags. |
links schema
| key | type | description |
|---|---|---|
repo | string (URL) | canonical repository URL. must be present when links is included. |
docs | string (URL) | documentation site URL. |
demo | string (URL) | live demo or playground URL. |
site | string (URL) | project website URL. |
any additional key with an https:// value is also accepted.
example
---
declared: "1.0"
kind: whatis
name: Pagefind
handle: pagefind
headline: Static low-bandwidth search at scale
kind_of_project: library
status: stable
license: MIT
language: [rust, javascript]
stack: [wasm, nodejs]
maintained_by: [bglw]
tags: [search, static-sites, wasm, jamstack]
links:
repo: https://github.com/CloudCannon/pagefind
docs: https://pagefind.app
demo: https://pagefind.app/docs/demo
---
Pagefind is a fully static search library that runs in the browser.