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 |

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.

Animated walkthrough: the Article shows the image from the library, stored as a portable reference.
- Open the Article INT001 Orders: order-to-cash overview, linked to INT001: Orders, in the editor.
- Right-click in the content and choose Insert Image from Library.
- 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.
- 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.
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;">
srccontains the resolved URL used for display in the editordata-ndi-namestores the portable name-based reference; on save the editor re-encodes this as{ndi}/logogoesherein the databaseclass="ndi-m"applies the selected size modifierstyleprovides 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:

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.

Animated walkthrough: archive and restore are reversible, Permanently Delete is not.
- Find the image, here Contoso draft diagram, open its Action menu, choose Archive, and confirm. It leaves the list.
- Tick Include archived. The card is back, marked Archived.
- Open its Action menu, choose Restore, and confirm. The image is live again.
- 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.