Skip to content

Commit ad89787

Browse files
paulsmithpaulsmith
authored
Merge pull request #3 from VibiumDev/codex/vibium-docs-site
Replace vibium.com site with Vibium docs site
2 parents 0a7b44f + 1262e89 commit ad89787

81 files changed

Lines changed: 8542 additions & 422 deletions

Some content is hidden

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

‎.github/workflows/deploy-pages.yml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
name: Deploy Vibium Site to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: github-pages
15+
cancel-in-progress: false
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- name: Checkout
22+
uses: actions/checkout@v6
23+
24+
- name: Build and upload Astro site
25+
uses: withastro/action@v6
26+
with:
27+
path: ./site
28+
package-manager: pnpm@latest
29+
build-cmd: make -C .. build
30+
env:
31+
SITE_URL: ${{ vars.PAGES_SITE_URL || 'https://vibium.com' }}
32+
BASE_PATH: ${{ vars.PAGES_BASE_PATH || '/' }}
33+
ASTRO_TELEMETRY_DISABLED: true
34+
35+
deploy:
36+
needs: build
37+
runs-on: ubuntu-latest
38+
environment:
39+
name: github-pages
40+
url: ${{ steps.deployment.outputs.page_url }}
41+
steps:
42+
- name: Deploy to GitHub Pages
43+
id: deployment
44+
uses: actions/deploy-pages@v5

‎.gitignore‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
site/node_modules/
2+
site/dist/
3+
site/.astro/
4+
site/src/content/docs/
5+
llms.txt
6+
llms-full.txt
7+
site/public/llms.txt
8+
site/public/llms-full.txt
9+
site/public/llms/
10+
.pnpm-store/
11+
.DS_Store

‎Makefile‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
PYTHON ?= python3
2+
PNPM ?= pnpm
3+
NODE ?= node
4+
DEV_SERVER_ADDRESS ?= 127.0.0.1
5+
6+
SITE_DIR := site
7+
CLEAN_MANIFEST := scripts/clean-manifest.txt
8+
SITE_NODE_MODULES_DIR := $(SITE_DIR)/node_modules
9+
10+
.PHONY: all build rebuild serve preview test install clean distclean help
11+
12+
all: build
13+
14+
build:
15+
$(PYTHON) scripts/build_llms_txt.py
16+
$(PYTHON) scripts/sync_starlight.py
17+
$(PNPM) --dir $(SITE_DIR) exec astro build
18+
$(PYTHON) scripts/postprocess_site.py
19+
20+
rebuild: clean build
21+
22+
serve:
23+
$(PYTHON) scripts/build_llms_txt.py
24+
$(PYTHON) scripts/sync_starlight.py
25+
$(PNPM) --dir $(SITE_DIR) exec astro dev --host $(DEV_SERVER_ADDRESS)
26+
27+
preview: build
28+
$(PNPM) --dir $(SITE_DIR) exec astro preview
29+
30+
test: build
31+
$(NODE) --test $(SITE_DIR)/scripts/built-site.test.mjs
32+
33+
install:
34+
$(PNPM) --dir $(SITE_DIR) install
35+
36+
clean:
37+
$(PYTHON) scripts/clean_generated.py $(CLEAN_MANIFEST)
38+
39+
distclean: clean
40+
rm -rf $(SITE_NODE_MODULES_DIR)
41+
42+
help:
43+
@printf '%s\n' \
44+
'Targets:' \
45+
' make build Regenerate public LLM docs, sync Starlight content, and build site/dist.' \
46+
' make rebuild Clean generated site output, then run make build.' \
47+
' make serve Regenerate public LLM docs, sync Starlight content, and start Astro dev server.' \
48+
' make preview Build, then preview site/dist.' \
49+
' make test Build, then verify site/dist routes, LLM assets, and analytics.' \
50+
' make install Install site dependencies with pnpm.' \
51+
' make clean Remove generated outputs listed in scripts/clean-manifest.txt.' \
52+
' make distclean Run clean and remove site/node_modules.'

‎README.md‎

Lines changed: 72 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,77 @@
1-
# vibium.com
1+
# Vibium Website
22

3-
Landing page for [Vibium](https://vibium.com) — browser automation built for AI.
3+
[![Agent readability: 33/100](https://img.shields.io/badge/a14y-33%2F100-c2410c?label=agent%20readability)](https://a14y.dev/badge/?s=33&v=0.2.0&a=24&t=38&p=8&f=16&w=0&e=0&n=14&d=2026-05-26&m=site&u=https%3A%2F%2Fvibium.com%2F)
44

5-
## Local Development
5+
Browser automation for AI agents and humans, built on WebDriver BiDi.
66

7-
Just open `index.html` in a browser. No build step required.
7+
This repository contains the user-facing [Vibium](https://github.com/VibiumDev/vibium)
8+
website and documentation. The homepage is an Astro page at `/`, while the
9+
documentation is published under `/docs/`.
810

9-
## Links
11+
The docs are plain Markdown so they render well on GitHub, in Starlight, and
12+
inside an agent context window.
1013

11-
- [Twitter](https://twitter.com/VibiumDev)
12-
- [GitHub](https://github.com/VibiumDev)
13-
- [Contact](mailto:vibes@vibium.com)
14+
## Contents
15+
16+
- [Introduction](docs/introduction.md)
17+
- [Installation](docs/installation.md)
18+
- [Quickstart](docs/quickstart.md) — a few lines, copy-paste.
19+
- [Getting Started](docs/getting-started.md) — the mental model.
20+
- [Tutorial: Filling a Form End-to-End](docs/tutorial.md) — a worked example.
21+
- [Core Concepts](docs/concepts.md)
22+
- [Command Reference](docs/commands/index.md)
23+
- [MCP Server Integration](docs/mcp-integration.md)
24+
- [Client Libraries](docs/client-libraries.md)
25+
- [Troubleshooting](docs/troubleshooting.md)
26+
- [FAQ](docs/faq.md)
27+
- [Contributing](docs/contributing.md)
28+
29+
## Site generation
30+
31+
The top-level `Makefile` is the build entrypoint:
32+
33+
- `make build` regenerates public LLM docs, syncs Markdown and MDX into
34+
Starlight, builds the static site in `site/dist/`, and postprocesses the
35+
generated output for agent-readable surfaces.
36+
- `make rebuild` removes generated site output first, then runs the full build.
37+
- `make serve` regenerates content and starts the local Astro dev server.
38+
- `make test` builds the site and verifies the homepage, `/docs/` routes,
39+
root LLM assets, agent-readable generated files, and Google Analytics wiring.
40+
- `make clean` removes generated output listed in `scripts/clean-manifest.txt`
41+
and deletes stray `.DS_Store` files.
42+
43+
Edit the homepage in `site/src/pages/index.astro`. Edit canonical docs content
44+
in `README.md` and `docs/`; `scripts/sync_starlight.py` copies those files into
45+
Starlight under `/docs/`.
46+
47+
Edit canonical brand imagery in `site/src/assets/brand/` and landing page
48+
imagery in `site/src/assets/landing/`. The favicon files in `site/public/` are
49+
stable served assets.
50+
51+
The generated `site/public/llms.txt` is a spec-compliant index served at
52+
`/llms.txt`; it links to Markdown copies of the docs under `/llms/`. The
53+
generated `site/public/llms-full.txt` keeps the single-file context form for
54+
agents that prefer one large document.
55+
56+
`scripts/postprocess_site.py` runs after Astro builds. It writes same-path
57+
Markdown mirrors into `site/dist/`, adds language classes to generated code
58+
blocks, adds `<lastmod>` values to the XML sitemap, and publishes
59+
`site/dist/sitemap.md`.
60+
61+
## Agent readability
62+
63+
The badge above reflects the latest live `https://vibium.com/` a14y site audit.
64+
To check unpublished changes locally, build with a localhost `SITE_URL`, preview
65+
the static output, and run the site audit against that preview:
66+
67+
```sh
68+
SITE_URL=http://127.0.0.1:4323 make build
69+
pnpm --dir site exec astro preview --host 127.0.0.1 --port 4323
70+
npx -y a14y check http://127.0.0.1:4323/ --mode site --output agent-prompt --max-pages 200
71+
```
72+
73+
After deployment, refresh the badge with the `Embed badge:` URL printed by:
74+
75+
```sh
76+
npx -y a14y check https://vibium.com/ --mode site --max-pages 200
77+
```

‎docs/client-libraries.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
---
2+
title: Client Libraries
3+
---
4+
5+
Vibium provides first-class libraries for JavaScript/TypeScript, Python, and
6+
Java. Each one wraps the same underlying binary, so the behavior matches the
7+
CLI exactly.
8+
9+
## Installation
10+
11+
```sh
12+
# JavaScript / TypeScript
13+
npm install vibium
14+
15+
# Python
16+
uv add vibium
17+
```
18+
19+
Java (Gradle):
20+
21+
```groovy
22+
implementation 'com.vibium:vibium:26.3.18'
23+
```
24+
25+
## JavaScript / TypeScript (async)
26+
27+
```js
28+
import { browser } from 'vibium'
29+
30+
const browserSession = await browser.start()
31+
const vibe = await browserSession.page()
32+
33+
await vibe.go('https://example.com')
34+
const png = await vibe.screenshot()
35+
36+
await browserSession.stop()
37+
```
38+
39+
The JavaScript client also exposes a synchronous flavor that works well in a
40+
Node REPL — see the project README for details.
41+
42+
## Python (sync)
43+
44+
```python
45+
from vibium import browser
46+
47+
browser_session = browser.start()
48+
vibe = browser_session.page()
49+
50+
vibe.go("https://example.com")
51+
text = vibe.text()
52+
print(text)
53+
54+
browser_session.stop()
55+
```
56+
57+
The Python client also has an async flavor; the API is the same with `await`
58+
in front of every call.
59+
60+
The Python client locates the bundled Vibium binary automatically. To use a
61+
custom build, set:
62+
63+
```sh
64+
export VIBIUM_BIN_PATH=/path/to/your/vibium
65+
```
66+
67+
## Java
68+
69+
```java
70+
var browserSession = Vibium.start();
71+
var vibe = browserSession.page();
72+
73+
vibe.go("https://example.com");
74+
var png = vibe.screenshot();
75+
76+
browserSession.stop();
77+
```
78+
79+
The published Maven Central artifact bundles native binaries for every
80+
supported platform.
81+
82+
## Mapping CLI commands to library calls
83+
84+
The libraries mirror the CLI:
85+
86+
| CLI | Library (Python sync, illustrative) |
87+
| ---------------------------------- | ------------------------------------------------------- |
88+
| `vibium go <url>` | `vibe.go(url)` |
89+
| `vibium map` | `vibe.map()` |
90+
| `vibium find text "<text>"` | `vibe.find_text(text)` |
91+
| `vibium click @e2` | `vibe.click("@e2")` |
92+
| `vibium fill @e3 "<value>"` | `vibe.fill("@e3", value)` |
93+
| `vibium text` | `text = vibe.text()` |
94+
| `vibium eval "<js>"` | `vibe.eval(js)` |
95+
96+
Refer to each language's package documentation for exact method names — the
97+
shape of the API is the same across all three.
98+
99+
## Lifecycle
100+
101+
- `browser.start()` boots a browser process (or attaches to a running one).
102+
- `browserSession.page()` opens a new tab and returns a handle.
103+
- `browserSession.stop()` shuts the browser down cleanly.
104+
105+
You generally want one `browser.start()` per process and one `page()` per
106+
logical session.

‎docs/commands/check.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: vibium check
3+
---
4+
5+
Toggle a checkbox.
6+
7+
## Synopsis
8+
9+
```
10+
vibium check @e<num>
11+
```
12+
13+
## Description
14+
15+
Sets the checkbox referenced by `@e<num>` to its checked state. If you need to
16+
explicitly uncheck a checked box, click it directly with [`click`](click.md)
17+
instead.
18+
19+
## Examples
20+
21+
```sh
22+
vibium check @e7
23+
```
24+
25+
Find first, then check:
26+
27+
```sh
28+
$ vibium find label "I agree to the terms"
29+
@e7 input label="I agree to the terms"
30+
31+
$ vibium check @e7
32+
```
33+
34+
## See also
35+
36+
- [`vibium click`](click.md), [`vibium select`](select.md), [`vibium fill`](fill.md).

‎docs/commands/click.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: vibium click
3+
---
4+
5+
Click an element by reference.
6+
7+
## Synopsis
8+
9+
```
10+
vibium click @e<num>
11+
```
12+
13+
## Description
14+
15+
Performs a real mouse click on the element identified by `@e<num>`. The
16+
reference must come from a recent [`map`](map.md) or [`find`](find.md) call.
17+
18+
Use [`wait`](wait.md) afterward if the click triggers navigation or a delayed
19+
DOM update.
20+
21+
## Examples
22+
23+
Click the second mapped element:
24+
25+
```sh
26+
vibium click @e2
27+
```
28+
29+
Click an element you've located by text — find first, then click the
30+
reference it returns:
31+
32+
```sh
33+
$ vibium find text "Sign in"
34+
@e4 link "Sign in"
35+
36+
$ vibium click @e4
37+
```
38+
39+
## See also
40+
41+
- [`vibium map`](map.md), [`vibium find`](find.md)
42+
- [`vibium wait`](wait.md)

0 commit comments

Comments
 (0)