Skip to main content

Adding Images

Use this workflow for every documentation image so pages render correctly in production without committing large media files to Git.

Why Images Are Managed Separately​

  • Documentation images are stored in a local project root img directory, not in markdown folders.
  • The img/content path is gitignored, so image files are not committed to this repository.
  • You must upload images to live separately via SFTP.

This keeps the git repository lean while still allowing documentation pages to reference production-hosted assets.

Required Folder Structure​

If img does not exist at the project root, create it.

Store images under:

/img/content/<client>/<site>/<filename>

Examples:

/img/content/scottsdale-mint/fishbowl/fb-product-sync.png
/img/content/gsm-outdoors/middleware/order-flow-diagram.webp

Markdown Syntax​

Always use pathname:// as the image URL prefix:

![<ALT TEXT>](pathname:///img/content/<client>/<site>/fb-product-sync.png)

Real example:

![Fishbowl Sync Settings](pathname:///img/content/scottsdale-mint/fishbowl/fb-product-sync.png)

Authoring Standards​

  • Use descriptive, human-readable alt text. Describe what the image shows and why it matters.
  • Use lowercase, hyphenated filenames.
  • Keep images scoped to the correct client and site path.
  • Prefer compressed formats (.webp, optimized .png) when quality allows.

Upload Workflow​

  1. Save the image locally to /img/content/<client>/<site>/.
  2. Reference it in markdown with pathname:///img/content/....
  3. Upload the same file to live via SFTP, preserving the same path.
  4. Run npm run build to confirm docs compile.
  5. Verify the page on live after deployment.

Common Mistakes​

  • Using /static/img/... paths for content screenshots.
  • Omitting the pathname:// prefix.
  • Uploading to a different client/site directory than the markdown reference.
  • Assuming images are in git because markdown files were committed.