- 7 minutes to read

What is the Image Library?

The Nodinite Image Library is a centralized database for storing, organizing, and reusing images across your documentation. It replaces the need to upload the same image multiple times or rely on external URLs that may become unavailable. To start using it, see the Images overview.

  • ✅ Upload an image once and reuse it in every Article and Custom Metadata Image field
  • ✅ Keep references portable between Test and Production with the {ndi} name slug
  • ✅ Choose a display size per insertion without touching the original file
  • ✅ Store alt text once for screen reader accessibility everywhere

The Problem It Solves

Before the Image Library, embedding images in articles required:

  • Uploading from a local file for every individual article — no sharing between articles
  • Pasting from clipboard — one copy stored per article, impossible to update globally
  • Using external URLs — risk of broken images if the source server changes
  • Re-entering alt text every time — no standardized accessibility metadata
  • No searchable gallery — no way to find previously uploaded images

The Image Library addresses all of these limitations with a single, searchable, centrally managed collection.

Key Capabilities

Capability Description
Upload Upload PNG, JPEG, GIF, WebP, or SVG images up to 10 MB
Gallery Browse all images in a tile-based gallery with search and tag filter
Edit metadata Update name, title, alt text, description, and tags after upload
Replace image Replace the image file in place in the Web Client; the name slug and every existing reference stay the same
Copy Reference Copy the name-based reference token to clipboard for manual insertion
Archive and Restore New 7.12 Archive retires an image and Restore brings it back; archived images show a broken image indicator in articles
Permanently Delete New 7.12 Removes an image for good, live or archived
Show in Mapify / Mermaid New 7.12 Shows the image with its Tags and the Articles that reference it in Mapify or as a Mermaid diagram
Search Full-text search across name, title, description, and alt text
Tags Organize images with free-form tags; filter the gallery by tag
Size modifiers Control display size at insertion time without editing the source image
Accessibility Alt text stored centrally; applied automatically at every insertion point

Insert Image picker with the image Contoso order-to-cash flow selected, its title, slug, alt text, description, size, an empty Alt Text Override, and Size m (7.12)
The image picker in the Article editor: search or filter by tag on the left; details, Alt Text Override, and Size on the right. Leave Alt Text Override blank to use the image's own alt text.

Use an image in an Article

In the Article editor, right-click in the content and choose Insert Image from Library, or use the toolbar button; see Add images, files, and links to an Article.

Insert the image Contoso order-to-cash flow into the Article INT001 Orders: order-to-cash overview, then save, animated walkthrough (7.12)
Animated walkthrough: the Article shows the image from the library, stored as a portable reference.

  1. Open the Article INT001 Orders: order-to-cash overview, linked to INT001: Orders, in the editor.
  2. Right-click in the content and choose Insert Image from Library.
  3. Search for order-to-cash and pick Contoso order-to-cash flow. The panel shows its title, slug, alt text, description, and size, with an Alt Text Override and a Size.
  4. Click Insert, then Save and close. The Article shows the image.

The editor stores the image as {ndi}/contoso-order-to-cash-flow, so the same Article works in every environment; see Name-Based Image References.

Images in the library are identified by a unique name slug (e.g., logogoeshere). The name is:

  • Lowercase and URL-safe — spaces and special characters are replaced with hyphens on upload
  • Unique across the entire Image Library
  • Stable across environments — the same name slug refers to the same image in Test and Production

This is why name-based references are preferable to ID-based references: database IDs differ between environments, but names are chosen by the uploader and remain consistent everywhere.

HTML Reference

When inserting an image using the editor toolbar, Nodinite generates the following HTML:

<img src="/api/ImageAssets/name/logogoeshere/File"
     data-ndi-name="logogoeshere"
     alt="Your alt text"
     class="ndi-m"
     style="max-width: 384px; height: auto;">
  • src contains the resolved URL used for display in the editor
  • data-ndi-name stores the portable name-based reference; on save the editor re-encodes this as {ndi}/logogoeshere in the database
  • class="ndi-m" applies the selected size modifier
  • style provides an inline fallback for editors that do not load the stylesheet

Markdown Reference

In Markdown Articles, images are referenced using the {ndi} token followed by the image name (see the Macros Reference for every content token):

![My logo][img-logo][m]

[img-logo]: {ndi}/logogoeshere

The Markdown rendering engine resolves {ndi}/logogoeshere to /api/ImageAssets/name/logogoeshere/File at render time. The size modifier [m] is converted to the CSS class ndi-m before the document is rendered.

Inline Markdown Style

For a single-use insertion, the inline form can also be used:

![My logo]({ndi}/logogoeshere)

Size Modifiers

Both the HTML editor picker and Markdown editor support size modifiers, which add a CSS class to the rendered image to constrain its maximum width. The original image file is never modified.

Modifier CSS Class Max Width Typical Use
Original (none) Full width / natural Full-width architecture diagrams
xxs ndi-xxs 64 px Tiny icon-like inline images
xs ndi-xs 128 px Small inline thumbnails
s ndi-s 256 px Small illustrations
m ndi-m 384 px Medium screenshots (default)
l ndi-l 512 px Standard documentation screenshots
xl ndi-xl 768 px Large diagrams
xxl ndi-xxl 1024 px Extra-large architecture diagrams

A fixed size is never wider than the place the image sits in: in a narrower column, an xl or xxl image is scaled down to fit (7.12). When the same image needs to appear at different sizes in different articles, apply different size modifiers at each insertion point — the source image in the library is unchanged.

Supported Image Formats

Format MIME Type Notes
PNG image/png Preferred for screenshots and UI images
JPEG image/jpeg Preferred for photographs
GIF image/gif Static frame rendering; full animation is a future enhancement
WebP image/webp Modern compressed format
SVG image/svg+xml Scalable vector format; dimensions stored as not applicable (scalable by nature)

Maximum file size: 10 MB per upload.

Permissions

Operation Required Permission
View images (gallery, metadata, file) Authenticated
Upload new images Create on Articles New 7.12
Edit image metadata Modify on Articles
Replace an image file Modify on Articles
Archive, Restore, and Permanently Delete images Modify on Articles New 7.12

All authenticated users can view and insert images from the library. Uploading needs Create, and editing, replacing, archiving, and deleting need Modify, on Articles in the user's Role (Permission Set for the Repository Model). Images are user content, so Permanently Delete needs no Administrator Role (see Two delete models). Read access is intentionally broad — images embedded in articles must be loadable by any logged-in user who can read the article.

Image Lifecycle

When an image is archived:

  • The image is soft-deleted — the binary data is retained in the database but marked as archived, and Restore brings it back
  • Any article referencing the archived image will display a broken image indicator in the browser
  • This is intentional — broken images are visible so writers can identify and fix broken references

New 7.12 Permanently Delete removes the image and its file for good, whether it's live or archived: you don't have to archive it first. See Manage images for the steps.

Archive the image Contoso draft diagram, restore it, then permanently delete it, animated walkthrough (7.12)
Animated walkthrough: archive and restore are reversible, Permanently Delete is not.

  1. Find the image, here Contoso draft diagram, open its Action menu, choose Archive, and confirm. It leaves the list.
  2. Tick Include archived. The card is back, marked Archived.
  3. Open its Action menu, choose Restore, and confirm. The image is live again.
  4. Open its Action menu, choose Permanently Delete, and confirm that this can't be undone. The image is gone, even with Include archived on.

Files in the File Library behave the same way, with the same Action menu: View, Edit, Copy Reference, Show in Mapify, Show in Mermaid, Archive or Restore, and Permanently Delete.

To update an existing image (for example, after a UI redesign), replace it in place in the Image Library in the Web Client by uploading the new file for that image. The name slug stays the same, so every existing {ndi}/name reference across articles and Custom Metadata fields shows the new image right away. You don't need to archive the image first: archiving retires an image, replacing updates it. Shared files in the File Library are replaced the same way.

Tip

Before archiving or deleting an image, use Show in Mapify or search article content for the name slug (e.g., logogoeshere) to find all articles that reference it.

Next Steps