Adding Images to Markdown Documentation

Adding Images to Markdown Documentation¶

Folder Structure Setup¶

In VS Code, organize your project with a dedicated images folder:

your-documentation-site/
├── _posts/
│   ├── 2025-09-25-your-article.md
├── assets/
│   └── images/
│       ├── screenshots/
│       ├── diagrams/
│       └── logos/
└── _config.yml

Best Practice: Create a assets/images/ folder at your site root. This keeps images organized and easily accessible.

Image Sizing Guidelines¶

Recommended Image Sizes¶

Screenshots: 800-1200px wide (will scale down automatically)
Small icons/buttons: 50-100px wide
Diagrams: 600-1000px wide
Full-width images: 1200px+ wide

File Size Optimization¶

Keep images under 500 KB when possible
Use PNG for screenshots with text
Use JPG for photos
Consider WebP for better compression

Basic Image Syntax¶

Standard Markdown Image¶

![Alt text](path/to/image.png)

With Title (hover text)¶

![Alt text](path/to/image.png "Image title")

Sizing Images in Markdown¶

Method 1: HTML Tags (Most Control)¶

<img src="/assets/images/screenshot.png" alt="Terminal screenshot" width="600">

Method 2: HTML with Percentage¶

<img src="/assets/images/diagram.png" alt="Network diagram" style="width: 80%;">

Method 3: CSS Classes (if your site supports them)¶

![Proxmox dashboard](/assets/images/proxmox-dash.png){: .img-responsive .img-center}

Three Image Examples¶

Example 1: Small UI Element (150px)¶

<img src="/assets/images/terminal-icon.png" alt="Terminal icon in taskbar" width="150">

<img src="/assets/images/terminal-icon.png" alt="Terminal icon in taskbar" width="150">

Use for: Small UI elements, icons, buttons, menu items

Example 2: Medium Screenshot (600px)¶

<img src="/assets/images/vs-code-interface.png" alt="VS Code editor showing markdown file" width="600">

<img src="/assets/images/vs-code-interface.png" alt="VS Code editor showing markdown file" width="600">

Use for: Code editor screenshots, dialog boxes, small application windows

Example 3: Full Screenshot (800px)¶

<img src="/assets/images/proxmox-dashboard.png" alt="Proxmox VE web interface dashboard" width="800">

<img src="/assets/images/proxmox-dashboard.png" alt="Proxmox VE web interface dashboard" width="800">

Use for: Full application screenshots, complete desktop views, detailed dashboards

VS Code Workflow¶

1. Taking Screenshots¶

Linux (for your documentation):

gnome-screenshot -a - Select area
gnome-screenshot -w - Select window
Save to your Downloads folder first

2. Adding Images in VS Code¶

Create the image folder: Right-click in Explorer → New Folder → assets/images
Copy your screenshot: Drag from file explorer into the assets/images folder
Insert the image: Type the HTML img tag or use Markdown syntax
Preview: Use Ctrl+Shift+V to preview your markdown

3. Quick Image Insert Snippet¶

In VS Code, create a snippet for faster image insertion:

Ctrl+Shift+P → "Configure User Snippets" → "markdown"
Add this snippet:

"img": {
    "prefix": "img",
    "body": [
        "<img src=\"/assets/images/$1\" alt=\"$2\" width=\"$3\">"
    ],
    "description": "Insert responsive image"
}

Now type img + Tab to quickly insert image tags!

File Naming Best Practices¶

Good Names¶

proxmox-vm-creation-dialog.png
linux-terminal-setup-complete.png
docker-compose-file-structure.png

Bad Names¶

Screenshot1.png
image.png
pic.jpg

Rules:

Use lowercase
Separate words with hyphens
Be descriptive
Include the article topic

Testing Your Images¶

Before Publishing¶

Preview in VS Code: Ctrl+Shift+V
Check mobile sizes: Images should be readable on phones
Verify paths: Make sure image paths work when published
Alt text: Always include descriptive alt text for accessibility

Common Path Issues¶

<!-- Wrong - won't work when published -->
![Screenshot](./images/screenshot.png)

<!-- Correct - works in production -->
![Screenshot](/assets/images/screenshot.png)

Pro Tips¶

Consistent sizing: Pick 2-3 standard widths and stick to them
Lazy loading: Some Jekyll themes support loading="lazy"
Dark mode: Consider how images look on dark backgrounds
Compression: Use tools like TinyPNG before adding large images
Alt text: Write it like you're describing to someone who can't see it

Example Article Structure¶

---
layout: post
title: "Setting up Proxmox VE"
draft: false  
date: 2025-09-25
description: Complete guide to installing Proxmox VE on a mini PC
---

## Setting up Proxmox VE

First, download the ISO from the official site:

```html
<img src="/assets/images/proxmox-download-page.png" alt="Proxmox download page showing latest ISO" width="600">

Next, boot into the installer. You should see this screen:

<img src="/assets/images/proxmox-installer-menu.png" alt="Proxmox installer boot menu" width="800">

The installation will create a dashboard like this:

<img src="/assets/images/proxmox-final-dashboard.png" alt="Completed Proxmox installation dashboard" width="800">

Start with these basics, and you'll have professional-looking documentation with properly sized, accessible images!