Narrative Overhaul: Homepage & Documentation

[shrugs]

Positioning

ENSNode is the ENSv2-ready developer platform.

Highlight ENSNode's ENSv1 + ENSv2 Multichain next-gen Omnigraph API.

In general advertise APIs, not apps. Users want 'Omnigraph API', not 'ENSRainbow'.

'build ensv2-ready apps today'

social proof marquee with integration logos

refactor the entire docs app to focus on APIs, not apps.

vs

and put all of the details about the different apps and how to run them and configure them in some lower-level reference docs

Unifying the APIs

With the re-orientation around the Omnigraph API and the narrative of 'just use this api' for external developers, it makes sense to re-surface other ENSNode APIs via the Omnigraph. In particular, we'd re-surface the Resolution API in Account.primaryNames and Domain.records to provide users of the Omnigraph API a single point of access for all of ENSNode's core features.

Migration Timeline

• some sort of urgency-inducing 'migrate to ENSNode by ___' countdown timer or something on the homepage.
• a visual timeline of major events in the ENSv2 release, along with 'what happens if you haven't migrated' callouts
  • contracts deployed (but not ratified)
  • period of time where apps can upgrade UniversalResolver, indexer backends
  • ENSv2 goes live date
    • callout that apps that haven't migrated are left behind
• call to action to migrate to ENSNode Omnigraph
  • CTA for new developers -> 'use the omnigraph' goes to quickstart
  • CTA for existing developers -> goes to 'migrate an existing app'

GraphQL API Documentation

• quickstart
  • quick example response for a domain search so they get a feel for things
  • triage users into cookbook vs client integration
• Migrate from Legacy Subgraph API
  • re-statement of ENSv2 will not be supported by Subgraph API
  • re-statement that Omnigraph is the modern ENS API
    • more accurately aligned with the ENS protocol now and into the future
  • high-level overview of differences, knowing that the developer is somewhat familiar with the subgraph api model
  • 'feature request' CTA — if omnigraph is missing a feature they relied on from the subgraph api
  • TBD how ensjs is going to use (or not) the indexer — if a user relied on the subgraph-backed features of ensjs, they should probably migrate to omnigraph anyway, not sure that ensjs should depend on an indexer at all, now that it's not 'decentralized infrastructure'
  • tools:
    • ensnode docs skill
    • ensnode omnigraph skill
    • ensnode omnigraph-migration skill
      • additional skill with extra knowledge of migration patterns, in particular should work with the user to modify the data access patterns in their app, needs to be able to re-write graphql queries
• cookbook w/ inline execution
  • ala previous Examples Page
  • high-level example queries and associated discussion
  • inline execution of gql requests against mainnet
    • playground optionally editable
    • layout modeled after @scalar/astro
  • "open in ENSAdmin" button that populates the example query/variables in ensadmin
• client integration
  • type generation
    • graphql-code-generator quickstart
    • gql.tada quickstart
  • query clients
    • urql integration example
    • graphql-request integration example
• tools
  • ensnode docs skill
    • ala mintlify's autogenerated docs skill
  • ensnode omnigraph skill
    • omnigraph integration skill, helping users integrate with new or existing apps with few-shot examples for popular patterns
• api reference
  • there's no good existing tooling for this, frankly, so i propose we more or less roll-our-own with a focus on clarity
  • i.e. for each major entity, render their major properties, complete with links to the returned entity's
    • abstract away all of the verbose connections/inputs/etc entities that most introspectors render
    • result is a simple page w/ ToC documenting major entities and their properties using the types/description from the GraphQL Introspection result
• playground — external link out to ENSAdmin

ENSNode Documentation

• rewrite the introduction 'What is ENSNode' to refocus on the 'ens developer platform' angle, highlight APIs over apps, discuss why indexers are necessary for your app.
• keep hosted instances but needs a redesign

move all of the following into a lower-level of prominence

• keep pull requests, releases

• keep terminology, but refactor as necessary to focus on currently-used omnigraph terminology

  • move subgraph-focused terminology to subgraph api documentation

• running ensnode locally for development needs a once-over

• self-hosting needs a full rewrite, remove the TODO/WIP sections and just be confident in what we do document

• drop 'Subgraph Compatibility Tooling'

• drop 'ENS v2 Notes'

• drop 'Indexing ENS-Compatible On-Chain Names'

Legacy Subgraph API Documentation

• low billing
• keep ensjs integration, drop 'viem/chain'
• subgraph-specific terminology
• refactor querying best practices
• move the 'Mainnet-Registered Subnames of Subregistries' document to here or honestly just drop it

ENSAwards

pretty clear 'ensv2 readiness' checks + season push

Unified Documentation

We should have a single documentation destination, either Mintlify (in-progress) or Astro/Starlight (current).

Pros for mintlify include:

• very pretty defaults
• interactive request playground
• auto-generated by openapi spec

Cons for mintlify include:

• no graphql support whatsoever
• minimally extensible (i.e. not extensible enough to support a custom graphql api explorer)
• no programmatic deployments (extremely annoying devops)
• we already have our existing documentation files in astro/starlight

Pros for starlight:

• we're already using it
• devops is relatively straightforward (vercel)
• extremely extensible (it's just astro, react, can import third-party modules, etc)

Cons for starlight:

• the starlight-openapi project is nice but doesn't support interactive playground for http requests
• no good graphql documentation generation plugin

Doubling Down on Starlight

mintlify's openapi rendering is beautiful and i like their request playground a lot, but it's not flexible enough for the rest of our documentation, mainly due to the custom work necessary to make the graphql api docs really good. with @scalar/astro now available, we have a beautiful openapi renderer with inline execution that works well within astro, so we can refocus on a single documentation framework/platform

• biome/astro/starlight/everything to latest
  • enable biome experimental html support, re-enable organizeImports, reformat entire project
  • ensure formatting and typechecking works well within .astro files
• @scalar/astro component for OpenAPI Reference Pages
• custom CSS to remove the .scalar-mcp-layer element
• custom styling to match existing starlight theme
• custom configuration to tailor the component to our needs
• ensure we have llms.txt and llms-full.txt being auto-generated by our starlight
• run a major /simplify across the docs codebase or ask claude to do a configuration audit
• publish an ensnode docs skill that includes knowledge of how to interact with the apis (skill.md)