---
title: Add images and shared assets to a page
description: "Colocate page-specific images next to their markdown, and put shared images in wwwroot for one canonical URL."
canonical_url: https://usepennington.net/how-to/pages/images-and-assets/
sidecar_url: https://usepennington.net/how-to/pages/images-and-assets.md
content_hash: sha256:c9a6f58bc788be3c147a670483a98e6b8087cbe12808b5b81131c53a850c3885
tokens: 763
uid: how-to.pages.images-and-assets
reading_time_minutes: 2
---

Guides
# Add images and shared assets to a page

Colocate page-specific images next to their markdown, and put shared images in wwwroot for one canonical URL.

 
To keep an image next to the markdown that references it, drop it into a folder alongside the page under `Content/`. When the same file is needed from multiple pages — a logo, a cover photo, a shared diagram — put it in `wwwroot/` instead so it has one canonical URL.

 
## Before you begin

 
 - An existing Pennington site with at least one markdown page (see [Serve markdown through Blazor Pages](https://usepennington.net/tutorials/getting-started/first-page.md) if not).
 - The target markdown file is known.
 - The project has a `wwwroot/` folder for shared static files (the default for Web SDK projects).
 
 
## Where to put images

 
### Colocated next to the markdown file

 
Drop the image into a folder alongside the page — typically an `assets/` subfolder. Pennington copies every non-markdown file under `Content/` to the same relative path in the output, so the image ships with the page automatically. Reference it with a relative path:

 
```markdown
![Alt text](./assets/colocated.png)
```

 
The link resolves correctly whether the page is served at `/main/images-and-assets/` or under a locale prefix.

 
### Shared in `wwwroot/`

 
When the same image is referenced from multiple pages, drop it into `wwwroot/` so it has one canonical URL. The ASP.NET host serves `wwwroot/` as static web root by default, so `wwwroot/shared.png` is served at `/shared.png`. Reference it with a leading slash:

 
```markdown
![Alt text](/shared.png)
```

 
When deploying under a sub-path, `BaseUrlHtmlRewriter` prepends the base URL at response time — avoid hard-coding the sub-path. See [Host under a sub-path (base URL)](https://usepennington.net/how-to/deployment/base-url.md).

 
## Verify

 
 - Run `dotnet run` and open the page that references the colocated image — the image renders inline.
 - Visit the shared-asset URL directly (for example, `/shared.png`) — the file loads.
 - Run `dotnet run -- build` and confirm both files appear in `output/` at their original relative paths.
 
 
## Related

 
 - [Pennington.Infrastructure.MarkdownContentOptions](https://usepennington.net/reference/api/markdown-content-options.md) — `ContentPath`, `ExcludePaths`, `FilePattern`. Use `ExcludePaths` to keep a subtree of `Content/` out of the output.
 - [Front matter key reference](https://usepennington.net/reference/front-matter/keys.md) — when an image is set as a social card or cover image via front matter.
 - [Dev mode and build mode share one code path](https://usepennington.net/explanation/core/dev-vs-build.md) — how `GetContentToCopyAsync` fits the content pipeline.
 
 
[Previous
                
                Mark drafts, schedule posts, tag pages, and control sort order](https://usepennington.net/how-to/pages/drafts-tags-ordering.md)[Next
                    
                Forward visitors from a renamed page](https://usepennington.net/how-to/pages/redirects.md)