This documentation is also published as Markdown for efficient machine reading: the whole site is indexed at /llms.txt, and every page has a clean Markdown copy under /_llms/. These are generated from the same source and cost far fewer tokens to read than this rendered HTML.

Skip to main content Skip to navigation
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 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).

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.