Skip to content

Commit ad9e548

Browse files
kael-odinkael-odin
committed
feat(docs): Copy for LLMs button + API Playground + visual polish
- Copy for LLMs dropdown (Copy / View / Open in ChatGPT / Open in Claude) on every doc page - /<slug>.md endpoint via Astro Container API + turndown, with build-time check script - API Playground component (B3): renders any OpenAPI op as a try-it-out form, embedded on /api/account/info as dogfood - API integration guide trimmed (~496 -> ~320 lines), folded troubleshooting - API sidebar reordered: Account Info to position 3, single-item groups flattened, Worker/Runs internals by usage frequency - Code-block visual overhaul: system mono stack, neutral borders, soft surfaces - Aside callouts gain semantic icons; <details> blocks get card treatment - Footer keeps Starlight default EditLink + Pagination (Edit-on-GitHub enabled) - Dark-mode home hero CoreClaw title fixed (root cause: :global() doesn't work in plain .md style blocks) - Stale REST-style paths in builds-and-runs.md replaced with POST style + cross-links - Version examples switched to <version> placeholder across all language samples
1 parent 735f479 commit ad9e548

33 files changed

Lines changed: 2357 additions & 563 deletions

‎astro.config.mjs‎

Lines changed: 87 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,55 @@ export default defineConfig({
3232
starlight({
3333
plugins: [starlightImageZoom()],
3434
title: 'CoreClaw',
35+
expressiveCode: {
36+
// Use github-dark/light for now — they're well-tested and
37+
// legible. We tone down the chrome via styleOverrides so
38+
// they fit the site's quieter teal palette instead of
39+
// shouting in primary GitHub colours.
40+
themes: ['github-dark', 'github-light'],
41+
styleOverrides: {
42+
borderRadius: '10px',
43+
borderColor: 'hsla(220, 14%, 60%, 0.22)',
44+
// System monospace stack — looks native on macOS / Windows
45+
// / Linux without shipping a webfont. JetBrains Mono and
46+
// Fira Code only kick in if the user already has them.
47+
codeFontFamily:
48+
'ui-monospace, "SF Mono", "Cascadia Mono", "JetBrains Mono", "Fira Code", "Source Code Pro", Menlo, Consolas, "DejaVu Sans Mono", monospace',
49+
codeFontSize: '0.8125rem',
50+
codeLineHeight: '1.7',
51+
codePaddingBlock: '0.95rem',
52+
codePaddingInline: '1.1rem',
53+
// Lift line-numbers / scroll-bars to subtle teal
54+
scrollbarThumbColor: 'hsla(199, 50%, 50%, 0.25)',
55+
scrollbarThumbHoverColor: 'hsla(199, 50%, 50%, 0.5)',
56+
// Frame chrome (window bar, file tab) — neutral, then
57+
// a thin teal underline to mark active state
58+
frames: {
59+
editorActiveTabBackground: 'transparent',
60+
editorActiveTabBorderColor: 'transparent',
61+
editorActiveTabIndicatorTopColor: 'transparent',
62+
editorActiveTabIndicatorBottomColor:
63+
'hsl(199, 89%, 50%)',
64+
editorTabBarBackground: 'transparent',
65+
editorTabBarBorderBottomColor:
66+
'hsla(220, 14%, 60%, 0.18)',
67+
editorTabBorderRadius: '6px',
68+
terminalTitlebarBackground:
69+
'hsla(220, 14%, 96%, 0.6)',
70+
terminalTitlebarBorderBottomColor:
71+
'hsla(220, 14%, 60%, 0.18)',
72+
terminalTitlebarForeground: 'hsl(220, 14%, 32%)',
73+
terminalBackground: '#0f1117',
74+
terminalTitlebarDotsForeground:
75+
'hsla(220, 14%, 70%, 0.6)',
76+
terminalTitlebarDotsOpacity: '0.7',
77+
frameBoxShadowCssValue:
78+
'0 1px 2px 0 rgb(0 0 0 / 0.05)',
79+
tooltipSuccessBackground: 'hsl(151, 55%, 40%)',
80+
tooltipSuccessForeground: 'white',
81+
},
82+
},
83+
},
3584
logo: {
3685
src: './src/assets/logo.png',
3786
alt: 'CoreClaw Logo',
@@ -51,6 +100,13 @@ export default defineConfig({
51100
MobileMenuFooter: './src/components/MobileMenuFooter.astro',
52101
TableOfContents: './src/components/TableOfContents.astro',
53102
Banner: './src/components/Banner.astro',
103+
PageTitle: './src/components/PageTitle.astro',
104+
Footer: './src/components/Footer.astro',
105+
},
106+
editLink: {
107+
// Adjust the path/branch if the docs source moves.
108+
baseUrl:
109+
'https://github.com/Core-Claw/scraper-webui-docs/edit/main/',
54110
},
55111
customCss: [
56112
'./src/styles/common.css',
@@ -421,27 +477,31 @@ export default defineConfig({
421477
'zh-CN': '基础 URL 与认证',
422478
},
423479
},
480+
// Account info comes early — users typically hit it
481+
// first to verify their API key and check balance
482+
// before doing anything else.
483+
{
484+
label: 'Account Info',
485+
slug: 'api/account/info',
486+
translations: {
487+
'zh-CN': '账户信息',
488+
},
489+
},
424490
{
425491
label: 'Worker',
426492
collapsed: true,
427493
translations: {
428494
'zh-CN': 'Worker',
429495
},
430496
items: [
497+
// Highest-frequency action goes first.
431498
{
432499
label: 'Start Worker',
433500
slug: 'api/worker/run',
434501
translations: {
435502
'zh-CN': '运行爬虫',
436503
},
437504
},
438-
{
439-
label: 'Abort Worker',
440-
slug: 'api/worker/abort',
441-
translations: {
442-
'zh-CN': '中止爬虫',
443-
},
444-
},
445505
{
446506
label: 'Worker Detail',
447507
slug: 'api/worker/detail',
@@ -456,6 +516,13 @@ export default defineConfig({
456516
'zh-CN': '搜索 Worker',
457517
},
458518
},
519+
{
520+
label: 'Abort Worker',
521+
slug: 'api/worker/abort',
522+
translations: {
523+
'zh-CN': '中止爬虫',
524+
},
525+
},
459526
],
460527
},
461528
{
@@ -464,14 +531,12 @@ export default defineConfig({
464531
translations: {
465532
'zh-CN': 'Runs',
466533
},
534+
// Reordered by usage flow: after starting a
535+
// worker you check its detail, fetch results,
536+
// read logs, export, rerun if needed; History
537+
// is the catch-all browse-everything endpoint
538+
// and goes last.
467539
items: [
468-
{
469-
label: 'Run History',
470-
slug: 'api/run/history',
471-
translations: {
472-
'zh-CN': '运行历史',
473-
},
474-
},
475540
{
476541
label: 'Run Detail',
477542
slug: 'api/run/detail',
@@ -507,39 +572,23 @@ export default defineConfig({
507572
'zh-CN': '重新运行',
508573
},
509574
},
510-
],
511-
},
512-
{
513-
label: 'Tasks',
514-
collapsed: true,
515-
translations: {
516-
'zh-CN': 'Tasks',
517-
},
518-
items: [
519575
{
520-
label: 'Start Task',
521-
slug: 'api/task/run',
576+
label: 'Run History',
577+
slug: 'api/run/history',
522578
translations: {
523-
'zh-CN': '运行任务（模板）',
579+
'zh-CN': '运行历史',
524580
},
525581
},
526582
],
527583
},
584+
// Single-endpoint group flattened — was a one-item
585+
// collapsible folder, now shows up directly.
528586
{
529-
label: 'Account',
530-
collapsed: true,
587+
label: 'Start Task',
588+
slug: 'api/task/run',
531589
translations: {
532-
'zh-CN': '账户',
590+
'zh-CN': '运行任务（模板）',
533591
},
534-
items: [
535-
{
536-
label: 'Account Info',
537-
slug: 'api/account/info',
538-
translations: {
539-
'zh-CN': '账户信息',
540-
},
541-
},
542-
],
543592
},
544593
{
545594
label: 'Code Examples',

‎docs/next-steps.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Next-step integration guide
2+
3+
Two pieces of infrastructure are scaffolded and ready to use. This doc
4+
covers what's done, what's pending, and what to flip on next.
5+
6+
---
7+
8+
## API Playground (B3)
9+
10+
**Where**: `src/components/ApiPlayground.astro`
11+
12+
**Status**: component built and styled, not yet embedded on any page.
13+
14+
### What it does
15+
16+
Renders one OpenAPI operation as a try-it-out form. Reads
17+
`public/openapi.json` at build time, so the form schema, defaults, and
18+
examples stay in sync with the source-of-truth spec — no runtime fetch.
19+
20+
For a given operation it shows:
21+
22+
- METHOD + path header (color-coded by verb)
23+
- API-key field (only if the op declares `security: [{ apiKey: [] }]`),
24+
password-typed, persisted to `sessionStorage` so the user doesn't
25+
re-paste between operations within the same tab
26+
- Query / path parameter inputs with placeholders pulled from the spec
27+
- JSON body editor pre-filled with the first declared example
28+
- Send Request → real `fetch` to production
29+
- Response panel: status badge (green/orange/red), latency, pretty JSON
30+
31+
### How to embed it
32+
33+
#### Step 1 — convert the target page from `.md` to `.mdx`
34+
35+
```bash
36+
mv src/content/docs/api/account/info.md src/content/docs/api/account/info.mdx
37+
```
38+
39+
#### Step 2 — add the import below the frontmatter
40+
41+
```mdx
42+
import ApiPlayground from '../../../components/ApiPlayground.astro'
43+
```
44+
45+
Adjust the `../` count to match the file's depth.
46+
47+
#### Step 3 — drop the component anywhere in the body
48+
49+
```mdx
50+
<ApiPlayground method="POST" path="/api/v1/account/info" />
51+
```
52+
53+
That's it. The component looks the operation up in `openapi.json` and
54+
renders the form. If the op isn't in the spec, the component shows a
55+
visible inline error in dev — no silent failure.
56+
57+
### Critical: CORS
58+
59+
The browser will call `https://openapi.coreclaw.com` from
60+
`https://docs.coreclaw.com`. The API needs to respond with:
61+
62+
```
63+
Access-Control-Allow-Origin: https://docs.coreclaw.com
64+
Access-Control-Allow-Headers: api-key, content-type
65+
Access-Control-Allow-Methods: GET, POST, OPTIONS
66+
```
67+
68+
If CORS is missing, the playground surfaces a "Network error" status
69+
with the browser's CORS message in the response panel. Coordinate with
70+
the API team to allowlist the docs origin before going live.
71+
72+
### Recommended rollout
73+
74+
1. Pick **one** safe operation to dogfood first — `/api/v1/account/info`
75+
is a good candidate (read-only, low blast radius).
76+
2. Verify CORS, then expand to the rest of the worker / run / task ops.
77+
3. Consider adding a banner in dev/staging like
78+
"Requests will hit production" so users don't accidentally trigger
79+
real Worker runs.
80+
81+
### Future polish
82+
83+
- Pre-flight balance check before "Send Request" on operations that
84+
cost credits
85+
- Save request history per operation in `localStorage`
86+
- Generate curl / Python / Node code snippets below the form, rebuilt
87+
from current form values
88+
89+
---
90+
91+
## Edit on GitHub (B10) — already live
92+
93+
`astro.config.mjs` has:
94+
95+
```js
96+
editLink: {
97+
baseUrl: 'https://github.com/Core-Claw/scraper-webui-docs/edit/main/',
98+
}
99+
```
100+
101+
Each page footer renders an "Edit page" link that opens GitHub's web
102+
editor on the source file. No further action unless the repo moves.
103+
104+
---
105+
106+
## File map (current state)
107+
108+
| Path | Purpose |
109+
|------|---------|
110+
| `src/pages/[...slug].md.ts` | Markdown export endpoint (Container API + turndown) |
111+
| `src/components/CopyForLLMs.astro` | Header dropdown — Copy / View / ChatGPT / Claude |
112+
| `src/components/PageTitle.astro` | Header slot override (places button next to H1) |
113+
| `src/components/Footer.astro` | Footer slot override — default EditLink + Pagination only |
114+
| `src/components/ApiPlayground.astro` | Embeddable try-it-out form (B3, ready to use) |
115+
| `scripts/check-copy-for-llms.mjs` | `pnpm build` post-check: every doc has a non-empty .md export |
116+
| `astro.config.mjs` | Slot overrides + editLink + Expressive Code theme |
117+
| `src/styles/common.css` | Code-block visual upgrade + aside/details polish + content-width tightening |

‎package.json‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,9 @@
66
"scripts": {
77
"dev": "astro dev",
88
"start": "astro dev",
9-
"build": "astro build",
9+
"build": "astro build && node scripts/check-copy-for-llms.mjs",
10+
"build:no-check": "astro build",
11+
"check:copy-for-llms": "node scripts/check-copy-for-llms.mjs",
1012
"preview": "astro preview",
1113
"astro": "astro"
1214
},
@@ -20,11 +22,13 @@
2022
"react": "^19.2.4",
2123
"react-dom": "^19.2.4",
2224
"sharp": "^0.34.2",
23-
"starlight-image-zoom": "^0.14.1"
25+
"starlight-image-zoom": "^0.14.1",
26+
"turndown": "^7.2.1"
2427
},
2528
"devDependencies": {
2629
"@eslint/js": "^9.39.4",
2730
"@playwright/test": "^1.59.1",
31+
"@types/turndown": "^5.0.5",
2832
"eslint": "^9.39.4",
2933
"globals": "^17.4.0",
3034
"playwright": "^1.59.1",

0 commit comments

Comments
 (0)