Ask or search…
Comment on page


Add an image to a page
You can insert full-width images into your space, which can be aligned to the left, center, or right. You can optionally include alt text and/or a caption. For accessibility purposes, we highly recommend setting alt text.

Example of an image block

Image blocks can display a gallery of images, like this:
A photo of books at a library
You can now convert image blocks to full width by clicking on the
Block handle
next to the block. Read more about full-width blocks.

Light & Dark mode

You’re able to set different images for the light and dark mode versions of your published site. GitBook will automatically display the correct image depending on the mode your visitor is in.
To choose an image for light or dark mode, click the “Replace image” button while hovering over your image.
Setting a Light or Dark mode image
Note that light and dark mode images are not yet supported in some cases like Page covers or Card covers.

Light & Dark mode through GitHub/GitLab Sync

You can also add light & dark mode images in Markdown through HTML syntax (<picture> and <source>).
For block images, use the <figure> HTML element with a <picture> and <source> in it:
Text before
media="(prefers-color-scheme: dark)"
alt="GitHub logo"
<figcaption>Caption text</figcaption>
Text after
For inline images (images with text around them), use the <picture> HTML element with a <source> in it:
Text before the image
media="(prefers-color-scheme: dark)" />
alt="The GitHub Logo"
and text after the image
Note that we are not yet supporting GitHub-only syntax through #gh-dark-mode-only or #gh-light-mode-only.


Hover over your image, and you’ll see the SIZE control appear in the top-right corner. Click on it to change the size of your image from the available options.
  • Full - removes all size specifications and displays either a full size or capped at a maximum width of 735 pixels for larger images
  • Small - 25% of the image size
  • Medium - 50% of the image size
  • Large - 75% of the image size
In the event that the image exceeds the size of the editor, the image’s width will be limited to the ratio of the editor’s width instead.
When it comes to resizing images in an image gallery, the process and results can differ from resizing single images.

Resizing images through Git Sync

If you want more control over the sizing of your image, you can specify the exact size using markdown in GitHub or GitLab.
When we export an image, we use the HTML tag <img/>. As per the specifications, we can specify the dimensions of the image using the width and height attributes, which only accept values in pixels or a combination of a number and a % sign. Valid variants of specifying the image dimensions are: <img width="100" /> <img width="100%" />
If you are looking to embed external content into your pages, take a look at how to embed a URL.

Representation in Markdown

//Simple Block
//Block with Caption
![The GitBook Logo](
//Block with Alt text
<figure><img src="" alt="The GitBook Logo"></figure>
//Block with Caption and Alt text
<figure><img src="" alt="The GitBook Logo"><figcaption><p>GitBook Logo</p></figcaption></figure>
//Block with different image for dark and light mode, with caption
<source srcset="" media="(prefers-color-scheme: dark)">
<img src="" alt="GitHub logo">
<figcaption>Caption text</figcaption>


The maximum file size limit is 100mb for uploaded images.
Last modified 2d ago