diff --git a/doc/bugs/img_vs_align.mdwn b/doc/bugs/img_vs_align.mdwn
deleted file mode 100644
index dcb9129b9..000000000
--- a/doc/bugs/img_vs_align.mdwn
+++ /dev/null
@@ -1,11 +0,0 @@
-The *[[ikiwiki/directive/img]]* directive allows for specifying an
-*align* parameter -- which is of limited usability as the image is
-embedded as `<p><img ...></p>`.  That's at least what I see on
-<http://www.bddebian.com:8888/~hurd-web/hurd/status/>.  On the other
-hand, CSS is supposed to be used instead, I guess.  (But how...  I forgot
-almost of my CSS foo again ;-) it seems.) --[[tschwinge]]
-
-> [[!img logo/ikiwiki.png align=right]]The [img tag doesn't create P tags](http://git.ikiwiki.info/?p=ikiwiki;a=blob;f=IkiWiki/Plugin/img.pm;h=32023fa97af8ba8e63192cacaff10a4677d20654;hb=HEAD), but if you have surrounded the img directive with newlines, they will result in paragraph tags.
->
-> I've edited the URL you provided to demonstrate this -- hope you don't mind! I've also added an inline, right-aligned image to this page.[[!tag done]]
-> -- [[Jon]]
diff --git a/doc/ikiwiki/directive/img.mdwn b/doc/ikiwiki/directive/img.mdwn
index 94cc754bd..b847aa239 100644
--- a/doc/ikiwiki/directive/img.mdwn
+++ b/doc/ikiwiki/directive/img.mdwn
@@ -22,6 +22,12 @@ You can also pass `alt`, `title`, `class`, `align` and `id` parameters.
 These are passed through unchanged to the html img tag. If you include a
 `caption` parameter, the caption will be displayed centered beneath the image.
 
+Note that for the `align` parameter to work, you have to make sure that the
+`img` directive isn't surrounded with newlines, as the [[Markdown]] renderer
+would otherwise put the image into its own paragraph, inhibiting this
+functionality from working.  On the other hand, CSS should probably rather be
+used instead.
+
 The `link` parameter is used to control whether the scaled image links
 to the full size version. By default it does; set "link=somepage" to link
 to another page instead, or "link=no" to disable the link, or