Repository navigation
feat(docs): the Hub's look, Copy for AI, and a guide to installing with an AI assistant - #240
Conversation
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.
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the
|
ApprovabilityVerdict: Approved at Macroscope's review found this PR approvable — This updates the docs’ appearance and adds Markdown-copy actions plus guidance for AI-assisted installation. Sharing is reader-initiated, and the guide stresses command review, backups and protecting secrets. You can add or adjust custom eligibility rules. Learn more. |
…ith 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).
Dismissing prior approval to re-evaluate 0fb94aa
…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.
Why
Scai asked for the docs to be styled like the landing pages. The docs already shared the Hub's header and tokens, but they still looked like a different site: offset shadows on code, callouts, the search box and the buttons; Fumadocs' rounded chrome; white code blocks; a filled sky sidebar item; sky underlines. The Hub's redesigned pages (hub-preview.pelican.dev: the homepage,
/plugins/announcements,/eggs/7-days-to-die,/faq) dropped the shadows and use square corners, 3px edges on cards and controls, 2px rules between rows, navy code in both themes and sky only as an accent. This PR makes the docs follow them. No new look was invented: each block inapp/global.cssnames the Hub class it copies (fromresources/css/site/{base,app,plugins,eggs,standalone}.css).The second part follows up on Scai's request in this PR: give people faster ways to use the docs with an AI assistant (copy a page or the whole docs), and a recommended guide for installing the panel for production with one.
What changes
1. The docs in the Hub's look
.pl-themeswitch (sky active half),.pl-btn--smallbuttons with no shadow; 17px links; navy ground and a slate line in dark. 72px tall rather than the Hub's 88px, because it stays fixed while you read.pl-side: white (navy card in dark), 2px rule, current page light sky with a 3px sky edge; uppercase muted section labels.pl-pp__kicker+.pl-pp__title(46px max), 18px lede.pl-prose a: underline in the text colour, sky on hover.pl-prose code: flat chip, no edge.pl-eg__pre: navy in both themes (code navy in dark), Shiki's dark colours, file name in a bar, square copy button, sky highlighted lines.pl-alert: 3px edge, 8px left edge in the tone, card surface, no shadow; tones are the Hub's.pl-mdx table: 3px edge, sky head, 2px rules, hover row.pl-pp__toctabs (bold muted, 3px sky underline).pl-cardwith Hub form fields (3px inputs, bold labels); the choices fill navy (sky in dark) like.pl-tablook: 'classic', white/navy-card boxes with 2px edges and navy linesFiles:
app/global.css: the docs section is rewritten. Every docs rule is under.dt-root, or under:root:has(.dt-root)for the search dialog, which Fumadocs portals out. The old shared rules (prose links and code,figure.shiki, callouts) are kept unchanged in an "Interim pages" block so/faqkeeps its look; they go when the interim pages do.ui/tokens.css: additive--pl-*page roles taken from the Hub's.pltokens (--pl-fg,--pl-ground,--pl-card,--pl-rule,--pl-chip,--pl-hover(-strong),--pl-kicker,--pl-code, tones). Nothing on the interim pages reads them.--pl-kickeris the Hub's#0b79adone shade darker (#0a76a8), so the 14px kicker passes 4.5:1 on the page ground (4.48 → 4.67).app/docs/[[...slug]]/page.tsx,components/setup/setup-panel.tsx,components/mdx/tabs.tsx: stabledt-*hook classes instead of matching Fumadocs' Tailwind strings.Tabsonly gains a class, because/faquses it too.components/mdx/mermaid.tsx: base theme with the site colours, classic look, the text face by name.All Fumadocs features are kept: search, sidebar, TOC, tabs, copy buttons, the setup panel and Mermaid. No dependencies were added.
2. Copy for AI, and a guide to installing with an assistant
components/docs/page-actions.tsx):/docs/md/<page>.md, the filelib/llms.tsalready builds). If the reader has filled in Your setup, a> My setup (…): domain …, web server …, HTTPS (SSL), PHP …, install folder ….line goes on top, so the assistant answers for their install. The page text itself is not changed./llms-full.txt, every page in one file (231 KB, about 60k tokens).ViewOptionsPopover(GitHub, View as Markdown, ChatGPT, Claude, Cursor, Scira), styled as a Hub menu.ClipboardItemis created inside the click and filled when the download finishes./docs/guides/ai-assistant/, "Installing with an AI Assistant" (first under Guides, linked from Getting Started):llms.txt,llms-full.txt,<page>.md.pelican-queueand theschedule:runcron; permissions; theAPP_KEYkept off the server; backups and updates.wrapflag (lib/shiki-setup.ts, tested inlib/shiki-setup.test.mjs) wraps long lines and shows the block in full. The prompts use it. Separately, empty lines in plain-text blocks collapsed to 0px; they now keep their height.No new MDX components and no new dependencies.
Screenshots
Headless Chrome, full page, Next dev server. Before:
origin/feat/fumadocs-nextat323a25e. After: this branch atda3fe97.Page actions and the "Open" menu
New:
/docs/guides/ai-assistant/The before → after tables below are from the first commit (
da3fe97). The later commits add the actions row under each title, the guide and its link on Getting Started./docs//docs/panel/getting-started/(admonitions, a table, code)/docs/panel/webserver-config/("Your setup", nested tabs, code)/docs/eggs/creating-a-custom-egg/(admonitions, tables; first 3000 px)Search dialog (
nginx, on Getting Started)Verification
bun test: 81 pass, 0 fail (2 new, for thewrapflag).bun run typecheck: passes.bun run build: passes on0fb94aa(check-content: 36 pages ok;check-paths: ok). The egg data the build refreshes (data/eggs.json,public/data/eggs/forgejo/forgejo.json) is not committed.Interim pages untouched: I pixel-diffed
/,/faq/,/eggs/and/support/(1440 light and dark;/faq/and/eggs/also at 390) between base and branch, with the same egg data./faq/,/eggs/and/support/: 0 px./differs only inside remote images (plugin screenshots, sponsor logos) that load at different moments between runs; it was 0 px in an earlier run. The first diff caught.dt-tabsleaking onto/faq(+11px); that is fixed in this commit.Contrast (WCAG): kicker 4.67:1 on the ground; muted text 7.9:1; sidebar current item 15.6:1 (dark 10.0:1); sky table head 8.8:1; dark muted text 10.8:1; code title bar 11.4:1; warning and error tones on white 5.0:1 and 6.6:1.
Focus: I tabbed to the top-bar search box, the theme switch, a sidebar link, a prose link (dark), a code copy button (dark) and a "Your setup" choice. Each shows a 3px ring, inset where a scroll area would clip it.
Copy buttons, in headless Chrome with clipboard access granted, clicking the real buttons and reading the clipboard back. Copy page on Webserver Configuration, with a domain and Caddy set in Your setup, copied 9,805 characters that start with
> My setup (from the docs' "Your setup" box): domainpanel.example.org, web server Caddy.and then the page. Copy all docs copied 231,037 characters (llms-full.txt). Both buttons showed "Copied".The production build served by
router/dev-server.mjs(the same routing as pelican.dev):/docs/guides/ai-assistant/,/docs/guides/ai-assistant.mdand/llms-full.txtreturn 200, and the guide is inllms.txt.The guide's facts were checked against the docs: PHP 8.5/8.4;
/var/www/pelican; MySQL 8.4+, MariaDB 10.11+, PostgreSQL 17+; Wings on 8080 and SFTP on 2022;pelican-queueand theschedule:runline from Troubleshooting; the update script on the Update page.Not checked
The prompts were not run through ChatGPT, Claude or an agent against a real server. They are written from the docs, not from a test install.
The
https://pelican.dev/llms.txt,llms-full.txtand/docs/<page>.mdlinks in the guide and prompts return 404 on pelican.dev today; hub-preview serves them. They work once pelican.dev switches to this build. The buttons fetch from the site the reader is on, so they work everywhere now.The copy buttons in Safari and Firefox, and on a real phone: tested in headless Chrome only.
Safari, Firefox and real phones: headless Chrome only, at 1440 and 390 px. Tablet widths (768–1180 px) are not screenshotted.
The docs on hub-preview.pelican.dev: checked on the local dev server and the local build only.
Shiki's github-dark comment colour on navy is 3.9:1, under 4.5:1. That is better than 3.05:1 before, but it would need a custom Shiki theme to fix; out of scope here.
In the Mermaid diagram on
/docs/, some labels wrap onto two lines ("Basement / Server"). Readable; left as it is.The Hub's copy of
tokens.cssis not updated; the Hub repo was read-only for this PR. The new--pl-*tokens are published at/docs/ui/v1/tokens.csswith this build.The docs 404 page, the "leaving pelican.dev" dialog and print styles are unchanged and not re-checked.
/plugins/server-backups-proreturns 404 on hub-preview, so/plugins/announcementswas the plugin-page reference.Note
Add Hub styling to docs, Copy for AI actions, and AI assistant install guide
.dt-root.PageActionsin page-actions.tsx with Copy page, Copy all docs (from/llms-full.txt), and view options. Copy page can prepend a setup note built from the user's stored setup values.transformerWrapShiki transformer in shiki-setup.ts that applies adt-wrapclass to code blocks with awrapmetadata flag; also restyles Mermaid diagrams with explicit light/dark theme variables and an Instrument Sans font stack.wraptoken triggers wrapping (wrapper/nowrapdo not).Macroscope summarized 0fb94aa.