Insert images

How do I insert an image?

In addition to text, images are often the most important components of typical content pages. With VisualEditor, images can be uploaded to the wiki and inserted into a page in one step.

Here we highlight the most important questions when inserting images with VisualEditor.

Pictures are inserted via the menu item Insert> Media :


The dialog box Media Settings opens:

When you upload a new image, the upload page shows the following message:

"If you are not able to upload this file under the policies of [wikiname], please close this dialog and try another method. You may also want to try the default upload page."

You can ignore this notice if your wiki administrator did not create copyright policies. If in doubt, contact your wiki administrator for image usage rights in your organization.


After uploading, you will edit the necessary image settings: Details, General Settings, and Advanced Settings.


Here you can associate the picture with a namespace and with categories. media settings 7.0.png

  • Target namespace: The picture can be assigned directly to a namespace. The access rights of the namespace are also applied to the image. This means that only users with access to the namespace can see the image and find it on the wiki.
  • Name: The name should be descriptive so that the image can later be found with the search function.
  • Description: This description is mainly useful for photos or infographics where the image name does not adequately describe the image content.
  • Categories: Here the picture can be assigned to categories. If the category does not exist yet, it will be saved as a "wanted category".

Error message when saving: If the image already exists, an error message appears:


If you want to overwrite the existing file, you can click on the file name and overwrite the file via the file page in the wiki. This is done with the "Upload a new version of this file" link in the "File usage" section. This cannot be done in VisualEditor itself.

General Settings

  • Here, the picture gets a description that is used for different purposes: 987654.png
  • Caption: The caption is used in framed images and thumbnails. Note: If you change an image to frameless and then back to framed, you must re-enter the caption.
  • Alternate text: The alternate text should be entered for each image since it replaces the image in certain contexts. For example, this so-called "alt" text is used by users who work with screen readers. Screen readers are used by users with visual limitations, but search engines can also read this text. In some business areas, the indication of the "old" text is also required by law. If you are not sure, ask your company accordingly.

Advanced Settings

In "Advanced Settings," set the image size and position. Often, photos or screenshots are too big to display in full size on one page and need to be resized: screenshot1.png

The following settings are possible:

  • Position:
    • Wrap text around this item:
      • Left: The image is displayed on the left side of the text, starting at the first line of the current paragraph..
      • Center: The image is shown centered above the current paragraph.
      • Right:The image is shown on the right side of the text, starting at the first line of the current paragraph.
  • Image type: The following example shows an image that is 450 x 252px in size. When you insert an image with VisualEditor, the image is always linked to the full-sized version of the file in the Media Viewer. To suppress the link on an image, you need to add an empty link attribute to the image tag in source code:
    • frameless image with link (standard): [[File:adult-chair-company-380769.jpg|frameless]]
    • frameless image without link:[[File:adult-chair-company-380769.jpg|frameless|link=]] - this is the setting for the frameless image in the table below
Image type Output Description
Example of a thumbnail image
This is the caption.
The thumbnail version shows the image with a default width of 300px. The width can be adjusted as needed.

In addition, the image caption is shown below the image. A magnifying symbol shows that the image can be enlarged.

The frameless version shows the image without a border. The width can be adjusted as needed (here, we set the example to 300px).

The image caption is not shown below the image.

By default, the image is inserted without wrapping around text. It will break a sentence up right where it is inserted. The image by default is displayed centered.

The image size and positioning can, however, be adjusted as needed.

Example: Image type frame
This is the caption
The framed version is similar to a thumbnail image.

In comparison to a thumbnail, it does not show the magnifying glass symbol and is inserted as a full-width image on the page.

To adjust the size, you have to insert the image on the page and then edit it to activate the "Set full width" button.

Basic adult-chair-company-380769.jpg The basic version is like the frameless version.

By default it does not wrap around text, but breaks the text where it is inserted.

The image is inserted in full width, while the frameless image is inserted in thumbnail width (300px). The size can, however, be adjusted.

  • Image size:
    • Default: displays the image at a width of 300px.
    • Custom: allows entering a custom size.
    • Make full size: resets the size to the actual size of the image.

Where do I save the image?

You can easily save pictures and files in the (Main) namespace. If you have created additional namespaces, you can also save images in these namespaces. Prerequisite are the corresponding access rights to the respective namespace. If pictures are to be generally usable and are not subject to access restrictions, pictures are best kept in the main namespace (pages).

How big is my picture?

How big should the image be so that I can use it on a wiki page? The question depends on what should be done with the picture. Often, a picture will be displayed as a thumbnail small on the page first. The picture itself can be viewed in its original size.

If you want to create printable PDF manuals, the images should be uploaded as large as possible. However, it is important to remember that the files will not get too large for your wiki pages to load quickly. Images over 100 KB are rather unusual on a web page, while images under 20 KB are often not sharp enough when printing on paper. If you create documentation with your wiki, which is also printed out as a manual, then you should consider a suitable strategy.

How do I change an already uploaded image?

In the editing mode of the page, it is possible to edit the image with a double-click. Use the "Change image" button to exchange the image accordingly.

If you want to use a new version of the same image, open the "Special: Upload file" page in a new browser tab (so you do not lose any changes on your wiki page). There you can save already existing pictures with or without warning under the same name again. The original image is kept as a version.

Technical Details

BlueSpice extension: BlueSpiceInsertFile