Images and other assets

Images and other documents linked to from any specific page should live as near to that page as possible.

Always follow our naming conventions when adding assets to the documentation.

Linking to images and assets

Images and assets can be linked to relative to the current file, in the same way that we link to pages relative to any particular page. For more information on relative URLs, see Linking to other pages.

Folder structure

The simplest strategy is to create a folder for your page, use a +page.md file for the page content, and then create an assets folder at the same level as the +page.md.

For example, if we had the following file:

...
└── foo/+page.md

and we wanted to add images to it, we would do the following:

...
└── foo
    ├── assets
    │   └── my-image.jpeg
    └── +page.md

This ensures that it’s clear which images belong to which files. If files are shared between multiple pages, a shared/assets folder can be created at the closest common parent of the pages.

The following example demonstrates a shared folder for two files, foo.md, and bar.md at the same level in the folder structure:

...
└── parent
    ├── shared
    │   └── assets
    │       └── shared-image.jpeg
    ├── foo
    │   ├── assets
    │   │   └── foo-image.jpeg
    │   └── +page.md
    ├── bar
    │   ├── assets
    │   │   └── bar-image.jpeg
    │   └── +page.md
    └── +page.md

Each page would reference shared-image.jpeg as follows:

![image alt text](../shared/assets/shared-image.jpeg)