Assets and Generated Downloads

StarryBio copies the public/ directory into the static build and validates configured local asset paths before building. Use it for profile images, favicons, card images, local icon files, and generated downloads.

Local and remote assets

Store local files below public/, then refer to them without the public/ prefix:

public/
└── assets/
    └── images/
        ├── profile.jpg
        ├── project-cover.webp
        └── default/             # StarryBio defaults

profile: {
  name: 'Morgan Lee',
  description: 'Designer and writer.',
  image: 'assets/images/profile.jpg',
},
favicon: '/assets/images/default/favicon.svg',

Both assets/images/profile.jpg and /assets/images/profile.jpg resolve to the same file under public/. On Cloudflare, Vercel, Netlify, and normal static hosts, StarryBio emits the asset below /assets/...; on a GitHub Pages project site, it emits /REPOSITORY/assets/... automatically. pnpm validate confirms each configured local asset exists and is inside that directory. Paths that try to leave public/ are rejected.

Keep your own images directly under public/assets/images/ or its custom subdirectories. The default/ directory is maintained by StarryBio and may change during updates.

HTTP(S) asset URLs are also supported:

profile: {
  name: 'Morgan Lee',
  description: 'Designer and writer.',
  image: 'https://cdn.example.com/morgan.jpg',
},

Remote assets are fetched directly by visitors, not downloaded into the StarryBio build. Choose a reliable HTTPS host and remember that its availability, privacy policy, caching, and content changes are outside your deployment. The project CSP permits HTTPS image sources; HTTP is accepted by validation but is not a good production choice.

Where assets can be used

Setting	Accepts local/remote asset paths	Notes
favicon	Yes	Adds the document icon link.
profile.image	Yes	Required profile image.
seo.image	Yes	Social sharing image; make it absolute or set canonicalUrl.
featured[].image	Yes	Decorative card image.
sections[].links[].icon	Yes, or SVG data/Simple Icon	Icon shown beside a link.
featured[].icon, status.*.icon	Yes, or SVG data/Simple Icon	Same icon model.

For a local icon, icon: 'assets/icons/mail.svg' is sufficient. Inline SVG path strings beginning with M and SVG source containing a <path> are also supported. Use Managing Content for the Simple Icons object form.

Generated Open Graph image

Enable ogImage to create a themed 1200×630 social image at build time.

ogImage: {
  enabled: true,
  output: 'public/og.png', // optional; .png or .svg under public/
  title: 'Morgan Lee', // optional; falls back to seo.title
  subtitle: 'Designer and writer', // optional; falls back to seo.description
},
seo: {
  image: '/og.png',
  canonicalUrl: 'https://links.example.com',
},

The generator uses the selected StarryBio theme, the profile name, and the title/subtitle fallback shown above. It creates SVG directly when the output ends in .svg; otherwise it renders a PNG. The default output path is public/og.png.

Generating a file does not automatically add it to social metadata. Set seo.image to the matching public path, as in the example, and configure an absolute seo.canonicalUrl so the generated image becomes an absolute sharing URL. For a GitHub Pages project site, the canonical URL must include /REPOSITORY/; the Pages workflow rebases the local image path before it is made absolute. See SEO and Analytics.

Generated QR code

qr: {
  enabled: true, // generates the file during the build
  showButton: true, // optional; controls the Download QR code profile action
  url: 'https://links.example.com', // optional only when seo.canonicalUrl exists
  output: 'public/qr.png',
},

The build generates a 960-pixel QR code. url is optional only if seo.canonicalUrl is configured, in which case that canonical URL becomes the encoded value. The output must stay under public/ and end in .png or .svg; use the default public/qr.png unless you specifically need SVG output.

enabled controls QR generation. showButton independently controls whether the profile displays the “Download QR code” action; it defaults to true for existing configurations. Set showButton: false to generate and deploy the QR file without exposing the profile action, so it remains available at its public output URL. Test the downloaded file and scan it after deployment. A QR code should normally encode the final canonical production domain, not a local or workers.dev preview URL.

Generated contact card

contactCard: {
  enabled: true,
  output: 'public/contact.vcf',
  name: 'Morgan Lee',
  email: 'hello@example.com',
  phone: '+1 555 123 4567',
  website: 'https://links.example.com',
  organization: 'Morgan Lee Studio',
  title: 'Designer',
},

An enabled contact card requires a non-empty name and at least one of email, phone, or website. The output must be a .vcf file under public/; the default is public/contact.vcf.

StarryBio emits vCard 3.0 text, escapes vCard separators and newlines, removes a leading mailto: from the email field, and folds long lines by UTF-8 byte length. The page then shows an “Add Contact” download action. Open the final file in the contacts app your audience uses to verify its interpretation.

Every card field is public because the resulting .vcf is downloadable by anyone. Do not include a private phone number, personal address, or internal organization details simply because the file is generated during build.

Generated-file lifecycle

Before every build, StarryBio removes both the configured output and its default output for each generator. When a generator is disabled, its output is removed so an older og.png, qr.png, or contact.vcf does not accidentally remain in the next deployment.

Generated output paths and Simple Icon files are ignored by Git. They are reproducible build artifacts, not source assets. To keep a manually authored image or vCard, choose a different file path and do not enable a generator that uses that same path.

Asset review checklist

1. Run pnpm validate after changing any local path.
2. Run pnpm build and inspect dist/ or use pnpm preview.
3. Test the QR and vCard download actions on the built site.
4. Confirm seo.image resolves to a public, absolute URL after the custom domain is connected.
5. Use descriptive, optimized images; StarryBio provides fixed image dimensions in its rendered components but does not resize or host remote images for you.

Related: Managing Content, SEO and Analytics, and Security and Privacy.