Skip to content

Managing Images

This section covers how to add, replace, and organize images (screenshots, diagrams) in the EPMware documentation.

Image Organization

All images are stored under docs/assets/images/ and organized by documentation section:

docs/assets/images/
├── epmware-logo.png
├── favicon.ico
├── configuration/
│   ├── application-config-overview.png
│   ├── dimension-classes-grid.png
│   ├── property-configuration-view.png
│   └── ...
├── security/
├── workflow/
├── deployment/
├── export/
├── logic-builder/
├── administration/
└── appendices/
    ├── oracle-epm-overview.png
    ├── integration-architecture.png
    └── ...

Each section folder corresponds to a documentation section. Place images in the folder that matches the section where they will be used.

Image Naming Conventions

Use descriptive, self-documenting filenames:

Good Name Bad Name
dimension-classes-grid.png image43.png
property-configuration-view.png screenshot1.png
enable-workflow-filtering.png img_2024.png
oracle-epm-overview.png appendix-a-fig1.png

Naming rules:

  • Use lowercase letters only
  • Separate words with hyphens (-)
  • Make the name describe what the image shows (e.g., add-server-popup.png)
  • Use .png format for screenshots

Image Markdown Syntax

The standard pattern for images with captions in EPMware docs:

![Descriptive alt text](../assets/images/section/image-name.png)<br/>
*Caption describing what the image shows*

The <br/> tag is important — it forces a line break so the italic caption appears directly below the image instead of on a separate paragraph.

Image Path Patterns

The correct image path depends on the location of the markdown file:

Markdown File Location Image Path Pattern
docs/configuration/applications.md ../assets/images/configuration/filename.png
docs/security/index.md ../assets/images/security/filename.png
docs/appendices/oracle-epm-cloud.md ../assets/images/appendices/filename.png
docs/index.md assets/images/filename.png

Files at the root level (docs/index.md) do not need ../ because assets/ is in the same directory. Files one level deep (inside section folders) need one ../ to navigate up to docs/ before descending into assets/.

Adding a New Image

  1. Capture or prepare the image as a .png file.
  2. Give it a descriptive filename following the naming conventions above.
  3. Copy it to the appropriate section folder under docs/assets/images/.
  4. Add the image reference in the markdown file using the syntax pattern above.
  5. Run mkdocs serve and verify the image displays correctly.

Replacing an Existing Image

  1. Prepare the new image with the same filename as the one being replaced.
  2. Copy it to the same location, overwriting the old file.
  3. Run mkdocs serve and verify the updated image displays correctly.
  4. If the new image has a different filename, update all markdown references to the image. Use your editor's search-across-files feature to find all references.

Extracting Images from Word Documents

When converting content from the Word document source, images need to be extracted and renamed. A Python script (extract_admin_images.py) is available for this purpose.

Manual Extraction

If you prefer to extract images manually:

  1. Make a copy of the .docx file and rename the extension to .zip.
  2. Extract the ZIP file — images are located in the word/media/ folder.
  3. The images will have generic names like image1.png, image2.png, etc.
  4. Rename each image with a descriptive name that matches its content.
  5. Move the renamed images to the appropriate section folder under docs/assets/images/.

Using the Image Extraction Script

The extract_admin_images.py script automates extraction and organization:

python extract_admin_images.py "EPMware Administrator's Guide v7.6.docx"

The script will:

  • Extract all images from the Word document
  • Organize them into section folders based on their location in the document
  • Generate a reference file mapping original image numbers to new descriptive names
  • Create update scripts (.sh and .ps1) for batch-updating markdown references

Image Placeholders

When converting content before images are ready, use placeholder references:

![Application Configuration Overview](../assets/images/configuration/application-config-overview.png)<br/>
*Application configuration screen showing registered applications*

Even if the image file does not exist yet, keeping the reference with a descriptive name makes it easy to replace later. The page will show a broken image icon, but the correct path is already in place.

Image Sizing

If an image is too large on the page, you can control its size by wrapping it in HTML with a width attribute, though this is rarely needed since MkDocs and the Material theme handle responsive sizing automatically.