DEV Community: RadarMakers

Why Apache returned 502 for our Go uploads

Live alternatives to a well known tool, only after five real matches

Programmatic SEO pages and thin content: noindex until there are three items

A Heading Count Is Only the Start of an Outline Review

An Image Loading Attribute Is a Hint, Not a Performance Result

Letting crawlers read noindex on Next.js auth pages

IndexNow in Go: tell search engines about new pages in one request

Blocking SSRF in Go when your server fetches URLs that users type

Counting visitors without cookies or storing IP addresses

Open Graph images for every page with Next.js ImageResponse

Auditing your own backlinks with a Python script: dedupe hosts, check rel, find what is live

I built 8 free maker tools: six never upload your files, two fetch a URL for you

What the proxy changed

Why an early length check helped

The drain is bounded for a reason

Request bodies without a trustworthy length

A transport limit is not a memory limit

Extension policy is part of the safety design

What to observe in production

Review the implementation as a set of invariants

Two charts from the implementation record

Checklist for investigating a proxy upload error

The same upload had different outcomes

The limit applies to the request body

Reject by declared length before parsing

The drain has its own ceiling

Unknown lengths keep the reader guard

What is verified and what remains open

Sources

What the hub actually says

Why five, and why the job matters

What a tool page would show

Images that are live, and images that wait

Links from the catalog

Validate every candidate before counting it

Attribute the fields the table actually shows

Keep an empty hub honest and useful

Match structured data to visible content

Review the route as a visitor and a crawler

Avoid implying endorsement or a complete review

Treat the snapshot as a dated observation

Keep the publication rule understandable

What changed between the two checks

What this does not prove

Sources

Two kinds of generated pages

One gate, one definition of "live"

What the page emits

The sitemap follows the same rule

Three days later, the same check

When the product lookup fails

Renaming without losing the old URLs

What this does not tell you

Test boundary behavior, not only the happy case

Keep metadata and sitemap checks together

Separate page quality from index eligibility

Preserve meaning when category routes are renamed

Keep decisions small and reversible

Takeaways

Sources

Start with the observed ranks

Extract the sequence as well as the histogram

Separate shared navigation from page content

Review words before changing levels

Verify the rendered result

Record a bounded result

Read the totals chart beside the rank table

Record enough context to repeat the inventory

Scope the outline to the right region

Compare label sequences, not only counts

Separate semantic structure from visual styling

Test interactive and responsive states

Turn findings into a focused change

Explain what this sample can and cannot say

Make the review repeatable for future edits

Avoid turning a sample into a site-wide claim

Count the literal attributes

Make the extraction reproducible

Follow the count with a placement review

Define the next measurement

Keep the conclusion inside the evidence

Read the second chart as a route comparison

Preserve the response before parsing it

Make parsing decisions visible

Separate source order from what a person sees

Keep priority decisions tied to purpose

Treat image accessibility as a different review

Use a before and after record

Bound the conclusion

Turn the inventory into a handoff another developer can use

Recheck when the content model changes

The rule that is easy to get backwards

What we had

The change

Why a header and not a meta tag

What we left alone

The cost we accepted

Checking what the server sends

What this does not tell you

Takeaways

What IndexNow asks for

The client

Fire and forget, on purpose

Calling it after a successful write

Serving the key file from Next.js

Testing it

What it does not promise

Takeaways

The obvious version and its gap

Check the address the connection uses

Which addresses count as public

Redirects that you follow yourself

Tests

Takeaways

What gets stored

The browser side: a beacon and nothing else

The server side: filter, derive, forget

Counting a unique visitor with one insert

Cleaning up

What this does and does not promise

How we test it

Takeaways

A route handler per image, a versioned URL in the metadata

One shared layout

Per page data

Measuring text before drawing it

Caching at three levels

How we test it

Takeaways

The six that stay in your browser

The two that need a server

The pattern that keeps them testable

What I would do the same way again

RadarMakers — Tue, 10 Nov 2026 01:22:58 +0000

An oversized upload should give someone a useful rejection. In our case, the browser received "Upload failed: 502" even though the Go handler had a file-too-large response. The affected site was RadarMakers, a free launch platform for indie makers, with Apache forwarding uploads to Go.

The interesting part was the difference between the application response and the response that reached the browser. The workaround checks the declared request length before parsing multipart data, attempts a bounded discard of an oversized body, then writes the rejection.

This account comes from the current handler and its Git history. The earlier failure is documented there; I have not reproduced it for this article. The code explains a specific workaround, with limits that matter as much as the happy path.

The failure was not simply that the application rejected a large file. The browser saw a 502 from Apache when the Go server reset the connection while the proxy was still forwarding the body. A direct request to the API had produced the handler response instead. That distinction is why the investigation followed the request across both hops.

Start a similar incident by capturing the browser response, the proxy error log, and the application log for the same request window. Compare a request sent through the public route with one sent directly to the service in a controlled environment. Keep the same method, headers, body, and authentication state. If the two paths differ, inspect how the proxy handles upstream resets and unread request bytes before changing the application status code.

This case record does not claim that every 502 during an upload has this cause. A proxy can return a gateway error for many upstream failures. Here the repository comment identifies the reset during body forwarding, and the recorded comparison showed a different response on the direct path. Those are the facts behind this particular workaround.

The handler checks the declared Content-Length before wrapping the body or calling the multipart parser. When that value exceeds the request threshold, it takes a rejection path without parsing the form. This avoids spending image parsing work on a request that the server already intends to reject.

The header is only an early signal. A client can omit the length or send a value that does not describe the bytes that arrive. The source therefore keeps a second guard with http.MaxBytesReader before ParseMultipartForm. The Go documentation describes that reader as a request body limit that returns a MaxBytesError after a read crosses the configured size, and says it may tell the response writer to close the connection if possible.

The two checks answer different questions. The first decides whether the declared size already exceeds the limit and can be rejected before parsing. The reader limit protects the path where the header cannot make that decision. Neither check proves that the image is safe to decode. Content length limits transport size; image validation has separate responsibilities.

On the declared oversized path, the handler attempts to discard up to five times the body limit. With the current constant, that is a maximum read attempt of 25 MiB. The io.CopyN call writes to io.Discard, so these bytes are consumed for connection handling and are not stored as an upload.

A bounded drain is a tradeoff, not a universal recipe. Reading a portion of a rejected body can give a proxy a chance to finish forwarding bytes already in flight, but an unbounded read would let an oversized client keep the handler occupied for an arbitrary amount of data. The cap makes the maximum discard request explicit. The code ignores the returned byte count and error, then writes the 400 response, so it does not claim that every oversized body was fully consumed.

The comparison is important when changing the constants. Raising the file limit also changes the allowed request size and may change the maximum drain if the multiplier stays fixed. Increasing only the drain cap changes how much rejected traffic the handler may read. These values should be reviewed separately and tested with the proxy configuration that actually fronts the service.

HTTP request bodies can arrive without a useful declared size. The handler still wraps the body with MaxBytesReader, so the multipart parse cannot consume an unbounded body through this path. The same fallback also matters if the declared value is smaller than the bytes actually read. The header check is therefore an optimization and early rejection, not the sole security boundary.

A test suite should cover both known and unknown lengths. For a declared body above the threshold, assert that the early branch returns the intended status and message without parsing a multipart field. For a body whose declared size does not cross the threshold but whose actual bytes exceed it, assert that the reader limit controls the result. If the request uses chunked transfer, exercise the actual server and proxy path because middleware and proxy buffering can affect which component sees the limit first.

Avoid writing a test that only calls the handler directly and then declaring the production 502 fixed. The original difference occurred across Apache and Go. A direct handler test can verify the application branch, but it cannot verify how a deployed proxy handles a reset. Keep those claims separate in test names and release notes.

The configured limit is applied to the request body and multipart parsing. After the file is read, the handler also decodes and re-encodes the image. A compressed image can represent far more pixels than its byte size suggests. That is why the code checks the image header before decoding all pixels, and why the comment explains the risk of an extremely large image dimension.

The header buffer in the handler is 64 KiB. io.ReadFull attempts to fill that buffer, while treating EOF and unexpected EOF as conditions that can still leave a usable short header. The checkImage call receives only the bytes actually read. If the header cannot be parsed, the handler returns a client error before calling sanitizeImage.

A request size limit and a dimension check protect different resources. The first bounds incoming body bytes. The second rejects an image whose decoded dimensions would require unreasonable memory. Re-encoding then creates a cleaned output from pixels rather than copying the original file bytes. These operations should remain independently visible in code review because a change to one does not remove the need for the others.

The current allowlist accepts PNG, JPG, JPEG, and GIF after lowercasing the filename extension. SVG is deliberately absent because it is an active document format when served from the same origin. WebP is also absent because this implementation uses the standard library image path and re-encodes supported pixels. The allowlist is not a statement that every file with an accepted suffix is valid; the image decoder and sanitizer still inspect its contents.

A filename suffix is user supplied. It should not be treated as proof of the media type. The handler reads a header, checks it against the expected extension, seeks back to the start, reads the file, and sanitizes the decoded content. If a new format is added, test mismatched suffixes, malformed headers, oversized dimensions, and the final saved output. Also confirm that the chosen decoder and encoder remove metadata that should not be retained.

Instrument the rejection path without logging the file contents or sensitive request data. Useful fields include the route, the outcome category, whether the declared size crossed the threshold, and whether the request had a usable length. Avoid recording raw filenames if they may contain personal data. A counter by outcome can help detect a burst of rejected uploads, but it cannot show whether the proxy delivered the intended response. For that, compare proxy status and application status in a request trace with a safe correlation identifier.

Keep the logs explicit about boundaries. The application can record that it wrote a 400 response. The proxy log can record what it returned to the client. If those values differ, the path between the two is the subject of the next investigation. Do not collapse them into one field called upload status.

The existing order expresses a set of useful invariants. Authentication is checked before upload processing. Declared oversized bodies are rejected before multipart parsing. Other bodies are wrapped in a byte limit. The multipart form must contain the expected file field. The extension must be allowed. Image data is checked from its header before a full decode. The source bytes are re-read from the start for sanitization, then only the cleaned result is saved.

When refactoring, preserve the ordering or explain which property has changed. A helper that moves parsing above the length check may reintroduce the expensive path. A helper that copies original bytes to disk may preserve metadata or unsafe content. A broader format list may bypass the established sanitizer. Write a test for each boundary that matters rather than asserting only that a valid PNG succeeds.

The documented workaround is deliberately narrow. It changes the oversized declared-length path so the handler can attempt a capped drain before writing its intended response. It does not claim to solve every proxy timeout, every malformed multipart form, or every malicious image. That narrow description is more useful to the next person debugging a similar symptom than a general promise that uploads are now safe.

The threshold chart shows the exact request limit and drain ceiling read from internal/handler/upload.go. The format chart counts the extensions in the source allowlist: four accepted suffixes and two explicitly absent formats discussed in the code comments. These are implementation facts, not measurements of traffic or an estimate of risk. The diagrams already in the asset folder remain useful for request flow and the branch order; the charts add the actual values that a reader may want to compare with a proposed code change.

Before changing either number, rerun the relevant tests and inspect the deployment proxy limits, upload timeout, and body buffering configuration. This repository record documents the Go handler and its comments. It does not establish the settings of every reverse proxy or the behavior of every client.

[ ] Compare the public route and direct service response with the same request.
[ ] Correlate proxy and application logs for one request.
[ ] Check whether the content length is present and whether it matches the bytes sent.
[ ] Test the early rejection and the reader limit as separate paths.
[ ] Keep the rejected body drain capped and explain the cap.
[ ] Verify body size and decoded image dimensions independently.
[ ] Confirm the file header and extension agree before sanitizing.
[ ] Save only the re-encoded output when that is the security policy.
[ ] Test through the deployed proxy before claiming the client response is fixed.
[ ] Record which observations are from source, tests, or production logs.

Commit 33cb05b, dated August 26, 2026, records an oversized upload returning 502 through Apache and 400 when sent directly to the API. That comparison is the historical observation. It places the discrepancy between the direct API response and the response delivered through the proxy.

The handler comments describe the mechanism: the body limit was crossed while Apache was still forwarding the upload, the Go connection reset, and Apache answered the browser with a bare 502. The intended rejection lost its useful explanation along the way.

That is the documented behavior of this deployment. It should not be read as a universal rule that every call to MaxBytesReader immediately resets a connection. The Go documentation for MaxBytesReader describes a reader that errors when reads exceed the limit and, where possible, tells the response writer to close the connection afterward.

The distinction matters when investigating a similar symptom. A browser's status describes what arrived at the browser. Reading the handler's error branch alone does not establish that its response survived the proxy path.

The size constant remains small and explicit. Excerpt from internal/handler/upload.go:

    const maxFileSize = 5 << 20 // 5MB

The expression is 5 MiB. The comment and user-facing message say MB, but the binary count is what the code enforces. More precisely, this is a request body limit. A multipart upload includes framing and fields as well as the file, so it is not an exact allowance of 5 MiB for image bytes alone.

The handler first checks authentication and returns 401 if claims are absent. The length decision discussed here happens after that check. It is not a description of how an anonymous request is processed.

Choosing this body threshold is an application design decision. The source supplies the value; it does not establish that this is the right threshold for every upload service.

The added branch sits before the reader wrapper and multipart parser. Excerpt from internal/handler/upload.go:

    if r.ContentLength > maxFileSize {
        io.CopyN(io.Discard, r.Body, 5*maxFileSize)
        writeJSON(w, http.StatusBadRequest, map[string]string{"message": "file too large (max 5MB)"})
        return
    }

The decision uses the declared length before reading body bytes. Once that length exceeds the threshold, the handler already knows which response it intends to send. It does not parse the multipart form or inspect the image on this branch.

It still reads from the body before responding. Those bytes go to io.Discard; they are not accepted as an upload. The purpose, stated in the comments, is to let the 400 travel back through Apache while accommodating data the client has already sent.

The selected status is 400, with the existing file-too-large message. That is the application's response choice. The patch changes how the handler reaches that response rather than increasing the accepted upload size.

Multiplying the body threshold by five gives a discard cap of 25 MiB. That value is a separate design decision: the comments explicitly reject unbounded draining as a way for a client to make the server keep reading indefinitely.

The operation attempts to copy up to that amount from the body. The Go documentation for CopyN says it copies the requested count or stops on an error, returning the copied count and an error. This handler ignores both return values and proceeds to write 400.

For bodies whose actual size matches their declared size, a body over 5 MiB and no larger than 25 MiB fits within the drain budget. An earlier read error can still prevent a complete drain. A body larger than 25 MiB can leave bytes unread after the cap is reached.

Those consequences follow from the code. They do not establish that every oversized upload now avoids 502. The handler attempts a bounded accommodation of the proxy path; it does not verify that all bytes were consumed or guarantee delivery of its response.

A byte cap also should not be described as a time limit. This branch specifies an amount to discard, not a duration. Any claim about complete timeout protection would need evidence beyond these lines.

The declared length check is not the only protection. Requests that bypass it still encounter the original wrapper and parser. Excerpt from internal/handler/upload.go:

    r.Body = http.MaxBytesReader(w, r.Body, maxFileSize)

    if err := r.ParseMultipartForm(maxFileSize); err != nil {
        writeJSON(w, http.StatusBadRequest, map[string]string{"message": "file too large (max 5MB)"})
        return
    }

This includes requests without a declared length and those declaring a length at or below the threshold. The nearby comment also identifies an inaccurate declaration as a reason to retain the reader guard.

The branches therefore serve different purposes. Declared oversize selects the capped drain and rejection. Otherwise, actual reading remains bounded by MaxBytesReader before multipart parsing. Removing that wrapper would discard the protection for requests the length check cannot reject in advance.

There is another detail in the error handling: every error returned by this multipart parsing call maps to the same file-too-large message. Seeing that message is not, by itself, proof that the reader limit caused the parse error.

The history documents the earlier proxy failure. The current source contains the declared-length branch, the 25 MiB discard cap, and the retained 5 MiB reader limit. These are inspectable implementation facts.

The graphics README reports no regression test for the declared-length drain or Apache workaround in this checkout. Nearby image tests cover other concerns. They do not demonstrate that this response reaches a browser through Apache, and no such regression coverage is claimed here.

For a similar investigation, compare direct and proxied responses, then inspect what happens to unread request data when the handler rejects it. Keep the acceptance threshold, drain budget, and unknown-length behavior explicit. This patch makes those choices visible, while leaving a clear boundary around what its code and historical observation can support.

Go net/http documentation for MaxBytesReader:
Go io documentation for CopyN:
RadarMakers source: internal/handler/upload.go and the recorded change 33cb05b dated August 26, 2026.

RadarMakers — Sat, 31 Oct 2026 05:02:57 +0000

A page of alternatives is easy to fake. Pick a famous product, list anything from the same category, and the URL looks useful. On RadarMakers the directory does the opposite. A tool page is added only when at least five live products do the same job as one well known tool. A shared category or a shared tag is not enough.

This post uses the directory as it was served on 28 October 2026. The hub returned HTTP 200. Its visible sentence was: "No alternatives page is published yet, because no well known tool has five live matches in the catalog." Requests for /alternatives/notion returned 404. The same is true for any other tool slug. There is a route, and there is no published tool page.

The title is "Alternatives directory". The description says a page is added when at least five live products do the same job as one well known tool.

The introduction says the maker tagline and the pricing label come from the listing. It also says each published page has its own introduction, a comparison table, and answers to common questions. The order on a page follows community votes, then overall score, then the earlier launch.

Three questions are on the hub:

When is an alternatives page published? When five or more live products do the same job as one well known tool. A shorter list stays off the directory.
Does the table review the well known tool? No. The table shows RadarMakers products only. It uses the maker tagline and pricing label. It does not score the named tool and it does not add features the listing does not state.
How can a product appear on a list? Submit it for free with a confirmed account and wait for review. The reviewer checks that the website matches the listing. The product joins a page only when its job matches that tool and at least five live products qualify.

Those sentences are the page. They are not a claim that five substitutes exist for any named product today.

The constant in frontend/src/lib/saas-alternatives.ts is MIN_SAAS_ALTERNATIVES = 5. A target is a hand-written record: a slug, a name, an introduction, questions, and a list of product slugs. The publisher keeps a target only when at least five of those slugs are live. If the list is empty, the hub renders the empty sentence and the tool route calls notFound.

The hand-written list is the point. Two products in "AI Tools" can both be live and still do different jobs. Putting them on a "ChatGPT alternatives" page because they share a category would invent a comparison the listings do not support. The code comment says not to add a tool that has four matches.

On 28 October 2026 the target list was empty. That is why the sitemap on that day listed https://radarmakers.com/alternatives and no tool URLs under it. The hub entry changed two days later, as described further down.

The unpublished template still describes the table. The headings are Product, Tagline, and Pricing label. Each product name links to /product/<slug>. The pricing cell uses the maker label already stored on the product: free, freemium, paid, or open source. There is no extra price, no feature grid, and no winner.

The page would also repeat its own questions as FAQ structured data. None of that HTML is on the public site until a target qualifies.

The hub Open Graph image is /og/alternatives.png, 1200 by 630. Its alt text is "Discover alternatives | RadarMakers". The Twitter card is a separate file, /og/alternatives-x.png, 1200 by 675, with the alt text "Discover alternatives on RadarMakers. Tools from indie makers." Both returned HTTP 200 as image/png on 28 October 2026. The small header illustration is /illustrations/saas-alternatives/alternatives-header.svg.

Five taller cards exist for Notion, Trello, Canva, Zapier, and Calendly. They are 1200 by 675 and they are reachable as image files. They are not attached to a tool page, because those pages return 404. A template card that still says "Tool Name" is not published.

A recheck on 31 October 2026 gave the same picture. All seven image files, the two hub images and the five named cards, answered HTTP 200 as PNG files at the stated sizes. All five named tool routes still answered 404.

Source: HTTPS requests to radarmakers.com, checked October 31, 2026 at 04:55 UTC. Chart: RadarMakers.

The tool route, when a page exists, uses the generic Open Graph image. It uses a named Twitter card only for a slug that has one of those five files. Every other slug uses the generic Twitter card.

A product page can link to a tool page with the sentence "See this product on the {name} alternatives page". A category page can list the same tool pages when one of its products is on that list, and the product card in that category can show the same link. On 28 October 2026 those links had nothing to point at, because no tool page was published. The hub itself is linked from the footer and from /tools.

The threshold is necessary, but it does not establish that five products solve the same problem. Start with a plain language job statement. A shared category label is not enough. A tool that includes a notes feature is not automatically a replacement for a knowledge base. A design product with export is not automatically an image editor.

For every candidate, open the public product site and its directory listing. Confirm that it is live and that the available description supports the proposed comparison. Record the date and evidence. Exclude a product when the listing does not support the claimed use. Do not fill a missing detail with a guess. The five distinct live product IDs must be counted after status and duplicate checks.

This method also makes future maintenance possible. Products can change purpose, become unavailable, or leave the directory. Revisit each candidate set after material listing changes. If fewer than five still qualify, the page should stop presenting itself as an eligible comparison under the policy. A saved spreadsheet or a short review record is enough to make the decision reproducible.

The template uses product name, maker supplied tagline, and pricing label. Explain that narrow scope. The page does not independently review the named commercial tool and does not score a winner. A tagline is short maker supplied copy, not a verified feature specification. A label such as free, freemium, paid, or open source is not a price schedule.

If you add a new field, define its source and update method. A feature grid can appear authoritative while its claims become stale. A smaller table with current attributable facts may be more useful than a broad matrix built from uncertain details. Link readers to the product page for current terms. Do not infer an amount, usage cap, trial, or entitlement from a pricing label.

A method note should say what makes a product eligible, when records were checked, which fields come from the listing, and how a maker can suggest a correction. If the list is curated, explain the rule without implying independent testing. Disclose a connection when it could affect how the page should be interpreted.

State the inspection date and correction route. When a maker asks why a product appears, the team can point to the same job definition and evidence standard. Keep private correspondence private. Disclose an editorial or commercial connection when it affects how a reader should interpret the comparison.

An empty hub can explain the inclusion rule and link to broader discovery. It should not imply that comparison pages exist when they do not. Make the empty state useful by explaining what a future page would contain and where a reader can browse now. Avoid promising a specific date unless the team has made that commitment.

An empty state can still produce broken internal links if a category card or product page points to an unqualified target. Test links from the hub, product detail, category page, and sitemap. A route that returns an error for an unknown or unqualified target may be correct, but it should not be linked as if it were ready.

The recorded snapshot showed five named image cards prepared for Notion, Trello, Canva, Zapier, and Calendly, while no target comparison page was published. Those assets are not proof of completed editorial review. Keep design files, route records, and published content as separate states. A card can exist before the page qualifies, and that distinction should be clear to anyone reading the evidence.

Structured data describes the page; it does not repair vague copy or guarantee a result in search. Use a type only when its definition fits. Questions and answers in markup should be visible to a reader. Product names, canonical URLs, and table values should agree across visible text and metadata.

Recheck the output after the candidate set changes. A cached page can retain a former comparison after the live list no longer qualifies. Inspect a fresh build and the served response. Confirm status code, robots metadata, canonical, and sitemap membership together. Do not leave a self canonical on a removed route or point every potential page to the hub without a reason.

Start at the hub and follow every link. Open each product and target route. Verify response codes, title, description, canonical, robots directives, and visible content. Check the sitemap for the hub and eligible targets. Test an unknown slug and a target that previously qualified but no longer does. Update links after removing a route.

The initial HTML should contain the information a crawler needs without depending on a client side fetch. Check the social card and its alt text against the page that actually loads. A live response check verifies behavior at the time of inspection. It does not establish whether a search engine indexed the page or how it ranks.

Use a simple editorial worksheet: target name, shared job, candidate products, evidence, live status, distinct count, review date, and decision. Then review whether the title implies endorsement, whether the introduction explains limits, whether fields are attributed, and whether the empty state offers a working next step. This small record makes the page easier to maintain than a claim that it is curated.

[ ] Define the shared user job before collecting candidates.
[ ] Confirm each candidate is live, distinct, and supported by evidence.
[ ] Attribute maker supplied copy and pricing labels.
[ ] Keep the empty hub accurate and useful.
[ ] Verify route status, canonical, robots, internal links, and sitemap.
[ ] Ensure structured data matches visible page content.
[ ] Record evidence dates and recheck after catalog changes.

A page titled as an alternative list can sound like a verdict. Explain that the page is a directory of products whose public descriptions matched a defined job. Do not say that one is better, safer, faster, or cheaper unless the team has evidence and a published method for that claim. Keep editorial copy distinct from maker supplied text.

If community signals affect ordering, label them carefully. Votes indicate recorded interest, not a universal preference. Comments contain individual reports, not a representative survey. A rating captures member responses, not an independent test. Explain the sort rule where a reader encounters it, and avoid converting a position in the list into a quality award.

Give each product a route to its source page. Readers can inspect current terms and capabilities there. If a field is missing, state that it is not provided rather than filling the gap. If a product site is unavailable, pause the inclusion review and do not treat its stale listing as current evidence.

The date beside a live check is part of the evidence. The hub response, target route responses, and card files are observations from October 28, 2026. They do not say what the routes return today. When this article is reused, repeat the checks and update the date before describing current behavior.

Keep raw response notes or a small reproducible script where the team can find them. Store the requested URL, final URL after redirects, status code, content type, and retrieval date. Avoid collecting unrelated response data. A short audit trail helps distinguish a route that was never published from one that became unavailable later.

Do not treat the existence of an image as proof that a route is complete. A share card can be prepared in advance, but its title, image, and description need to match a public page before release. Check the initial HTML and metadata on the actual URL. If a page is not eligible, avoid linking its card as if the comparison were live.

The October 28 response count covers one inspected hub and five inspected tool routes. It is a snapshot for those addresses, not an error rate for the site or a statement about later responses.

A threshold is easiest to maintain when it is described in the same language as the user job. Explain that the route requires five live products that do the same kind of work, not merely five products with a shared tag. Put the rule near the empty state and in the internal review checklist. This makes a rejection easier to explain and helps another editor apply the same standard later.

The implementation should fail closed for a target that has not been deliberately configured. A popular product name in a URL is not enough reason to generate a page. Keep the set of approved targets explicit, and make sure the rendering route checks both membership in that set and current product eligibility. An unknown slug should not inherit a generic page with a misleading heading.

When the data source is unavailable, avoid treating the failure as a successful empty result. The page builder should preserve the distinction between no qualifying set and an unsuccessful lookup. Decide whether to show a temporary response, serve a recent cached page, or omit the route from the sitemap, then test that policy. The response should not claim that no alternatives exist if the underlying lookup failed.

The October 28 snapshot had one awkward detail. The hub said that no alternatives page was published, yet it was a normal index eligible URL listed in the sitemap. That is an empty listing page offered to search engines, which is the same thin content problem that category pages solve with a threshold.

A change deployed on October 30 closed that gap. The hub metadata now asks for the published target list first. When the list loads and is empty, the page emits noindex, follow. When the lookup fails, the page keeps its default metadata, so an API error does not quietly mark the hub noindex. The hub also stopped emitting an item list with zero entries in its structured data. The sitemap now adds the hub only when the first tool page is published.

// frontend/src/app/alternatives/page.tsx, excerpt
const pages = await getPublishedSaasAlternatives().catch(() => null);
return pages && pages.length === 0 ? { ...baseMetadata, robots: { index: false, follow: true } } : baseMetadata;

On October 31 the served hub carried <meta name="robots" content="noindex, follow"/>, and the sitemap had no URL under /alternatives. The visible sentence and the three questions were unchanged. Visitors still get the same page, with the same explanation of the rule. The only difference is that the site no longer asks search engines to index a directory with nothing in it.

Source: RadarMakers route checks on October 28 and October 31, 2026, and sitemap.xml on both dates. Chart: RadarMakers.

The target list in the code was still empty on October 31, so the five match rule had nothing to evaluate. That is the expected state for a rule that refuses to publish on a category match alone. The empty list is not a bug to fix by adding weaker targets. It is a record that no hand checked set has reached five live products yet.

Two habits come out of this change. First, an empty state needs its own metadata decision, the same as a thin category. Second, the failure case needs a separate decision, written next to the code, so that a timeout does not flip a page into noindex or into the sitemap by accident.

An empty directory is not a review of Notion, Trello, Canva, Zapier, Calendly, or any other product. It does not say that RadarMakers has no products in those jobs. It says no hand-checked set of five live products was published for one well known tool. Search engines were told about the hub URL through IndexNow on 28 October 2026. That notice does not create tool pages, and it does not say the hub is indexed.

RadarMakers alternatives implementation, frontend/src/lib/saas-alternatives.ts, route and template behavior recorded in this article.
RadarMakers live response inspection recorded October 28, 2026. The hub returned HTTP 200 and the five named target routes returned HTTP 404.
RadarMakers live recheck on October 31, 2026: hub response and robots meta tag, five named tool routes, seven image files, and sitemap.xml.
RadarMakers alternatives hub metadata change deployed October 30, 2026, frontend/src/app/alternatives/page.tsx.

RadarMakers — Sat, 31 Oct 2026 05:02:27 +0000

Generating pages from your own data is the cheap way to give a site hundreds of URLs. It is also the cheap way to publish hundreds of pages that say almost nothing. We chose to treat listings with fewer than three live products as too small for index eligibility. This post shows the rule we use for our category and tag pages: when the lookups succeed, a page with fewer than three live products emits noindex metadata while it stays available to visitors. The examples come from RadarMakers, where categories like Developer Tools are built from the catalog.

Three is our number. It is an application rule, not a search engine requirement and not a measured quality score. The rest of this post is about how to make such a rule behave well, including what it does when the data is missing.

Category pages live at /categories/<slug>. Selected categories have editorial copy in src/lib/category-pages.ts, followed by their live product listings.

Tag pages live at /tag/<slug>. Their text is assembled from facts about the products carrying the tag, using helpers such as listFacts, tagIntro and tagFaq in src/lib/tag-pages.ts. The helpers describe what the catalog returns at that moment and avoid quality claims.

Both kinds apply the same threshold.

The category threshold is a constant and a one-line function in the same file:

// frontend/src/lib/category-pages.ts, excerpt
export const MIN_INDEXED_PRODUCTS = 3;

// frontend/src/lib/category-pages.ts, excerpt
export function categoryIndexable(liveCount: number): boolean {
  return liveCount >= MIN_INDEXED_PRODUCTS;
}

Tag pages use a separate constant with the same value, MIN_PRODUCTS = 3, from src/lib/best-ranking.ts. The same file defines what counts as a product for this purpose:

// frontend/src/lib/best-ranking.ts, excerpt
export function liveProducts(products: Product[]): Product[] {
  return [...new Map(products.filter((p) => p.status === "live").map((p) => [p.id, p])).values()];
}

For category and tag metadata, liveProducts counts only products with the status live and removes duplicate IDs, so a product that appears twice in the fetched data counts once. A product that is not live never raises the number.

Here is what that rule looked like against the live catalog on October 31, 2026. I counted distinct live product IDs for each of the 16 categories through the public products endpoint, then read the robots meta tag from each served category page.

Source: radarmakers.com public products endpoint and served category HTML, checked October 31, 2026 at 04:55 UTC. Chart: RadarMakers.

Seven categories had three or more live products and served no robots override. Nine had fewer than three and served noindex, follow. Three of those nine had no live products at all. The two categories sitting exactly on the line, Apps and Other, both had three live products and both were index eligible. That is the boundary doing what the constant says.

The category layout builds its metadata and adds a robots field only when the page is below the threshold:

// frontend/src/app/categories/[slug]/layout.tsx, excerpt
    ...(empty ? { robots: { index: false, follow: true } } : {}),

At or above the threshold the layout emits no robots field, so the default applies. The tag page is explicit in both directions:

// frontend/src/app/tag/[slug]/page.tsx, excerpt
    robots: { index: products.length >= MIN_PRODUCTS, follow: true },

follow: true is deliberate. A thin page is still a normal page for people, and crawlers that support the directive are still allowed to follow its links to the product pages. The metadata asks search engines that support it not to index the page. It does not stop them from crawling it, and a crawler can only read the instruction if it is allowed to fetch the page, which is why these pages are not blocked in robots.txt.

When I checked the live site on 2026-10-28, the served HTML matched this. The Developer Tools category page had no robots meta tag, the Other, Web Games and Health category pages had <meta name="robots" content="noindex, follow"/>, and a tag page such as /tag/ai had index, follow. Those are the pages as served on that day. Counts change as products are added, and this check says nothing about what any search engine did with them.

Our sitemap policy excludes listings below the same threshold used by their metadata. A URL that we mark noindex and also offer in the sitemap would send two opposite signals, and the comment in sitemap.ts says the map must not offer such pages. The sitemap performs its own requests, so its inclusion decision is not derived from the metadata response.

For categories, the sitemap code keeps only entries that pass categoryIndexable. It also needs two more things before a URL goes in: the ranked list for the category must load, and the list must give a valid date to use as lastmod. That date comes from a small helper:

// frontend/src/lib/category-pages.ts, excerpt
    const t = Date.parse(p.content_updated_at || p.launched_at || p.created_at || "");

It takes the latest valid date among the products, preferring a content update date, then the launch date, then the creation date. A category whose list cannot be loaded drops out of the sitemap rather than appearing with a guessed date.

Tags need an eligible tag, at least three live matching products in the data the sitemap fetched itself, and a valid product date. Passing the count gate is necessary but not sufficient. On 2026-10-28 the live sitemap listed these five category URLs, and none of the three noindex category pages I fetched, Other, Web Games and Health, was among them:

$ curl -s https://radarmakers.com/sitemap.xml | grep -o "<loc>https://radarmakers.com/categories/[^<]*</loc>"
<loc>https://radarmakers.com/categories/ai-tools</loc>
<loc>https://radarmakers.com/categories/developer-tools</loc>
<loc>https://radarmakers.com/categories/productivity</loc>
<loc>https://radarmakers.com/categories/design</loc>
<loc>https://radarmakers.com/categories/fintech</loc>

Catalogs move, so a dated check goes stale quickly. On October 31, 2026 I repeated the check across all 16 category pages and the sitemap. The sitemap now listed seven category URLs instead of five. The two new ones were Apps and Other. Other had been one of the noindex pages on October 28. By October 31 it had reached three live products, it served no robots override, and the sitemap listed it. Nothing in the code changed for that to happen. The catalog crossed the threshold and both signals followed.

Source: radarmakers.com/sitemap.xml and served category HTML, checked October 31, 2026 at 04:55 UTC. Chart: RadarMakers.

The useful result is the empty cells. No category page served noindex while also appearing in the sitemap, and no index eligible category was missing from it. That agreement is what the shared threshold is supposed to produce. It is a snapshot of what the server sent at one time, and it still says nothing about what any search engine did with those pages.

This is the part worth spelling out, because a rule that depends on a count has to say what happens when the count is unavailable. The category layout makes two lookups at the same time, the category itself and the live products of that category, each with a short timeout:

// frontend/src/app/categories/[slug]/layout.tsx, excerpt
  const [category, empty] = await Promise.all([
    withinDeadline(getCategories())
      .then((c) => (c ?? []).find((x) => x.slug === slug) ?? null)
      .catch(() => null),
    withinDeadline(getProducts({ status: "live", category: slug, limit: MIN_INDEXED_PRODUCTS }))
      .then((p) => !categoryIndexable(liveProducts(p ?? []).length))
      .catch(() => false),
  ]);

Three outcomes follow from this code:

If the category is not found, or its lookup fails, the layout emits index: false, follow: true. We deliberately emit noindex when category data is unavailable.
If the category is found and the product lookup succeeds, the count decides. A lookup that resolves with null is treated as an empty list, so it counts as zero products and gets noindex.
If the category is found and the product lookup throws or times out, the catch handler returns false for empty. The layout then emits no robots field, and the page stays index eligible.

The third case is a policy, and the comment in the file states it: when the API fails, we do not guess. For a response whose category lookup succeeds but whose product lookup rejects or times out, the layout omits the robots override. This post does not establish how long any indexing effect of that would last. We chose to leave the page open in that case, instead of marking it noindex on the strength of a count we never got. Another policy would emit noindex whenever the count cannot be fetched, and a site with many thin pages and an unreliable API might prefer it. The point is to decide on purpose and write it down, not to inherit whatever an empty catch happens to do.

This failure path covers category metadata only. It does not describe successful rendering of the page, and I am not describing tag page failure behavior here.

Category slugs were renamed in migration 050: ai became ai-tools, devtools became developer-tools, and mobile became apps. Products point to categories by ID, so the rename did not touch them. The old addresses are kept by permanent redirects built from one table in the code, RENAMED_CATEGORY_SLUGS, for both /categories/<old> and /best/<old>. On the live site, /categories/devtools answers with a 301 to /categories/developer-tools.

"Index eligible" means the metadata allows indexing. It does not mean any page is indexed.
Three products is not a threshold that search engines publish. It is where we drew the line for these pages.
No traffic, ranking or indexing results are reported here. The checks above show what the server sends, not what happened afterwards.
The count gate is only part of the sitemap rule. The data checks decide inclusion too.

The threshold is meaningful only when the record definition is consistent. A list with two distinct live IDs should fail. A list with three should pass. Repeating one live ID must not make a two product category pass. Adding a pending or archived listing must not raise the live count. Put these cases in tests for both categories and tags because separate constants can drift even when they currently share a value.

Do not count a client side display if server metadata uses another query. The visitor could see three cards while metadata sees two records after duplicate removal. The reverse could happen if metadata counts something not rendered. Keep the filtering rule visible and compare the page, metadata, and sitemap against the same source where practical.

A successful empty lookup is different from a failed request. When a request times out, the code cannot honestly conclude that the category has zero products. Return distinct states for success with products, success with no products, and failure. The renderer can then show a useful empty state for the first case and a temporary error or retry path for the second. Metadata and sitemap policy should also be explicit for failure.

Avoid catching every exception and replacing it with an empty array. That hides operational failure and may change robots metadata by accident. If you cache the last successful result, document its age limit and invalidation behavior. A retry can help with a transient problem, but excessive retries can increase load during an outage. Do not claim a recovery guarantee unless the service provides one.

Robots metadata and sitemap generation are separate code paths. For the same category fixture, compare the live count, robots directive, canonical, response status, and sitemap decision. A deliberately noindex page should not also be included in the sitemap under this policy. An index eligible page can still be excluded if the data request fails or there is no valid last modified date.

A sitemap is a discovery hint, not a promise of indexing. Google says it helps search engines learn which URLs a site considers important, but it does not guarantee that a URL appears in results. A noindex route may still be discoverable through links. Align signals, but do not describe a sitemap inspection as an indexing result.

Test below, at, and above the boundary, plus duplicate IDs, no valid date, and request failure. Run the cases for categories and tags. Add a test that inspects generated metadata and a separate one for sitemap output. Parse generated output rather than relying only on a screenshot.

Keep redirects in the same review. When a category slug changes, assert the old path resolves to the intended new path. Check redirect status, final URL, canonical, and internal links. A redirect map preserves old paths only when its destination is correct. Test the destination instead of merely checking that a redirect happened.

A mechanical count cannot decide whether the page answers a real query. Three unrelated products can satisfy a code condition and still make a weak comparison. A carefully edited page about a smaller category may answer a narrow need. Treat the threshold as a guardrail and review the content separately.

Read each generated page as a visitor. Does the introduction describe the category without claiming unsupported features? Can someone compare products using facts that are actually present? Is there a useful next step? A heading followed by a handful of cards may be too little. Consider adding a genuine editorial explanation or keeping the route out of search until it helps the intended audience.

Do not create interchangeable paragraphs by inserting a category name into a template. That makes URLs look different while saying the same thing. Use catalog facts only when they are accurate and useful. A missing price field does not prove that a product is free or paid. Avoid turning a blank feature field into a negative statement.

As listings change, review routes whose state crosses the boundary. Record which categories changed and check metadata and sitemap output. A page becoming index eligible is a code state, not proof of traffic or ranking. Label the date of a live inspection and keep operational changes separate from visitor analytics.

[ ] Test two distinct live records, the threshold, and duplicate IDs.
[ ] Handle successful empty results separately from failed requests.
[ ] Inspect metadata and sitemap output with the same fixtures.
[ ] Review whether the page answers a distinct visitor need.
[ ] Test old slugs through to the final destination.

A renamed slug affects more than a route lookup. Search metadata, sitemap entries, breadcrumbs, internal links, and cached social cards can each retain the earlier path. Keep one redirect map and test the old and new address together. A permanent redirect should lead to the final canonical path rather than another redirect chain. Update internal navigation to point directly to the current address even when the redirect remains for old links.

Check that the destination still passes the index eligibility rule. A redirect to a category that is itself noindex may preserve access while not producing the intended search landing page. That is a policy choice worth recording. Do not keep a redirect merely because a prior slug existed if the destination no longer represents the same category.

When a category is merged, preserve the old route only if the new route is a genuine replacement. Otherwise, an honest not found response can be better than redirecting every retired category to a broad page. The destination should match the previous visitor intent. Review the heading and introduction after the redirect, not only the status code.

A deployment checklist can exercise the same URLs across HTML, sitemap, and redirects. Fetch the old route, follow redirects, inspect canonical metadata on the destination, then search the sitemap for the final path. This gives the team a repeatable record of how the policy behaved at release time. None of these checks alone proves that an external search engine has updated its index.

When evidence is incomplete, avoid turning a failed data request into a permanent content judgment. A temporary API failure should not make the application claim a category has no products. Store the failed state, preserve the last good result if the product policy allows it, and make the result age visible to the team. The public page should not quietly present stale data as current.

Review the threshold itself on a schedule, but change it only when a visitor need and the implementation evidence justify a change. A threshold set too low can expose pages with little distinct value. A threshold set too high can keep useful specialist pages out of search eligibility. The right value is a local tradeoff, not a universal SEO number.

Write down who can change the rule and which tests must pass. Include the sitemap, metadata, failure behavior, and page copy. That makes a policy adjustment reviewable and prevents a constant change from leaving contradictory comments or an outdated article behind.

Keep the category and tag thresholds aligned. In this code they are two constants with the same value.
Document what your metadata does when a lookup fails.
Keep old URLs alive with permanent redirects when you rename slugs.
Inspect the served HTML and the sitemap with curl after you deploy.

RadarMakers implementation snapshot checked October 28, 2026: frontend/src/lib/category-pages.ts, frontend/src/lib/best-ranking.ts, frontend/src/app/categories/[slug]/layout.tsx, frontend/src/app/tag/[slug]/page.tsx, and frontend/src/app/sitemap.ts.
Google Search Central, Block Search Indexing with noindex: https://developers.google.com/search/docs/crawling-indexing/block-indexing
RadarMakers live category and sitemap checks described in this article, recorded October 28, 2026 and repeated October 31, 2026.
RadarMakers public products endpoint, live product counts per category, checked October 31, 2026.

RadarMakers — Fri, 30 Oct 2026 22:52:56 +0000

A page can have one H1 and still be awkward to navigate. It can also have many lower level headings for a sensible reason. A useful heading audit records both the ranks and the words, then reads them in order.

I inspected the initial HTML of five live RadarMakers routes on October 30, 2026, around 11:49 UTC. The tools collection has a deeper structure than the other sampled pages. That difference is visible in the data, but interpreting it requires reading the sections.

Source: retained RadarMakers production responses captured October 30, 2026. Chart: RadarMakers.

The tools response has 27 heading elements in total. Seventeen are H3 or H4. Every sampled route has exactly one H1. These are literal response counts, including shared footer headings. They are not counts of unique topics or a complete accessibility assessment.

The W3C heading tutorial explains that headings organize content and that ranks should express the section hierarchy. A count alone does not establish whether a heading describes its section or whether a visitor can understand the resulting outline.

Save the HTML to page.html. This snippet prints the order and the counts from the same response.

from collections import Counter
from pathlib import Path
from bs4 import BeautifulSoup

soup = BeautifulSoup(Path("page.html").read_bytes(), "html.parser")
headings = soup.select("h1,h2,h3,h4,h5,h6")
for heading in headings:
    print(heading.name, heading.get_text(" ", strip=True))
print(dict(Counter(heading.name for heading in headings)))

The retained tools response begins with its H1, followed by H2 "Choose a tool". It then includes H3 group labels such as "Check a page" and "Plan a launch". Tool names under those groups use H4. Later, FAQ questions use H3 beneath the FAQ H2. Those relationships explain why the page has a deeper histogram.

A linter that simply recommends fewer H4 elements would miss the design decision. The relevant question is whether each level describes an actual child section and whether the group labels help people choose a task.

The sale page has three H2 elements. All three belong to shared footer groups: "Explore", "Help", and "Legal". Its sale content is currently an empty state without an H2. Saying that it has three detailed content sections would therefore be wrong.

This is why the capture keeps the heading text. The same count can describe a substantive article outline, a catalog grid, or shared site navigation. If the page has a main landmark, scope a second extraction to that landmark and compare the two views. If it does not, identify the intended content wrapper in source before assuming a broad selector represents the article.

Do not silently delete the footer from the dataset. Keep the whole response inventory, then label the scoped interpretation. Someone repeating the audit should know why their total differs from a content-only count.

Read the sequence without the paragraphs between it. Can you tell what the page offers and which sections belong together? Does a heading describe a task, a category, or only a vague benefit? If two neighboring headings could be swapped without changing the meaning, they may need clearer wording.

Next, inspect visual styling separately. A small heading can still be structurally important. A large line of marketing copy can still be a paragraph. Choose the element for its role, then style it. Making every card title an H2 just to obtain the same font size can flatten meaningful groups.

For a repeated card component, inspect its callers. A fixed heading level may work on a collection page and create a jump when reused inside a nested section. Pass the intended level or use separate variants when that makes the hierarchy explicit. Do not introduce a new abstraction until the actual reuse requires it.

Initial HTML may include streamed or conditionally displayed content. The sequence here describes the retained response, not a completed browser accessibility tree. After any proposed change, inspect the page with its normal styles and with a heading navigation tool or screen reader.

Check desktop and narrow layouts. Verify that hiding a decorative block does not leave a confusing heading in the accessible structure. Inspect the FAQ expanded and collapsed states. A heading inventory is a preparation step for those tasks, not a substitute for them.

If the outline already expresses the sections clearly, keep it. A review should be able to conclude that a deeper structure is justified. Changing markup merely to produce a smaller chart would optimize the report instead of the page.

This sample establishes five single H1 responses and a tools outline that reaches H4. It also shows that footer headings can dominate a small page's count. It does not establish search performance or certify accessibility.

The useful output is a sequence another person can inspect, a table they can reproduce, and a small set of questions tied to real sections. That is enough to turn a heading count into a practical review without pretending the count is the verdict.

Source: RadarMakers HTTPS captures, October 30, 2026. Evidence includes response hashes, every observed heading label, and extraction data. No source code or production content was changed.

The companion chart sums the heading counts for each retained route and labels the deepest rank observed. The tools response contains 27 heading elements and reaches H4. The launch checklist contains ten. The press, about, and sale responses contain eight, nine, and four. These totals include shared page regions because the capture counts the full response.

The chart makes route size visible, not outline quality. A larger count can result from useful subgroups, repeated cards, a long FAQ, or site chrome. The sale response is a useful warning: its three H2 elements belong to the shared footer groups, while its sale content is an empty state without an H2. The total cannot tell that story unless the labels and page are read too.

The deepest rank is also descriptive. The fact that a page reaches H4 does not establish that H4 is wrong. The fact that another route stops at H2 does not prove that its hierarchy is sound. The next step is to compare the ordered labels with the content and the component structure.

For each response, preserve the requested URL, final URL after redirects, status code, capture time, content type, and response hash. Store the parser version and extraction script with the data. Keep the complete heading sequence alongside the histogram so another reviewer can see whether a total came from page content or shared layout.

If the page changes between captures, do not overwrite the earlier evidence. Save a new capture and label the comparison date. A route can change headings because content changed, a template changed, a feature flag changed, or a response was served to a different state. The record should make those possibilities visible instead of collapsing them into one count.

Separate response capture from browser inspection. The initial HTML is a useful reproducible artifact, but it may not include content inserted after JavaScript runs. A rendered browser tree can differ because of hydration, disclosure controls, or conditional rendering. Name which artifact supports each statement.

A whole-document selector includes the header, main content, footer, and any hidden template fragments present in the response. That scope is useful when documenting all literal headings, but a reader asking about the article outline may need a second view limited to the main landmark or the known content container.

Do not silently replace one scope with another. Keep a whole-response inventory, then identify the content region separately. Record the selector and the reason it represents the page content. If the page has no main landmark, inspect the template and explain which element was used. A scoped table should be labeled as scoped so its totals do not look directly comparable to a whole-page table.

Hidden content requires attention. Some components keep collapsed panels in the document, while others insert them only after activation. A static response can count a heading that a visitor cannot currently see. A browser accessibility tree can expose a different set depending on state. Inspect the page in the state that matches the question, and record whether the disclosure was open or closed.

Two pages can have the same H1 and H2 totals while presenting very different structure. Preserve each heading rank and normalized text in document order. Then read the list without paragraph copy, as a visitor using heading navigation might encounter it. The list should convey the major topics and the relationships among nested sections.

Normalization must not erase meaning. Removing extra whitespace is usually useful. Removing all punctuation or collapsing labels with similar words can merge distinct headings. Keep the original text in the evidence and create a normalized field only for comparison. If a heading is empty or hidden, include that fact instead of dropping it silently.

A useful review asks whether each heading labels the content that follows, whether sibling sections use a consistent level, and whether a new section is actually nested under the preceding topic. Do not turn these questions into an automatic ban on skipped ranks without consulting the relevant guidance and the page context. A heading rank communicates structure, not visual size.

For repeated card grids, decide whether each card title is truly a section heading. A page with a list of many tools may need a group heading and links with descriptive names, not a heading element for every small card title. Another page may use headings for each item because users navigate among substantive sections. The component should reflect the content role rather than a font style.

A design system can make H2 and H3 look similar, or make an ordinary paragraph look large. That visual choice does not define the document outline. Choose the semantic element for the section relationship, then use CSS to create the desired appearance. This keeps visual hierarchy flexible without encoding it as an inaccurate heading rank.

If a design system has a component named Heading, inspect how it chooses the HTML element. A component that always emits H2 may work on a flat page and become misleading when nested inside another section. Where callers need different structure, pass an explicit semantic level or expose separate components whose purpose is clear. Avoid a level prop that allows impossible values without validation.

Review the component with its actual call sites. A single rendered page cannot reveal how the shared component behaves in other contexts. Search the repository for its use, capture representative routes, and check the result after the component change. Keep the evidence tied to the exact pages and states tested.

Inspect the outline after opening and closing accordions, menus, tabs, and other controls that change content visibility. Determine whether hidden content remains in the accessibility tree and whether that behavior matches the interaction. A count from initial HTML cannot answer every state question.

Check narrow and wide layouts when responsive components differ. A mobile navigation menu can contain duplicated labels or heading-like text that does not appear in the desktop structure. A hidden duplicate can remain in the response. Avoid assuming that visually hidden means absent from assistive technology, or that a display rule changes the semantic rank.

Use a keyboard and a heading navigation feature in a screen reader or browser tool to test the resulting experience. Note the start point, page state, and route. If a heading is missing from the navigation list, inspect whether it is a heading in the rendered DOM or only styled text. If an unexpected heading appears, inspect whether it is hidden, duplicated, or part of a shared region.

When the outline is confusing, identify the exact relationship that is unclear before changing markup. A vague section title may need clearer words. A card title may be a link rather than a heading. A nested topic may need a rank that reflects its parent section. A repeated footer label may be correct as a site region while irrelevant to the article outline.

State the proposed change and the expected evidence. For example, name the route, state which heading moves into the main region, and describe what the ordered list should show afterward. Avoid goals such as reduce headings by a third or eliminate all H4 elements. Those targets optimize counts without explaining how a person benefits.

After an edit, repeat the same capture and browser checks. Compare the ordered heading list, not just the aggregate numbers. Verify that the content text remains present, shared navigation still works, and the accessible name of interactive controls remains clear. A reduced count is not automatically an improvement.

If no change is warranted, write that conclusion. A deeper outline can be correct when it reflects genuine groups and nested content. Recording the reason helps prevent a later cleanup from flattening the structure merely to make a chart look simpler.

The retained evidence establishes the heading counts and labels for five public RadarMakers responses on October 30, 2026. It shows one H1 on each route, nine H2 and nine H3 and eight H4 elements on the tools route, and footer-only H2 elements on the sale page. The capture and extraction records let another reviewer reproduce those observations.

It does not establish an accessibility conformance result, search ranking effect, visitor success rate, or user preference. The counts do not say whether an individual label is understandable without reading it. The static response may not represent every rendered state. Those limits should remain close to the result when it is shared.

A bounded report is still useful. It gives a reviewer a place to start, a reproducible sequence to inspect, and a set of concrete questions for the page owner. The goal is not to produce a perfect score. It is to make the document structure easier to reason about and to verify any change against the actual experience.

Keep a small evidence bundle for each review: the retained response, a structured heading sequence, the extraction script, the rendered state notes, and the final decision. Give each capture a date and a content hash. When a route is checked again, create a new record rather than replacing the earlier response. This makes the change visible and prevents a reviewer from comparing numbers from different page versions without noticing.

A second person should be able to reproduce the inventory without needing the original browser session. Document the requested route and whether redirects occurred. Note whether scripts ran, whether any controls were opened, and which selector defined the main content view. If the extraction process changed, save the parser version and explain the difference. A reproducible method is more useful than a screenshot of a histogram because it shows how the evidence was made.

When a proposed heading change is reviewed, compare the ordered labels and ranks before and after. Then read the page and test the route using keyboard navigation. If the counts are unchanged but the labels are clearer, the content may still have improved. If the counts change but the sequence is less understandable, the numeric result may be a regression. Keep the decision tied to the structure people encounter, not the appearance of the chart.

The five captured routes were selected to demonstrate an audit. They do not represent every route type, every user state, or every page served to every visitor. A site-wide statement would require an inventory of route templates and a sampling method that covers those templates. It would also need a plan for dynamic content and authenticated views if those matter to the question.

When extending the sample, group routes by template or meaningful content type. Explain why each route was selected and preserve the same capture method. If a category page and a tool page use different heading components, they should not be assumed to have the same outline behavior. The reported result should say exactly which routes were inspected.

This caution is practical, not ceremonial. A small sample can identify a concrete page worth reviewing. It cannot support a claim about all visitors or all content. Keeping the scope visible lets another developer use the result without overgeneralizing it.

RadarMakers — Fri, 30 Oct 2026 22:52:16 +0000

A performance audit can start with a cheap question: which image loading instructions did the server actually send? That question is narrower than asking whether a page is fast. Keeping the two separate makes the first script useful without turning it into an invented benchmark.

I captured five public RadarMakers pages over HTTPS on October 30, 2026, at about 11:49 UTC. The sample includes the free maker tools collection, a press kit, an about page, a launch checklist, and a sale catalog. This is a convenience sample from one site, not a representative survey of the web.

Route	loading lazy	Attribute absent	Total img elements
/press	16	0	16
/about	1	0	1
/tools	3	0	3
/launch-checklist	6	1	7
/for-sale	2	2	4

Source: retained RadarMakers production responses captured October 30, 2026. Chart: RadarMakers.

Across this sample, 28 of 31 img elements have loading set to lazy. Three omit the attribute. None explicitly says eager. The three categories partition literal markup; they do not partition actual request start times.

The HTML image specification defines loading behavior. An omitted attribute has eager behavior by default, but this inventory deliberately keeps omitted and explicitly eager instructions separate. That distinction can reveal framework defaults or intentional source changes. Lazy loading also does not promise that an image will wait until a particular scroll position.

Save a response as page.html, then run this Python snippet with Beautiful Soup installed. It uses the bytes on disk rather than fetching a changing page during analysis.

from collections import Counter
from pathlib import Path
from bs4 import BeautifulSoup

soup = BeautifulSoup(Path("page.html").read_bytes(), "html.parser")
counts = Counter()
for img in soup.select("img"):
    value = img.get("loading", "").strip().lower()
    category = value if value in {"lazy", "eager"} else "unspecified"
    counts[category] += 1
print(dict(counts))
print("total", sum(counts.values()))

For the retained launch checklist response, the result is lazy 6, unspecified 1, and total 7. The absent eager key means zero observed elements, not a missing measurement. If you expect malformed loading values, record them in a separate invalid category. The captured sample has none.

A page with CSS backgrounds, canvas artwork, or images inserted after hydration needs additional inspection. This code counts img elements in one server response. It does not discover every visual resource the browser can display.

Look at the first screen in a real browser. Identify the image that supplies useful content immediately. Inspect whether its loading instruction fits that role. An image near the top of the source is not necessarily visible near the top of every viewport. Responsive styles and hidden theme variants can change the relationship.

On the sale page, two hero image elements omit loading and two empty state images are lazy. That markup is consistent with separate light and dark variants. It does not establish that all four are visible or that four independent downloads occur. Check computed styles, preload behavior, and the request waterfall before making that claim.

The press kit has sixteen lazy img elements. That is a starting point for checking the gallery, not a reason to mark every image as high priority. A gallery can contain many previews that a visitor never reaches. Prioritizing them all could create a different problem.

If the suspected issue concerns the largest visible image, record the viewport, cache state, network setting, and browser version before comparing a change. Keep a trace and identify the resource involved. Compare equivalent runs rather than treating the count of lazy attributes as a speed score.

If the suspected issue concerns missing content during scrolling, test that behavior directly. Scroll at an ordinary pace, use the keyboard, and check what happens under a slower connection. A markup count cannot tell you whether a placeholder reserves enough space or whether the image has useful alternative text.

For a component change, compare the generated HTML before and after. Confirm that the intended image changed and unrelated gallery elements did not. Then repeat the browser task. The response inventory and browser evidence answer different questions, and both belong in the review record.

The measured result is 31 img elements across five responses, with 28 explicit lazy hints and three absent loading attributes. There is no measured loading delay, speed improvement, accessibility verdict, or ranking outcome in those numbers.

That boundary is useful. It gives a developer a small repeatable inventory, a specific page to inspect, and a clear next observation. It also keeps a convenient script from producing a confident answer to a question it never measured.

The companion chart expresses the same five captures as a fraction of each route total. The press kit, about page, and tools collection show explicit lazy hints on every captured image element. The launch checklist has six lazy hints among seven images. The sale catalog has two among four. Those fractions are arithmetic from the table, not an additional browser observation.

This view can make an inspection queue easier to choose, but it still cannot tell you which images matter most. A route with every image marked lazy could have an important first-screen image. A route with a lower fraction could have decorative images that are correctly deferred. Treat the ratio as a prompt to inspect the actual page, not a target to maximize.

The denominator matters. The about page contains one image element in the captured HTML. Its ratio is therefore one of one, but a single image says little about a gallery page. Always display the fraction next to a percentage. That prevents the tiny sample from looking like a broad benchmark.

A reproducible inventory starts by saving the exact response bytes. Record the route, retrieval time, response status, content type, and a cryptographic hash. Keep the response in a research folder with the extraction code and the generated table. If the page changes later, a reviewer can tell whether a different count came from a new page or a parser change.

Do not let a script silently fetch production while it computes a report. A changing route can produce different markup between runs, and a network error can be mistaken for an empty page. Separate capture from analysis. Capture once, inspect the status, store the body, then make the parser consume that file. A failed or non-HTML response should produce an explicit error rather than a table of zeros.

When saving public page data, keep the retained material appropriate for the project and avoid recording secrets or private account information. These routes are public, but the same workflow may later be applied to authenticated pages. Make the scope of the capture clear before reusing the script.

A small parser can classify the literal attribute without pretending to know browser behavior:

from collections import Counter
from pathlib import Path
from bs4 import BeautifulSoup

soup = BeautifulSoup(Path('page.html').read_bytes(), 'html.parser')
counts = Counter()
for img in soup.select('img'):
    raw = img.get('loading')
    if raw is None:
        counts['absent'] += 1
    elif raw.strip().lower() in {'lazy', 'eager'}:
        counts[raw.strip().lower()] += 1
    else:
        counts['other'] += 1
print(dict(counts))

This version distinguishes an absent attribute from an invalid value. An empty loading attribute is not silently rewritten into a valid state by the report. If the page contains unusual whitespace or an invalid value, preserve that raw value in a separate detail file and decide how the specification treats it before interpretation.

For a larger audit, store one record per image with route, position in the document, raw loading value, source URL, alt text presence, and relevant responsive attributes. Avoid collecting more fields than the review needs. The purpose is to explain what the browser received and identify the image that deserves follow-up, not to build an image analytics warehouse.

Keep the parser deterministic. Use the same HTML parser version, selector, normalization, and category names for every route. If one response was processed differently, note the exception. A stable process makes the observed difference easier to discuss with the person who owns the component.

HTML order is not visual position. Grid layout, absolute positioning, responsive CSS, hidden variants, and hydration can alter which image appears first in the viewport. A list of img elements does not contain the complete rendering context. It also does not prove that every image source was requested.

Start with a browser inspection at the viewport where the issue was reported. Identify the visible image and its role. Check whether the image is decorative, content-bearing, a logo, or part of a gallery. Inspect the computed layout and confirm which responsive source is selected. If the page renders both light and dark assets in the HTML, compare the browser network panel and visibility state before counting downloads.

Review the network waterfall when the question concerns request timing. Record the page, viewport, cache state, network profile, browser build, and the request you are evaluating. A controlled comparison can show whether a change moved a request or altered the rendered result. Do not turn one run into a general performance promise.

If the question concerns a user who scrolls, test the scroll behavior. If the question concerns a slow connection, test the relevant connection profile. If the question concerns an image that shifts content, inspect its dimensions and layout reservation. Each question requires an observation that the markup count cannot supply.

An image near the top of a page may be the main content or a secondary decoration. The decision to defer it should follow the page purpose and the actual rendered experience. Do not set every element to eager because it appears in the first part of the source. Do not set every element to lazy because the gallery is long.

Before changing a component, list the intended behavior for each image class. A page logo, a product screenshot, an empty-state illustration, and a lower gallery preview may need different treatment. Confirm whether the image is already preloaded or referenced in another way. Duplicate instructions can make the HTML harder to understand without changing the request that the browser makes.

After the edit, capture the same route again and compare literal markup. Then repeat the browser observation that motivated the change. The first comparison checks that the implementation changed as intended. The second checks whether the visible behavior changed. Report both findings separately.

Do not claim that a lazy attribute caused a measured speed improvement unless the measurement actually isolates that change. A faster run can come from cache state, server timing, a different image, or another concurrent change. The inventory offers an implementation clue. A separate performance experiment must establish a performance result.

Loading behavior and alternative text solve different problems. An image can load at the right time and still lack a useful text alternative. An empty alternative can be appropriate for a decorative image, while a functional image may need a concise description of its purpose. Do not use the presence of alt text as evidence that loading behavior is correct, or the reverse.

Review the rendered content and the image role. Ask what information a person would lose if the image were unavailable. If the adjacent text already supplies the same content and the image is decorative, the alternative may be empty. If an image is a link or button, its accessible name should explain the action. Follow the HTML specification and accessibility guidance for the actual component rather than adding a generic description to every file.

The data in this article contains no audit of alt text quality. It contains only image loading attributes and image element totals from retained responses. That distinction protects the report from promising an accessibility result it did not collect.

A useful change record has four parts: the original response inventory, the reason for review, the implementation decision, and the post-change evidence. Link the affected component and the capture artifacts. State which images were expected to change. Include a browser check when the change is intended to alter rendered behavior.

If the counts do not change after a source edit, investigate whether the wrong page variant was edited or whether the production response is stale. If the counts change but the browser behavior does not, that can still be a valid result. The markup changed, while the observed request schedule did not. Preserve that finding instead of forcing the story into a performance win.

For repeated page templates, test a representative route and then verify the other affected routes. Do not assume that all callers pass the same image role. A shared component can produce different results based on route data, theme state, or responsive source. The regression list should match those variations that actually exist in the application.

The capture provides one dated view of five public routes. It shows 31 img elements, 28 explicit lazy hints, three absent loading attributes, and no explicit eager values. It also gives the route-level breakdown shown in both charts. The results can be reproduced from the retained HTML and parser, but they are not a sample of other websites.

The evidence does not measure load time, largest contentful paint, user satisfaction, accessibility conformance, search traffic, or ranking. It does not show every CSS image or every request after client-side rendering. Those are separate research questions. A good audit names what it knows and what it has not measured.

That restraint makes the inventory more actionable. A developer can inspect a specific route, locate a potentially important image, reproduce the markup count, and decide whether a browser trace is needed. A report that says only that there are many lazy attributes would not provide that path.

Source: retained RadarMakers production responses, October 30, 2026. Full capture hashes and extraction data accompany the draft. Cover and charts are original editorial graphics based on that inventory.

A short handoff should identify the route, image element, observed attribute, source capture, and next check. Avoid writing only that a page has many lazy images. The person receiving the note needs to know whether the suspected element is a hero, a gallery preview, a product screenshot, or a decorative state. Include a locator that can be found in the response or browser inspection, but keep the report free of private data.

State the question in a way that can be answered. If the concern is whether the first meaningful image is delayed, ask for a browser trace of that image under the relevant viewport and network conditions. If the concern is that a large gallery requests too many files, inspect which sources are actually requested and whether the browser defers them. If the concern is layout movement, examine the rendered box and reserved dimensions. A count of loading hints cannot resolve those questions by itself.

Keep the requested change narrow. If a developer changes one component prop, name which routes should reflect it and what the response inventory should show. If a route-level template is shared, identify another route that exercises a different image role. The regression sample should cover the component behavior that matters, not every URL on the site by default.

After the handoff, record what was tested and what was not. A change can pass the markup check and still require a browser observation. A trace can show no request difference even though the attribute changed. Those are useful findings when they are reported accurately. Do not convert an implementation change into an unmeasured speed claim.

An image collection can change shape when a product adds alternate themes, responsive variants, thumbnails, or a new empty state. The old inventory remains a valid record of its capture, but it should not be treated as a permanent description of the route. Refresh the capture when the template or content model changes in a way that affects img elements.

If you automate the review, schedule it around a meaningful code change or a review event that the team can maintain. A daily count without a response to differences can create noise. A check attached to a component change can show exactly which route changed. Store the output where a reviewer can compare it with the source diff and the browser result.

Do not make the automated check fail merely because the number changes. A new product image may be an intentional content update. Alert on a condition tied to a clear expectation, such as an unexpected missing image source or a disallowed attribute value, and have a person review the page context. Inventory should make deliberate changes visible, not prevent all change.

The source captures here are intentionally small. Five pages are enough to explain a reproducible method, but they do not define a site-wide policy for every image. Before generalizing, list the remaining route templates and choose a sample that covers their actual image roles. Report that scope openly and keep the route observations separate from conclusions about performance.

RadarMakers — Fri, 30 Oct 2026 14:32:27 +0000

Sign-in pages are the classic thing to hide from search. The reflex is to put them in robots.txt and move on. On RadarMakers we did exactly that, and then changed our minds about one path. This post shows the two small edits, the reasoning behind them, and, just as important, what the change does not prove.

robots.txt and noindex answer different questions. robots.txt says whether a crawler may fetch a URL. noindex says whether a page that was fetched may appear in search results. The second one can only be read from a response, so a crawler that is not allowed to fetch the URL never sees it.

Google's documentation on blocking indexing with noindex says this directly: for a noindex rule to be effective, the page must not be blocked by robots.txt. If it is blocked, the crawler never sees the rule, and the URL can still show up in search, for example when other pages link to it.

That makes a Disallow line a poor tool for removing a URL that search engines already know about. It stops the visit that would have delivered the instruction to leave.

Our frontend has a sign-in flow, and the OAuth callback lives at /auth/callback. It is a client component that reads the query string and either sends the person on or shows an error. A URL such as /auth/callback?error=... is the kind of address that appears when a sign-in does not complete.

Before the change, src/app/robots.ts included /auth/ in its disallow list:

// frontend/src/app/robots.ts, excerpt, before commit 46f72d7
      disallow: ["/admin", "/dashboard", "/auth/", "/api/", "/reset-password", "/forgot-password"],

The commit message and code comment name /auth/callback?error= style URLs as the reason for the change. This post does not include crawl data about them, and it makes no claim about whether or when any of them left an index.

One commit, 46f72d7, made two edits that only make sense together.

First, "/auth/" came out of the disallow list. Nothing else in the list moved:

// frontend/src/app/robots.ts, excerpt, current
      disallow: ["/admin", "/dashboard", "/api/", "/reset-password", "/forgot-password"],

Second, next.config.ts got a headers() function that adds X-Robots-Tag: noindex to responses handled by Next.js for paths matching /auth/:path*, which includes /auth and /auth/callback:

// frontend/next.config.ts, excerpt
  async headers() {
    return [{ source: "/auth/:path*", headers: [{ key: "X-Robots-Tag", value: "noindex" }] }];
  },

The diagram shows the intended behavior for a crawler that follows the rules. In the first panel the crawl is blocked, so the response is never fetched. In the second the crawl is allowed, the response carries the header, and the directive can be read. Removing the block and adding the header happen in the same commit, so the first panel is not claiming that a noindex header already existed behind the block.

A robots meta tag in the page <head> would also work for an HTML page. We chose a response header for these reasons, and they are design choices rather than requirements:

One entry in next.config.ts covers everything under the path. In the Next.js route syntax :path* matches zero or more path segments, so /auth/callback is covered, and so is any page we add under /auth/ later, without touching that page.
The rule lives next to the other routing configuration, not scattered across page files.
The callback is a client component, and we preferred not to build a separate server layout only to carry a robots tag.

Google documents X-Robots-Tag as the way to send the same directive in an HTTP response, and it applies to responses that have no HTML head at all.

The other disallow entries are still in robots.txt: /admin, /dashboard, /api/, /reset-password and /forgot-password. This commit leaves them unchanged. The comment above that list mentions authentication and crawl budget, but it does not establish that every listed route requires a signed-in session, and this post does not evaluate those rules.

For /auth/ the commit did one specific thing: because the goal was for the directive to be readable, the crawl block went away for that path.

Allowing the crawl means a crawler can fetch /auth/ URLs again. The comment in the file gave crawl budget, meaning the resources a search engine spends crawling a site, as a reason to block paths like these. We decided that, for this one path, letting the directive be read is worth more than the goal of reducing crawler requests. That is a judgment call for a small site, not a rule. If your auth area is large, or your crawl budget is a real constraint, weigh it differently.

It is worth looking at the actual responses instead of trusting the config file. When I checked on 2026-10-28, robots.txt on the live site no longer listed /auth/:

$ curl -s https://radarmakers.com/robots.txt
User-Agent: *
Allow: /
Disallow: /admin
Disallow: /dashboard
Disallow: /api/
Disallow: /reset-password
Disallow: /forgot-password

Sitemap: https://radarmakers.com/sitemap.xml

And a callback URL with an error parameter answered with the header:

$ curl -sI "https://radarmakers.com/auth/callback?error=access_denied" | grep -i x-robots-tag
x-robots-tag: noindex

That is all this check shows: the server is configured the way the commit intended. It says nothing about what any search engine has done with those URLs.

It is not a measured result. This post describes a configuration and the reasoning for it. It does not report indexing changes, timing or traffic.
Search engines decide for themselves when to fetch a page again and what to do with it. A crawler that never returns will never see the header.
noindex is a request to compliant crawlers. It is not access control. Keep the real protection on the server, which is what the authentication is for.
I describe the behavior Google documents. Other search engines publish their own rules.

A Disallow stops the crawl, and a crawl is the only way a crawler can read noindex. Do not use both on the same URL when you want the page out of an index.
Use Disallow to restrict crawling. If the goal is exclusion from search through noindex, let crawlers that support it fetch the directive, whether the URL is new or already known.
An X-Robots-Tag header in next.config.ts covers a whole path with one entry, including pages you add later.
Check the real response with curl -I after you deploy.
Say what you changed and why. Leave out results you have not measured.

RadarMakers — Fri, 30 Oct 2026 07:39:13 +0000

When a maker's product goes live on RadarMakers, we want search engines to know about the new page without waiting for a crawler to find it. IndexNow is a small protocol for exactly that: you send the URLs that changed, and the participating search engines are told about them. This post shows our Go client, the key file it needs, and what the protocol actually promises.

The IndexNow documentation describes two things.

A key you can prove you own. The key is 8 to 128 characters of letters, numbers and dashes. You host it in a UTF-8 text file, by default named after the key and placed at the root of the site, for example https://example.com/your-key.txt, and the file contains the key. The documentation strongly recommends the root location. A file elsewhere on the host has to be named in each request with keyLocation, and then only covers URLs under its own folder.

A request listing the changed URLs. A single URL can go in a GET query string, but several URLs go in one JSON POST with the host, the key, an optional keyLocation and a urlList of up to 10,000 URLs.

The FAQ lists a global endpoint, https://api.indexnow.org/indexnow, next to the endpoints of individual search engines, and says you may submit to only one of them, because a submission is shared with all IndexNow enabled search engines.

// internal/indexnow/client.go, excerpt
var validKey = regexp.MustCompile(`^[a-zA-Z0-9-]{8,128}$`)

// ... Client declaration omitted

func New(siteURL, key string) *Client {
    if key == "" {
        return nil
    }
    u, err := url.Parse(siteURL)
    if err != nil || u.Host == "" || u.User != nil || (u.Scheme != "https" && u.Scheme != "http") || !validKey.MatchString(key) {
        log.Print("indexnow: invalid public site URL or key format; disabled")
        return nil
    }
    return &Client{origin: u.Scheme + "://" + u.Host, host: u.Host, key: key,
        endpoint: "https://api.indexnow.org/indexnow", http: &http.Client{Timeout: 5 * time.Second}}
}

Without a key, or with a key or site URL that does not look right, New returns nil. Both methods handle a nil receiver, so the rest of the code calls the client the same way whether IndexNow is configured or not. A development machine without a key simply sends nothing.

Submit builds the payload. It only accepts local absolute paths and turns them into full URLs on our own origin, so nothing else can end up in the list:

// internal/indexnow/client.go, excerpt
urls := make([]string, 0, len(paths))
for _, path := range paths {
    if !strings.HasPrefix(path, "/") || strings.HasPrefix(path, "//") || strings.Contains(path, "\\") {
        return fmt.Errorf("expected a local absolute path")
    }
    urls = append(urls, c.origin+path)
}
payload := struct {
    Host        string   `json:"host"`
    Key         string   `json:"key"`
    KeyLocation string   `json:"keyLocation"`
    URLList     []string `json:"urlList"`
}{c.host, c.key, c.origin + "/" + c.key + ".txt", urls}

The request goes out as POST with Content-Type: application/json; charset=utf-8, the header the documentation shows. A response of 200 or 202 counts as success; anything else is an error.

The repositories call Notify, not Submit:

// internal/indexnow/client.go, comment omitted
func (c *Client) Notify(paths ...string) {
    if c == nil {
        return
    }
    paths = append([]string(nil), paths...)
    go func() {
        ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
        defer cancel()
        if err := c.Submit(ctx, paths); err != nil {
            log.Printf("indexnow: %v", err)
        }
    }()
}

Three choices are packed into those lines:

It runs in its own goroutine, so publishing a product never waits for a search engine.
It uses a fresh context with a 5-second timeout, not the request's context, so the ping does not depend on the publishing request being cancelled or finished.
It logs failures and does not retry. The sitemap is another way for search engines to find the page, and a later qualifying event, such as a product being set live again, sends another submission. We chose not to add a retry queue for this.

The paths slice is copied before the goroutine starts, so a caller that reuses its slice cannot change what gets sent.

The product repository calls Notify only after the database write succeeded and only when the product is live:

// internal/repository/product.go, excerpt
err := r.db.QueryRowContext(ctx, query+" RETURNING slug", status, id).Scan(&slug)
if err == nil && status == model.StatusLive {
    r.indexNow.Notify("/product/" + url.PathEscape(slug))
}

The same pattern covers a product created as live and a product whose status is set back to live. Community posts do it when a post ends up published after it is created, updated or approved. Each event sends its own single URL; the client can take several paths in one call, but we do not collect separate events into a batch.

The site itself is a Next.js app, and the key is only known at runtime, from an environment variable. The file is answered by src/proxy.ts, whose matcher only covers top-level .txt paths:

// src/proxy.ts, imports omitted
export function proxy(request: NextRequest) {
  const pathname = request.nextUrl.pathname;
  if (!isIndexNowKeyPath(pathname, process.env.INDEXNOW_KEY)) return NextResponse.next();
  return indexNowKeyResponse(pathname, process.env.INDEXNOW_KEY);
}

export const config = { matcher: ["/:file([^/]+\\.txt)"] };

// src/lib/indexnow-key.ts, comment omitted
export function isIndexNowKeyPath(pathname: string, key: string | undefined): boolean {
  return !!key && /^[a-zA-Z0-9-]{8,128}$/.test(key) && pathname === `/${key}.txt`;
}

export function indexNowKeyResponse(pathname: string, key: string | undefined): Response {
  if (!isIndexNowKeyPath(pathname, key)) return new Response(null, { status: 404 });
  return new Response(key, {
    headers: { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" },
  });
}

Only the exact path for the configured key answers, with the key as plain text. Any other .txt path passes through to the rest of the app. We checked the live site: the key path answers 200 with text/plain; charset=utf-8, no-store and a body equal to the key, and a made-up key path answers 404.

The client tests point the endpoint at a local httptest server. One test calls Notify with two paths and checks the exact JSON that arrives, including the keyLocation and both full URLs. Another makes the server answer 429 and checks that Submit returns an error, checks that a cancelled context fails, and checks that https://elsewhere.test, //elsewhere.test and /\elsewhere.test are refused as paths. A third checks that a client created without a key, or with a key that is too short or contains a slash, is nil, and that calling Notify and Submit on it is safe.

The IndexNow FAQ is direct about this. A 200 only means the search engine received the URLs; the first request may get a 202 while the key is verified. Submitting a URL does not guarantee that it is indexed. Each search engine decides for itself, and every submitted URL counts toward the site's crawl quota. The FAQ also says IndexNow is meant for recently added, updated or deleted URLs, recommends using it together with a sitemap, and advises against resubmitting unchanged URLs.

Validate the key and the site URL once, and return a nil client when IndexNow is not configured, so callers never need a feature flag.
Notify after the database write succeeds, from a goroutine with its own short timeout.
Accept only local paths and build full URLs on your own origin.
Serve the key file at the root with the key as plain text, and nothing else on that route.
Keep your sitemap. IndexNow is a hint about what changed, not a replacement.

RadarMakers — Thu, 29 Oct 2026 13:00:20 +0000

Two features on our site fetch addresses that strangers type in. When a maker submits a product, the server fetches the product's website to find a logo. And the meta tag and social card checker fetches any public page you give it and shows what a link preview would contain.

A server that fetches arbitrary URLs is a classic server side request forgery risk. The server can reach things nobody else can: the API on localhost, a database container on the internal network, or a cloud metadata service on 169.254.169.254. If a user can point the fetcher there, the server becomes their proxy.

This post shows the Go client we use for this, and why the check sits inside the dialer instead of before the request.

The first idea is to look up the hostname, check that every address it resolves to is public, and then make the request:

ips, err := net.LookupIP(host)
// ... reject if any ip is not public
resp, err := http.Get(rawURL)

The problem is that on a new direct connection, the client resolves the hostname again, independently of the check. If it receives a different answer, it can connect to an address the check never approved. A hostname with a very short TTL can answer the check with a public address and the connection's lookup with 127.0.0.1. This is known as DNS rebinding, and a check before the request cannot see it, because by the time the client connects, the answer that was checked is no longer the one being used.

Redirects make it worse. A perfectly public page can answer with a redirect to http://127.0.0.1/, and a default client follows it without asking anyone.

Go's net.Dialer has a Control field. Its documentation says that if Control is not nil, it is called after creating the network connection but before actually dialing. By then the hostname has been resolved, and the address argument holds the IP and port of this particular connection attempt. That is exactly the value we want to check.

// internal/audit/ssrf.go, comments omitted
func NewPublicOnlyClient(timeout time.Duration, maxRedirects int) *http.Client {
    dialer := &net.Dialer{
        Timeout: timeout,
        Control: func(network, address string, _ syscall.RawConn) error {
            host, _, err := net.SplitHostPort(address)
            if err != nil {
                return fmt.Errorf("bad address")
            }
            ip := net.ParseIP(host)
            if ip == nil || !isPublic(ip) {
                return fmt.Errorf("address is not public")
            }
            return nil
        },
    }
    return &http.Client{
        Timeout:   timeout,
        Transport: &http.Transport{DialContext: dialer.DialContext, Proxy: nil, DisableKeepAlives: true},
        CheckRedirect: func(req *http.Request, via []*http.Request) error {
            if len(via) > maxRedirects {
                return fmt.Errorf("too many redirects")
            }
            if req.URL.Scheme != "http" && req.URL.Scheme != "https" {
                return fmt.Errorf("redirect to a non-web address")
            }
            return nil
        },
    }
}

A few details carry the weight here:

Anything that is not an IP is refused. If address does not parse as an IP, net.ParseIP returns nil and the dial fails. The check never has to trust a name.
Every connection attempt is checked. If a hostname has several addresses and the dialer tries more than one, each attempt calls Control. A redirect opens a new connection, so it goes through Control as well, whatever DNS says about the new host.
Proxy: nil. The http.Transport documentation says that if Proxy is nil, no proxy is used. Go's default transport reads proxy settings from the environment. With a proxy configured, the dialer would connect to the proxy, and Control would only ever see the proxy's address, not the target's.
DisableKeepAlives: true. Connections are not reused between requests, so each request opens its own connection and passes through Control.

// internal/audit/ssrf.go, comments omitted
func isPublic(ip net.IP) bool {
    if ip.IsLoopback() || ip.IsPrivate() || ip.IsUnspecified() ||
        ip.IsLinkLocalUnicast() || ip.IsLinkLocalMulticast() ||
        ip.IsInterfaceLocalMulticast() || ip.IsMulticast() {
        return false
    }
    if v4 := ip.To4(); v4 != nil {
        if v4[0] == 100 && v4[1] >= 64 && v4[1] <= 127 {
            return false
        }
        if v4[0] == 0 {
            return false
        }
    }
    return true
}

The net.IP helpers cover loopback, the private ranges 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 and fc00::/7, link-local addresses, which include the metadata address 169.254.169.254, and multicast. The two extra checks block carrier-grade NAT, 100.64.0.0/10, and 0.0.0.0/8, which have no helper.

Be honest with yourself about what this is: a deny list of the ranges that matter for our server. The Go documentation for IsPrivate itself says it "does not describe a security property of addresses, and should not be used for access control". There are special purpose ranges this function does not list. If your network has other internal ranges, or translates addresses between IPv6 and IPv4, add them or, better, also block outgoing connections to internal networks at the firewall, so the code is not the only line of defense.

The logo fetcher lets the client follow redirects, up to its limit. The meta tag checker wants to show every redirect step to the user, so it turns automatic redirects off and follows them by hand:

// internal/inspect/inspect.go, excerpt, comments omitted
c := *client
c.CheckRedirect = func(*http.Request, []*http.Request) error { return http.ErrUseLastResponse }
c.Jar = nil

Each hop is a new request through the same guarded client, so each new connection passes Control. Before following a hop, the checker also requires an http or https scheme, a hostname, no username or password in the URL, and either no explicit port or port 80 or 443, and it stops after 5 redirects.

One more thing worth copying from it: errors shown to the user are turned into short fixed sentences. Blocked addresses, timeouts, redirect limits and unsupported redirect targets get their own fixed messages, and other connection failures become "could not connect to the address". The raw error text, which can contain internal addresses, never reaches the page.

The address list is tested with literal addresses, including the ones that motivate it:

// internal/audit/ssrf_test.go, abridged: fewer entries, reasons shortened
blocked := map[string]string{
    "127.0.0.1":       "loopback",
    "10.0.0.5":        "private network",
    "172.17.0.2":      "the Docker network the database sits on",
    "169.254.169.254": "cloud metadata service",
    "100.64.0.1":      "carrier-grade NAT",
    "fe80::1":         "link-local",
    // ...
}

The client itself is tested by pointing it at a local httptest server. That server listens on loopback, so the request must fail at the dialer:

// internal/audit/ssrf_test.go
func TestPublicOnlyClient_RefusesLoopbackAtDial(t *testing.T) {
    srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("secret"))
    }))
    defer srv.Close()

    client := NewPublicOnlyClient(2*time.Second, 3)
    resp, err := client.Get(srv.URL)
    if err == nil {
        resp.Body.Close()
        t.Fatal("a loopback server was reachable through the public-only client")
    }
}

The same fact makes the redirect limit awkward to test: a local test server can never be reached through the guarded client. So that test builds the client and then swaps in http.DefaultTransport, which keeps the redirect policy under test while removing the dial check.

What the tests do not do is simulate a real rebinding DNS server. The argument for the design is the one above: the check runs on the address being dialed, so there is no second lookup to race against.

Do not check a hostname and then fetch it. Check the IP inside the dialer, in net.Dialer.Control, where the address is the one the connection will use.
Refuse anything in Control that is not a parseable IP.
Turn off environment proxies for this client, or the check only sees the proxy.
Treat the address list as a deny list for your own network, and add an egress firewall rule if you can.
Follow redirects through the same guarded client and validate scheme, port and credentials on every hop.
Never show raw connection errors to the user.

RadarMakers — Thu, 29 Oct 2026 07:30:44 +0000

We wanted three numbers for RadarMakers: how many pages were viewed, roughly how many people viewed them each day, and where they came from. We did not want a cookie banner, a third-party script, or a table full of IP addresses. This post explains the implementation, a Go backend with Postgres and a Next.js frontend, and its limits.

We do not store a separate event row for every page view. Every page view increments counters in a set of aggregate tables, each keyed by the UTC day: views and visitors per day, views per hour, per page, per referrer host, per country, per device class, per campaign, and per pair of internal pages for "came from this page to that page". A page view becomes "+1" in several of those tables, and there is no row that ties them together.

The one table that is not a pure counter is analytics_seen:

CREATE TABLE IF NOT EXISTS analytics_seen (
    day     DATE NOT NULL,
    visitor TEXT NOT NULL,
    PRIMARY KEY (day, visitor)
);

It exists only to tell whether a visitor was already counted today. The visitor column holds a daily hash, never an IP address.

A small client component in the Next.js layout attempts one beacon each time the path changes to a page we count, skipping a repeat of the same path:

// components/PageTracker.tsx, excerpt
const first = countedPath === null;
const ref = first ? document.referrer : window.location.origin + countedPath;
// ... campaign comments omitted
const params = new URLSearchParams(window.location.search);
const src = first ? params.get("ref") || params.get("utm_source") || undefined : undefined;
countedPath = pathname;
const body = JSON.stringify({ path: pathname, ref, src });
navigator.sendBeacon("/api/v1/track", new Blob([body], { type: "application/json" }));

It writes no cookie and nothing to local storage. The only state is two module variables that live as long as the loaded page. In a single page app document.referrer stays the same after client side navigation, so the real referrer is sent only for the first counted page; after that the component sends the previous counted page of our own site. The server records that as an internal move when the previous page is a valid, counted path different from the current one.

Before sending anything, the component checks a few things:

// lib/track-optout.ts, called from components/PageTracker.tsx
export function skipTracking(nav: TrackNavigator): boolean {
  return nav.doNotTrack === "1" ||
    nav.globalPrivacyControl === true ||
    nav.webdriver === true;
}

If Do Not Track is "1", Global Privacy Control is true or navigator.webdriver is true, nothing is sent. Browsers driven by automation, such as Playwright or Selenium, set navigator.webdriver; we added that check after our own page tests started to inflate the counts. MDN marks navigator.doNotTrack as deprecated and non-standard, part of a discontinued specification, and points to Global Privacy Control as one of the alternatives browsers are exploring. We choose to skip counting when either privacy signal is present. The component also waits until it knows whether the user is logged in and sends nothing for administrators; that exclusion lives in this client component, not in the public endpoint. Both the component and the server skip the admin panel, account pages and the API.

The Go handler answers 204 No Content, also when it drops a request, so the response does not reveal the filter rules; the route's rate limiter in front of it can still answer 429. The handler reads up to 2048 bytes of the body for parsing, then reads and discards up to another 1 MiB before answering. It drops empty and bot-like User-Agents, such as anything containing bot, crawl, headless or curl, and paths it does not count. It cuts the query string and fragment off the path, so /products/x?secret=1 is counted as /products/x.

Referrers are reduced to a host. A visit from a search results page is stored as google.com, not as the full URL with the search terms. A referrer from our own site is not a source at all; it becomes the "from" side of an internal move.

Then come the two personal inputs, the IP address and the User-Agent. They are used in memory for three things and then dropped:

the country, looked up in a local database file, or ?? when unknown;
the device class, desktop, mobile or tablet, from a few substrings of the User-Agent;
the daily visitor hash.

// internal/handler/analytics.go
func visitorHash(secret string, at time.Time, ip, ua string) string {
    sum := sha256.Sum256([]byte(secret + "|" + at.UTC().Format("2006-01-02") + "|" + ip + "|" + ua))
    return hex.EncodeToString(sum[:])[:32]
}

The hash covers an application secret, the UTC date, the IP address and the User-Agent, and only the first 32 hex characters are kept. Requests with the same IP address and the exact same User-Agent string get the same hash within a UTC day, as long as the secret does not change, and a different hash on the next day, because the date is part of the input.

The repository records a page view in one transaction. The first statement decides whether this is a new visitor for the day:

// internal/repository/analytics.go, excerpt
res, err := tx.ExecContext(ctx,
    `INSERT INTO analytics_seen(day, visitor) VALUES($1::date, $2) ON CONFLICT DO NOTHING`, day, e.Visitor)
if err != nil {
    return err
}
n, err := res.RowsAffected()
if err != nil {
    return err
}
newVisitor := int(n)

If the row is new, RowsAffected is 1; if the hash was already there, the conflict is ignored and it is 0. That number is then added to the daily visitors counter and the per-country visitors counter, while views always get 1:

INSERT INTO analytics_daily(day, views, visitors) VALUES($1::date, 1, $2)
ON CONFLICT (day) DO UPDATE SET views = analytics_daily.views + 1, visitors = analytics_daily.visitors + $2

The other counters follow the same INSERT ... ON CONFLICT DO UPDATE pattern. Since paths and referrer hosts come from strangers, the tables for pages, referrers, internal moves and traffic sources have a daily threshold of distinct values, for example 5000 paths. Once a threshold is reached, new values go into a single "other" row instead. The check and the insert are separate queries, so concurrent requests can overshoot a threshold a little; it is a guard against flooding, not an exact limit.

A goroutine started with the server runs the cleanup at startup and then once an hour. Each run deletes every analytics_seen row from an earlier UTC date and aggregate rows older than 400 days. This follows UTC dates, not an exact 24 hour lifetime: a hash written at 23:59 UTC stays until the first successful run after midnight, which is usually within the hour.

It is an estimate. Two people whose requests come from the same IP address with the exact same User-Agent string count as one visitor. One person whose IP address changes during the day, for example when switching from Wi-Fi to mobile data, usually counts as two. A visitor who opts out or blocks the beacon is not counted at all.
The hash is not anonymous to us. Anyone with the application secret and a guess of someone's IP address and User-Agent could recompute that day's hash and see whether it is in the table. That is part of why the hashes are deleted by the first cleanup after the UTC day ends. The aggregate tables hold no hashes.
The claim is about the analytics tables. The IP address and User-Agent are not written to any of them. Your reverse proxy, web server or hosting provider may still keep access logs with IP addresses; check those separately if you make a promise to your users.
The counters use no stable visitor key across days. They do not report returning visitors or individual browsing histories, only single internal moves from one page to another.

The handler test runs against a real disposable Postgres database. It sends rejected requests and checks that nothing was counted, sends realistic ones, moves an injected clock to the next day, and finally reads every row of the analytics tables it lists as text and fails if any of them contains the test IP address or the strings Firefox or Mozilla from the test User-Agent:

// internal/handler/analytics_test.go, excerpt
for r.Next() {
    var line string
    r.Scan(&line)
    rows++
    if strings.Contains(line, testIP) || strings.Contains(line, "Firefox") || strings.Contains(line, "Mozilla") {
        t.Errorf("%s stores personal data: %s", tbl, line)
    }
}

It also fails if there were no rows to inspect, because a check that looks at an empty database proves nothing. A separate unit test checks that the hash is stable within a day and changes with the date, the IP address, the User-Agent and the secret.

Store counts, not visits. A row per page view is a log, whatever you call it.
If you need daily uniques, a hash of a secret, the date, the IP and the User-Agent, deleted after the day ends, plus an INSERT ... ON CONFLICT DO NOTHING, gives you an estimate without a cookie.
Reduce referrers to hosts and strip query strings from paths before they reach the database.
Put a threshold on distinct values in tables that strangers can fill with made-up paths and hosts.
Write the test that greps your tables for the test IP address and User-Agent. It can catch accidental storage of those values in the tables it scans.

RadarMakers — Wed, 28 Oct 2026 14:00:08 +0000

A link to a product page should show that product in the preview card, not the same site banner as every other link. On our launch platform, live product pages use a 1200 x 630 PNG generated on the server with ImageResponse from next/og. Tag pages use the same generator except for eight tags: ai, ai-agents, audio, design, finance, music, open-source and productivity. Those tags use static Open Graph images at /og/tag/<slug>.png and separate Twitter images at /og/x/tag/<slug>.png. This is the image for one of the products listed on RadarMakers:

Nothing in that image was drawn by hand for this product. The layout is shared, the name, tagline and logo come from the database, and the text sizes were picked by measuring the text before rendering. Here is how the pieces fit together, using our real code on Next.js 16.

Next.js offers two ways to serve a generated image. The opengraph-image.tsx file convention adds the image to a route segment and writes the og:image tags for you. Or you can return an ImageResponse from an ordinary route handler and point your metadata at it yourself.

We use route handlers: /product-og/[slug] and /tag-og/[slug]. The product page's generateMetadata builds the image URL with a version taken from the data that appears in the image:

// app/product/[slug]/layout.tsx, excerpt
const ogImages = [{ url: `/product-og/${encodeURIComponent(slug)}?v=${ogVersion(p)}`, width: 1200, height: 630, alt: `${p.name} on RadarMakers` }];

and passes ogImages to both openGraph.images and twitter.images. Doing it this way gives us three things we rely on below: a URL version derived from the product name, tagline and logo URL, our own cache headers, and a fallback image when something fails.

Product and tag images share one file, lib/og-shared.tsx. It holds the size, the colors, the fonts and the background:

// lib/og-shared.tsx, excerpt, comments omitted
export const OG_WIDTH = 1200;
export const OG_HEIGHT = 630;

// ... colors and the Fonts type omitted

let fontsPromise: Promise<Fonts> | null = null;

export function loadFonts(): Promise<Fonts> {
  fontsPromise ??= (async () => {
    const dir = path.join(process.cwd(), "src/assets/og");
    const [regular, bold] = await Promise.all([readFile(path.join(dir, "DejaVuSans.ttf")), readFile(path.join(dir, "DejaVuSans-Bold.ttf"))]);
    return { regular, bold, regularMetrics: readFontMetrics(regular), boldMetrics: readFontMetrics(bold) };
  })().catch((err) => {
    fontsPromise = null;
    throw err;
  });
  return fontsPromise;
}

The fonts are read once per process and kept as a promise. If reading fails, the promise is cleared, so the next request tries again instead of failing forever. The same function also reads the font metrics we need for measuring text, which comes up in a moment.

Backdrop() returns one SVG with everything that never changes: the curved panel, the radar rings, the frame for the logo, our mark and the footer line. Each image is then a 1200 x 630 div with the backdrop and a few absolutely positioned text blocks on top.

The Next.js docs list the limits to design for: only flexbox and a subset of CSS, no display: grid, and only ttf, otf and woff fonts. Our layout stays inside those limits: the root is a flex container, and every text block is an absolutely positioned div with display: flex and whiteSpace: "nowrap".

The product image takes three fields:

// lib/og-product.tsx, excerpt
export async function renderProductOg(product: Pick<Product, "name" | "tagline" | "logo_url">): Promise<Uint8Array> {
  const fonts = await loadFonts();
  const logo = await fetchLogo(product.logo_url);
  const name = fitName(fonts.boldMetrics, product.name);
  const tagline = wrapTagline(fonts.regularMetrics, product.tagline);

The tag image takes only the tag name and draws a fixed tag illustration where the logo would be. Both end the same way: new ImageResponse(element, { width: OG_WIDTH, height: OG_HEIGHT, fonts: satoriFonts(fonts) }), read into a Uint8Array so the bytes can be cached.

The logo needed the most care, because it is user content. fetchLogo only accepts a path of the form /uploads/<file name>, fetches it from our own API origin with a 4 second timeout, rejects an empty body or one larger than 2 MiB after downloading it, and checks the first bytes of the file for PNG, JPEG, GIF or SVG instead of trusting the extension. Anything else returns null, and the image shows a tile with the first letter of the product name. The renderer never fetches an address that came from a user.

Our design template has a fixed box for the name: 552 px wide on one line. A short name should stay at 60 px. A longer name should get smaller, down to 40 px. A name too long even at 40 px gets cut and ends with three periods. The tagline gets at most two lines of 30 px.

CSS has no rule for "shrink this text until it fits the box", so we measure. lib/og-text.ts reads advance widths straight from the font file: it looks each character up in the font's Unicode BMP cmap table and takes the width from hmtx. Characters above U+FFFF, such as most emoji, and characters the font does not have get the width of the font's fallback glyph, so text full of them is measured only roughly. Then it adds up the widths:

// lib/og-text.ts, excerpt, comments omitted
export function textWidth(font: FontMetrics, text: string, size: number, letterSpacing = 0): number {
  let total = 0;
  for (const ch of text) total += font.advance(ch.codePointAt(0)!) * size + letterSpacing;
  return total;
}

Fitting the name is then a loop from the largest size down, in 2 px steps:

// lib/og-text.ts, excerpt, comments omitted
const SAFETY = 1.03;
export const NAME_BOX = 552;
export const NAME_MAX_SIZE = 60;
export const NAME_MIN_SIZE = 40;

// ... tagline constants and the clean and truncate helpers omitted;
// clean collapses whitespace, truncate cuts until the text plus "..." fits

export function fitName(
  bold: FontMetrics,
  rawName: string,
  box = NAME_BOX,
  max = NAME_MAX_SIZE,
  min = NAME_MIN_SIZE,
): { text: string; size: number; letterSpacing: number } {
  const name = clean(rawName);
  const spacing = (size: number) => (-1.8 * size) / max;
  const width = (text: string, size: number) => textWidth(bold, text, size, spacing(size)) * SAFETY;
  for (let size = max; size >= min; size -= 2) {
    if (width(name, size) <= box) return { text: name, size, letterSpacing: spacing(size) };
  }
  return { text: truncate((t) => width(t, min) <= box, name), size: min, letterSpacing: spacing(min) };
}

Three details are worth copying:

The safety factor. Our measurement ignores kerning and rounding, so every width is multiplied by 1.03 before it is compared with the box. A few percent of slack is cheaper than a name that touches the logo frame.
The letter spacing scales with the size. The template uses -1.8 px at 60 px, so a smaller size gets proportionally less negative spacing, and the measurement includes it.
The font is the same file everywhere. The renderer draws with the DejaVu Sans files we pass in fonts, and the measurement reads the same files. Measuring with one font and drawing with another would make the numbers meaningless.

wrapTagline does the same for the tagline: it fills the first line word by word, puts the rest on the second, and cuts the second line with three periods if needed. A single word longer than a line is broken where it stops fitting.

Because the result of all this is plain data, a name and a size, the text is placed in the JSX with fixed coordinates. One more helper, textBox, turns the template's baseline into a top and a lineHeight from the font's ascent and descent, so text sits exactly where the design file puts it.

Rendering a PNG is the slow part, and preview crawlers ask for the same image again and again. We cache at three levels.

The URL. ogVersion is a short FNV-1a hash of the name, tagline and logo URL. It goes into the ?v= parameter of the image URL in the metadata. When a maker renames a product, the page starts pointing at a new image URL. That helps a platform that fetches the page again pick up the new image. It does not force any platform to fetch the page again.

The process. The route handler keeps rendered PNGs in a small in-memory cache, keyed by slug and version:

// app/product-og/[slug]/route.tsx, excerpt
const product = await getProductBySlug(slug).catch(() => null);
if (!product || product.status !== "live") return await fallback();

const key = `${slug}:${ogVersion(product)}`;
let png = ogCache.get(key);
if (!png) {
  png = await renderProductOg(product);
  ogCache.set(key, png);
}
return new Response(png as BodyInit, { headers: IMAGE_HEADERS });

OgCache is a Map used as a least recently used list: up to 200 entries, each expiring after six hours. Product and tag images share it, with a tag: prefix on tag keys.

HTTP. Successful images go out with:

Content-Type: image/png
Cache-Control: public, max-age=3600, s-maxage=86400, stale-while-revalidate=604800

The fallback. If the product does not exist, is not live, or anything throws, the handler returns a static PNG with Cache-Control: public, max-age=300. The fallback has a five minute freshness lifetime, while a real image stays fresh for an hour in browser caches and a day in shared caches. After the five minutes, a cache that respects the header asks again, which matters for a product that was waiting for review and has since gone live. A sharing service may still keep its own copy of the preview longer than that.

The fitting and caching code has no React and no renderer in it, so it runs under node --test. The tests load the real font files:

// tests/og-text.test.mjs, excerpt
test("a name too long even at 40 px is truncated with three periods and fits", () => {
  const fit = fitName(bold, "An extraordinarily long product name that cannot possibly fit in one line");
  assert.equal(fit.size, 40);
  assert.ok(fit.text.endsWith("...") && fit.text.length < 60);
  assert.ok(textWidth(bold, fit.text, fit.size, fit.letterSpacing) <= NAME_BOX);
});

Other tests check the font metrics against known values from the DejaVu tables, that a tagline wraps into two lines that both fit, that identical inputs give the same version and that changing the name, the tagline or the logo URL gives a different one, and that the cache evicts the least recently used entry and drops expired ones with an injected clock. The tag page test loads the real page module with a fake lookup for ai-tools, a tag without a static card, and checks that its metadata points at a versioned /tag-og/ai-tools URL and that renaming this tag changes that address.

These tests do not render a PNG. For that we check the live site after a deploy:

curl -s -A "Slackbot-LinkExpanding 1.0" https://yoursite.com/product/some-slug -o page.html
grep -o '<meta property="og:image" content="[^"]*"' page.html
curl -s -D - -o og.png "https://yoursite.com/product-og/some-slug?v=..." | grep -iE "^HTTP|content-type|cache-control"
python3 -c "from PIL import Image; print(Image.open('og.png').size)"

and then open the PNG and look at it. When we last did this, the product page above pointed at its versioned image, the image answered 200 with image/png and the long cache header, and it measured 1200 x 630. An unknown slug answered 200 with the fallback image and max-age=300.

Point your metadata at a route that renders the image, and put a version of the image's inputs in the URL.
Keep one shared layout and pass only the page data in. Our product and tag images differ by a label, a field or two and an illustration.
If the design needs text to shrink or stop at a number of lines, measure it with the same font file the renderer uses, add a little slack, and place the result with fixed coordinates.
Never let the renderer fetch a URL a user typed. Fetch from your own storage, check the bytes, reject files that are too large.
Cache the PNG bytes in the process, send long cache headers for real images and short ones for the fallback.

If you generate preview images differently, for example with the opengraph-image file convention, I would like to hear what made you choose it.

RadarMakers — Wed, 28 Oct 2026 08:30:04 +0000

Liquid syntax error: 'details' tag was never closed

RadarMakers — Tue, 27 Oct 2026 13:54:32 +0000

Launching a small product means a pile of small chores: a favicon set, a few screenshots in a nice frame, tracked links for every channel, a changelog, a launch checklist, and a check that your link previews actually work. We built tools for these into RadarMakers, a launch platform for indie makers, and made them free with no account.

There are eight of them, and they split into two honest groups. Six run entirely in your browser. Two need to fetch a public page, so they send the address you type to our server. This post explains both groups and the code pattern that keeps all eight easy to test.

Launch UTM link builder. Builds tracked links for many channels and destination pages at once, imports a CSV, checks that campaign names are spelled consistently and downloads a campaign sheet.
Launch date planner. Turns a launch date into a dated task list you can tick off and export as a calendar file or Markdown.
Screenshot mockup and launch image exporter. Frames a real screenshot with padding, a background and a shadow, lets you blur private details, and exports launch images at several sizes.
Favicon and PWA icon package builder. Turns one logo into a favicon.ico, PNG sizes and a web manifest, with a real 16 pixel preview.
Batch image optimizer with a file size target. Compresses several screenshots towards a target size and gives you the files plus a CSV report.
Changelog and release notes generator. Turns a list of changes into a Markdown or HTML changelog, grouped by type.

Four of these accept files, and each reads them in the page: the UTM builder reads a CSV with FileReader.readAsText, the favicon builder loads the logo through an object URL into an Image, and the screenshot mockup and image optimizer read the file with file.arrayBuffer() and decode it with createImageBitmap. The results are drawn on a canvas or built in JavaScript and offered as downloads made from a Blob, or a ZIP for the favicon package. These six tools process your working input locally and create downloads in your browser. They do not upload your files.

The meta tag checker and the Open Graph and social card checker answer a different question: "what does this live page actually tell search engines and social networks?" A browser cannot reliably read arbitrary sites unless those sites allow cross origin access. So these two tools send the address to our backend. The server fetches the page, follows permitted redirects, reads its tags and checks any referenced share images. It reads the HTML without running the page's JavaScript, so the previews approximate what each platform shows rather than reproduce it exactly.

We say this on the page, in plain words, above the input:

The address you type is sent to our server. The server downloads that public page once, reads its tags and sends the result back. Neither the address nor the result is stored, and the limit is 20 checks per minute.

That wording is a little shorter than reality, since the server also follows redirects and checks share images, as described above. On the server side, three decisions matter:

The handler and the inspector do not log or persist the submitted URL or the inspection result.
The fetch goes through a dialer that rejects loopback, private, link local and other blocked IP ranges on every connection.
A rate limiter allows 20 requests per minute per IP, shared by both checkers.

// cmd/server/main.go, excerpt
inspector := inspect.New(audit.NewPublicOnlyClient(8*time.Second, 0))
inspectLimiter := custommw.NewRateLimiter(20, time.Minute)
r.With(inspectLimiter.Middleware).Post("/tools/inspect-url", handler.NewToolsInspectHandler(inspector).Inspect)

Both checkers also have a manual mode, where you type a title and description or pick an image from your disk to preview a card. That mode stays local like the other six tools.

We separate reusable processing logic from React components, with shared inspection code for both URL checkers. Most tools have a logic.ts with pure functions and no React or DOM, next to a component that handles input, canvas drawing and downloads. Each tool has its own test file that runs in plain Node with node --test. Today the eight tools plus their shared URL inspector have 199 test declarations between them, covering the logic, some component interactions, generated files and server rendered page HTML.

A small example from the UTM builder. Campaign names that differ only in case or spacing split your analytics into separate rows, so the tool normalizes them and tells you what it removed instead of silently transliterating:

// utm-link-builder/logic.ts
export function cleanValue(raw: string, normalize: boolean, separator: Separator): { value: string; removed: string[] } {
  const trimmed = raw.trim();
  if (!normalize) return { value: trimmed, removed: [] };
  const removed: string[] = [];
  let kept = "";
  for (const char of trimmed.toLowerCase()) {
    if (/[a-z0-9_\s-]/.test(char)) kept += char;
    else if (!removed.includes(char)) removed.push(char);
  }
  const value = kept.trim().replace(/\s+/g, separator);
  return { value, removed };
}

// tests/utm-link-builder.test.mjs, excerpt
test("cleanValue lowercases, converts whitespace and reports skipped characters without transliteration", () => {
  assert.deepEqual(cleanValue("  Café Launch!! \t2026 ", true, "-"), { value: "caf-launch-2026", removed: ["é", "!"] });
});

Because the logic does not touch the DOM, the same functions run in the browser and in the test runner. Canvas drawing is not covered by these Node tests. In the image optimizer, the encoder is passed into the logic as a callback, so the tests exercise our size targeting rather than the browser's codecs.

/launch-checklist

Say where the data goes. "Runs in your browser" is a strong promise. When a tool cannot keep it, say so next to the input, not in a privacy policy.
Build downloads from Blobs. For images, CSV and text, the browser can do the whole job, so there is no reason to upload a file only to hand it back.
Keep logic out of components where you can. Pure functions are what make a refactor safe to test without clicking through the page.

The tools are free to use without an account. If you build tools like these, I would like to hear how you handle the line between local processing and server fetches.