Skip to content

Commit ffa5fd4

Browse files
dkundel-openaidkundel-openai
committed
docs: various docs redesigns (#67)
* docs: reset search buttons * docs: fix title link * docs: change line-height of code snippets * docs: color typescript on landing page * docs: change navbar icons to contain text * docs: further design revisions * docs: add github and npm link
1 parent e81953a commit ffa5fd4

File tree

10 files changed

+289
-40
lines changed

10 files changed

+289
-40
lines changed

‎docs/astro.config.mjs‎

Lines changed: 6 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -317,6 +317,10 @@ export default defineConfig({
317317
title: 'OpenAI Agents SDK',
318318
components: {
319319
SiteTitle: './src/components/Title.astro',
320+
PageTitle: './src/components/PageTitle.astro',
321+
SocialIcons: './src/components/SocialIcons.astro',
322+
Sidebar: './src/components/Sidebar.astro',
323+
MobileMenuFooter: './src/components/MobileFooter.astro',
320324
},
321325
// defaultLocale: 'root',
322326
locales: {
@@ -330,20 +334,10 @@ export default defineConfig({
330334
},
331335
},
332336
social: [
333-
{
334-
icon: 'x.com',
335-
href: 'https://x.com/OpenAIDevs',
336-
label: 'OpenAI on X',
337-
},
338-
{
339-
icon: 'github',
340-
href: 'https://github.com/openai/openai-agents-js',
341-
label: 'Agents SDK on GitHub',
342-
},
343337
{
344338
icon: 'seti:python',
345339
href: 'https://github.com/openai/openai-agents-python',
346-
label: 'Agents SDK for Python',
340+
label: 'Python SDK',
347341
},
348342
],
349343
editLink: {
@@ -352,7 +346,7 @@ export default defineConfig({
352346
plugins,
353347
sidebar,
354348
expressiveCode: {
355-
themes: ['dracula', 'one-light'],
349+
themes: ['houston', 'one-light'],
356350
},
357351
customCss: ['./src/styles/global.css'],
358352
}),

‎docs/src/components/MobileFooter.astro‎

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
---
2+
import { Icon } from '@astrojs/starlight/components';
3+
import LanguageSelect from '@astrojs/starlight/components/LanguageSelect.astro';
4+
import SocialIcons from '@astrojs/starlight/components/SocialIcons.astro';
5+
import ThemeSelect from '@astrojs/starlight/components/ThemeSelect.astro';
6+
import { ParseStatus } from 'astro:schema';
7+
8+
const additionalLinks = [
9+
{
10+
label: 'View on GitHub',
11+
href: 'https://github.com/openai/openai-agents-js',
12+
icon: 'github' as const,
13+
},
14+
{
15+
label: 'View on npm',
16+
href: 'https://www.npmjs.com/package/@openai/agents',
17+
icon: 'npm' as const,
18+
},
19+
];
20+
---
21+
22+
<div class="mobile-preferences sl-flex">
23+
<div class="social-icons">
24+
<SocialIcons />
25+
{
26+
additionalLinks.map(({ label, href, icon }) => (
27+
<a {href} target="_blank" rel="noopener noreferrer" class="sl-flex">
28+
<Icon name={icon as any} />
29+
<span>{label}</span>
30+
</a>
31+
))
32+
}
33+
</div>
34+
<ThemeSelect />
35+
<LanguageSelect />
36+
</div>
37+
38+
<style>
39+
@layer starlight.core {
40+
.social-icons {
41+
display: flex;
42+
margin-inline-end: auto;
43+
gap: 1rem;
44+
align-items: center;
45+
padding-block: 1rem;
46+
}
47+
.social-icons:empty {
48+
display: none;
49+
}
50+
.mobile-preferences {
51+
justify-content: space-between;
52+
flex-wrap: wrap;
53+
border-top: 1px solid var(--sl-color-gray-6);
54+
column-gap: 1rem;
55+
padding: 0.5rem 0;
56+
}
57+
58+
.social-icons a {
59+
color: var(--sl-color-text-accent);
60+
padding: 0.5em;
61+
margin: -0.5em;
62+
text-decoration: none;
63+
align-items: center;
64+
65+
span {
66+
font-size: var(--sl-text-sm);
67+
margin-inline-start: 0.3rem;
68+
}
69+
70+
@media (max-width: 72rem) {
71+
span {
72+
@apply sr-only;
73+
}
74+
}
75+
}
76+
a:hover {
77+
opacity: 0.66;
78+
}
79+
}
80+
</style>

‎docs/src/components/PageTitle.astro‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
import Default from '@astrojs/starlight/components/PageTitle.astro';
3+
4+
const isHomepage =
5+
Astro.locals.starlightRoute.id === '' ||
6+
Astro.locals.starlightRoute.id === Astro.locals.starlightRoute.lang;
7+
const rawTitle = Astro.locals.starlightRoute.entry.data.title;
8+
const keyword = 'TypeScript';
9+
const idx = rawTitle.indexOf(keyword);
10+
let beforeKeyword = rawTitle;
11+
let afterKeyword = '';
12+
let hasKeyword = false;
13+
14+
if (isHomepage && idx !== -1) {
15+
beforeKeyword = rawTitle.slice(0, idx);
16+
afterKeyword = rawTitle.slice(idx + keyword.length);
17+
hasKeyword = true;
18+
}
19+
---
20+
21+
{
22+
isHomepage ? (
23+
<h1 id="_top" class="sr-only">
24+
{beforeKeyword}
25+
{hasKeyword ? <span class="keyword">{keyword}</span> : ''}
26+
{afterKeyword}
27+
</h1>
28+
) : (
29+
<Default />
30+
)
31+
}
32+
33+
<style>
34+
@layer starlight.core {
35+
h1 {
36+
margin-top: 1rem;
37+
font-size: var(--sl-text-h1);
38+
line-height: var(--sl-line-height-headings);
39+
font-weight: 600;
40+
color: var(--sl-color-white);
41+
}
42+
43+
.keyword {
44+
color: var(--openai-primary);
45+
}
46+
}
47+
</style>

‎docs/src/components/Sidebar.astro‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
import { Icon } from '@astrojs/starlight/components';
3+
import Default from '@astrojs/starlight/components/Sidebar.astro';
4+
// const { sidebar } = Astro.locals.starlightRoute;
5+
---
6+
7+
<Default />
8+
9+
<div class="openai-github-link sl-hidden md:sl-flex flex-col gap-5">
10+
<a
11+
href="https://github.com/openai/openai-agents-js"
12+
target="_blank"
13+
rel="noopener noreferrer"
14+
>
15+
<Icon name="github" />
16+
<span>View on GitHub</span>
17+
</a>
18+
<a
19+
href="https://www.npmjs.com/package/@openai/agents"
20+
target="_blank"
21+
rel="noopener noreferrer"
22+
>
23+
<Icon name="npm" />
24+
<span>View on npm</span>
25+
</a>
26+
</div>

‎docs/src/components/SocialIcons.astro‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
import config from 'virtual:starlight/user-config';
3+
import { Icon } from '@astrojs/starlight/components';
4+
5+
const links = config.social || [];
6+
---
7+
8+
{
9+
links.length > 0 && (
10+
<>
11+
{links.map(({ label, href, icon }) => (
12+
<a {href} target="_blank" rel="noopener noreferrer" class="sl-flex">
13+
<Icon name={icon} />
14+
<span>{label}</span>
15+
</a>
16+
))}
17+
</>
18+
)
19+
}
20+
21+
<style>
22+
@layer starlight.core {
23+
a {
24+
color: var(--sl-color-text-accent);
25+
padding: 0.5em;
26+
margin: -0.5em;
27+
text-decoration: none;
28+
align-items: center;
29+
30+
span {
31+
font-size: var(--sl-text-sm);
32+
margin-inline-start: 0.3rem;
33+
}
34+
35+
@media (max-width: 72rem) {
36+
span {
37+
@apply sr-only;
38+
}
39+
}
40+
}
41+
a:hover {
42+
opacity: 0.66;
43+
}
44+
}
45+
</style>

‎docs/src/components/Title.astro‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
---
22
import Logo from './Logo.astro';
3+
const { siteTitle, siteTitleHref } = Astro.locals.starlightRoute;
34
---
45

5-
<Logo height="24" alt="OpenAI Agents SDK" />
6+
<a href={siteTitleHref} class="site-title sl-flex">
7+
<Logo height="24" alt={siteTitle} />
8+
</a>

‎docs/src/content/docs/index.mdx‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: OpenAI Agents SDK for TypeScript
2+
title: OpenAI Agents SDK TypeScript
33
description: The OpenAI Agents SDK for TypeScript enables you to build agentic AI apps in a lightweight, easy-to-use package with very few abstractions.
44
---
55

@@ -15,6 +15,8 @@ import helloWorldExample from '../../../../examples/docs/hello-world.ts?raw';
1515
<Fragment slot="cta">Let's build</Fragment>
1616
</Hero>
1717

18+
## Overview
19+
1820
The [OpenAI Agents SDK for TypeScript](https://github.com/openai/openai-agents-js)
1921
enables you to build agentic AI apps in a lightweight, easy-to-use package with
2022
very few abstractions. It's a production-ready upgrade of our previous

‎docs/src/content/docs/ja/index.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: OpenAI Agents SDK for TypeScript
2+
title: OpenAI Agents SDK TypeScript
33
description: The OpenAI Agents SDK for TypeScript enables you to build agentic AI apps in a lightweight, easy-to-use package with very few abstractions.
44
---
55

0 commit comments

Comments
 (0)