Markdown: a simple method for scaling images

DEVONthink Tips
1

The following construct allows to scale an image in a Markdown document, while still using the original Markdown image command. No further css is needed. It turns out that a critical element is the empty line between the div statement and the image command (that’s why I missed this a long time ago). Use margin: auto; to center the image horizontally, without that it will be left aligned. This is to my knowledge the easiest, least intrusive way of achieving this with minimal HTML cluttering up the markdown.

<div style="width:20%; margin: auto;">

![A caption goes here](x-devonthink-item://9204B0C4-3CA5-4975-BFAE-F401533AEDA9) 
</div>

If you associate a css sheet with Markdown in DT, you can further fine tune the global appearance of figures by customizing the figure environment, e.g to have the caption in somewhat smaller font and e.g. italics, set the background color, add a frame.

This hack depends sensitively on the ability to use md commands inside a HTML environment, so it’s potentially fragile. It could stop working with a future update of the md engine.

Important: No one is forced to use this. I have a good case for myself, and I figured (pun intended) that it would be worth sharing with those that also see some value in scaling and centering images in md.

Note: This writeup replaces the original method, that was much more cumbersome. Some of the discussion below refer to that old version.

2

Why not use CSS in an external stylesheet for that? It would keep the md document a lot cleaner.

I just noticed your usage of 10pt for font size. I’d discourage that: Absolute sizes for anything (except maybe one pixel borders) are not a good idea in these times of widely varying display sizes. Something like 0.9em (or any relative unit) would be a lot more flexible.

And: If you want a figure in HTML, use a figure element. It is there for exactly this case, and brings its own capture child. More semantics, better accessibility. And why use display:table for a div if you introduce your caption with a br anyway?

3

I really prefer & suggest this approach too. Adding HTML or CSS code basically kills the primary advantage (being human-readable like plain text) of Markdown documents. Call me an old-fashioned purist :slight_smile:

1 Like
4

Thanks, @chrillek and @cgrunenberg for the feedback. I wholeheartedly agree that the bulky html block for the scaled images is annoying. But in order to fine-tune the environment for each figure, all the parameters would have to show up there, and can’t be in a css file. Having said that, in most cases the user probably only wants to adjust the width, and maybe the left/center/right alignment on a per-image basis. Everything else should probably go into a css, as you suggest.

use a figure element.

@chrillek: Well, that would have worked if I had not been stuck in HTML3 world. I didn’t know about the figure environment in HTML5. I now also realize that it is this very figure environment that shapes the appearance of the Markdown image environment. That explains a lot. I was wondering what css elements I would have to manipulate to e.g. format the caption. And all your other remarks about my html code are of course true. I’m essentially hacking this stuff by throwing things together, playing with it until it works, and then I stop :frowning: . And then hope for forum feedback to make improvements. Standing on the shoulders of DT giants.

Looking into all this again this morning, I suddenly found a method that allows to scale md images (and format other aspects) with leaving the md image command intact! In fact, I had tried this a long time ago and it did not work, and it turns out a single extra linefeed makes the difference. I’ll post that later today.

One question about putting things in a css file: Of course, any formatting that can be punted into a css-file should be, to keep the md clean. The natural place would be the css template that can be specified in the DT prefs. However, to my knowledge this template is not available in DTTG, so to me this path is a no-go. I only see two other paths:

  1. The css sits at a publicly available URL; this will not work in offline mode.
  2. The css is located at as file in DT and is referenced on the first line of the md file as css:x-devonthink-item://04126D5E..., which mucks up the md source right at the top, but otherwise works reliably on DTTG as well.

The best solution would be to add the ability to specify a css template in DTTG. We need to convince Eric.

5

Wow. Did you fall down a wormhole? HTML 3 – what kind of environment is that? This version appeared in 1997 and was superseeded in the same year by HTML 4. Which also went out of fashion about 10 years ago.

Do you think that that’s necessary? I’d understand the requirement if you were publishing art books, for example. Otherwise, I do not think that it’s even a good idea to “fine tune” the style for every figure. Readers like consistency (I suppose). I’d go for a maximum of three widths (and leave the rest of the parameters the same for all figures): 98% of the container’s width (to allow for some white space left and right), 48% of the container’s width to allow for two images side by side, and 48% of the container’s width to allow for an image to the left of the text (i.e. the text flows “around” it at its right side). Of course, if you’re using a 3- or 4-column layout (are you?), 1, 2, 3, and 4 column wide images would perhaps be needed.

Even if the idea of having special styles for every image were more appealing, it has one important disadvantage: You have to change every single image definition if you (for example) want them to be 30% or 50% wide. That’s a bit like foregoing “styles” (is that the term?) in Word - if you decide that your second level heading has to be 14 instead of 16 points, you’d have to change every single one of them by hand. Instead of changing the style.

But: What are we really talking about here: A high-end web site that has to be mega attractive to millions of people – or rendering some technical stuff as fast possible, sufficiently “nice” and in a way that conveys the information as well as possible? The less special cases you take into account, the easier the task is becoming. And if it’s only you and some colleagues who’ll ever be looking at your rendered MD … maybe less is more.

I think so, too. However, this approach has one drawback: The global CSS overwrites all styles predefined by DT. So a global stylesheet has to provide for everything. I find that a bit disappointing. And then there’s of course

which means that

or @aedwards?

6

I’m with @chrillek on this… unless there’s some particular requirement for formatting and presentation, why not settle on a comfortable middle ground of “That’s pretty good” that applies to all images?

And while I’m less of a Markdown purist like @cgrunenberg or @chrillek since I do a ton of tinkering, I do agree that including raw HTML in Markdown should be much more limited than what you’re proposing. However, “different strokes”, yeah? (And not the dreadful TV show I used to watch )

index
:stuck_out_tongue:

7

Well, I’m a subatomic physicist for my day job, and I wield whatever computer stuff is necessary. Typically as far as I need to get the job done, but not further, as my to-do list is already too long. For my own research webpage, I’ve had for 15 years now an instance of PmWiki, so no html involved there. Other than that, I fiddle with html for things like fudging the appearance of Markdown documents :slight_smile: Using <b>, <em>, <img>, and <h1,2,3> goes a long way. Today I added <figure> to my repertoire, and I’m also stoked about <details> and <summary>!

As I wrote in my previous post: no it’s not. As you suggest, I only use the md docs as internal working documents, so they need to be utilitarian in the first place, but when they are too rough, it bugs me. So I put a bit of work in.

Currently (and that’s where my burst of activity on Markdown is coming from) I’m making a growing number of flashcards for my DT-internal spaced repetition practice system. Someone on this forum had mentioned how one can use <details> and <summary> to make nice cards where you expand the answer. That together with LaTeX formulae and nice images makes for excellent cards written in markdown. I like those cards to look nice when I go through them. So yes, I spend a bit of effort on formatting.

8

I’ve now redone the original post, and describe what I believe must be the simplest possible way to effect scaling and alignment of a markdown image.

9

Perhaps a MD template for that would be helpful? It could also contain a style element at its top that defines different styles for these flashcards (if that is desired). It could also predefine the details and summary sections (less typing when filling in the flashcards).

1 Like
10

Yes, I made a template to quickly make a new card, and put it in the DT template folder.

11

Note this useful trick:

< img src=“x-devonthink-item://40C41285-D0D3-484C-9946-AB2BF53B031E” width=“500” style=“float:right”>

width=“xxxx” … sets the size with xxxx pixels
style=“float:yyyy” … sets the float as “center, right, left” … cent is text above and below, right text is left of image, left text is right of image.

12

There’s no center value for float. And float itself comes with some inherent problems.
Also, img dimensions should be set in CSS, modern browsers use the width and height attributes to determine the aspect ratio.

13

Ok - then show the examples.

14

I’m not going to repeat myself here. There’s no point in hijacking old threats, nor in posting the same stuff twice.

1 Like
16

Me thinks this should be easier, actually

17

Markdown is what it is. It was conceived to to make producing HTML easier.

You can use CSS to scale images and generally determine the visual appearance.

1 Like
18

We are dealing here with heavily extended Markdown (which one could call MultiMarkdown, which is however a specific implementation by Fletcher Penney), not John Gruber’s original use case. These extensions have been morphing continually over time. Within this context, it is wrong to state that “it is what it is”. If the community wants something it’s apparently being added. Why the desire for image attributes is so strongly contested here, I do not understand. There is a huge gap between wanting simple image scaling and alignment and “hey, if you need perfection, write it in LaTeX”.

In fact, Fletcher Penney makes my case:

Obviously, images are handled just fine by Markdown (with the exception of attributes as noted above.) However, without some more information, images are not easily translated into other document formats (e.g. PDF).

To handle this, my XSLT files will make use of <img> dimensions (e.g. height and width). If present, the image will be scaled. If only one dimension is specified, the image will be scaled proportionately. If neither height nor width is specified, then the image will be scaled such that its width is the same as a column of text. This is to prevent high resolution images from overflowing the page. Unfortunately, it has the side effect of “zooming” in on smaller images. So, if you have images that are being scaled in a way that you do not desire, simply specify at least one dimension.

Note in particular the issue of scaling small images to full width.

As such Mmd V6 allows image (and link) attributes inline. And some of it actually works in the Markdown system implemented in DT (seemingly not all, but I have not really played much with testing out attributes other than width), for now:

This image ![Alt text](https://math.ucr.edu/home/baez/ecological/fox_white.jpg)
is unscaled.

Now we scale by pixel:
![](https://math.ucr.edu/home/baez/ecological/fox_white.jpg style="width:200px"   
)

And now by percent:
![](https://math.ucr.edu/home/baez/ecological/fox_white.jpg style="width:50%"  
)

I rest my case :slight_smile:

19

Some context here: I was referring to a post by someone who hijacked a year-old thread, giving misleading advice.

As to the general question: Yes, MMD does allow including attributes in image and link markup. No, I don’t think that this is a good idea to use that for sizing images.

Assuming that the intended output format is HTML (things might be different for, e.g., PDF).

![](url width=200px) (from Penney’s example) results in <img src=... width=200> And here’s what MDN has to say about inline dimensions in img elements:

Note: Including height and width enables the aspect ratio of the image to be calculated by the browser prior to the image being loaded. This aspect ratio is used to reserve the space needed to display the image, reducing or even preventing a layout shift when the image is downloaded and painted to the screen. Reducing layout shift is a major component of good user experience and web performance.

So, in 2023, a single width is not helpful.

Alternatively, one could use a style attribute like
![](url style="width: 50%;") (which is a lot better than specifying pixels).
Now, the image will be 50% of its surrounding box element. Which causes an interesting difference between images in a paragraph (inline) and on their own line.

![Isolated image is rendered as a figure](x-devonthink-item://4646CB4A-7DFE-4986-8078-1D313B7988F8 style="width: 50%;")

A paragraph with an inline image ![Inline image is rendered … inline](x-devonthink-item://4646CB4A-7DFE-4986-8078-1D313B7988F8 style="width: 50%;") in the middle… how does that work?

Bildschirmfoto 2023-07-30 um 12.39.11
Bildschirmfoto 2023-07-30 um 12.39.111700×1150 60.9 KB

Isolated images are put inside a figure element, inline ones are not. The user has specified seemingly the same width for both, but the result is very different.

That is not a shortcoming of MMD, things are working as documented. And with an appropriate stylesheet, one can make that difference disappear.

And that’s a better approach, I believe: Write a CSS that does The Right Thing. For example, having an image display at 50% width on a smartphone might not make a lot of sense. Media (or, nowadays, container) queries in the CSS can take care of these issues. And a CSS allows one to apply the same style to all images (e.g. to add a shadow or whatever) – with attributes added to the MD, you’d have to do that for every image. Tedious.

If a single image needs to be treated differently, one can still use an id attribute in the MD and refer to it in the CSS.

1 Like
20

It is more complicated to use a CSS Style sheet, which I already do for color tagging.

Drag and drop images into DT groups are common.
Easy image inserting with EASY scaling is within the ethos of fast Markdown writing. Not super perfect typesetting like latex. If you need that go Rmarkdown and Knitr/Pandoc.

This is a way to fast documentation - faster than word, formatted and printable and deployable.

I can code and hack with the best of them - just built R-Shiny deployment for an Apple Silicon ARM VM last night. Since the ARM binaries are not avail. It is not about hacking, been there done that.

It is about fast, easy note taking - to produce formatted output fast for a hectic workflow.

Perhaps CSS tagging for multiple common scales 50%, 75%, etc … hmmm good idea- thanks for the challenge!

my point … simple fast note taking and documentation. Image scaling is just annoying in DT now.