Upgrade the docs site to VitePress 2 and add a custom landing page#809
Merged
Conversation
Previously, JSR reference plugins were applied in their original order, causing packages later in the list to override packages earlier in the list when both matched the same reference. Reversing the application order ensures that packages listed first take precedence, as intended.
Move the documentation site from VitePress 1.6.3 to 2.0.0-alpha.17 (the latest "next" release) and replace the stock default theme with a distinctive Fedify identity. Build/tooling: - Bump VitePress to 2.0.0-alpha.17 (Vite 7, Vue 3.5, Shiki 3), and move @shikijs/vitepress-twoslash to 3.x to match Shiki; bump the group-icons and llms plugins to compatible releases. - Preload the languages used in JSDoc example code fences via markdown.languages: Shiki 3 no longer lazily loads them while Twoslash renders hover tooltips, which otherwise broke the build. - Allow vitepress-plugin-mermaid's unmet VitePress peer in pnpm-workspace.yaml; it has no VitePress 2 release yet, but the withMermaid wrapper works under 2. - Add @fontsource-variable/bricolage-grotesque (display font) and lucide-vue-next (feature icons). Design: - Derive a contrast-checked brand palette from the logo (its blues are Tailwind's sky scale) and apply it through the default theme's CSS variables; use Bricolage Grotesque for headings and the hero. - Replace the default home layout with a custom landing page (HomeLanding.vue): a narrative hero with a federated-network illustration, package-manager install tabs (npm/pnpm/Yarn/Deno/Bun) and a "runs on" runtime strip (Node.js, Deno, Bun, Cloudflare Workers), a feature grid using Lucide icons and the official ActivityPub logo, a code showcase, an interop section, and a closing call to action. - Drop the "Quick demo" playground link from the Tutorials menu. Assisted-by: Claude Code:claude-opus-4-8
The landing page's "Batteries included" feature grid largely duplicated the "Why Fedify?" spec stack, so fold the two together. - Remove the feature grid section (component data, markup, and CSS). - Give each spec in the stack its own vector icon in place of the generic check mark: the official ActivityPub logo, plus Lucide icons (braces, file-pen, signature, user-search, server, badge-check, link) for the rest. - Annotate specs that have a formal designation with a small muted monospace id (e.g. RFC 9421, FEP-8b32, draft-cavage-http-signatures-12) and add Activity Streams 2.0, linking each row to its manual page. - Re-balance the alternating section backgrounds now that a section is gone, and tighten the stack rows on mobile so they stay compact instead of wrapping into bulky two-line rows. Assisted-by: Claude Code:claude-opus-4-8
Replace the text chips in the landing page's "Plays well with others" section with a monochrome logo wall, where each logo links to that project's official website in a new tab. - Most marks are inline currentColor SVGs from Simple Icons (Mastodon, Misskey, Lemmy, Pleroma, PeerTube, Pixelfed, Ghost). - Akkoma and Hollo aren't in Simple Icons, so their SVGs are vendored under docs/public/logos/ (from the FediverseIconography project) and rendered through a CSS mask so they also follow currentColor and adapt to light and dark themes. Assisted-by: Claude Code:claude-opus-4-8
Add a "Works with your stack" section to the landing page to highlight one of Fedify's strengths: it slots into the web framework you already use, and even without a first-party package it is easy to wire up yourself because it is built on the web-standard Request and Response. - Show a logo wall of the frameworks with an official integration package (Express, Fastify, Koa, Hono, h3, Nuxt, SvelteKit, NestJS, Next.js, Astro, SolidStart, Fresh), each linking to its section in the integration manual. - Add a "No official package? No problem." callout with a compact custom-middleware snippet, linking Request and Response to MDN and pointing to the custom middleware guide. See: https://github.com/fedify-dev/fedify/blob/main/docs/manual/integration.md Assisted-by: Claude Code:claude-opus-4-8
Highlight another of Fedify's strengths: reliable activity delivery through a message queue, and the variety of broker backends it can run on. - Three points: activities are queued and retried with exponential backoff; a two-stage fan-out keeps delivery to large audiences fast while retrying each inbox independently; and the queue backend is pluggable. - A broker logo wall (Redis, PostgreSQL, RabbitMQ, MySQL, MariaDB, SQLite, Deno KV, Cloudflare Queues, and more), each linking to its section in the message queue manual. - Re-balance the alternating section backgrounds for the inserted section. See: https://github.com/fedify-dev/fedify/blob/main/docs/manual/send.md See: https://github.com/fedify-dev/fedify/blob/main/docs/manual/mq.md Assisted-by: Claude Code:claude-opus-4-8
Highlight that Fedify is instrumented with OpenTelemetry out of the box, which is invaluable when operating a federated server in production, with detailed structured logging as a bonus. - Spell out the appeal: distributed traces for every operation, metrics for delivery, queue depth, signature verification, and more, export to any OTLP backend, plus traceable structured logs through LogTape. - Pair the copy with a trace-waterfall mock built from real Fedify span names, rather than a fourth logo wall, for visual variety. - Link to the OpenTelemetry manual, and keep the alternating section backgrounds intact by inserting the section before the call to action. See: https://github.com/fedify-dev/fedify/blob/main/docs/manual/opentelemetry.md See: https://github.com/fedify-dev/fedify/blob/main/docs/manual/log.md Assisted-by: Claude Code:claude-opus-4-8
Showcase Fedify's core Vocabulary API: type-safe ActivityPub objects backed by a real JSON-LD processor, so applications never have to deal with JSON-LD's rough edges themselves. - A normalization demo drives the point home: the four equivalent JSON-LD forms of "to" (a compact string, an array, a full IRI, and an array of the full IRI) all read back as one typed value through the accessor. - A second snippet contrasts the id accessor (no network request) with the dereferencing accessor that fetches and hydrates a remote object, e.g. actorId versus getActor(). - A check list covers standard-compliant output, form normalization, the getActor()/getObject() dereferencing accessors, and the origin-based security model (FEP-fe34), linking the FEP. - Re-balance the alternating section backgrounds for the inserted section, and share the check-list styles with the observability section. See: https://github.com/fedify-dev/fedify/blob/main/docs/manual/vocab.md Assisted-by: Claude Code:claude-opus-4-8
Highlight that Fedify is ready for the ActivityPub API, i.e. the client-to-server (C2S) side of the protocol, which is something of a holy grail in the fediverse. - Explain that POST requests to an actor's outbox are routed through typed listeners and authorized however the application likes, so clients speak the standard ActivityPub outbox rather than a bespoke API. - A check list covers typed outbox listeners, the authorize() hook for pluggable authentication, and the standard-not-bespoke benefit. - Pair the copy with an outbox.ts demo using setOutboxListeners(), on(Create, ...), and authorize(). - Place it as the closing capability before the call to action, which also keeps the alternating section backgrounds intact. See: https://github.com/fedify-dev/fedify/blob/main/docs/manual/outbox.md Assisted-by: Claude Code:claude-opus-4-8
Mention that help is available from the Fedify community, which is one of the project's appeals, as a short closing line in the call-to-action band. The line points to GitHub Discussions and the Matrix chat space, and notes that questions can be tagged with #Fedify in the fediverse. It sits just above the sponsors line so the community comes first. See: https://github.com/fedify-dev/fedify/blob/main/README.md Assisted-by: Claude Code:claude-opus-4-8
Add a "Backed by an investment from" strip to the bottom of the docs landing page that credits the Sovereign Tech Agency, whose Sovereign Tech Fund invested in Fedify. The credit shows the official Sovereign Tech Agency logo rather than a plain text wordmark. The SVG was taken from the agency's own site, had its framework-specific fill classes stripped, and a solid fill baked in so it can be used as a CSS mask. Rendering it through a mask with background-color: currentColor lets the mark follow the active theme, appearing dark on the light theme and light on the dark theme, and turn the brand color on hover. The link points at the project's page and carries an aria-label for accessibility. https://www.sovereign.tech/tech/fedify
On wide desktop screens the hero's right column has space to spare, so the artwork looked a little small. Add a min-width: 1080px rule that grows the hero artwork to fill more of the column and bumps the Fedify mark at its center from 38% to 42%, giving the logo noticeably more presence (about 167px to 210px wide) while the surrounding rings and nodes scale with it. The rule is gated behind the breakpoint and bounded by the column, so tablet and mobile layouts are untouched and the artwork cannot overflow. Assisted-by: Claude Code:claude-opus-4-8
Tune the landing page wording so Fedify reads as what it is, a
full-featured framework for federation rather than merely an ActivityPub
or protocol library, while making clear that it stays modular and does
not impose an application architecture.
The change touches the few beats that carry positioning, leaving the
feature sections to demonstrate the breadth on their own and keeping the
existing plain, non-promotional voice:
- Hero lede now opens with "a TypeScript framework that handles
federation, signatures, discovery, activity vocabulary, and delivery
behind type-safe APIs" and adds that it is modular, so you can adopt
the whole thing or just the parts you need and it never dictates how
your app is built.
- The "What's Fedify?" headline changes from "One library that lets
your app speak to the entire fediverse" to "A federation framework,
not just a protocol library," and its body lists what Fedify covers
before noting it is that broad yet modular and won't decide how the
rest of your app is structured.
- The frameworks section leads with "Fedify doesn't take over your
app," reinforcing that it runs as middleware alongside your existing
routes, and the heading now says "web framework" to avoid clashing
with Fedify-as-framework.
Assisted-by: Claude Code:claude-opus-4-8
Following a holistic review of the landing page, add the capabilities it
undersold, broaden the tooling story, and regroup the sections so related
beats sit together.
Content:
- Add a data-ownership section ("Your data, your schema"): your actors,
posts, and followers stay in your own database and schema, read
through dispatcher callbacks, while Fedify keeps only its internal
state in a pluggable KvStore (in memory, or Redis, PostgreSQL, MySQL,
SQLite, Deno KV, or Cloudflare Workers KV). This is the clearest proof
of the framework-yet-modular positioning.
- Broaden the CLI section into a developer-tooling beat: add the
fedify tunnel command, and mention @fedify/lint (catches common
federation mistakes) and @fedify/debugger (a live inbox and outbox
dashboard) so the whole development loop is visible.
- Drop the lone first-person voice ("We implement it" becomes "Fedify
implements it") and the mild overclaim "every time" from the
vocabulary point.
Order:
- Pair the two "fits into your app" beats by moving the data-ownership
section up next to the web framework section (your framework, then
your data), which also separates the framework and interop logo walls
with a text section for better rhythm.
- Move the CLI tooling beat ahead of observability, following the
natural build-then-operate progression.
- Section background banding still alternates throughout.
Assisted-by: Claude Code:claude-opus-4-8
Assisted-by: Codex:gpt-5.2-codex
The vocabulary, observability, and ActivityPub API sections marked each list item with the same generic checkmark, which read like a checkbox and carried no meaning. Replace it with a per-item Lucide icon, drawn from the lucide-vue-next set already used by the stack and delivery sections, and restyle the icon badge to match those sections (a brand colored line icon on a soft tint with a subtle border) rather than the solid blue check. Icon choices: - Vocabulary: badge-check, shapes, external-link, shield-check. - Observability: activity, gauge, plug, scroll-text. - ActivityPub API: webhook, key-round, blocks. Every icon name was checked against the installed lucide-vue-next declarations before use, and all three sections were verified in light and dark. Assisted-by: Claude Code:claude-opus-4-8
✅ Deploy Preview for fedify-json-schema ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: ASSERTIVE Plan: Pro Run ID: ⛔ Files ignored due to path filters (2)
📒 Files selected for processing (2)
📝 WalkthroughWalkthroughUpgrades the docs site from VitePress 1 to VitePress 2 alpha, adds a custom ChangesVitePress 2 Upgrade and Custom Landing Page
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request upgrades VitePress to version 2 (alpha) along with its related plugins, introduces a custom home landing layout (HomeLanding) with custom brand styling and the Bricolage Grotesque font, and preloads markdown languages to prevent rendering errors. Additionally, several SVG logos are added, and peer dependency rules are adjusted for compatibility. Feedback on the changes highlights that the newly added lucide-vue-next package is deprecated and suggests replacing it with the official @lucide/vue package.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
Codecov Report✅ All modified and coverable lines are covered by tests. 🚀 New features to boost your workflow:
|
The docs landing page imported its icons from lucide-vue-next, which npm
now marks as deprecated ("Package deprecated. Please use @lucide/vue
instead."). Move the dependency to @lucide/vue and update the import in
the landing page component; every icon the page uses exists in the new
package.
The package was pinned at ^1.20.0, the current release. The review
suggested ^0.475.0, but that version predates the rename and is not the
latest.
fedify-dev#809 (comment)
Assisted-by: Claude Code:claude-opus-4-8
Member
Author
|
/gemini review |
Contributor
There was a problem hiding this comment.
Code Review
This pull request upgrades VitePress to version 2 (alpha) and introduces a custom landing page layout (HomeLanding) along with brand theming, display typography (Bricolage Grotesque), and new SVG logos. It also updates dependencies, configures preloaded languages in docs/.vitepress/config.mts to prevent Shiki highlighting errors, and adds peer dependency rules for Mermaid. Feedback suggests sorting the newly added languages array alphabetically to improve maintainability.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
The site used GitHub's generic repository preview as its og:image, so shared links carried no brand identity. Replace it with a 1200x630 card (docs/public/og.png) that matches the new landing page: the logo, the Fedify wordmark in the brand gradient, the "Build for the fediverse, skip the boilerplate." tagline, and a fedify.dev footer. Point og:image at the new card and add og:image:width, height, type, and alt, og:type, and twitter:card (summary_large_image) with twitter:image so it renders as a large card on services that read the Twitter tags. The image URL is absolute against fedify.dev, as Open Graph requires. Assisted-by: Claude Code:claude-opus-4-8
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/.vitepress/config.mts (1)
377-379: 🧹 Nitpick | 🔵 Trivial | ⚡ Quick winConsider adding a comment explaining why plugins are reversed.
The reversal of
jsrRefPluginsaffects the order in which plugins process markdown. Adding a brief comment explaining why reverse order is necessary would help future maintainers understand this non-obvious choice.📝 Suggested comment
- for (const jsrRefPlugin of jsrRefPlugins.toReversed()) { + // Register JSR ref plugins in reverse order so that more specific packages + // (e.g., `@fedify/vocab`) take precedence over broader ones (e.g., `@fedify/fedify`). + for (const jsrRefPlugin of jsrRefPlugins.toReversed()) { md.use(jsrRefPlugin); }🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/.vitepress/config.mts` around lines 377 - 379, The loop that iterates through jsrRefPlugins using toReversed() lacks a comment explaining why the plugins must be processed in reverse order, which is non-obvious to future maintainers. Add a brief comment immediately before the for loop that explains why jsrRefPlugins.toReversed() is necessary and how the reverse order affects the plugin processing behavior, making the code's intent clear to developers who maintain it later.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@docs/.vitepress/config.mts`:
- Around line 377-379: The loop that iterates through jsrRefPlugins using
toReversed() lacks a comment explaining why the plugins must be processed in
reverse order, which is non-obvious to future maintainers. Add a brief comment
immediately before the for loop that explains why jsrRefPlugins.toReversed() is
necessary and how the reverse order affects the plugin processing behavior,
making the code's intent clear to developers who maintain it later.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 7069c939-1bc2-4b74-a5db-7aae87b20a8f
⛔ Files ignored due to path filters (1)
docs/public/og.pngis excluded by!**/*.png
📒 Files selected for processing (1)
docs/.vitepress/config.mts
On narrow screens the landing page code samples were cut off on the right. The non-wrapping <pre> blocks have overflow-x: auto, but their grid and flex tracks lacked min-width: 0, so instead of scrolling the blocks widened past the viewport and the page's overflow: clip cut them off. Add min-width: 0 to the code window, the terminal, and the vocabulary demo column so each block stays within its column and the existing horizontal scroll engages. On phones the samples no longer fit on one line at all, so wrap them there rather than scrolling: at most 600px wide the code switches to white-space: pre-wrap with overflow-wrap: anywhere, which also breaks otherwise unbreakable tokens such as the full ActivityStreams IRI in the vocabulary demo. The desktop layout is unchanged. Assisted-by: Claude Code:claude-opus-4-8
The og:image and twitter:image tags were hard-coded to https://fedify.dev/og.png, the stable host. The docs also deploy to an unstable site and to PR previews, each built with SITEMAP_HOSTNAME set to its own URL, and og.png only reaches the stable site on a tagged release. So those non-stable deploys served pages whose image tag pointed at fedify.dev, where the file did not exist yet, which is the 404. Derive the absolute image URL from SITEMAP_HOSTNAME (falling back to https://fedify.dev/ for local builds) so it matches whichever host is serving the page. The og.png itself lives in docs/public, so every build already emits it at the site root. Assisted-by: Claude Code:claude-opus-4-8
BotKit, a framework for building ActivityPub bots, and DrFed, a web-based ActivityPub debugging platform, are sister projects built on Fedify by the same team. Add a quiet line to the landing footer, under the community and sponsors lines, that links to both with their small logos. It is deliberately understated rather than a feature section, so it reads as a footnote about the wider family rather than competing with Fedify's own pitch. Assisted-by: Claude Code:claude-opus-4-8
Contributor
|
Pre-release has been published for this pull request: Packages
DocumentationThe docs for this pull request have been published: |
A review noted that the jsrRefPlugins.toReversed() loop gave no reason for iterating in reverse, which is easy to misread as accidental. Add a comment recording the rationale behind the earlier priority fix: the package list is ordered by precedence, but a later-registered jsrRef plugin overrides earlier ones for the same reference, so the plugins are applied in reverse to let the first-listed package win. No behavior change. Assisted-by: Claude Code:claude-opus-4-8
sij411
approved these changes
Jun 18, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Here's the preview: https://2ff11e56.fedify.pages.dev/.
The documentation site has been running on VitePress 1.6.3 with the stock default theme. It works, but it still looks like a default VitePress site: the home page is the stock hero above a grid of one-line feature cards, and nothing carries Fedify's colors. This PR upgrades VitePress to the 2.0 line, applies a Fedify color and type palette across the whole site, and replaces the home page with a custom landing page. The manual and reference pages are otherwise unchanged.
VitePress moves from 1.6.3 to 2.0.0-alpha.17, and the plugins that have to move with it do. The Twoslash plugin follows Shiki up to 3.x, and the group-icons and llms plugins are bumped to releases built against VitePress 2. Mermaid has no VitePress 2 release yet, so it stays at 2.0.17 with a peer-dependency override in pnpm-workspace.yaml; pnpm only warns on the unmet peer, and
withMermaidstill wraps the config cleanly. Shiki 3 is stricter about languages it has not been told to load, and Twoslash re-highlights the code it finds in hover tooltips, so docs/.vitepress/config.mts now preloads the languages used across the docs. The same change also corrects the priority order of the JSR ref plugin.The branding lives in a new docs/.vitepress/theme/brand.css, wired up from docs/.vitepress/theme/index.ts. The logo's blues turn out to be Tailwind's sky scale, so the brand tokens are built from sky with contrast-checked steps for light and dark. Those tokens set the link, button, and accent variables that the default theme already reads. A display typeface, Bricolage Grotesque, is self-hosted through Fontsource and applied to the hero and to the
h1throughh3headings; body text, navigation, and the sidebar keep the readable base font.The landing page is one component, docs/.vitepress/theme/components/HomeLanding.vue, rendered as a custom layout through frontmatter in docs/index.md. It drops the default feature grid for a single narrative. In order, it covers what Fedify is, the ActivityPub-related specifications it implements, a code sample, the type-safe vocabulary API, queued delivery and fan-out, web framework integration, pluggable storage, interoperability with existing software, the CLI and debugging tools, OpenTelemetry, and the client-to-server ActivityPub API, then closes with a short community note and a credit to the Sovereign Tech Agency.
The copy presents Fedify as a framework rather than only a protocol library, but a modular one: an application uses the parts it needs and keeps its own routes, database schema, and queue backend. The artwork uses the Lucide icon set and CC0 Simple Icons. No emoji, no hand-drawn shapes. Third-party logos render through CSS masks so they take the current text color and follow light and dark, and a few are vendored under docs/public/logos/.
This is docs-site work. It does not touch the library and needs no CHANGES.md entry. The production docs build passes, and the new landing page was checked in both light and dark themes.
The following is the new Open Graph image: