Inhaltsverzeichnis

Image sizes
Embedding images
Images with closely associated text
Images with graphic markings
- Circled numbers lists
- "Live editing" images on Zendiwiki pages

Zendiwiki: Manual of Style: Images in User Guides

This guide explains how to insert images into Zendiwiki guides in a uniform and consistent manner. It is recommended to follow these rules, especially for content in the guides namespace.

Image sizes

Embedding images

Images can be embedded in DokuWiki text as other media. For details see Image and Media Handling on the DokuWiki website. Images used in Zendiwiki articles should not normally be right or left aligned (see Zendiwiki: Manual of Style § Images). Reasonable exceptions are, of course, fine.

Floating text around images is not recommended. Try it with the example right below: Pull your browser window narrower. Do it in small steps to observe the unsightly effects in the example here:

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Consequat mauris nunc congue nisi vitae suscipit tellus mauris a. Morbi tempus iaculis urna id volutpat lacus laoreet non curabitur. Mi eget mauris pharetra et ultrices neque ornare. Tellus id interdum velit laoreet. Quis eleifend quam adipiscing vitae proin sagittis nisl rhoncus mattis. Lorem mollis aliquam ut porttitor. Proin nibh nisl condimentum id venenatis a condimentum vitae. Felis imperdiet proin fermentum leo. Semper quis lectus nulla at volutpat diam ut venenatis. Et ligula ullamcorper malesuada proin libero nunc consequat interdum. Vitae nunc sed velit dignissim sodales. Natoque penatibus et magnis dis parturient. Massa placerat duis ultricies lacus sed turpis tincidunt id aliquet. Non enim praesent elementum facilisis leo vel. Adipiscing vitae proin sagittis nisl. Nisi scelerisque eu ultrices vitae auctor eu augue ut.

So do not use the DokuWiki syntax for left or right alignment of images: whitespaces on the left or the right side of the image markup. Don't do this:

{{ my-image.png}}
{{my-image.png }}

What you can or should do:

{{my-image.png}}
{{ my-image.png }}

(First line: no whitespaces, image left bound without floating text. Second line: whitespaces on both sides, image centered.)

Images with closely associated text

Printed instruction manuals and handbooks often contain(ed) images with text annotations or graphic markings. For a while, one could have the impression that such visualizations in manuals stood as the silver bullet for easy understanding. This has tended to change with modern media – therefore the contain(ed) –, as increasingly smartphones and tablets in portrait format and with narrower screens determine reading behaviour.

With the Zendiwiki we try to find a middle way. We have implemented a solution to on the one hand bind a text block closely to an image, on the other hand the display is responsive, i.e. it can be displayed on wide as well as on narrow screens. The solution includes a customized technical component (an extension of the WRAP plugin) in conjunction with a design proposal and other DokuWiki plugins.

One of the main goals is to make it as easy as possible for authors to use. That is why exactly four image sizes are supported for text block mapping: Images with a width of 360, 540, 720 and 1080 pixels.

Medium sized images (width 540 pixels)

Example with caption:

(Change the size of the browser window, especially towards portrait.)

First item bullet list.
Second item bullet list.
Third item bullet list.

DokuWiki Syntax using <WRAP labeled-image-medium>:

<WRAP labeled-image-medium>

<figure>

{{waterfall-540.png}}

<caption>This text is the caption [...] </caption>

</figure>

<WRAP>

Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
[...]
facilisis leo vel. Adipiscing vitae proin sagittis nisl.
Nisi scelerisque eu ultrices vitae auctor eu augue ut.

  * First item bullet list.
  * Second item bullet list.
  * Third item bullet list.

Lorem ipsum dolor sit amet, [...]

</WRAP>
</WRAP>

Example without caption:

(Change the size of the browser window, especially towards portrait.)

First item bullet list.
Second item bullet list.
Third item bullet list.

Dokuwiki syntax even simpler without caption:

<WRAP labeled-image-medium>

{{waterfall-540.jpg}}

<WRAP>

Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
[...]
facilisis leo vel. Adipiscing vitae proin sagittis nisl.
Nisi scelerisque eu ultrices vitae auctor eu augue ut.

  * First item bullet list.
  * Second item bullet list.
  * Third item bullet list.

Lorem ipsum dolor sit amet, [...]

</WRAP>
</WRAP>

Small images (width 360 pixels)

Example: Small image with much text

(Change the size of the browser window, especially towards portrait.)

First item bullet list.
Second item bullet list.
Third item bullet list.

First item of the list.
Second item of the list.
Third item of the list.

Example: Small image with little text

(Change the size of the browser window, especially towards portrait.)

Lorem ipsum dolor sit amet.

First item of the list. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Consequat mauris nunc congue nisi vitae suscipit tellus mauris a. Morbi tempus iaculis urna id volutpat lacus laoreet non curabitur. Mi eget mauris pharetra et ultrices neque ornare. Tellus id interdum velit laoreet. Quis eleifend quam adipiscing vitae proin sagittis nisl rhoncus mattis. Lorem mollis aliquam ut porttitor. Proin nibh nisl condimentum id venenatis a condimentum vitae.
Second item of the list.
Third item of the list.

DokuWiki Syntax using <WRAP labeled-image-small>:

<WRAP labeled-image-small>

{{waterfall-360.png}}

<WRAP>

Lorem ipsum dolor sit amet.

  - First item of the list. [...]
  - Second item of the list.
  - Third item of the list.

</WRAP>
</WRAP>

Large sized images (width 720 pixels)

Example:

(Change the size of the browser window, especially towards portrait.)

First item bullet list.
Second item bullet list.
Third item bullet list.

DokuWiki Syntax using <WRAP labeled-image-large>:

<WRAP labeled-image-large>

<figure>

{{waterfall-540.png}}

<caption>This text is the caption [...] </caption>

</figure>

<WRAP>

Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
[...]
facilisis leo vel. Adipiscing vitae proin sagittis nisl.
Nisi scelerisque eu ultrices vitae auctor eu augue ut.

  * First item bullet list.
  * Second item bullet list.
  * Third item bullet list.

Lorem ipsum dolor sit amet, [...]

</WRAP>
</WRAP>

The above example uses an image with a medium size (540 pixels wide). The special syntax „labeled-image-…“ will only scale the image to the correct size if it is larger. If the image is smaller, you can stretch it using DokuWiki's default image resizing markup, as in the following example.

Example: Image stretched with DokuWiki markup

(Change the size of the browser window, especially towards portrait.)

First item bullet list.
Second item bullet list.
Third item bullet list.

DokuWiki Syntax for a proportionally stretched image "{{image.png?720}}":

<WRAP labeled-image-large>

<figure>

{{waterfall-540.png?720}}

<caption>This text is the caption [...] </caption>

</figure>

<WRAP>

Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
[...]
facilisis leo vel. Adipiscing vitae proin sagittis nisl.
Nisi scelerisque eu ultrices vitae auctor eu augue ut.

  * First item bullet list.
  * Second item bullet list.
  * Third item bullet list.

Lorem ipsum dolor sit amet, [...]

</WRAP>
</WRAP>

Images with full width (1080 pixels)

Example:

(Change the size of the browser window, especially towards portrait.)

First item bullet list.
Second item bullet list.
Third item bullet list.

DokuWiki Syntax using <WRAP labeled-image-full>:

<WRAP labeled-image-full>

<figure>

{{waterfall-540.png}}

<caption>This text is the caption [...] </caption>

</figure>

<WRAP>

Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
[...]
facilisis leo vel. Adipiscing vitae proin sagittis nisl.
Nisi scelerisque eu ultrices vitae auctor eu augue ut.

  * First item bullet list.
  * Second item bullet list.
  * Third item bullet list.

Lorem ipsum dolor sit amet, [...]

</WRAP>
</WRAP>

Example: Image stretched with DokuWiki markup

(Change the size of the browser window, especially towards portrait.)

First item bullet list.
Second item bullet list.
Third item bullet list.

DokuWiki Syntax for a proportionally stretched image "{{image.png?1080}}":

<WRAP labeled-image-large>

<figure>

{{waterfall-540.png?1080}}

<caption>This text is the caption [...] </caption>

</figure>

<WRAP>

Lorem ipsum dolor sit amet, consectetur adipiscing elit,
sed do eiusmod tempor incididunt ut labore et dolore
[...]
facilisis leo vel. Adipiscing vitae proin sagittis nisl.
Nisi scelerisque eu ultrices vitae auctor eu augue ut.

  * First item bullet list.
  * Second item bullet list.
  * Third item bullet list.

Lorem ipsum dolor sit amet, [...]

</WRAP>
</WRAP>

Images with graphic markings

To describe the content of an image, it can be helpful to place markers directly in the image. There are two ways to achieve this:

Outside of Zendiwiki, before uploading: Add markers directly to the image file using image editing software.
Directly on Zendiwiki pages: Use the draw.io plugin for „live editing“ on the page.

Since the first option depends on your individual image processing and preferred tools, it is not covered here.

Circled numbers lists

Zendiwiki provides a custom wrap plugin snippet to facilitate number markers in images: The circled number list. The plugin replaces the simple numbers in a numbered list with circled numbers. This makes it easier to reference corresponding markers on an image.

Example:

Wake up.
Drink coffee.
Get up
Drink more coffee.
Go to work.
Drink another coffee.

Custom DokuWiki Syntax using <WRAP circled-numbers-list>:

<WRAP circled-numbers-list>
  - Wake up.
  - Drink coffee.
  - Get up
  - Drink more coffee.
  - Go to work.
  - Drink another coffee.
</WRAP>

"Live editing" images on Zendiwiki pages

On Zendiwiki pages images with an edit option can be embedded. This is done with the following steps.

Step 1: Insert a markup snippet like the following at the point where the image is located on the page:

{{drawio>my-image.png}}

The image type must be png.

After saving the wiki page, the following clickable image is depicted:

Break it down:

drawio> creates an editable image on the Zendiwiki page.
my_image.png is the name of the PNG image to be created (not yet existing).

Step 2: Paste the image file into the editor and edit it.

If there are no very special design requirements for the wiki page, then the recommendation is to use the following markups, if necessary in a slightly modified or adapted form.

en:zendiwiki:manual-of-style:zendiwiki-drawio-custom-shape-library.png

An easy way to use these markers is to import them into your draw.io scratchpad. The shapes are included in this import file: https://zendi.ph-weingarten.de/zendiwiki-drawio-image-markers.xml

Example:

en:zendiwiki:manual-of-style:waterfall-540-editable.png

Lorem ipsum dolor sit amet.

First item of the list.
Second item of the list.
Third item of the list.

DokuWiki Syntax:

<WRAP labeled-image-medium>

{{drawio>waterfall-540-editable.png}}

<WRAP>

Lorem ipsum dolor sit amet.

<WRAP circled-numbers-list>

  - First item of the list. 
  - Second item of the list.
  - Third item of the list.

</WRAP>
</WRAP>
</WRAP>

— Initial author: M. Schäfer 2022/10/25