Skip to main content

Media Uploads — Content Reference

Folder: static/img/

Pycora Pro stores all media — images, logos, photos — in a single folder. Decap CMS gives you a media library to upload, browse, and select files.

python ssg pro jamstack static site generator

Where Media Lives​

LayerPath
On diskstatic/img/
In your content/img/filename.ext
On the live sitehttps://your-site.com/img/filename.ext

The mapping is defined in static/admin/config.yml:

media_folder: "static/img"
public_folder: "/img"
  • media_folder — where files are saved on disk
  • public_folder — the URL prefix used in content

Supported Formats​

Pycora Pro works with any image format your browser supports.

FormatBest ForNotes
AVIFHero images, featured imagesSmallest file size
WebPGeneral useWide browser support
JPGPhotosUniversal
PNGLogos, icons with transparencyLarger files
SVGIcons, logosScalable, tiny

Tip: Convert large JPGs and PNGs to WebP or AVIF before uploading. This keeps your site fast and your Lighthouse score high.

UseSizeFile Size
Hero image1600×900Under 200 KB
Featured image1200×630Under 150 KB
Project card800×600Under 100 KB
Client photo400×400Under 50 KB
LogoSVG or 200×200Under 20 KB
Favicon32×32 or 64×64Under 10 KB

How to Upload an Image​

  1. Open the CMS at /admin/
  2. Open any page with an image field (e.g., Pages → Home Page → Hero → Image)
  3. Click the image field
  4. Click Upload
  5. Select a file from your computer
  6. Wait for the upload to finish
  7. Click Save

The image is stored in static/img/ and referenced as /img/filename.ext.

How to Use an Existing Image​

If the image is already in static/img/:

  1. Click the image field
  2. Click Choose an existing image
  3. Browse the media library
  4. Select the image
  5. Click Save

How to Replace an Image​

  1. Open the image field
  2. Click Upload
  3. Select the new image
  4. Click Save

The new file is committed. The old file remains in static/img/ — you can delete it manually via Git if you want.

How to Delete an Image​

  1. Open the media library (click any image field → Choose an existing image)
  2. Hover over the image you want to delete
  3. Click the trash icon
  4. Confirm

Warning: Deleting an image used elsewhere on your site will break those pages. Check first.

Image Naming Best Practices​

Use clean, descriptive filenames:

GoodBad
hero-homepage.avifIMG_2024_final_v2.jpg
client-alvio.avifUntitled-1.png
logo-dark.svglogo (1).svg

Rules:

  • All lowercase
  • Use hyphens, not spaces
  • No special characters
  • Keep it short

Where to Use Images​

Every image field in Pycora Pro maps to a specific section:

PageFieldPurpose
Home Page → Herohero.image.urlHero image on the homepage
Home Page → Intro Grid 1intro_grid1.imageFirst grid image
Home Page → Intro Grid 3intro_grid3.imageThird grid image
Home Page → Testimonialtestimonial.imageTestimonial background
Home Page → Testimonial → Clienttestimonial.client.imageClient photo
About PageimageAbout page image
Contact PageimageContact page image
Blog PostsimageFeatured image per post
ProjectsimageFeatured image per project
Site Settingsimage, favicon, logoGlobal brand assets

How Images Are Served​

Pycora Pro copies everything from static/ to output/ on every build. So:

static/img/hero.avif  →  output/img/hero.avif  →  /img/hero.avif

No image processing. No CDN transformation. The file you upload is the file that ships.

Optimizing Images​

Before uploading, optimize your images:

  1. Resize to the largest size needed (see recommended sizes above)
  2. Convert to AVIF or WebP using a tool like Squoosh
  3. Compress — aim for 60–80% quality
  4. Upload

For AVIF support in your editor, see the Squoosh guide.

Best Practices​

  • Use AVIF or WebP — smallest file sizes
  • Resize before uploading — do not upload 4000px photos
  • Name files descriptively — helps with SEO and organization
  • Keep static/img/ organized — no subfolders needed, but keep it clean
  • Delete unused images — keeps the repo lean

Troubleshooting​

Image does not appear after upload​

  1. Check that static/img/ contains the file
  2. Check that the field value starts with /img/
  3. Refresh with Ctrl + Shift + R
  4. Check the terminal for build errors

Upload fails with an error​

  1. Check that Terminal 1 (Decap server) is running (local mode)
  2. Check that the file is under 10 MB
  3. Check that static/img/ exists and is writable

Image appears broken on the live site​

The image path in your content must match a file inside static/img/. Check for typos in the filename.

Image is too large / slow to load​

Convert to WebP or AVIF using Squoosh. Aim for under 200 KB per image.

Existing image is not in the media library​

The media library reads from static/img/. If the file exists on disk but not in the library:

  1. Check that the file name has no spaces
  2. Refresh the CMS page
  3. Check that media_folder is correct in config.yml

What's Next?​

You have completed the Content Creation Reference. You can now:

👉 Back to Content Creation Overview →