Skip to main content

your first whoami.md

this guide walks through creating a whoami.md file, publishing it to GitHub, and appearing in the directory.

step 1: create your profile repository​

whoami.md must live in a specific location. the highest-priority location is the root of your GitHub profile repository -- a repo with the same name as your username.

if <your-username>/<your-username> doesn't exist, create it on GitHub as a public repository. if it does exist, you'll publish the file there.

step 2: create the file​

run init to scaffold the file with your required fields:

npx declared-md init whoami

the CLI will ask for:

  • your name
  • your handle (URL slug -- lowercase, alphanumeric, hyphens only)
  • optionally, your GitHub username (to prefill from your public profile)

output: a whoami.md file in the current directory.

step 3: edit the file​

open whoami.md and fill in the fields. example:

---
declared: "1.0"
kind: whoami
name: Ana Ferreira
handle: ana-ferreira
headline: Full-stack developer focused on sustainable supply chain software
location: Recife, BR
status: open-to-work
roles: [software-engineer, technical-writer]
stack: [typescript, react, node, postgresql]
focus: [supply-chain, open-source]
languages: [pt-BR, en]
available_for: [freelance, consulting, mentorship]
tags: [brazil, northeast, b2b]
pronouns: she/her
timezone: America/Recife
links:
  github: https://github.com/ana-ferreira
  site: https://anaferreira.dev
  email: mailto:ana@anaferreira.dev
---

I'm a full-stack developer based in Recife, Brazil.

see the whoami.md spec for the full field reference.

step 4: validate​

before publishing, validate the file:

npx declared-md validate ./whoami.md

a valid file shows:

valid whoami.md

an invalid file shows the exact fields that failed:

invalid whoami.md

  x handle: must be 2-39 characters, lowercase letters, numbers, and hyphens only
  x links.site: must be a valid HTTPS URL (must start with https://)

2 errors found.

fix all errors before publishing.

step 5: preview (optional)​

preview how the directory will render your profile:

npx declared-md preview ./whoami.md

opens a local server at http://localhost:3939.

step 6: publish to GitHub​

commit and push the file to <your-username>/<your-username>:

git add whoami.md
git commit -m "add whoami.md"
git push

the file is now public and at the canonical location.

step 7: wait for the next crawl​

the indexer runs on a schedule (or manually). after the next run, your profile appears at:

https://declared-md.github.io/people/<your-handle>

indexing is not instant. if you don't appear within 24 hours, see troubleshooting.