Skip to content

Images and screenshots

An image that stands alone in its paragraph gets a framed look: centred, a thin border, rounded corners and a soft shadow. No markup or option is needed.

Open the settings page.
![The settings page](./images/settings.png)

With allowHtml: true, an <img> on its own line, between blank lines, is framed too. The image keeps its own width.

These are not framed:

  • an image inside a sentence, or on the line straight after text with no blank line between
  • two or more images in one paragraph
  • an image inside a link, a table cell, a heading or a footnote
  • an image that opens a list item (- ![...](...) or - <img ...>); a screenshot below a step’s text, after a blank line, is framed

Pages without allowHtml are rendered in the browser by the web part, so they show the frame as soon as the updated Better Doctor Markdown solution is deployed, before any publish. Pages with allowHtml are rendered at publish time and pick it up on their next publish; every page republishes once, because the renderer version changed.

With allowHtml: true, add class="plain" to an <img>:

<img src="./images/logo.png" alt="Logo" class="plain">

Without allowHtml there is no opt-out: a Markdown image alone on its line is always framed.

<kbd> renders as a key cap. Nest them for a combination; only the inner keys get a box:

Press <kbd><kbd>Ctrl</kbd>+<kbd>S</kbd></kbd> to save.

The web part styles these classes on every site. Content-project shortcodes can emit them; inline style is stripped by the sanitizer, so classes are the only way to style.

Markup Styled as
p.bdoctor-screenshot > img added by the renderer; framed, the image keeps its own width
figure.bdoctor-screenshot.bdoctor-w-N > img + figcaption (N = 5 to 100, step 5) framed, figure width: N%, image fills it, caption centred under it
figure.bdoctor-screenshot.bdoctor-w-auto > img + figcaption framed, figure fits the image
img.plain never framed
kbd, kbd > kbd key caps; the outer combo wrapper has no box
span.bdoctor-menu-path > strong + › bold items, muted separator
details.bdoctor-collapse > summary bordered fold-away box

Set width with a bdoctor-w-* class on the figure, not a width attribute: a browser ignores width on <figure>.

A shortcode that runs before Markdown parsing must emit the figure without blank lines inside it. A blank line ends the HTML block, so an <img> on its own line inside the figure is framed again as p.bdoctor-screenshot, and it no longer fills the figure.

Renaming any of these classes would break content projects, so new classes are added instead.