Hey!

I remember a LONG time ago trying to decide between using figure and image for this very reason. The disadvantage of image, is that an image can't have any "text" beneath it. Specifically, with figure, the indented text beneath it becomes the "caption" under the image. The caption at symfony.com isn't particularly well formatted, but that's the idea (you can see in the image below how it looks with the default sphinx theme).

I'm not sure either how this might end up looking when we render it in the PDF - it might have no effect at all, I just don't know! What do you think about making the image itself a bit smaller?

.

Oh, wow, I really missed that caption. They should be styled better in the documentation. Now it looks like the caption is just the normal content, which leads to mixed semantics and a less readable docs. It looks the same (no style) inside the PDF. A simple margin like .figure .caption{ margin: 0 20px; } makes a great difference.

It seems that images are scaled down automatic in PDF (see image below). Scaling down the images themselves is a lot better, if it is done with the right tool. It will decrease page load time (a little bit) and it solves the confusing how it works in the PDF.

It is maybe an idea to put something like this inside the symfony.com stylesheet, to make sure images aren't wider than the content:

.box_article img{
    max-width:100%;
}

@wouterj +1 for making the image just a little bit smaller to fit on the page naturally, at its full width Do you want to do that? And about the CSS, can you open another issue on that - then I'll tag it with website so that Fabien knows to look for it.

Thanks!

@weaverryan I will create a new issue for the CSS and when I get some better image editor than Paint, I will resize the image.

@weaverryan I have created an issue (#2034) and updated this PR to only resize the image, it should be ready to merge now.

Awesome all around! The captions look much much better now on the site (... needs a force-refresh to see them)