doc:inserting_images [Knowledge Commons]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
//part of the [[start|GtC documentation]]//

====== Inserting images and videos ======

//Try out all these techniques below in the [[playground:playground]].//

----

===== Inserting images =====

Both DokuWiki and Markdown syntax work for images. The first step is to **know where the image is** that you want to display. For external images (on the web), it could be something like `https://www.growingthecommons.org/images/screen_wiki_hu_d50df2aeb9adf2de.webp`, which happens to be the location of one of the images on the [[https://www.growingthecommons.org|Growing the Commons landing page]]:

{{https://www.growingthecommons.org/images/screen_wiki_hu_d50df2aeb9adf2de.webp?350}}

For internal images in DokuWiki, "where it is" includes the [[namespace]], or just `:` if there is no namespace.
So the location, or address, of 

{{wisw:wild_swimming.jpg?200}}

is `wisw:wild_swimming.jpg`, written out, with [[#sizing|sizing]], as `{{wisw:wild_swimming.jpg?200}}`.
The the namespace is `wisw` and the file name is `wild_swimming.jpg`, connected by a `:`. You need both to locate the image, except if you are working in the same namespace. If you are on the [[wisw:wild swimming]] topic page, you can just refer to the image as `wild_swimming.jpg`.

You can find all the existing internal images, with their correct addresses, through the Media Manager, in the {{spanner-icon.png|this is an illustration, don't click here!}} spanner icon menu, top right.

==== DokuWiki syntax ====

The most basic way of displaying an image on DokuWiki is to enclose the address of the image in double braces, with no extra spaces inside the braces, like this: `{{:favicon.ico}}`, which gives you {{:favicon.ico}}; or `{{https://licensebuttons.net/l/by-sa/4.0/88x31.png}}`, which gives {{https://licensebuttons.net/l/by-sa/4.0/88x31.png}} — both inline.

Many images are too large to display inline, and you probably want them in a separate paragraph:
`{{:logo_wide_rounded.png}}` (on a line by itself) gives

{{:logo_wide_rounded.png}}

To get it in the middle, you would put spaces inside the `{{ ` and ` }}` like `{{ :logo_wide_rounded.png }}`

==== Markdown syntax ====

In Markdown, the equivalents are `![](:favicon.ico)` ![](:favicon.ico)
`![](https://licensebuttons.net/l/by-sa/4.0/88x31.png)` ![](https://licensebuttons.net/l/by-sa/4.0/88x31.png)
and `![](:logo_wide_rounded.png)`

![](:logo_wide_rounded.png)

----

==== Sizing ====

So, it's the wrong size for you? You add a number for the width (in pixels) that you want, after the address.
Height is adjusted in proportion.

Using the above examples: `{{:favicon.ico?100}}` is {{:favicon.ico?100}} and `{{:logo_wide_rounded.png?200}}` is {{:logo_wide_rounded.png?200}}

Similarly, in Markdown, `![](:favicon.ico?100)` is ![](:favicon.ico?100) and `![](:logo_wide_rounded.png?200)`is ![](:logo_wide_rounded.png?200) though curiously, the text splits after each actual image.

==== Text associated with an image ====

If you want specific text to appear when a reader hovers over your image, you do it like this:

* DokuWiki, after the `|` character: `{{:favicon.ico|This is the 'favicon' used for the site: DokuWiki}}`
* Markdown, between the square brackets:  `![This is the 'favicon' used for the site: Markdown](:favicon.ico)`

which give you these (hover over the images to see the text):

{{:favicon.ico|This is the 'favicon' used for the site: DokuWiki}} and ![This is the 'favicon' used for the site: Markdown](:favicon.ico)

==== Image alignment ====

{{icon-menu-for-browsing.png }}There are 4 options for image (or video) alignment.{{ icon-menu-for-editing.png}}
  - With no alignment, as above, the image appears in line with the text either side it.
  - For left alignment, you leave a space between the filename and the closing `}}`, like `{{icon-menu-for-browsing.png }}`. The image is on the left, and if its height is more than one line of text, the text continues line after line with the image staying on the left.
  - With middle alignment, the image is put on a line by itself, but in the middle. You put spaces on either side, like `{{ :favicon.ico }}`
  - Right alignment is just the opposite of left alignment, like `{{ icon-menu-for-editing.png}}`.

{{ :favicon.ico }} The last three are demonstrated just above. Hover the images above to see which one is which. You will also see the effects if you try the toolbar approach, which now follows.


----

===== Inserting images with the toolbar =====

This allows you to choose simple options without needing to remember how to code them as above.
While you are editing a page, clicking on the image icon on the toolbar {{image-icon.png|this is an illustration: don't click here!}} brings up a pop-up window. First find the image you want.

When you click on the name of the file you want you get a pop-up, to choose how to display it, in terms of link, alignment and size. It's called "Link settings" but really it means "Image settings"! Here's what that pop-up looks like, and what it means. If you hover over the different options (in the real one, not this illustration!) it explains some of what each one means. The table here elaborates a little.

{{ :doc:link-settings-box.png?nolink |this is just illustration, for info try the real thing!}}

^ Link Target | Link to detail page | Direct link to original | No Link | Show only the link, not the image |
^ Alignment | No align (text runs on) | Left align (to the left of ongoing text) | Middle (and text goes below) | Right align (to the right of ongoing text) |
^ Image size | Small (200px wide) | Medium (400px wide) | Large (600px wide) | Original size |

Try them out here: I've inserted the link target images with their own "link target", all with no align and original size.
  * {{:doc:link-detail-icon.png|}}"Link to detail page" means that if you click on the image, it will take you to the page in DokuWiki that gives details about the image.
  * {{:doc:direct-link-icon.png?direct|}}"Direct link to original" is useful when you want to display a small version of a large graphic, so if a reader clicks on it it goes straight to the full size version of the image. A better example might be {{:doc:2024-09-24_18-39-24.png?direct&40|}}
  * {{:doc:no-link-icon.png?nolink|}}"No link" means what it says: clicking on the image does nothing.
  * {{:doc:only-link-icon.png?nolink|}}"Show only the link" will give the link as text, {{:doc:only-link-icon.png?linkonly|}} and if you click on the text you will go to the image.

So, say you choose, by clicking on: Direct link to original; No align; Medium. The click on "Insert". You get something like this (I've just uploaded a random image):

`{{:doc:2024-09-24_18-39-24.png?direct&400|}}` which is displayed as

{{:doc:2024-09-24_18-39-24.png?direct&400|}}

As this is a DokuWiki function, this gives you an image in DokuWiki syntax.
Feel free to explore other options yourself. 

Ask us, if you would like to be shown around this tool.

----

===== Basics for inserting videos =====

Inserting videos is not very simple. We struggled a bit before getting the hang of it.\\ Please ask for help! 
For more information around this subject, try [[wiki:syntax]] and [[WRAP]].

==== Using the toolbar ====
There is an button icon on the right of the editing toolbar for videos: {{video-icon.png|this is an illustration: don't click here!}}:
click on that, and a pop-up asks you to put in the full URL of the video you want.

Trying that now with `https://www.youtube.com/watch?v=Qr5Q3VvpI7w` gives the code
`{{youtube>Qr5Q3VvpI7w?}}`: that's clearly special treatment for YouTube. The video appears as

{{youtube>Qr5Q3VvpI7w?}}

Similarly, `https://www.youtube.com/watch?v=lLYt1zlqUtE` gives you `{{youtube>lLYt1zlqUtE?}}` default size,

{{youtube>lLYt1zlqUtE?}}

==== DokuWiki syntax ====

There are other more complex ways of embedding videos. If you want control over the size, you can write something like this:\\
`{{url>https://www.youtube.com/embed/lLYt1zlqUtE 560,315}}`

which gives you the slightly larger, left-aligned

{{url>https://www.youtube.com/embed/lLYt1zlqUtE 560,315}}

If you want other alignments (e.g. centering) you can use [[WRAP]].

----

===== Further information =====

For more, see the more complete [[wiki:syntax]] page, and the [[WRAP]] function.

----