Skip to content

Document guren.dev with its own OKF bundle, then publish that graph instead of the example's #459

Description

@7nohe

Follow-up to #454, which publishes a static docs-viewer snapshot at guren.dev/_guren/docs. That snapshot is built from examples/blog, because the site itself has nothing to show: web/ has no docs/ at all.

The stronger claim is the site documenting itself. A visitor reading "your app's knowledge graph" on a page that is a Guren app should be able to open that app's own graph, not a sample's — and unlike the example, it keeps growing as the site does.

What the site's graph looks like today

Running guren spec:generate in web/ and reading the graph back:

nodes 11  edges 8
  doc:docs/spec/{domain,er,modules,screens}.md
  code:db/schema.ts, app/Models/, routes/, modules/,
       app/Http/Controllers/, resources/js/pages/, (all source files)

No entity nodes, no ADRs, no document-to-document edges: entity nodes come from the entities: frontmatter of hand-written docs, so a bundle of generated views alone produces a skeleton. The blog example's bundle is 21 nodes / 18 edges and exercises every node kind, which is why #454 ships that one.

What this needs

  1. ADRs for guren.dev. The decisions are real and mostly already argued in code comments (Workers + D1, the cookie-less Analytics Engine middleware, prerendering docs into static modules at build time, the admin allowlist). The comments are a starting point, not a source: each ADR has to state the reason the decision was actually made.
  2. Commit web/docs/spec/ and gate it. check --spec runs for examples/blog only (ci.yml). Publishing the site's spec views without a drift gate means the page whose whole claim is "checked" can serve a spec that no longer matches the code it describes.
  3. Point the snapshot at the new bundlebundleRoot in web/scripts/prerender-docs-viewer.ts — or publish both, one URL each, if the example is still worth showing as a teaching bundle.

Notes

  • The generator already refuses to publish a bundle with no nodes or edges, so a misresolved root fails the build rather than shipping a blank screen.
  • examples/blog/** is a deploy trigger as of feat(web): publish the docs viewer's graph at guren.dev/_guren/docs #454; if the published bundle moves to web/, that trigger can go back to being about the example only.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions