Repo: unify docs with e18e and awesome-e18e

[43081j]

We currently have the following resources:

• this repo (replacement manifests, legacy docs)
• the e18e site (replacement docs)
• awesome-e18e (recommended libs/tools, including the ones in this repo)

It would be nice if we could come up with a way that all docs and replacements exist in this repo, but get synchronised into the e18e site.

similarly, if the awesome-e18e list was curated and synchronised with the modules in this repo (since it needs non-replacement recommendations too - useful tools and what not).

this suggests replacements need:

• a human readable category (e.g. "CLI tools")
• a script to sync them up into the e18e site repo (probably should live in the e18e repo)

[outslept]

Hmm.. For 1 maybe keep human‑readable names centralized in json and reference categories by slug everywhere else. The generator resolves slugs to titles and CI fails on unknown slugs

// awesome-items.json
{
  "categories": [
    { "slug": "assertions", "title": "Assertions" },
    { "slug": "data-structures", "title": "Data Structures" },
    { "slug": "cli", "title": "Command Line Interfaces (CLI)" },
    { ... }
  ],
  "items": [
    {
      "name": "clack",
      "url": "https://github.com/bombshell-dev/clack",
      "description": "CLI framework for building interactive prompts.",
      "category": "cli",
      ... 
    },
    { ... }
  ]
}

For e18e website: edit mr to keep frontmatter in a comment at the top of each doc. For diffs: author them as fenced unified diff blocks; the e18e build converts “- / +” lines into [!code --]/[!code ++] and renders them as TypeScript by default.

What we'll have in this repo:

import { Buffer } from 'node:buffer'
- import bufCompare from 'buf-compare'

const buf1 = Buffer.from('303')
const buf2 = Buffer.from('808')

- bufCompare(buf1, buf2)
+ Buffer.compare(buf1, buf2)

What we should get in e18e/e18e

import { Buffer } from 'node:buffer'
import bufCompare from 'buf-compare' // [!code --]

const buf1 = Buffer.from('303')
const buf2 = Buffer.from('808')

bufCompare(buf1, buf2) // [!code --]
Buffer.compare(buf1, buf2) // [!code ++]

I haven't come up with any other way to preserve the diffs, I don't mind removing them though

[43081j]

that could work

the docs we already put in e18e are the source of truth right now, so we'd basically copy those here and overwrite the ones that exist. then update the diffs to be github-friendly, then transform them during sync like you say.

all snippets will be JSON or typescript so the ts language should work fine

for the slugs, you're probably right that it shouldn't be a human readable name as the consumer should decide that