Embedding in Existing Sites

Sourcey's output is static HTML that can be dropped into any existing website. Astro projects can mount Sourcey directly with the first-class integration; other frameworks can build into their public directory.

Astro integration

Install Sourcey and add the integration to astro.config.mjs:

import { defineConfig } from "astro/config";
import sourcey from "sourcey/astro";

export default defineConfig({
  site: "https://example.com",
  integrations: [
    sourcey({
      config: "./docs/sourcey.config.ts",
      routeBase: "/docs",
    }),
  ],
});

During astro dev, Sourcey serves the docs through Vite and watches the config, markdown, and spec inputs. During astro build, Sourcey writes the complete static docs surface into the Astro output directory under /docs.

Subfolder deployment

For other frameworks, build the output directly into your site's public directory:

sourcey build -o ./public/docs

Your existing site framework (Astro, Next.js, Hugo, plain Nginx) serves the public/ directory as static files. The sourcey output at /docs/ is completely self-contained: its own CSS, its own JS, its own search index. No conflicts with your main site's styles or scripts.

Build script integration

Add a build script to your package.json when your framework does not have a Sourcey integration:

{
  "scripts": {
    "build:docs": "cd docs && npx sourcey build -o ../public/docs"
  }
}

This assumes your sourcey config and markdown live in a docs/ subdirectory. Adjust paths to match your project layout.

Embeddable output

For iframe embedding, use the --embed flag. This strips the <html>, <head>, and <body> wrappers, producing bare content suitable for injection into an existing page.

sourcey build --embed -o ./embed

Warning

Embedded output expects its CSS and JS files to be served from the same directory. Make sure the output directory is accessible at the path the iframe src points to.

Real-world example

This documentation site is itself built with sourcey. The setup:

A docs/ directory in the sourcey.com repo contains sourcey.config.ts and all markdown files
sourcey/astro mounts that config at /docs
astro dev serves Sourcey through Vite for local authoring
astro build writes the generated docs into the final static output
The "Docs" link in the navbar points to /docs/

The marketing site and the documentation site are independently built and independently styled. They share a URL but nothing else.