diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 6467786..62a3de2 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -1,11 +1,27 @@
 import { defineConfig } from 'vitepress';
 
+export function resolveDocsBase(env: NodeJS.ProcessEnv = process.env): string {
+  const explicitBase = env.DOCS_BASE ?? env.VITEPRESS_BASE;
+
+  if (explicitBase) {
+    return explicitBase;
+  }
+
+  const repositoryName =
+    env.GITHUB_ACTIONS === 'true'
+      ? env.GITHUB_REPOSITORY?.split('/')[1]
+      : undefined;
+
+  return repositoryName ? `/${repositoryName}/` : '/';
+}
+
+const repositoryBasePath = resolveDocsBase();
+
 export default defineConfig({
   title: '@bquery/ui',
   description: 'Production-grade web component library for the bQuery project',
-  base: '/',
+  base: repositoryBasePath,
   themeConfig: {
-    logo: '/logo.svg',
     nav: [
       { text: 'Guide', link: '/guide/getting-started' },
       { text: 'Components', link: '/components/' },
diff --git a/tests/docs-config.test.ts b/tests/docs-config.test.ts
new file mode 100644
index 0000000..b319acd
--- /dev/null
+++ b/tests/docs-config.test.ts
@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'bun:test';
+import config, { resolveDocsBase } from '../docs/.vitepress/config.ts';
+
+describe('docs config', () => {
+  it('defaults to the site root outside GitHub Pages builds', () => {
+    expect(resolveDocsBase({})).toBe('/');
+  });
+
+  it('uses the repository base path for GitHub Pages assets in GitHub Actions', () => {
+    expect(
+      resolveDocsBase({
+        GITHUB_ACTIONS: 'true',
+        GITHUB_REPOSITORY: 'bQuery/ui',
+      })
+    ).toBe('/ui/');
+  });
+
+  it('allows overriding the docs base explicitly', () => {
+    expect(resolveDocsBase({ DOCS_BASE: '/preview/' })).toBe('/preview/');
+  });
+
+  it('wires the exported config to the resolved docs base', () => {
+    expect(config.base).toBe(resolveDocsBase());
+  });
+
+  it('does not reference a missing docs logo asset', () => {
+    expect((config.themeConfig as { logo?: string }).logo).toBeUndefined();
+  });
+});