1 #+OPTIONS: H:3 num:nil toc:t \n:nil @:t ::t |:t ^:nil -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
2 #+STARTUP: align fold nodlcheck hidestars oddeven lognotestate
3 #+SEQ_TODO: TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
4 #+TAGS: Write(w) Update(u) Fix(f) Check(c)
5 #+TITLE: Images and XHTML export
6 #+AUTHOR: Sebastian Rose and the Worg people
7 #+EMAIL: sebastian_rose gmx de
9 #+CATEGORY: worg-tutorial
10 #+SETUPFILE: ../macros.setupfile
11 #+MACRO: imageurl /img/org-mode-unicorn.png
14 [[file:../index.org][{Back to Worg's index}]]
18 Images are inserted into an Org file in a fashion similar to links:
20 : [[file:{{{imageurl}}}]]
22 The =file:= prefix is optional, as long as a known image type is used. Org-mode
23 recognizes images by the file name suffix. Recognized suffixes are all the
24 members of =org-export-html-inline-image-extensions= which defaults to the list
25 =("png" "jpeg" "jpg" "gif")=. That said, the images above could as well be
26 included using this link:
31 : [[{{{imageurl}}}][Monocerus glaucus]]
32 exports to a link to the image:
34 <a href="{{{imageurl}}}">Monocerus glaucus</a>
38 For this tutorial, we assume the variable =org-export-html-inline-images= is
39 unchanged from it's standard setting, i.e. =maybe=. Images are shown in the
40 exported page this way. And we will talk about visible images only.
42 Don't be afraid. Most of the text in this little tutorial is just blind text
43 (and in gray color therefor).
45 Read the basics about images in XHTML export in the Org-mode manual,
46 [[http://orgmode.org/manual/Images-in-HTML-export.html#Images-in-HTML-export][Section Images]] (e.g. show a thumbnail, that links to a high resolution image...).
51 Let's simply put an image inside a paragraph like this
53 : Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy nibh
54 : [[[[{{{imageurl}}}]]]]
55 : euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.
57 {{{BeginWarningBox}}} Note, that *empty lines are crucial*. The exporter will
58 start a new paragraph, if you add an empty line before or after the image. You
59 can easily try that yourself, simply by adding an empty line before and/or
60 after the image and export again.{{{EndWarningBox}}}
62 To see the result, export your Org file to HTML (press =C-x C-e b=) and see the
63 results. Note, that the image is displayed just where you placed it.
68 Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy
69 nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi
70 enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis
71 nisl ut aliquip ex ea commodo consequat. Duis autem vel eum iriure dolor in
72 hendrerit in vulputate velit esse molestie consequat, vel illum dolore eu
73 feugiat nulla facilisis at vero et accumsan et iusto odio dignissim qui
74 blandit praesent luptatum zzril delenit augue duis dolore te feugait nulla
75 facilisi.{{{EndBlindText}}}
78 Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy
79 nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi
80 enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis
81 nisl ut aliquip ex ea commodo consequat. Duis autem vel eum iriure dolor in
82 hendrerit in vulputate velit esse molestie consequat, vel illum dolore eu
83 feugiat nulla facilisis at vero et accumsan et iusto odio dignissim qui
84 blandit praesent luptatum zzril delenit augue duis dolore te feugait nulla
85 facilisi.{{{EndBlindText}}}
92 Org-mode allows us to add HTML attributes to the exported image. There are
93 several useful attributes, some of which are mandatory, as the =src= and =alt=
94 attributes. Org-mode adds an empty =alt= attribute for you, if not supplied. You
95 can add additional attributes using a special syntax. E.g. you could change
96 the value of the =alt= attribute this way:
98 : #+ATTR_HTML: alt="My fancy value for the alt attribute."
101 You may add more attributes to an =#+ATTR_HTML:= line. More than one
102 =#+ATTR_HTML:= line is allowed for readability. Example:
104 : #+ATTR_HTML: alt="Zoomed image."
105 : #+ATTR_HTML: width="300" style="border:2px solid black;"
108 A full list of valid attributes can be found on
109 [[http://www.w3schools.com/tags/tag_img.asp]].
114 If you want text to flow around your images, the =style= attribute comes handy.
115 To place the image on the left, and let the text flow around the image on the
116 right, use this code:
118 : #+ATTR_HTML: style="float:left;"
120 Possible values for the =float:= CSS attribute are =left=, =right= and =none= (the
121 default). =left= causes the image to show up on the left of the text succeeding
122 the image, =right= will place the image on the right side of the text succeeding
125 You can control the gap between image and surrounding text, using the =margin:=
126 CSS attribute like so:
128 : #+ATTR_HTML: style="float:left;margin:20px 20px 20px 0px;"
130 The order of the values given, are the distances in the north east south, and
133 Again: *Please avoid empty lines before and after* the image, if you want to
134 achieve the effect shown in this example: one paragraph of text that flows
135 around two images. The exporter adds a =<p>= element for empty lines otherwise.
137 This code shows, how we can add attributes to the =<img ... />= tag in Org-mode:
139 : #+ATTR_HTML: style="float:right;margin:0px 0px 20px 20px;"
141 : Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy
142 : #+ATTR_HTML: style="float:left;margin:20px 20px 20px 0px;"
144 : euismod tincidunt ut laoreet dolore magna aliquam erat volutpat.
147 *Note:* The =#+ATTR_HTML:= line as well as the image definition have to be on a
148 single line respectively. Don't put _any_ additional text on those lines or the
149 attributes will not be added to the image tag on export!
155 #+ATTR_HTML: style="float:right;margin:0px 0px 20px 20px;"
157 This text is directly succeeds the first image, which is right
158 aligned. Because of the alignment, placing the image after the first few
159 lines would make no difference.{{{BeginBlindText}}}
160 Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy
161 nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi
162 enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis
163 nisl ut aliquip ex ea commodo consequat. Duis autem vel eum iriure dolor in
164 hendrerit in vulputate velit esse molestie consequat, vel illum dolore eu
165 feugiat nulla facilisis at vero et accumsan et iusto odio dignissim qui
166 blandit praesent luptatum zzril delenit augue duis dolore te feugait nulla
167 facilisi. Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam
168 nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat
169 volutpat.{{{EndBlindText}}} Text before the second image ends here.<
170 #+ATTR_HTML: style="float:left;margin:20px 20px 20px 0px;"
172 >This text is directly following the second image. No empty lines are added.
173 Neither before, nor after the image. We therefor see one big paragraph with
174 two images. Note, that browsers will place this second image where ever they
175 see fit. Browsers will not interrupt the text flow, just to place the image
176 add the exact point between two words.
177 {{{BeginBlindText}}}Lorem ipsum dolor sit amet,
178 consectetuer adipiscing elit, sed diam nonummy nibh euismod tincidunt ut
179 laoreet dolore magna aliquam erat volutpat. Ut wisi enim ad minim veniam, quis
180 nostrud exerci tation ullamcorper suscipit lobortis nisl ut aliquip ex ea
181 commodo consequat. Duis autem vel eum iriure dolor in hendrerit in vulputate
182 velit esse molestie consequat, vel illum dolore eu feugiat nulla facilisis at
183 vero et accumsan et iusto odio dignissim qui blandit praesent luptatum zzril
184 delenit augue duis dolore te feugait nulla facilisi.{{{EndBlindText}}}
189 ** Deprecated HTML attributes
191 You could use old-style HTML attributes, but those are deprecated:
193 : #+ATTR_HTML: alt="image" hspace="20" vspace="20" align="right"
195 The =vspace= and =hspace= attributes denote the vertical and horizontal gap in
196 pixels between the image and the surrounding text respectively.
200 And here is how to fill the width of your display with images and let the
201 lines break automatically. Just add =display:inline;= to the =style= attributes.
203 : #+ATTR_HTML: style="display:inline;margin:10px;"
205 : #+ATTR_HTML: style="display:inline;margin:10px;"
207 : #+ATTR_HTML: style="display:inline;margin:10px;"
209 : #+ATTR_HTML: style="display:inline;margin:10px;"
216 #+ATTR_HTML: style="display:inline;margin:10px;"
218 #+ATTR_HTML: style="display:inline;margin:10px;"
220 #+ATTR_HTML: style="display:inline;margin:10px;"
222 #+ATTR_HTML: style="display:inline;margin:10px;"
224 #+ATTR_HTML: style="display:inline;margin:10px;"
226 #+ATTR_HTML: style="display:inline;margin:10px;"
228 #+ATTR_HTML: style="display:inline;margin:10px;"
230 #+ATTR_HTML: style="display:inline;margin:10px;"
236 * Images with Captions
238 You might want to attach a caption to your images. You can do so using this
241 : #+CAPTION: Monocerus glaucus
242 : #+ATTR_HTML: alt="Monocerus glaucus"
243 : [[[[{{{imageurl}}}]]]]
246 In this case, empty lines before and after the image make no difference since
247 the exporter ends paragraphs and restarts them below the image.
252 #+CAPTION: Monocerus glaucus
253 #+ATTR_HTML: alt="Monocerus glaucus"
255 {{{BeginBlindText}}}Lorem ipsum dolor sit amet, consectetuer
256 adipiscing elit, sed diam nonummy nibh euismod tincidunt ut laoreet dolore
257 magna aliquam erat volutpat.{{{EndBlindText}}}
261 ** Captions and floating
263 There is no /figure/ element in XHTML and captions are not supported at all. But
264 the exporter wraps the =<img..../>= tag in certain containers to add the caption
269 <p><img src="path/to/img.png" alt="Monocerus glaucus" /></p>
270 <p>Monocerus glaucus</p>
274 To make text flow around your image, you need to adjust the styles for the
275 special HTML elements that wrap images with captions. The exporter puts the
276 default styles in the =<head>= section of your XHTML files. This is, what they
279 : div.figure { padding: 0.5em; }
280 : div.figure p { text-align: center; }
282 To achive the floating, add this to the top of the Org-file:
284 #+COMMENT: no width neccessary, CSS 2.1
286 : #+STYLE: <style type="text/css">
287 : #+STYLE:<!--/*--><![CDATA[/*><!--*/
288 : #+STYLE: div.figure { float:left; }
289 : #+STYLE: /*]]>*/-->
293 The crucial attribute is =float:left;=. Choose =float:right;= to place the images
294 on the right edge of your paragraphs. The styles will apply to _all_ images with
295 captions in your file.
298 *Note (again):* In this case, empty lines before and after the image make no
299 difference since the exporter ends paragraphs and restarts them below the
300 image. This said, a floating image with a caption will always sit on the top
301 left/right of the following paragraph.
309 Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy
310 nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi
311 enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis
312 nisl ut aliquip ex ea commodo consequat.{{{EndBlindText}}} This text
313 directly preceeds the image and ends here.<
315 <div class="figure" style="float:left;">
316 <p><img src="{{{imageurl}}}" alt="image" hspace="20" vspace="20" /></p>
317 <p>Equus Unicorn Viridis</p>
320 >This text directly follows the image. No empty are inserted before or after
321 the image. Note, that a new paragraph has started nonetheless.{{{BeginBlindText}}}
322 Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy
323 nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi
324 enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis
325 nisl ut aliquip ex ea commodo consequat. Duis autem vel eum iriure dolor in
326 hendrerit in vulputate velit esse molestie consequat, vel illum dolore eu
327 feugiat nulla facilisis at vero et accumsan et iusto odio dignissim qui
328 blandit praesent luptatum zzril delenit augue duis dolore te feugait nulla
329 facilisi. Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam
330 nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat
331 volutpat. Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper
332 suscipit lobortis nisl ut aliquip ex ea commodo.
333 Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy
334 nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi
335 enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis
336 nisl ut aliquip ex ea commodo consequat. Duis autem vel eum iriure dolor in
337 hendrerit in vulputate velit esse molestie consequat, vel illum dolore eu
338 feugiat nulla facilisis at vero et accumsan et iusto odio dignissim qui
339 blandit praesent luptatum zzril delenit augue duis dolore te feugait nulla
340 facilisi. Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam
341 nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat
342 volutpat. Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper
343 suscipit lobortis nisl ut aliquip ex ea commodo...{{{EndBlindText}}}
348 *** Problems with captions and float
350 The =float:left;= style causes following blocks to show up on the right of
351 your image. So did the following paragraph in the previous example.
352 Inevitably, this will happen against your will. In that case, put this after
356 : <br style="clear:both;" />
359 Or you could use the less obtrusive syntax:
361 : @<br style="clear:both;" />
366 In addition, =float:left;= changes the alignment of several images with caption
367 in a row. They now fill a row on the display, until the screen width is
368 filled with images. They now behave like simple text.
372 , #+ATTR_HTML: alt="image"
375 , #+ATTR_HTML: alt="image"
378 , #+ATTR_HTML: alt="image"
381 , #+ATTR_HTML: alt="image"
384 , ... etc. - many more ...
389 #+COMMENT: This has to be HTML, because we cannot include the styles into the head section.
390 #+COMMENT: Therefor, this has to be reworked if the output of the exporter changes.
395 <div class="figure" style="float:left;">
396 <p><img src="{{{imageurl}}}" alt="image" /></p>
400 <div class="figure" style="float:left;">
401 <p><img src="{{{imageurl}}}" alt="image" /></p>
405 <div class="figure" style="float:left;">
406 <p><img src="{{{imageurl}}}" alt="image" /></p>
410 <div class="figure" style="float:left;">
411 <p><img src="{{{imageurl}}}" alt="image" /></p>
415 <div class="figure" style="float:left;">
416 <p><img src="{{{imageurl}}}" alt="image" /></p>
420 <div class="figure" style="float:left;">
421 <p><img src="{{{imageurl}}}" alt="image" /></p>
425 <div class="figure" style="float:left;">
426 <p><img src="{{{imageurl}}}" alt="image" /></p>
430 <div class="figure" style="float:left;">
431 <p><img src="{{{imageurl}}}" alt="image" /></p>
434 <br style="clear:both;" />
442 Captions are often printed in italics. To do so, go to the top of your
443 Org-file again, and edit the styles again:
445 : #+STYLE: <style type="text/css">
446 : #+STYLE:<!--/*--><![CDATA[/*><!--*/
447 : #+STYLE: div.figure p { font-style:italic; }
448 : #+STYLE: /*]]>*/-->
454 <div class="figure" style="float:right;">
455 <p><img src="{{{imageurl}}}" alt="Save the unicorns" /></p>
456 <p style="font-style:italic;">Save the unicorns</p>
460 Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy
461 nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi
462 enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis
463 nisl ut aliquip ex ea commodo consequat. Duis autem vel eum iriure dolor in
464 hendrerit in vulputate velit esse molestie consequat, vel illum dolore eu
465 feugiat nulla facilisis at vero et accumsan et iusto odio dignissim qui
466 blandit praesent luptatum zzril delenit augue duis dolore te feugait nulla
467 facilisi. Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam
468 nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat
469 volutpat. Ut wisi enim ad minim veniam, quis nostrud exerci tation ullamcorper
470 suscipit lobortis nisl ut aliquip ex ea commodo.
471 Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy
472 nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi
473 enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis
474 nisl ut aliquip ex ea commodo consequat. Duis autem vel eum iriure dolor in
475 hendrerit in vulputate velit esse molestie consequat, vel illum dolore eu
476 feugiat nulla facilisis at vero et accumsan et iusto odio dignissim qui
477 blandit praesent luptatum zzril delenit augue duis dolore te feugait nulla
478 facilisi. Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam
479 nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat
481 Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam nonummy
482 nibh euismod tincidunt ut laoreet dolore magna aliquam erat volutpat. Ut wisi
483 enim ad minim veniam, quis nostrud exerci tation ullamcorper suscipit lobortis
484 nisl ut aliquip ex ea commodo consequat. Duis autem vel eum iriure dolor in
485 hendrerit in vulputate velit esse molestie consequat, vel illum dolore eu
486 feugiat nulla facilisis at vero et accumsan et iusto odio dignissim qui
487 blandit praesent luptatum zzril delenit augue duis dolore te feugait nulla
488 facilisi. Lorem ipsum dolor sit amet, consectetuer adipiscing elit, sed diam
489 nonummy nibh euismod tincidunt ut laoreet dolore magna aliquam erat
490 volutpat.{{{EndBlindText}}}
495 ** Final captions example
497 Here is a last weird example of what styles can do for you. Let's put the
498 caption to the right of an image.
500 : #+STYLE: <style type="text/css">
501 : #+STYLE:<!--/*--><![CDATA[/*><!--*/
502 : #+STYLE: div.figure {
503 : #+STYLE: width:235px; /* ensure the same width for each. */
504 : #+STYLE: float:left;
505 : #+STYLE: margin:5px;
507 : #+STYLE: div.figure p {
508 : #+STYLE: display:inline;
509 : #+STYLE: font-style:italic;
511 : #+STYLE: /*]]>*/-->
518 <div class="figure" style="width:235px;float:left;margin:5px;">
519 <p style="display:inline;"><img src="{{{imageurl}}}" alt="image" style="vertical-align:middle;" /></p>
520 <p style="display:inline;font-style:italic;">Michael</p>
523 <div class="figure" style="width:235px;float:left;margin:5px;">
524 <p style="display:inline;"><img src="{{{imageurl}}}" alt="image" style="vertical-align:middle;" /></p>
525 <p style="display:inline;font-style:italic;">Steve</p>
528 <div class="figure" style="width:235px;float:left;margin:5px;">
529 <p style="display:inline;"><img src="{{{imageurl}}}" alt="image" style="vertical-align:middle;" /></p>
530 <p style="display:inline;font-style:italic;">Carla</p>
532 <br style="clear:both;" />
533 <div class="figure" style="width:235px;float:left;margin:5px;">
534 <p style="display:inline;"><img src="{{{imageurl}}}" alt="image" style="vertical-align:middle;" /></p>
535 <p style="display:inline;font-style:italic;">Pete</p>
538 <div class="figure" style="width:235px;float:left;margin:5px;">
539 <p style="display:inline;"><img src="{{{imageurl}}}" alt="image" style="vertical-align:middle;" /></p>
540 <p style="display:inline;font-style:italic;">Paul</p>
544 If the sum of three =div.figure='s widths and margins were so wide, that three
545 Monoceri wouldn't fit in one row, this text would start on the very top of
548 Let's add another little paragraph here, to show how =float= works. How to get
550 =@= =<br style=="=clear:both=;" =/>=
552 @<br style="clear:both;" />
554 ...did the trick. It's advisable, to add this after the third image
555 above since the first paragraph starts with very short words.
562 1. Images are referenced using Org-mode's link syntax.
563 2. As for simple links, the =file:= prefix is optional, as long as the suffix is
564 a member of =org-export-html-inline-image-extensions=.
565 3. We can add HTML attributes to images
566 - using =#+ATTR_HTML:=
567 - Both, the =#+ATTR_HTML:= line and the image have to be on their own line.
568 4. We prefer the =style= attribute to align images. The most important CSS
569 attributes are =float:= and =margin:=.
570 5. We can add a caption to images, even though (X)HTML doesn't support
571 this. We use the special =#+CAPTION:= line to supply a caption. This has to
572 be on a single line, too.
573 6. The exporter wraps the image and the caption into a =<div class=="=figure">= and
574 two =<p>= elements. The first =<p>= element contains our image, the second one
576 7. By adding special styles for those elements to the top of our Org-file
577 (=#+STYLE:=), we can align images with captions, too.
578 8. Styles added for images with captions apply to all images with captions in