publishing

this page covers the canonical file locations, how the indexer discovers files, and what to do if your profile doesn't appear.

---

canonical locations

each standard has three valid locations. the indexer uses priority order -- if a subject has files at multiple locations, only the highest-priority one is indexed.

whoami.md (for individuals)

priority	location	example
1	root of <username>/<username> repo	GuilhermeAlbert/GuilhermeAlbert/whoami.md
2	root of <username>/declared repo	GuilhermeAlbert/declared/whoami.md
3	.github/whoami.md in any public repo	GuilhermeAlbert/any-repo/.github/whoami.md

whois.md (for organizations)

priority	location	example
1	root of the org's primary public repo	declared-md/declared-md/whois.md
2	root of <org>/declared repo	declared-md/declared/whois.md
3	.github/whois.md in any public repo	declared-md/any-repo/.github/whois.md

whatis.md (for projects)

priority	location	example
1	root of the project's primary repo	owner/my-project/whatis.md
2	root of <owner>/declared repo	owner/declared/whatis.md
3	.github/whatis.md in any public repo	owner/any-repo/.github/whatis.md

---

how the indexer discovers files

the indexer uses the GitHub Code Search API to find files by filename across all public repositories. it then filters results to the three canonical locations and validates each file.

latency: the GitHub Search API may have an index lag of a few minutes to a few hours for newly created or updated files. after the indexer runs, it takes up to one build cycle for the directory site to update.

frequency: the indexer is triggered manually or on a configured schedule. check the declared-md/index Actions tab for the latest run.

---

troubleshooting

my file doesn't appear in the directory

1. confirm the file is at a canonical location (see table above)
2. confirm the repo is public
3. confirm the file passes validation: npx declared-md validate ./whoami.md
4. check if the indexer has run since you published -- see the Actions tab in declared-md/index
5. check the invalid/<kind>/ directory in declared-md/index -- your file may be there with validation errors annotated

my file is in invalid/ with errors

the invalid/<kind>/ folder in the index repo stores files that were found but failed validation. each file has an HTML comment at the top listing the exact errors. fix the errors in your source file and wait for the next crawl.

my handle conflicts with someone else

handles are first-come, first-indexed. if two files claim the same handle, the one at the higher-priority location wins. to guarantee your handle, publish at priority 1 (your profile repo).