Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Build the directory as structured records plus an Astro page that renders those records into linked thumbnail cards. If you also want a page for each listing, create a dynamic route and use getStaticPaths() to generate one prerendered page per record. A content collection alone does not create routes.
Choose how the directory should work
Start with two decisions: where listing data and images will live, and whether visitors need a separate page for each item. Astro supports collection-backed content as well as other data sources; the right choice depends on how listings will be maintained.
As an Amazon Associate I earn from qualifying purchases.
| Choice | Use it when | Key consideration |
|---|---|---|
| Local images | You want to keep thumbnail files with the site. | Astro’s image guide supports associating an image with a collection entry using a path relative to that entry’s folder. |
| Remote image URLs | Images are hosted outside the project. | Configure approved remote sources if you want Astro image optimization; source authorization and optimization are distinct concerns. |
| Content collection | You want directory records managed as content. | Collection entries are stored outside src/pages/ and do not automatically become pages. |
| One listing page | Visitors only need to browse or click through to external destinations. | Render all records from a page in src/pages/. |
| Individual item pages | Each listing needs its own URL and details. | Add a dynamic route and generate its paths at build time. |
Store each directory entry as structured data
Keep each record’s visible title, stable URL identifier and thumbnail reference together. For example, a collection entry can provide these fields in its frontmatter:
---
title: Example site
slug: example-site
thumbnail: ./example-site.webp
url: https://example.com
---
A short description of the site.The thumbnail path here is an example of a local image reference relative to the entry’s folder. If you use remote images or an external data source instead, adapt the record shape and image handling accordingly. Keep identifiers stable: changing a title need not change the item’s URL.
#1 Best Overall
Astro content collections are not route files. Astro’s documentation notes that collections live outside src/pages/; a route must query the entries and render them.
Build the listing page
Put the directory listing page in src/pages/; Astro’s file-based routing uses supported files there to create routes. The following illustrates the rendering shape for collection data. Adjust the collection name and image lookup to match the schema in your project:
---
import { getCollection } from 'astro:content';
import { Image } from 'astro:assets';
const entries = await getCollection('sites');
---
<html lang="en">
<head>
<title>Website directory</title>
</head>
<body>
<main>
<h1>Website directory</h1>
<ul class="directory">
{entries.map((entry) => (
<li>
<a href={`/items/${entry.data.slug}/`}>
<Image
src={entry.data.thumbnail}
alt={`Screenshot of ${entry.data.title}`}
width={640}
height={400}
/>
<h2>{entry.data.title}</h2>
</a>
</li>
))}
</ul>
</main>
</body>
</html>The exact image import and fields depend on the collection schema and whether your images are local or remote. Give each thumbnail meaningful alternative text, preserve consistent image dimensions to keep the grid orderly, and make the image and visible title part of the same real link so it can be reached and activated with a keyboard.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsAdd a page for every directory item
For item pages, add src/pages/items/[slug].astro. The bracketed filename defines a dynamic route parameter. In a static build, return one path object per entry from getStaticPaths(); parameter keys must match the filename parameter, and parameter values must be strings.
---
import { getCollection } from 'astro:content';
export async function getStaticPaths() {
const entries = await getCollection('sites');
return entries.map((entry) => ({
params: { slug: String(entry.data.slug) },
props: { entry },
}));
}
const { entry } = Astro.props;
---
<html lang="en">
<head>
<title>{entry.data.title}</title>
</head>
<body>
<main>
<p><a href="/">Back to directory</a></p>
<h1>{entry.data.title}</h1>
<p>{entry.body}</p>
<p><a href={entry.data.url}>Visit {entry.data.title}</a></p>
</main>
</body>
</html>getStaticPaths() runs in an isolated scope. Fetch or query the data it needs inside that function rather than assuming it can access arbitrary variables declared elsewhere in the page frontmatter. If your directory uses an external data source instead of a collection, use that source inside the path-generation function and pass the corresponding item data through props.
Handle local and remote thumbnails
Local files
Local images can be associated with collection entries using a path relative to the entry’s folder, as described in Astro’s image guide. Use Astro’s image components when they fit your image workflow, and provide image dimensions so the page can reserve space while images load.
Remote URLs
If a thumbnail is served from another host and you want Astro to optimize it, configure image.domains or image.remotePatterns for the permitted sources. Astro’s documentation says remote images from other sources will not be optimized. Its <Image /> component can still help prevent layout shift, but do not assume that a remote image will receive transformations unless the source is allowed and your image service and deployment adapter support the desired transformation.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Keep the directory dependable
- Validate that every record has a title, a unique slug and a usable thumbnail reference before building.
- Check that each generated item URL corresponds to the parameter in the dynamic route filename.
- Use string route parameter values, even if an ID starts as a number in your source data.
- Keep thumbnail framing consistent so the directory is easy to scan; choose dimensions that suit your assets rather than stretching them.
- Use a visible title and a descriptive image alternative, and ensure the card link itself is an ordinary keyboard-accessible anchor.
- For remote images, verify the host against your configured domains or patterns and confirm your deployment’s image service supports the transformation you expect.
Troubleshoot common problems
Collection entries exist, but there are no item pages
Collection entries do not automatically become routes. Add a page under src/pages/ and, for a dynamic static route, export getStaticPaths() that returns the required paths.
Astro rejects a route parameter
Make the key in each params object match the bracketed parameter in the filename. Convert the value to a string before returning it.
The listing link points to a missing item
Compare the listing’s URL construction with the slug used in getStaticPaths(). They must use the same identifier and route pattern.
A remote image displays but is not optimized
Check whether its host is included in image.domains or image.remotePatterns. Then verify image-service and adapter support for the transformation you want; allowing a source and performing an optimization are separate steps.
A thumbnail is missing or has the wrong asset
Check the record’s image reference and confirm that its path is relative to the correct entry folder when using local collection images. For remote assets, verify the URL and permitted host.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
If your directory needs actual website screenshots as thumbnail assets, you can capture a page with one request instead of setting up a browser capture flow. See the ScreenshotNeo API documentation for its request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo removes cookie banners, newsletter popups and chat widgets before capture; bot checks, blank pages and failed loads are not billed. Its MCP server lets AI agents take screenshots, and the free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Learn more at ScreenshotNeo.
Sign up for 1,000 free screenshots a month, with no card required.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
