Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 8927e8f

Browse files
SamyPessezenoachtig
andauthored
Embeddable Docs Assistant (#3572)
Co-authored-by: Zeno Kapitein <zeno@gitbook.io>
1 parent 25e2b40 commit 8927e8f

File tree

70 files changed

+1860
-494
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

70 files changed

+1860
-494
lines changed

‎.changeset/angry-melons-sparkle.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@gitbook/embed": patch
3+
---
4+
5+
Initial version of the embed SDK.

‎.changeset/sweet-garlics-do.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"gitbook": minor
3+
---
4+
5+
Start routes for embeddable version of the assistant and docs pages.

‎.github/actions/setup-playwright/action.yml‎

Lines changed: 0 additions & 37 deletions
This file was deleted.

‎.github/workflows/deploy-preview.yaml‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -110,8 +110,8 @@ jobs:
110110
uses: ./.github/composite/setup-bun
111111
- name: Install dependencies
112112
run: bun install --frozen-lockfile
113-
- name: Setup Playwright
114-
uses: ./.github/actions/setup-playwright
113+
env:
114+
PUPPETEER_SKIP_DOWNLOAD: 1
115115
- name: Run Playwright tests
116116
run: bun e2e
117117
env:
@@ -131,8 +131,8 @@ jobs:
131131
uses: ./.github/composite/setup-bun
132132
- name: Install dependencies
133133
run: bun install --frozen-lockfile
134-
- name: Setup Playwright
135-
uses: ./.github/actions/setup-playwright
134+
env:
135+
PUPPETEER_SKIP_DOWNLOAD: 1
136136
- name: Run Playwright tests
137137
run: bun e2e
138138
env:
@@ -152,8 +152,8 @@ jobs:
152152
uses: ./.github/composite/setup-bun
153153
- name: Install dependencies
154154
run: bun install --frozen-lockfile
155-
- name: Setup Playwright
156-
uses: ./.github/actions/setup-playwright
155+
env:
156+
PUPPETEER_SKIP_DOWNLOAD: 1
157157
- name: Run Playwright tests
158158
run: bun e2e-customers
159159
env:
@@ -173,8 +173,8 @@ jobs:
173173
uses: ./.github/composite/setup-bun
174174
- name: Install dependencies
175175
run: bun install --frozen-lockfile
176-
- name: Setup Playwright
177-
uses: ./.github/actions/setup-playwright
176+
env:
177+
PUPPETEER_SKIP_DOWNLOAD: 1
178178
- name: Run Playwright tests
179179
run: bun e2e-customers
180180
env:

‎bun.lock‎

Lines changed: 60 additions & 42 deletions
Large diffs are not rendered by default.

‎package.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,8 @@
3434
"workspaces": {
3535
"packages": ["packages/*"],
3636
"catalog": {
37-
"@gitbook/api": "^0.136.0"
37+
"@gitbook/api": "^0.136.0",
38+
"bidc": "^0.0.2"
3839
}
3940
},
4041
"patchedDependencies": {

‎packages/embed/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
dist/
2+
standalone/

‎packages/embed/README.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# `@gitbook/embed`
2+
3+
Embed the GitBook Docs Assistant in your product or website.
4+
5+
# Usage
6+
7+
## As a script from your docs site
8+
9+
All GitBook docs site includes a script to easily embed the docs assistant as a widget on your website.
10+
11+
The script is served at `https://docs.company.com/~gitbook/embed/script.js`.
12+
13+
You can find the embed script from your docs site settings, or you can copy the following and replace the `docs.company.com` by your docs site hostname.
14+
15+
```html
16+
<script src="https://docs.company.com/~gitbook/embed/script.js"></script>
17+
<script>
18+
window.GitBook('show');
19+
</script>
20+
```
21+
22+
## As a package from NPM
23+
24+
Install the package: `npm install @gitbook/embed` and import it in your web application:
25+
26+
```tsx
27+
import { createGitBook } from '@gitbook/embed';
28+
29+
const gitbook = createGitBook({
30+
siteURL: 'https://docs.company.com'
31+
});
32+
33+
const iframe = document.createElement('iframe');
34+
iframe.src = gitbook.getFrameURL();
35+
36+
const frame = gitbook.createFrame(iframe);
37+
```
38+
39+
## As React components
40+
41+
After installing the NPM package, you can import prebuilt React components:
42+
43+
```tsx
44+
import { GitBookProvider, GitBookAssistantFrame } from '@gitbook/embed/react';
45+
46+
<GitBookProvider siteURL="https://docs.company.com">
47+
<GitBookAssistantFrame />
48+
</GitBookProvider>
49+
```

‎packages/embed/package.json‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
{
2+
"name": "@gitbook/embed",
3+
"description": "Embeddable components for GitBook",
4+
"type": "module",
5+
"exports": {
6+
".": {
7+
"types": "./dist/index.d.ts",
8+
"default": "./dist/index.js",
9+
"standalone": "./dist/standalone/index.js",
10+
"react": "./dist/react/index.js"
11+
}
12+
},
13+
"version": "0.0.0",
14+
"dependencies": {
15+
"@gitbook/api": "catalog:",
16+
"@gitbook/icons": "workspace:",
17+
"bidc": "catalog:"
18+
},
19+
"peerDependencies": {
20+
"react": "^18.0.0"
21+
},
22+
"devDependencies": {
23+
"typescript": "^5.5.3",
24+
"react": "^19.0.0"
25+
},
26+
"scripts": {
27+
"build": "tsc && bun build src/standalone/index.ts --bundle --minify --outdir=standalone",
28+
"typecheck": "tsc --noEmit"
29+
},
30+
"files": ["dist", "README.md", "CHANGELOG.md", "standalone"]
31+
}
Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
import { type GitBookFrameClient, createGitBookFrame } from './createGitBookFrame';
2+
3+
export type CreateGitBookOptions = {
4+
/**
5+
* URL of the GitBook site to embed.
6+
*/
7+
siteURL: string;
8+
};
9+
10+
export type GetFrameURLOptions = {
11+
/**
12+
* Authentication to use for the frame.
13+
*/
14+
visitor?: {
15+
/**
16+
* Signed JWT token for Adaptive Content or Visitor Authentication to use.
17+
*/
18+
token?: string;
19+
20+
/**
21+
* Unsigned claims to pass to the frame.
22+
* You can use these claims in dynamic expressions using `visitor.claims.unsigned.<claim-name>`.
23+
*/
24+
unsignedClaims?: Record<string, unknown>;
25+
};
26+
};
27+
28+
export type GitBookClient = {
29+
/**
30+
* Get the URL for a GitBook frame.
31+
*/
32+
getFrameURL: (options: GetFrameURLOptions) => string;
33+
/**
34+
* Create a new GitBook frame.
35+
*/
36+
createFrame: (iframe: HTMLIFrameElement) => GitBookFrameClient;
37+
};
38+
39+
export function createGitBook(options: CreateGitBookOptions) {
40+
const client: GitBookClient = {
41+
getFrameURL: (frameOptions) => {
42+
const url = new URL(options.siteURL);
43+
url.pathname = `${url.pathname.endsWith('/') ? url.pathname : `${url.pathname}/`}~gitbook/embed/assistant`;
44+
45+
if (frameOptions.visitor?.token) {
46+
url.searchParams.set('token', frameOptions.visitor.token);
47+
}
48+
49+
if (frameOptions.visitor?.unsignedClaims) {
50+
Object.entries(frameOptions.visitor.unsignedClaims).forEach(([key, value]) => {
51+
url.searchParams.set(`visitor.${key}`, String(value));
52+
});
53+
}
54+
55+
return url.toString();
56+
},
57+
createFrame: (iframe) => createGitBookFrame(iframe),
58+
};
59+
60+
return client;
61+
}

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /