Skip to content

Rebuild the docs on Next.js + Fumadocs under /docs, with the Worker that puts the Hub on pelican.dev - #234

Draft
alexevladgabriel wants to merge 23 commits into
mainfrom
feat/fumadocs-next
Draft

alexevladgabriel wants to merge 23 commits into
mainfrom
feat/fumadocs-next

Conversation

@alexevladgabriel

@alexevladgabriel alexevladgabriel commented Nov 2, 2026 •

Copy link
Copy Markdown
Member

Note

🤖 Claude Opus 5.5 responding on behalf of Scai

Moves the docs from Docusaurus to Next.js 16 + Fumadocs 16 (static export, still on Netlify) in the redesign's style, served under /docs. The rest of pelican.dev moves to the Pelican Hub. #239 (the /docs layout and the Cloudflare Worker) was merged into this branch, so this PR is now the whole docs side of the one-site pelican.dev.

Draft on purpose: merging this into main makes Netlify replace the live Docusaurus site. Hold it until launch day (router/README.md, "Switching pelican.dev over").

How pelican.dev works after the switch

Decided 15 November 2026: the Hub serves all of pelican.dev from Forge, the docs included. There's no Cloudflare Worker in front.

  • This repo packs each build (scripts/pack-docs.mjs):

    • the /docs files and _next/;
    • _root/ with the five root files (/llms.txt, /llms-full.txt, /update-panel.sh, /migrate-panel.sh, /migrate-wings.sh);
    • 404.html;
    • redirects.json, exported from netlify.toml.

    The "Publish docs build" workflow pushes it to docs-build (from main) or preview/docs-under-docs (from this branch).

  • The Hub downloads and serves it on pelican.dev and hub-preview, behaving like the Netlify site. See pelican/hub#286 and its docs/DOCS_ON_FORGE.md; nginx can serve the files without PHP.

  • The Hub serves everything else: the homepage, /plugins, /eggs, /sponsor, /faq, accounts and the old short links (pelican/hub#248, #285).

  • Machine URLs never move: panels keep calling hub.pelican.dev for update.json, downloads and the API.

  • Netlify keeps building a deploy preview for every PR.

  • Later, if needed: the Cloudflare Worker in router/worker.mjs (built, tested, not deployed) splits pelican.dev between Netlify and the Hub, for when the docs must survive a Hub outage.

What's in this PR

  • Docs: all 34 pages, now under /docs.
    • Light and dark themes, search built into the site (no server), and the "Your setup" box on Webserver Config.
    • <Admonition>, <Tabs>, <TabItem> and <Link> keep their Docusaurus names, so the MDX reads the same.
  • Old URLs: all 38 /docs/… URLs in production's sitemap still resolve: 35 directly, and 3 old disk-quota pages through redirects. netlify.toml has 22 redirects. /blog goes to the homepage for now (302); the Hub does the same after the switch.
  • Publishing for the Hub: scripts/pack-docs.mjs (with pack-docs.test.mjs) and .github/workflows/publish-docs.yml.
  • The Worker, for later:
    • router/worker.mjs with wrangler.toml and worker.test.mjs;
    • router/dev-server.mjs makes the same split locally;
    • router/README.md has the production setup (Forge) first, then the Worker steps.
  • Interim pages until the switch: the homepage, /eggs, /support and /faq are still in this build, so pelican.dev keeps working if this merges before the Worker is on. scripts/check-paths.mjs fails the build if a file lands outside /docs, the root files or that interim list. Remove them after the switch.
  • hub-preview: the publish workflow sends this branch's build to preview/docs-under-docs, so hub-preview.pelican.dev/docs shows it with the Hub's pages.
  • Tooling:
    • Installs and builds run on Bun (bun.lock, Node 22 for Next).
    • CI runs the content check, its 27 tests, the 11 router tests, the 2 pack tests, typecheck and build.
    • scripts/sync-eggs.mjs refreshes the interim /eggs data before a build.

Checked

  • CI is green on every push to this branch.
  • Locally on 1e6aafa:
    • bun run test:content gave 27 passed and bun run test:router 11 passed;
    • bun run build exports 34 docs pages, and the path check passes.
  • The Worker under wrangler dev (workerd), against the real Netlify site and Hub:
  • hub-preview serves this build under /docs next to the Hub's pages, with links working both ways.

Not verified / to decide

  • The switch itself: it needs Forge and DNS access, following pelican/hub#286's guide. The nginx block there is untested on Forge.
  • Browsers: not tested on real phones or in Safari or Firefox; screenshots come from headless Chrome.
  • Lance's Read .env with phpdotenv in update-panel.sh #238 (update-panel.sh reads .env with phpdotenv) targets main. If it merges first, main gets merged in here so the new site serves the same script.

Note

Move pelican.dev from Docusaurus to Next.js + Fumadocs with V12 redesign

  • Replaces Docusaurus with Next.js (App Router, static export to out), Fumadocs, Tailwind CSS 4, Shiki, and Mermaid; requires Node.js 22 and pnpm
  • Migrates all documentation to content/docs and content/pages with Fumadocs collections (source.config.ts), frontmatter titles, and meta.json sidebar order
  • Adds new V12 landing pages: interactive hero console, egg finder and filterable egg index backed by a synced Pelican Hub catalogue, plugin stage, release log, and support/sponsorship page
  • Provides setup-aware docs: a SetupPanel stores domain, path, web server, and PHP choices in localStorage, and setup-flagged code blocks substitute those values (lib/shiki-setup.ts)
  • Adds an ExternalLinkGuard that confirms before opening non-Pelican sites, plus Netlify build config with permanent redirects for short links and legacy docs paths
  • Risk: static/ assets moved to public/ and legacy doc URLs rely solely on the redirects in netlify.toml; old Docusaurus URLs not covered there will 404

Macroscope summarized 8554df8. (Automatic summaries will resume when PR exits draft mode or review begins).

- Docusaurus replaced by Next.js 16 + Fumadocs 16 static export (Netlify), content
  moved to content/docs with Docusaurus-compatible Admonition/Tabs/Link components
- Homepage, /eggs, /support, /faq and 404 rebuilt in the V12 B v3 design
- Docs themed to match, light and dark, with the B v3 top bar
- /eggs generated from the pelican-eggs index (scripts/sync-eggs.mjs): one card
  per real game, Steam art and icons, Hub links, search, sort and filters
- SetupPanel fills the reader's domain/web server/PHP/path into config blocks
- Leaving-site confirmation for links outside Pelican-owned sites
- netlify.toml with build settings and real 301 redirects
@netlify

netlify Bot commented Nov 2, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for pelica ready!

Name Link
🔨 Latest commit 2113c0b
🔍 Latest deploy log https://app.netlify.com/projects/pelica/deploys/6aff93364dfa1fef654bce2a
😎 Deploy Preview https://deploy-preview-234--pelica.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@coderabbitai

coderabbitai Bot commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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.

Share

@macroscopeapp

macroscopeapp Bot commented Nov 2, 2026 •

Copy link
Copy Markdown

Macroscope skipped reviewing this pull request. Per-review cost limit exceeded (workspace setting).

This review would cost an estimated $30.61, which exceeds your per-review limit of $10.00.

The top 3 files driving up this estimate:

File Diff Size Estimate
app/(landing)/home.css 91.58KB $5.49
lib/og-image.tsx 44.64KB $2.68
scripts/sync-eggs.mjs 37.93KB $2.28

Tip

To get this pull request reviewed, you can:

  1. Comment @macroscope-app on this PR to request a manual review (monthly spend limits still apply).
  2. Exclude the file(s) above from review by adding a pattern to your .macroscope/ignore.md — note that creating this file replaces Macroscope's built-in default ignores rather than extending them.
  3. Raise your cost limit in your workspace billing settings.

Turn off this reminder going forward

alexevladgabriel and others added 8 commits November 3, 2026 00:09
- SEO: per-page titles, descriptions, canonicals and social cards (lib/og.ts),
  sitemap.xml, robots.txt, JSON-LD (Organization, WebSite, SoftwareApplication,
  TechArticle, BreadcrumbList, FAQPage), descriptions for all docs pages
- AI: /llms.txt, /llms-full.txt and a Markdown copy of every docs page
  (/docs/<page>.md via a Netlify rewrite)
- OG images: 1200x630 PNGs for every docs page and site page, B v3 style
- /eggs: list with a row per game and an in-site details dialog per egg
  (variables, images, startup, ports, install script), lazy per-egg JSON;
  Hub kept for Install to Panel; duplicate eggs dropped; search, sort, filters
- Fix the docs welcome page's Contributors link
On deploy previews, og:image/twitter:image used https://pelican.dev, where the
images don't exist yet. Netlify's CONTEXT and DEPLOY_PRIME_URL now pick the
preview's own origin; canonicals stay on pelican.dev. Previews also get
noindex and a disallow-all robots.txt so they never compete with production.
- Site images with a real visual each: home console, eggs icon grid with the
  real egg count, support plan bars, FAQ question and answer, docs index chart
- Docs images: per-section colour and icon, title and description, and a
  window of real lines from the page (checked against the MDX at build time)
- Titles and descriptions measured with the real fonts; PNGs palette-encoded
  (all 38 now 991 KB, 20-45 KB each); JetBrains Mono added (OFL)
A light/dark switch in the nav (and the phone menu) that follows the
system setting by default and is shared with the docs. Dark styles keep
the V12 board: navy grounds, sky borders and offset shadows. Covers the
homepage, /eggs and its egg dialog, /support, /faq, 404 and the
leaving-site dialog. All text meets WCAG AA contrast.

Also moves the GitHub links out of two headings on /docs/, which
rendered as a link inside the heading's anchor link.
Dark mode drew four dividers (announcement bar, games section, final
call-to-action, the /support "Give once" band) as 3px borders that light
mode doesn't have, so switching theme pushed the page down by 3 to 9px.
They're inset shadows now, which take no space; light mode is unchanged.

The /docs/ diagram showed its source text (240px) and then jumped to the
drawn size. It now holds the diagram's 3:1 space while mermaid loads; the
source is still shown without JavaScript. Also stops a redraw from
deleting the diagram: mermaid removes any element with the id it's given,
and a class change on <html> that wasn't a theme change reused the id of
the diagram on the page.
- No Pterodactyl on the homepage: the hero and install migration notes
  and the "Not a reskin" fork framing are gone. 01 is now "Built to
  last.", about Pelican on its own terms. The migration guide stays in
  the docs.
- Features: "One box or a whole fleet" is a map of one panel wired to
  three example nodes, each with its game servers.
- Activity: an eggs stat, one line for the latest release instead of the
  release log, and a thank-you row for the top 10 contributors by
  commits since Pelican began (March 2024, bots left out).
- Sponsors are large logo cards (homepage and /support), with a "your
  logo here" card that points at the Company plan.
- Removed: the published funding plan (homepage and /support, to be
  redone), the "Run your servers. Help shape what's next." section, and
  the egg cards under the games strip. Game tiles now open that game's
  eggs on /eggs.
- Footer divider shows where it follows a navy section.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Pages copied from Docusaurus write :::note blocks tight (no blank lines
around the markers). Markdown reads that as one paragraph, which
remarkAdmonition doesn't match, so 16 callouts on 7 pages showed the
colons as text. Split the markers into their own paragraphs first, so
content merged from main works unchanged.
@alexevladgabriel

Copy link
Copy Markdown
Member Author

Note

🤖 Claude Opus 5.5 responding on behalf of Scai

This PR stays in draft. The docs part continues here: the move to Fumadocs with the pages kept in Markdown, search, callouts, and the Markdown copy of each page for AI tools.

The homepage and the other landing pages (/, /eggs/, /support/, /faq/) are being reworked separately and won't be merged from this PR. Until then they stay in the branch as a reference for the design.

The latest commit, 050a63618e, makes callouts written without blank lines around :::note render as boxes. That fixes 16 callouts on 7 pages, including the Podman warning that arrived with the merge of main. The Netlify build, header rules and redirect rules checks pass on head 050a63618ec9e07312d3e42d4c2c5dadc4ca2f2a.

Not verified: I checked the callouts on a local build in light and dark, but not on the deploy preview for this head.

README.md: keep this branch's Next.js/Fumadocs instructions, add main's Panel and Wings repo links, drop the Docusaurus lines. main's health endpoint and Wings version policy edits applied to the moved pages in content/docs/.
bun.lock is migrated from pnpm-lock.yaml with the same versions (Next
16.4.4, Fumadocs 16.17.10, React 19.3.1). pnpm's build allow-list becomes
trustedDependencies. CI and Netlify install with Bun and run the same
scripts with bun run; Next.js still builds on Node 22. A warm install
takes about 1s instead of 4s.
…239)

* feat: load everything the docs need from /docs/

pelican.dev will route only /docs/*, /llms*.txt and the install scripts to
this build; the Hub serves every other path.

- assetPrefix '/docs': pages load /docs/_next/...; the static export still
  writes out/_next/, so netlify.toml rewrites /docs/_next/* to it
- search index: app/api/search -> /docs/search.json (search client points there)
- Markdown copies: app/md -> app/docs/md (still served at /docs/<page>.md)
- docs share images: /og/docs/... -> /docs/og/...
- logo and favicon: /img/ -> /docs/img/
- /docs/sitemap.xml for the docs; /sitemap.xml keeps the landing pages
  (interim) and robots.txt lists both
- 301s from the old paths that other sites may link

* feat: share design tokens and site nav with the Hub

- ui/tokens.css: the V12 custom properties, font variables and dark tokens,
  moved out of home.css and global.css (both now read this one file)
- ui/nav.json: header items, footer columns and the call to action, with the
  Hub's paths (/plugins, /eggs, /sponsor) as site-relative links
- both published at /docs/ui/v1/ for the Hub to copy
- the docs bar and phone menu read their links from nav.json; while Netlify
  still serves the whole domain, netlify.toml sends /plugins and /sponsor
  where they live today (interim)

* feat: check the build stays under /docs/ and MDX runs no code

- scripts/check-paths.mjs (postbuild, check:paths): every file in out/ must
  be under docs/, one of the five root files, Netlify's, or on the INTERIM
  list (landing pages, each marked remove after the switch); docs pages must
  not load scripts, styles, images or share images from outside /docs/
- scripts/check-content.mjs (prebuild, check:content, CI): fails on MDX
  import/export or <script in content/, skipping code blocks

* feat: add a local router that serves pelican.dev as one site

router/dev-server.mjs (port 8020, no dependencies) serves /docs/* and the
five root files from out/ with Netlify's /docs/_next and .md mappings, and
proxies everything else to the Hub. router/README.md lists the paths and
sketches the Cloudflare Worker.

* feat: default to the dark theme

* fix: check MDX pages by parsing them, not by searching for import and <script

The content check only looked for import/export and <script, but MDX also
compiles {expressions} and {attribute values} into the site's JavaScript, so a
page with {(() => { while (true) {} })()} passed and would hang the build.

Each page is now parsed as MDX and checked against an allowlist: no
import/export, no {expression} except comments, only the components
mdx-components.tsx gives pages and a short list of HTML tags, no spread props,
on* handlers or dangerouslySetInnerHTML, attribute {values} only as literal data,
and no javascript:/vbscript:/data: URLs in JSX or Markdown links. All 35 pages
pass. scripts/check-content.test.mjs (pnpm test:content, in CI) covers 17 pages
that must fail and 7 that must pass.

An indented import/export is not blocked: @mdx-js/mdx 3 compiles it as a
paragraph of text, so the old comment saying otherwise was wrong.

* fix: check URLs in braced attribute values too

A braced value like href={'javascript:alert(1)'} passed as literal data
without its string being checked. Every string in literal data, nested
ones included, now goes through the same URL check as quoted values.

* fix(router): close the browser's response when the Hub cuts its own short

hubRes.pipe(res) leaves res open if the Hub's response ends early, so the
browser waited until it timed out. stream.pipeline closes it (and stops
the Hub's response if the browser leaves).

* fix(router): don't crash on a docs file that fails to open

createReadStream(full).pipe(res) left read errors unhandled, so a file
that couldn't be opened after stat() killed the router and with it the
Hub proxy. stream.pipeline ends that one response instead. The request
body now goes to the Hub through pipeline too, so a browser that aborts
an upload can't crash it either.

* feat(router): the Cloudflare Worker for pelican.dev, with tests and the switch steps

router/worker.mjs is the Worker router/README.md described: /docs/* and the
five root files from the Netlify site (pelica.netlify.app) without the
visitor's Cookie or Authorization and with Set-Cookie dropped, everything
else from the Hub with X-Forwarded-Host/-Proto/-Port/-For so it builds
pelican.dev URLs, and Next.js payload requests for Hub pages answered with
404 here. Redirects pass through (redirect: 'manual'); a Location on an
origin's own address (Netlify's trailing-slash 301s) becomes a path, so it
stays on pelican.dev.

router/worker.test.mjs (bun run test:router, now in CI) checks the routing
with fetch recorded. router/wrangler.toml holds the two origins, and the
pelican.dev/* route commented out for the switch. The README now lists the
switch in order, including the Hub settings, setting HUB_REDIRECT_HUMANS only
after TRUSTED_PROXIES (or every Worker request loops), and the rollback.

Run under wrangler dev (workerd) against the real origins: docs pages, the
301, /update-panel.sh, a Hub page, the 404 for a prefetch and 405 for a POST
to the docs all answered as above.

* fix(router): never let a // path pick the upstream host

Macroscope on #239 (critical): the Worker built the upstream URL with
new URL(path + query, origin), so a request for //attacker.example/ resolved
to https://attacker.example/ and the Hub request, with the visitor's Cookie
and Authorization, went there. The target is now the origin with the
visitor's path and query set on it (onOrigin()), for the docs and the Hub, so
the host is always one of the two. dev-server.mjs, which always proxied to its
fixed Hub, now parses the path the same way, so both routers agree on what a
//host/... path is.

Two new tests: //attacker.example/... (with a cookie) and /docs//attacker...
stay on hub.pelican.dev and pelica.netlify.app, and onOrigin() keeps the
origin and takes only the path and query. Under wrangler dev, //example.com/
is now answered by the Hub (404), not example.com.
#239 was merged into feat/fumadocs-next and its branch deleted, so the
preview build no longer ran. It now runs on feat/fumadocs-next (#234). It
still publishes to preview/docs-under-docs, so the Hub's preview settings
don't change, and the comment now says the Hub serves it from storage.
Until the Hub serves pelican.dev, this build answers every path there, and
the Docusaurus blog (in production's sitemap) would be a 404. /blog and
/blog/* now go to the homepage with a 302, as the Hub does after the switch
(pelican/hub#285).
@alexevladgabriel alexevladgabriel changed the title Move pelican.dev to Next.js + Fumadocs, with the V12 redesign Rebuild the docs on Next.js + Fumadocs under /docs, with the Worker that puts the Hub on pelican.dev Nov 15, 2026
… Forge

Decided: the Hub serves all of pelican.dev from Forge, the docs included, and
the Cloudflare Worker stays in router/ as the way to scale out later.

scripts/pack-docs.mjs packs out/ into what the Hub installs: the /docs files,
_next/, _root/ with the five root files (update-panel.sh, migrate-*.sh,
llms*.txt), the docs' 404.html, redirects.json (netlify.toml's 3xx rules
under /docs, so that file stays the one list) and BUILD.json.

The workflow (now publish-docs.yml) runs it and publishes main to docs-build
for production and feat/fumadocs-next to preview/docs-under-docs as before,
then asks that Hub to install it. Netlify keeps building pull requests.
router/README.md says which setup is production and lists the Forge steps;
the Worker steps are kept under "Switching to the Worker (later, if needed)".
Scai: "Let's go for bun and easy to read code." scripts/pack-docs.mjs now runs
on Bun: netlify.toml is read with Bun.TOML.parse instead of hand-written
matching, files are written with Bun.write, and the repo root comes from
import.meta.dir. Its tests run with bun test (bun:test). The workflow and the
package scripts call bun. The packed folder is the same: 6 redirects, the five
root files, 404.html, BUILD.json.
Scai: "We should make sure scripts are handled the same and easy to follow, for
new people and as well for agents."

- Every script in scripts/ and router/ runs on Bun (#!/usr/bin/env bun, and
  package.json calls bun), and starts with the same header: what it does in
  one line, then When:, Run: and Tests:, then the details.
- Every test is a <name>.test.mjs next to its code, written with bun:test
  (check-content and the Worker's tests move off node:test, keeping the page
  or path in the comparison so a failure still says which). `bun test` runs
  all 41; CI runs it as one step instead of three.
- package.json: test, dev:site (was preview:site, easy to confuse with
  Netlify's previews), check:*, sync:*, pack:*; the test:* scripts are gone.
- scripts/README.md lists every script (what, when, command, tests), what to
  run before a pull request and how to add one. README.md and AGENTS.md
  point there; the README also says pelican.dev is served by the Hub.
- The check-paths and dev-server headers no longer describe a Cloudflare route
  as production.

Checked: bun test (41 pass), bun run check:content, bun run build (prebuild and
postbuild on Bun), bun run pack:docs, bun run dev:site (/docs/ and
/update-panel.sh answer), bun run typecheck.
…e review's fixes

Three independent reviews scored the scripts (maintainability 6/10,
testability 5/10). This addresses their findings:

Shared paths: router/paths.mjs holds ROOT_FILES, isDocsPath, isNextPayload and
keepOnSite; check-paths, pack-docs, dev-server and the Worker import them
instead of keeping four copies.

Bugs:
- sync-eggs --if-online kept the saved data on any error, so a bug never
  failed the build. Now only network failures (NetworkError) do.
- pack-docs took netlify.toml rules for /docsfoo, and emptied whatever folder
  it was given (`pack:docs .` would delete the repo). It only takes /docs and
  below, and only writes to a folder named dist*.
- The Worker passed on a visitor's own X-Forwarded-For; both routers compared
  redirect Locations by prefix, so hub.pelican.dev.example.com counted as the
  Hub. Both fixed (keepOnSite compares origins).
- dev-server decided on the decoded path (/docs%2F... went to the docs, the
  Worker sends it to the Hub). It now decides on the path as sent and decodes
  only to find a file.
- check-paths counted one bad asset once per page that loads it.

Testability: every script's work is in exported functions, run under
import.meta.main. New tests for paths, dev-server (temp out/ and a fake Hub),
check-paths, pack(), sync-eggs' pure functions, and in check-content
vbscript:, a missing folder and COMPONENTS matching mdx-components.tsx.
bun test: 78 tests in 7 files (was 41 in 3), no temp folders left behind.
The publish workflow now runs bun test and the typecheck before it builds.

Readability: sync-eggs' timeouts, pool sizes and limits are named;
check-paths' hidden "ends with a dot" prefix rule is an explicit "*".
`start` (broken with the /docs asset prefix) is gone.

Docs: README and scripts/README say what to run before a pull request and
that the build rewrites the egg data; "Adding a script" covers hooking into
the build and testing; the Worker exception, the shared paths file, the
two-place MDX component list (noted in mdx-components.tsx too) and the
not-deployed Worker (wrangler.toml) are written down.
…second review pass

The re-review found that keepOnSite turned a redirect to
https://hub.pelican.dev//evil.example/x into //evil.example/x, which a browser
follows to another site. A path starting with // or /\ is now collapsed to one
slash (tested). Neither router is deployed.

Also from the second review:
- sync-eggs' header said --if-online "never fails the build"; it lists what
  really happens and every folder it writes (public/img/eggs/ was missing
  there and in README, AGENTS and scripts/README).
- README said the Hub serves the docs from Forge today; it's decided, not done.
- No hard-coded "five root files": ROOT_FILES in router/paths.mjs.
- pack-docs reads netlify.toml before emptying the output folder.
- check-paths uses isDocsPath from paths.mjs instead of a copy of its rule.
- scripts/README: paths.mjs is the second file without a shebang, and test
  files open with the command they're run with.
- dev-server takes a log function, so bun test no longer prints request lines.

bun test: 79 pass.
…th an AI assistant (#240)

* feat(docs): style the docs like the Hub's redesigned pages

The docs shared the header idea and tokens with the Hub's pages but still
drew hard offset shadows, rounded Fumadocs chrome and white code, so they
read as another site. They now use the Hub's pieces: square corners, 3px
edges on cards and controls, 2px rules, no offset shadows, navy code in both
themes, sky only as an accent.

- Top bar: the Hub nav's buttons, theme switch and search input; navy ground
  and a slate line in the dark theme.
- Sidebar and TOC: the Hub's app sidebar (light sky current item, sky edge)
  and the plugin page's section links.
- Page: the plugin page's kicker and title; the Hub's prose links, inline
  code chips, square lists, Markdown tables (3px edge, sky head).
- Code blocks: the egg page's navy install script, with Shiki's dark colours.
- Callouts: the Hub's alerts (3px edge, 8px tone edge). Tabs: the plugin
  page's tabs. "Your setup": a Hub card with its form fields.
- Page footer, search dialog: square, edged, no shadows. Mermaid: classic
  look in the site's colours.
- ui/tokens.css: the Hub's page roles as --pl-* tokens (additive).

Everything is scoped to .dt-root (or :root:has(.dt-root) for the search
dialog), so the interim landing pages are pixel-identical.

* feat(docs): copy pages for AI assistants, and a guide to installing with one

Every docs page gets three actions under its title:
- Copy page: the page as Markdown (/docs/md/<page>.md). When the reader has
  filled in "Your setup", a "My setup: ..." line goes on top, so an assistant
  answers for their install; the page text itself is not changed.
- Copy all docs: /llms-full.txt, every page in one file (~60k tokens).
- Open: Fumadocs' menu (GitHub, Markdown, ChatGPT, Claude, Cursor, Scira).

New page guides/ai-assistant ("Installing with an AI Assistant"): how to give
an assistant the docs (the buttons, llms.txt, llms-full.txt, <page>.md), a
prompt for a production Panel install (asks for OS, domain, web server,
database and Wings first, one step at a time, no secrets in chat, and ends on
a checklist: HTTPS with renewal, firewall ports, queue worker and cron,
permissions, APP_KEY kept off the server, backups and updates), prompts for
Wings, troubleshooting and updating, and rules for agents with shell access.
Linked from Getting Started.

Code blocks: a `wrap` flag (lib/shiki-setup.ts) wraps long lines, used by the
prompts; empty lines in plain-text blocks keep their height (they collapsed).

* fix(docs): show wrapped prompts in full, without the code block's 600px cap

* feat(install): one-command install with Docker Swarm and Traefik (IP by default, HTTPS with a domain), and Docker-first docs (#226) (#241)

* feat(install): pelican.dev/install.sh, the Panel on Docker Swarm with Traefik and automatic HTTPS

One command on a fresh server, in the spirit of Coolify and Dokploy:

  curl -fsSL https://pelican.dev/install.sh | sudo bash

It checks the server (Linux, x86_64/arm64, virtualization, ports 80/443, DNS),
installs Docker if missing, starts a one-node Swarm and deploys the "pelican"
stack from /opt/pelican: Traefik on 80/443 (HTTP to HTTPS, Let's Encrypt on the
first request, renewals on its own) and the Panel behind it (BEHIND_PROXY,
TRUSTED_PROXIES set to the network it shares with Traefik). Profiles: quick
(SQLite) or production (MariaDB 11.4 and Redis 7, passwords generated). With
--wings it installs Wings as the docs do and routes its domain through Traefik.

- Guided: asks for what's missing; with --yes every answer is an option, so
  automation and AI assistants can drive it. --dry-run shows the plan and
  writes the files without root and without touching the server.
- Configurable afterwards: settings in pelican.env (0600), stack.yml reads
  them, deploy.sh applies them (and updates the Panel). A second run keeps
  APP_KEY and passwords and refuses to switch profiles over existing data.
- Networks clear of Wings: docker_gwbridge is created on 10.204.0.0/24 before
  "swarm init" (it would take Wings' 172.18.0.0/16), and Swarm uses
  10.203.0.0/16 rather than 10.0.0.0/x, which cloud private networks use.
- Traefik in host-mode ports (real client IPs), readTimeout 600s for uploads,
  every service pinned to this node (local volumes).
- Safe output: the swarm join token is never printed; the log is root-only;
  Let's Encrypt's forbidden example.com contacts are refused up front.

Served as a root file (router/paths.mjs ROOT_FILES; the Hub's
DocsBuildService::ROOT_FILES needs it too). Tested in
scripts/install-sh.test.mjs (dry runs, generated stack parsed as YAML,
deploy.sh with a stub docker, shellcheck) and end to end in an Ubuntu 24.04 VM.

* docs: Docker first, as in #226, with the install script

Ports #226 (Lance) to the Fumadocs site:
- guides/docker becomes the top-level Getting Started (requirements, the
  virtualization check, Docker, swap), now opening with the one-command install.
- panel/advanced/docker becomes panel/install, the recommended install: the
  install script (profiles, options, files, changing settings, updating, Wings on
  the same server, troubleshooting, backups) and then Docker Compose by hand,
  with #226's plugins volume and the note on the old ghcr.io/pelican-dev path.
- The install without Docker moves to panel/standalone/*.
- Redirects for the six old paths (netlify.toml, which the Hub's redirects.json
  is built from), inbound links, the sidebar, the OG motifs, ui/nav.json.
- The AI guide's recommended prompt now drives the install script (asks the
  questions, writes the command, dry run first); the old prompt becomes the
  "Standalone install" tab.

* feat(install): serve the Panel on the server's external IP by default, no domain needed

Without --domain (or an empty answer), the Panel is served on
http://<external IPv4> (found automatically, or --ip), with the quick profile
and no other questions under --yes. A domain is still the way to HTTPS: give it
at install, or later by running the script again with --domain/--email (keys,
passwords and data kept) or setting PANEL_DOMAIN and LE_EMAIL and running
deploy.sh. After the switch, plain HTTP to the old IP lands on the domain.

- Traefik's routes now live in traefik/pelican.yml, written by deploy.sh from
  pelican.env (IP: the Panel on port 80 at any address; domain: HTTPS with
  Let's Encrypt, HTTP to HTTPS, Wings' domain). The Panel's APP_URL follows
  (PANEL_URL). Traefik no longer needs the Docker socket.
- Wings without a domain is reached on http://<IP>:8080 (ufw opens it); with a
  panel domain it needs its own, as before.
- The install waits for Swarm to finish rolling the services out before
  checking the Panel: a changed setting replaces the Panel, and the check used
  to reach the old one.
- Traefik's healthcheck runs every 10s, so it counts as 1/1 sooner.

Verified in the Ubuntu 24.04 VM: a fresh install with no domain, then adding a
domain (and Wings on one), then back, checking the new Panel right after each.

* feat(install): ask nothing by default, take PELICAN_* variables, pin Traefik

The model Coolify and Dokploy use: the installer runs straight through and
anything not given takes its default.

- No questions unless --interactive (or PELICAN_INTERACTIVE=1), which asks for
  each choice with explanations and needs a terminal. With no options it
  installs the Panel on the server's IP, quick profile, no Wings. A domain
  without an email, or Wings without its domain next to a Panel domain, stops
  with the option and the variable to set. --yes is still accepted, unused.
- Every option can be an environment variable (PELICAN_DOMAIN, PELICAN_EMAIL,
  PELICAN_PROFILE, PELICAN_WINGS, PELICAN_WINGS_DOMAIN, PELICAN_IP, PELICAN_DIR,
  PELICAN_IMAGE, PELICAN_STAGING, PELICAN_SKIP_DNS_CHECK, PELICAN_DRY_RUN,
  PELICAN_INTERACTIVE); the option wins. With sudo they go after it:
  curl ... | sudo PELICAN_DOMAIN=panel.example.com PELICAN_EMAIL=... bash
- Traefik pinned to v3.7.19 (was the moving v3 tag). Running the script again
  moves an install to the version it pins; PELICAN_TRAEFIK_IMAGE for another.

Docs and the AI prompt drop --yes and list the variables. Verified in the VM:
the script piped into sudo with variables re-ran an install with no questions
and moved Traefik to 3.7.19; --interactive answered through a pseudo-terminal.

* fix(install): Macroscope's review: staging, Wings re-runs, saved subnet, dry runs, share image

- Running again without --staging now moves a staging install to Let's Encrypt
  production (it kept the saved staging server). A CA set by hand is kept. Each
  CA gets its own certificate store (deploy.sh names it from LE_CA_SERVER), so
  staging certificates and the staging account don't carry over.
- Re-running with Wings running no longer fails: the binary is downloaded to
  wings.new and renamed over the running one (writing to it gave "text file
  busy", curl exit 23, before the stack was deployed).
- A second run keeps the PUBLIC_SUBNET saved in pelican.env (it reset it to
  10.203.250.0/24, moving TRUSTED_PROXIES and the network) unless
  PELICAN_PUBLIC_SUBNET asks for another.
- A dry run warns about example.com emails instead of stopping, so the docs'
  dry-run example works; a real run still refuses them.
- The panel/install share image quotes lines that are on the page (it was
  dropped). New lib/og-motifs.test.mjs checks every motif against its page.

Verified in the VM: a running /usr/local/bin/wings blocks the old download
(curl exit 23) and not the new one; staging, then a run without --staging,
switches caServer and the store to production.
…rnel modules RHEL 10 images leave out (#242)

- AlmaLinux, Rocky Linux and Oracle Linux 8, 9 and 10: get.docker.com adds Docker's repo named
  after them, which has no Docker Engine packages ("Unable to find a match: docker-ce"). They now
  install from Docker's CentOS repo.
- CentOS Stream, AlmaLinux and Rocky Linux 10 images lack xt_addrtype and xt_ipvs (Docker won't
  start / Swarm can't reach its services, 502), Oracle Linux's UEK kernel lacks xt_ipvs. The script
  installs kernel-modules-extra (or kernel-uek-modules-extra and -netfilter) for the running kernel
  before Docker, and restarts a Docker that was already running.
- Running the script again after a failed start now recovers: the module check runs every time,
  systemd's "start request repeated too quickly" lock is cleared, and a failed start shows Docker's
  last log lines.
- The docs' "Installing Docker" section says how to do the same by hand.
…contrast fixes (#243)

* fix(docs): resolve relative links against the page's folder, and check every link after the build

Pages kept Docusaurus-style relative links (../versioning, ./panel/install). With
trailingSlash the browser resolved them one folder too deep, so about 50 links on 13
pages went to 404s. lib/docs-href.ts resolves them at build time for the HTML pages and
the .md copies alike, and scripts/check-links.mjs (postbuild, check:links) fails the
build on any docs link to a page, file or #anchor that isn't there.

* ci: fetch the whole history so each page gets its own last-modified date

The last-modified plugin reads git. With a depth-1 checkout every page got the date of
the latest commit in the sitemap, article:modified_time, JSON-LD and "Last updated".

* docs: open pages with a plain sentence, fix heading levels, clearer titles

Pages that started with a heading or a warning box now say what they are for in one or two
sentences (facts already in the docs). Headings under the title start at H2 (index,
contributors, standalone install pages, SSL tabs). Vague titles say what and for which
part: "Using Redis with the Panel", "Advanced Wings Configuration", … (URLs unchanged).
Short descriptions for Podman, the webserver config and Cloudflare Tunnel are longer.

* fix(llms): llms.txt lists Plugins and the Hub's real URLs; serve /docs/llms.txt too

Adds the Plugin Hub, points Support at /sponsor, drops the trailing slash from the Hub's
/eggs and /faq, and links the Hub API docs that exist (hub.pelican.dev/docs/api). The phone
menu's links to the Hub's pages are plain <a>s, so they keep /sponsor instead of /sponsor/.

* feat(seo): docs JSON-LD names Pelican as author and publisher, with datePublished; link the Markdown copy

TechArticle's author and publisher are the Organization the Hub's home page defines
(@id https://pelican.dev/#organization). datePublished is the page's first commit (skipped
on a shallow clone). Each page has <link rel="alternate" type="text/markdown"> to its .md.

* fix(redirects): 301 old docs URLs that 404 today, and check every redirect target exists

/docs/panel/config, /docs/eggs/creating-a-custom-docker-image, /docs/panel/updating-panel,
/docs/wings/installing-wings, /docs/wings/updating-wings, /docs/team and /updatePanel.sh.
check-links now also fails when a /docs redirect points at a page that isn't built.

* fix(a11y): the phone sidebar and the search dialog work as dialogs from the keyboard

Phone sidebar: Escape closes it, the page behind it is inert, focus moves in when it opens
and back to the menu button when it closes. Search: focus returns to the button that opened
it, and a live region says how many results there are.

* fix(a11y): skip link, clearer names, readable code comments, visible edges and focus

- "Skip to content" is the first thing Tab reaches.
- The brand link's name includes its visible text; code scroll areas are named; "Open" reads "Open in…".
- Code comments use #8b949e (4.6:1 or more, also on highlighted lines).
- Dark-theme control edges are 3:1 or more; the search input shows a focus ring.
- The logo icon is a 5 KB WebP instead of the 36 KB PNG.

* fix(docs): keep descriptions and titles within what Google shows

Four descriptions ran to 166-180 characters and the Comparison title to 66
with ' | Pelican Docs'; Google cuts them at about 160 and 60.
* feat(scripts): read the latest Panel release from GitHub before each build

sync-release writes data/release.json (version, date, link). 5 s timeout,
one retry; any failure prints one line and leaves the committed fallback,
so the build never fails or waits on GitHub.

* feat(home): take the Panel version for llms.txt and the homepage from GitHub

home-data reads data/release.json and keeps its typed rc.2 values as the
fallback. The announcement bar keeps its rc.2 sentence only for rc.2.

* ci(publish): rebuild the docs daily so a new Panel release shows within a day

Adds a schedule that publishes the same branches a push does, passes
GITHUB_TOKEN to the build, and names the built branch and commit in
BUILD.json (BUILD_SHA/BUILD_BRANCH) since the daily run starts on main.

* refactor(scripts): make sync-release short enough to read at a glance

One fetch with a 5-second timeout, no retry (the build already falls back
and the docs rebuild daily), no custom error class or extra checks. Tests
cover the release picking only. 130 lines down to 50.

* ci(publish): just a daily schedule, no branch matrix

The daily run only needs to rebuild pelican.dev, which a scheduled run on main
already does like a push to main. Drops the branch-picking job, the matrix and
the BUILD_SHA/BUILD_BRANCH plumbing in pack-docs.

This branch has not been deployed

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants