Skip to main content

FAQ

Blue abstract topographic gradient cover for images-covers-faq

Publishing Images and Covers FAQ

Answers to common questions about hero, listing, and OG covers in a Docusaurus guide site—paths, roles, isolation, and promotion.

Publishing Images and Covers FAQ

Publishing images looks simple until a cover that works locally 404s after deploy, or a draft asset appears on the public site before Owner approval. This FAQ covers the patterns used by the Guidebook acceptance site.

What are hero, listing, and OG roles?​

Hero is the large image on the article page. Listing is the card image on hubs and sidebars. OG is the social preview crop, usually wider. The starter project stores them under assets.hero, assets.listing, and assets.og in front matter. Those fields only render if a theme consumer—here ArticleFrame and the homepage—reads them. Writing the fields alone on an unrelated theme does nothing.

Where should image files live?​

Put publishable files under the project static directory, commonly static/img/<slug>/.... During build, static/ is copied to the site root, so the public path drops the static segment: static/img/example/cover.webp becomes /img/example/cover.webp. Do not put static/ in Markdown or front-matter paths.

Can drafts use private images before promote?​

Yes. Managed drafts keep proposed assets in the private work directory. Native builds do not scan that directory. Covers become public static files only when an approved promote copies them into the configured static root. That isolation is intentional: a successful local preview of private work is not the same as a public deploy.

How do I register a new cover?​

  1. Register prose so the proposal digest matches the current Markdown.
  2. Run the cover skill with a plan that points at a real PNG/JPEG/WebP source and explicit variants.
  3. Register the cover change receipt before another image operation on the same article.
  4. Re-run QA, mark reviewed, and wait for Owner approval of the proposal digest before promote.

Skipping register after an image change leaves a stale digest and will fail promote checks.

What aspect ratios should I use?​

Match the layout. Guidebook homepage cards are tall full-bleed frames; article heroes can be square or wide depending on the frame CSS. OG previews commonly use about 1200×630. Encode with a quality floor that still fits your byte budget—managed cover scripts will refuse to silently upscale or drop below the plan’s quality floor.

Why did my cover disappear after changing baseUrl?​

Subpath deploys set baseUrl (for example /kb/). Public image URLs must include that prefix once. Prefer root-relative /img/... paths in content and let Docusaurus helpers apply baseUrl. Hard-coding a full origin without the subpath, or applying baseUrl twice in React, breaks images.

Do I need remote CDN URLs?​

No for acceptance. Local WebP under static/img/ is enough when the theme resolves public paths. Upload to a CDN only when you need a stable absolute URL for a third party; then register a URL receipt that matches the local bytes. Never invent fake temporary URLs.

What does QA check on images?​

Content QA verifies that referenced local assets exist, that front matter is coherent, and—when you pass a built dist—that HTML title, description, canonical, og:image, and body image src values match. It does not judge photographic quality. You still decide whether the crop serves the article.

Can I edit images directly in site/static during a revision?​

Prefer the managed workflow. Editing only the public static copy while a revision is open can desync hashes and leave private work pointing at outdated bytes. Begin a revision, change proposed assets, register, review, and promote with an explicit Owner approval of the proposal digest.