Skip to content

README.md

Latest commit

 

History

History
61 lines (37 loc) · 8.01 KB

README.md

File metadata and controls

61 lines (37 loc) · 8.01 KB
Raw

OpenAgentCore website

The website is the landing page plus the published documentation, built with VitePress and deployed to GitHub Pages. It reads the repository's docs/, contracts/ and docs.json in place: no page is copied, moved or rewritten.

Run it

pnpm --dir website install --frozen-lockfile
pnpm --dir website dev       # http://127.0.0.1:4180
pnpm --dir website build     # website/.vitepress/dist
pnpm --dir website test      # after build: navigation and output checks
pnpm --dir website preview   # serve the build at http://127.0.0.1:4181

How documentation reaches the site

  • The content root is the repository root. docs/** and contracts/** keep their paths as URLs, so docs/architecture.md is /docs/architecture. website/index.md and website/zh/index.md are mapped onto / and /zh/. Chinese sources in docs/zh/ and contracts/agents-api/zh/ map to /zh/docs/ and /zh/contracts/agents-api/; the language switch opens the matching page.
  • docs.json owns the page list and order: three tabs (Docs, API, Extend), each with groups of pages. The top nav shows one item per tab, and each page's sidebar shows only its own tab. /llms.txt lists every page under ## <tab> › <group> with a one-sentence summary taken from the page's first paragraph. Each page's frontmatter title is its label. Every Markdown page under docs/ and contracts/ is built, and a test fails when one is missing from docs.json.
  • Each page's source Markdown is published next to its HTML (/docs/architecture.md), and the README paths declared in docs.json redirect to their section index.
  • Relative links from a page to a file that is not a published page, such as CONTRIBUTING.md or openapi.yaml, are rewritten to GitHub at build time, so the Markdown works unchanged on GitHub and on the site.

The visual system combines warm paper surfaces, green accents and ruled sections. Landing headings use self-hosted Space Grotesk (loaded by the landing only); body text uses Inter and code uses Geist Mono. Chinese text uses the system Chinese sans-serif stack. Both light and dark themes share the same hierarchy.

Site appearance and metadata are configured in .vitepress/config.mts and .vitepress/theme/.

The landing page lives in .vitepress/theme/. landing-content.ts holds its English and Chinese copy; every claim there must be backed by a page in docs/ or contracts/, link labels equal the target page titles, and its Harness protocols follow Model execution. The hero lede and the description in config.mts are the same sentence.

The hero holds the title, the lede, the install command and the interactive example (components/ComposeLab.vue). Below it are four sections: an architecture image, the Session diagram, console screenshots and next steps, with four documentation shortcuts and the logo wall between the last two. components/SessionFlow.vue illustrates native execution, Core orchestration and multiple Session environments through a three-stage hand-drawn animation that scales to the column width. It autoplays while visible and offers previous/next buttons, a stage slider and pause/play. Reduced-motion preferences disable autoplay. The diagram uses the locally bundled Virgil font; its OFL license is stored beside the font in .vitepress/theme/assets/fonts/.

Launch video

components/LaunchVideo.vue renders the "Watch the launch film" link in the hero. The CDN-hosted video loads only when the link opens the modal player; nothing autoplays. The close button, Escape and backdrop dismiss the player.

Ecosystem logo wall

components/LogoWall.vue places two full-width logo rows between the documentation shortcuts and the closing section. The wall is transparent and borderless, allowing the landing page's background and grid to continue through it. Harness and model brands occupy the first row; cloud and compute brands occupy the second. They scroll in opposite directions, pause on hover or row keyboard focus, and have an explicit pause control. Reduced-motion preferences disable animation and leave both rows manually scrollable.

.vitepress/theme/ecosystem-logos.ts owns the brand list. These are ecosystem illustrations; supported Harness combinations remain defined by Model execution, and host requirements by Install Core and Web. Brand artwork does not establish deployment qualification or a partnership.

SVG files are bundled under .vitepress/theme/assets/logos/ and tinted with CSS (dark in the light theme, white in the dark theme), preserving their proportions. Their sources are:

  • AI brands, AWS, Azure, Google Cloud, Alibaba Cloud, Tencent Cloud, Huawei Cloud, Volcengine, Baidu AI Cloud and DigitalOcean: Lobe Icons, from @lobehub/icons-static-svg version 1.95.1, using the matching filename in its icons/ directory. MIT license: LICENSE-lobe-icons.txt beside the assets.
  • Docker: SVGL's Docker SVG. MIT license: LICENSE-svgl.txt beside the assets.
  • Hetzner: Simple Icons' Hetzner SVG. CC0 notice: LICENSE-simple-icons.txt beside the assets.
  • E2B: the medium white symbol from E2B's official brand assets, file e2b-symbol-white-m.svg. Preserve its proportions and clear space according to that source's usage guidance.

Brand names and marks belong to their respective owners. Keep provenance and license notices with any added or replaced artwork.

Publish

/install.sh serves website/install.sh, a Bash entry that downloads the latest GitHub Release installer before executing it and forwards all arguments. Installation behavior remains owned by the release launcher; new releases require no website rebuild. The custom domain uses the same GitHub Pages deployment as the website, with no separate DNS record for this path.

make check-website builds and tests the site. make check-docs checks repository Markdown links, including explicit heading IDs used by translations. core-check runs it for pull requests that change the website, published documentation or relevant Node dependencies; .github/workflows/website.yml builds and deploys main to GitHub Pages. A repository administrator enables Pages once: Settings → Pages → Source: GitHub Actions.

The publishing step reads html_url directly from the GitHub Pages API and passes it to the build as WEBSITE_URL. VitePress derives the base path from that URL, supporting both https://<owner>.github.io/<repository>/ and a custom domain set under Settings → Pages → Custom domain. An empty or invalid URL stops the build. Local builds omit WEBSITE_URL to serve from /.

Pull request checks build under the published /OpenAgentCore/ path. Output tests verify that generated navigation, assets, redirects and llms.txt links use the configured path and that local HTML links resolve to generated files. To check a deployment path locally, run WEBSITE_URL=https://example.com/OpenAgentCore/ make check-website.

Maintain bilingual documentation

The translation rules are in Documentation. Give each Chinese heading the English heading ID as an explicit {#id} anchor. Resolve relative links from the Chinese file to the corresponding Chinese document or shared original asset. The Harness catalog generator produces both language editions. Extend other generators before translating their output; preserve generated regions in otherwise authored pages byte for byte, with a Chinese explanation before the region. Update source_hash only after reconciling the complete translation with the source. pnpm --dir website check-translations checks coverage and freshness before the build. docs.json remains the single navigation order; titles are read from the selected language's source.