Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

9.1 KB
Raw Blame

Publishing an Alook Blog article

Blog is an independently built Next.js/MDX app. Author articles in src/content/<slug>.mdx and keep their images in public/blog/<slug>/. Keep the existing article URL when revising a post; use the redirect registry for an intentional URL move.

Required article elements

Use an exported JavaScript metadata object, not YAML frontmatter:

export const metadata = {
  slug: "example-guide",
  title: "A clear title that describes the article",
  date: "2026-10-09",
  author: "Alook Team",
  excerpt: "A useful description of the question this article answers.",
  readingTime: "5 min read",
  image: "/blog/example-guide/hero.webp",
};

Answer the reader's question before expanding on it.

![Description of what the diagram communicates](/blog/example-guide/hero.webp)

## A descriptive section heading

Include useful explanations, evidence, and relevant links.
  • Required metadata: slug, title, date, author, excerpt, readingTime. Slug must match the filename, using lowercase words separated by hyphens. Dates use valid YYYY-MM-DD; reading time uses N min read.
  • Optional: tags (unique lowercase kebab-case strings), seoTitle (nonempty when supplied), dateModified, image, draft, agentSummary. seoTitle changes search/social titles, not the visible H1. Set dateModified only for a substantive revision, never earlier than date.
  • The template owns the single H1. Start body sections at ##, then use ### for subsections. Do not add another # Title.
  • Register every published article once in src/lib/blog/topics.ts, with its real topic and reader job. A draft uses draft: true and must stay out of public discovery/navigation.
  • Use valid article paths and existing heading fragments for internal links. Prefer links that help the reader over a required link count. When publishing, check whether a relevant older article should link to this one.

Independent step guides

Structured onboarding pages use /tutorials/<slug>, registered in src/web/src/lib/step-guides.ts and rendered by src/app/tutorials/[slug]/page.tsx in this Blog app. They appear in the /tutorials directory; existing MDX guides keep /blog/<slug> URLs. Register the canonical title and description once. The main sitemap consumes this registry, so a release introducing a route must include both Blog and main sitemap changes.

Step guides render their text and mock UI on the server. Animation code loads only when its scene enters the viewport; provide explicit playback, reduced-motion static content, pause/cleanup and failure recovery. scripts/validate-step-guides.ts checks the rendered headings, body, canonical, metadata, anchors, CTA and footer during the Blog build. They do not enter the MDX discovery manifest or RSS.

Main Blog or Guides?

Same-topic content variants must use tags: ["guides"]. For example, applying the same collaboration problem to another coding-agent combination belongs in the supplementary /guides directory, not another similar main-Blog post. If the question and answer are unchanged, revise/link the existing article instead of creating a duplicate. Main-Blog additions need a distinct reader question explained during editorial review; the build cannot infer semantic similarity.

export const metadata = {
  // Keep the normal required article fields.
  tags: ["guides"],
};

Continue registering the article once in src/lib/blog/topics.ts for its category. Guides reuses those categories and the existing /blog/<slug> article URL, author/date display, images and reading template. Missing tags keeps old articles in the main Blog; other tags alone do not move an article. Do not retag existing posts without an editorial decision.

The tag excludes an article from the main Blog list and RSS, Keep exploring and Next Blog. The Blog footer links to the /guides directory; do not add individual guide articles to footer navigation. Readers find guides through that directory, direct/search links and relevant editorial body links. A guide's back/category links return to /guides. It remains in the existing discovery manifest and sitemap, with its own original canonical URL; do not add noindex merely because it is absent from the main list. Drafts remain private.

Images and sharing

Use normal Markdown image syntax and an existing local /blog/<slug>/... URL. Supported source formats are PNG, JPEG, WebP and SVG. Each referenced source must be at most 2 MiB; this ceiling is not a recommended target. Keep whole-article image cost low, especially on mobile. Preserve legibility in screenshots and diagrams.

Use meaningful alt text for informative images. An explicitly empty alt is appropriate only for a decorative image. Do not put keywords into alt text just to influence search.

The build reads real dimensions and generates src/lib/blog/image-assets.json; do not hand-edit this manifest. It also generates responsive WebP files in public/blog/_generated/ (gitignored). The MDX transform emits width/height, responsive sources and decoding hints. The first body image loads eagerly; subsequent images are lazy. Put the intended leading image first. Explicit JSX image markup must meet the same rendered requirements; ordinary Markdown is the supported default.

The OG metadata uses the same asset dimensions as the article. Without metadata.image, the existing /og/blog/<slug> route supplies a generated sharing image. Do not declare a fixed 1200×630 size for a differently sized source file. Check the final sharing image, not just the metadata string.

What Blog build checks

From the repository root, run:

pnpm --filter @alook/web build:blog

This includes source validation, image preparation, Next compilation, and rendered article validation before Worker packaging. The final packaging step stages the prerendered cache into Workers Static Assets, so the read-only cache works with raw Wrangler deployment as well. build:blog:next is the internal Next/standalone preparation step used by that command. validate:blog alone checks source files; it is not the full publishing gate.

Build errors include missing/invalid required metadata, invalid optional SEO title, duplicate H1 in Markdown, invalid/missing/oversized source images; then, in rendered articles: missing body/title/description, a missing or extra H1, incorrect canonical, noindex, duplicate heading IDs, conflicting/unparseable BlogPosting JSON-LD, missing local article/fragment/image resources, and inconsistent image or OG dimensions. Generated responsive resources must exist. Drafts must not become prerendered public articles. The full published article set must match topics and the discovery manifest (which supplies the main site sitemap). The main index and RSS contain only articles without the guides tag; /guides lists tagged MDX articles. Separate step guides live in /tutorials. Their two index sets must partition the published articles. Footer navigation may link to the /guides directory, but must not link to individual guide articles. Keep exploring / Next Blog recommendations must not include the Guides directory or guide articles.

The existing topic tests compare published MDX and the topic registry in both directions. Run related tests when changing templates or publication behavior; negative fixtures must demonstrate that invalid output actually fails. Keep image-assets.json regenerated with any source-image change so a clean checkout can typecheck before its first build.

Editorial review is still required

These checks do not evaluate truth, search intent, image legibility or originality. Before publication:

  1. State which reader question the article answers and how it differs from existing posts; update an older post when that serves readers better.
  2. Verify product steps against the current UI. Cite sources for external claims; distinguish tested behavior from documentation-based comparison, and record when volatile facts were checked.
  3. Use a real person or team byline. Add author/reviewer context only when accurate. Do not invent expertise or refresh dates to simulate freshness.
  4. Check long/multi-image articles at desktop and mobile sizes, including light and dark. Inspect image text, links, anchors and sharing metadata.
  5. Follow the existing content and deployment ownership. After deployment, check the public article, images and discovery entries. A successful build or merge is not proof that production has updated.

Title/description length, related-link opportunities and article image budgets are editorial decisions, not fixed ranking rules. Do not pad keywords or add FAQs solely for rich results. Google no longer shows FAQ or HowTo rich results; retain structured data only when it describes real visible content. Review Search Console page/query data when available to prioritize updates; HTTP 200 does not prove indexing or ranking.

References: Google Article metadata, Google image guidance, Search feature updates.