Adjust Image Sizes | Asciidoctor Docs

AsciiDoc

• • Introduction
    • Document Structure
    • Key Concepts
    • Document Processing
    • Normalization
• • Blocks
    • Delimited Blocks
    • Build a Basic Block
    • Add a Title to a Block
    • Assign an ID
    • Block Masquerading
    • Troubleshooting Blocks
• • Document Attributes
    • Attribute Entries
      • Attribute Entry Names and Values
      • Wrap Attribute Entry Values
      • Attribute Entry Substitutions
      • Inline Attribute Entries
    • Declare Built-In Attributes
      • Set Boolean Attributes
    • Declare Custom Attributes
    • Unset Attributes
    • Reference Attributes
      • Handle Unresolved References
    • Attribute Assignment Precedence
    • Counters
• • Element Attributes
    • Positional and Named Attributes
    • ID Attribute
    • Role Attribute
    • Options Attribute
• • Document Header
    • Document Title
      • Subtitle
    • Author Information
      • Using the Author Line
      • Add Multiple Authors to a Document
      • Assign Author and Email with Attribute Entries
      • Reference the Author Information
      • Compound Author Names
    • Revision Information
      • Using the Revision Line
      • Assign Revision Attributes with Attribute Entries
      • Version Label Attribute
      • Reference the Revision Attributes
    • Document Metadata
    • Document Header Reference
• • Document Type
• • Sections
    • Section Titles and Levels
      • Activate Section Title Links
    • Autogenerate Section IDs
      • Change the ID Prefix and Separator
    • Assign Custom IDs and Reference Text
    • Section Numbers
    • Section Styles for Articles and Books
      • Hide Special Section Titles
      • Number Special Sections
      • Colophon
      • Dedication
      • Abstract (Section)
      • Abstract (Block)
      • Preface
      • Book Parts
        • Part Numbers and Signifier
      • Chapters
      • Appendix
      • Glossary
      • Bibliography
      • Index
    • Section Attributes and Styles Reference
• • Paragraphs
    • Hard Line Breaks
    • Preamble and Lead Style
    • Paragraph Alignment
• • Discrete Headings
• • Breaks
• • Text Formatting and Punctuation
    • Bold
    • Italic
    • Monospace
    • Literal Monospace
    • Text Span and Built-in Roles
    • Highlight
    • Quotation Marks and Apostrophes
    • Subscript and Superscript
    • Using Custom Inline Styles
    • Troubleshoot Unconstrained Formatting Pairs
• • Lists
    • Unordered Lists
    • Ordered Lists
    • Checklists
    • Separating Lists
    • Compound List Items
• • Description Lists
    • Horizontal Description List
    • Question and Answer Lists
    • Description Lists With Marker
• • Links
    • Autolinks
    • URL Macro
    • Link Macro
    • Troubleshooting Complex URLs
    • Link & URL Macro Attribute Parsing
    • Mailto Macro
    • Link, URL, and Mailto Macro Attributes Reference
• • Cross References
    • Document to Document Cross References
    • Cross Reference Text and Styles
    • Validate Cross References
• • Footnotes
• • Images
    • Set the Images Directory
    • Insert Images from a URL
    • Position and Frame Images
    • Add Link to Image
    • Adjust Image Sizes
    • Specify Image Format
    • SVG Images
    • Images Reference
• • Audio and Video
• • Icons
    • Image Icons Mode
    • Font Icons Mode
    • Icon Macro
• • Keyboard Macro
• • Button and Menu UI Macros
• • Admonitions
• • Sidebars
• • Example Blocks
• • Blockquotes
• • Verses
• • Verbatim and Source Blocks
    • Source Code Blocks
      • Source Highlighting
      • Highlight Select Lines
      • Highlight PHP Source Code
    • Listing Blocks
    • Literal Blocks
    • Callouts
• • Tables
    • Build a Basic Table
    • Add a Title
      • Customize the Title Label
      • Turn Off the Title Label
    • Add Columns to a Table
      • Adjust Column Widths
      • Align Content by Column
      • Format Content by Column
    • Add Cells and Rows to a Table
      • Create a Header Row
      • Create a Footer Row
      • Align Content by Cell
      • Format Content by Cell
      • Span Columns and Rows
      • Duplicate Cells
    • Table Width
    • Table Borders
    • Table Striping
    • Table Orientation
    • Assign a Role to a Table
    • Nesting Tables
    • CSV, TSV and DSV Data
    • Table Reference
• • Equations and Formulas (STEM)
• • Open Blocks
• • Collapsible Blocks
• • Comments
• • Automatic Table of Contents
    • Customize the TOC Title
    • Adjust the TOC Depth
    • Position the TOC
    • TOC Attributes Reference
• • Docinfo Files
• • Includes
    • Offset Section Levels
    • Indent Included Content
    • Use an Include File Multiple Times
    • Include List Item Content
    • Include Content by Tagged Regions
    • Include Content by Line Ranges
    • Include Content by URI
• • Conditionals
    • ifdef and ifndef Directives
    • ifeval Directive
• • Substitutions
    • Special Characters
    • Quotes
    • Attribute References
    • Character Replacements
    • Macros
    • Post Replacements
    • Customize the Substitutions Applied to Blocks
    • Customize the Substitutions Applied to Text
    • Escape and Prevent Substitutions
• • Passthroughs
    • Passthrough Blocks
    • Inline Passthroughs
• • Reference
    • Syntax Quick Reference
    • Frequently Asked Questions (FAQ)
    • Compare AsciiDoc to Markdown
    • Document Attributes Reference
    • Character Replacement Attributes Reference
    • Glossary of Terms

AsciiDoc pre-spec

• AsciiDoc
• Asciidoctor
  • 2.0
• Asciidoctor.js
  • 3.0
  • 2.2
• AsciidoctorJ
  • 3.0
  • 2.5
• Asciidoctor PDF
  • 2.3
  • 2.2
  • 2.1
  • 2.0
• Asciidoctor EPUB3
  • 2.3
• Asciidoctor reveal.js
  • 5.0
  • 4.1
• Maven Tools
  • 3.2
• Gradle Plugin Suite
  • 5.0
  • 4.0
• Asciidoclet
  • 2.0
  • 1.5.6
• Asciidoctor Diagram
  • 3.0.1
• Browser Extension
• Community

• AsciiDoc
• Images
• Adjust Image Sizes

PDF Edit this Page Adjust Image Sizes

Since images often need to be sized according to the medium, there are several ways to specify an image size.

In most output formats, the specified width is obeyed unless the image would exceed the content width or height, in which case it scaled to fit while maintaining the original aspect ratio (i.e., responsive scaling).

width and height attributes

The primary way to specify the size of an image is to define the width and height attributes on the image macro. Since these two attributes are so common, they’re mapped as the second and third (unnamed) positional attributes on both image macros.

image::flower.jpg[Flower,640,480]

That’s equivalent to the long-hand version:

image::flower.jpg[alt=Flower,width=640,height=480]

The value of the width and height attributes should be an integer without a unit. The px unit is implied. Although the processor may allow it, you should never rely on a % value. While the % unit was supported in older versions of HTML, it was removed starting in HTML 5. If you need to specify a % value for PDF or DocBook output, use pdfwidth or scaledwidth, respectively. To scale the image relative to the content area in HTML output, use a role.

While the values of width and height can be used to scale the image, these attributes are primarily intended to specify the intrinsic size of the image in CSS pixels. The width and height attributes are mapped to attributes of the same name on the <img> element in the HTML output. These attributes are important because they provide a hint to the browser to tell it how much space to reserve for the image during layout to minimize page reflows. The height attribute should only be specified if the width attribute is also specified, and it should respect the aspect ratio of the image.

Automatic image scaling

The default Asciidoctor stylesheet implements responsive images (using width-wise scaling). If the width of the content area is smaller than the width of the image, the image will be scaled down to fit. To support this feature, the intrinsic aspect ratio of the image is preserved at all sizes.

Thus, when specifying the image’s dimensions, you should choose values that honor the intrinsic aspect ratio of the image. If the values don’t respect the aspect ratio, the height is ignored by the browser.

pdfwidth attribute

AsciiDoc recognizes the following attributes to size images when converting to PDF using Asciidoctor PDF:

• pdfwidth - The preferred width of the image in the PDF when converting using Asciidoctor PDF.

The pdfwidth attribute accepts the following units:

px	Output device pixels (assumed to be 96 dpi)
pt (or none)	Points (1/72 of an inch)
pc	Picas (1/6 of an inch)
cm	Centimeters
mm	Millimeters
in	Inches
%	Percentage of the content width (area between margins)
vw	Percentage of the page width (edge to edge)
iw	Percentage of the intrinsic width of the image

If pdfwidth is not provided, Asciidoctor PDF also accepts scaledwidth, or width (no units, assumed to be pixels), in that order. See image scaling in Asciidoctor PDF for more details.

scaledwidth attribute

AsciiDoc recognizes the following attributes to size images when converting to DocBook or when converting to PDF using Asciidoctor PDF. The scaledwidth attribute is ignored by other converters.

• scaledwidth - The preferred width of the image when converting to PDF using the DocBook toolchain. (Mutually exclusive with scale).

• scale - Scales the original image size by this amount when converting to PDF using the DocBook toolchain. (Mutually exclusive with scaledwidth).

scaledwidth sizes images much like pdfwidth, except it does not accept the vw unit.

The value of scaledwidth when used with DocBook can have the following units:

px	Output device pixels (assumed to be 72 dpi)
pt	Points (1/72 of an inch)
pc	Picas (1/6 of an inch)
cm	Centimeters
mm	Millimeters
in	Inches
em	Ems (current font size)
% (or no units)	Percentage of the content width (area between margins)

The scaledwidth attribute in AsciiDoc is mapped to the width attribute on the imagedata tag in DocBook, whereas the width attribute in AsciiDoc is mapped to the contentwidth attribute on the imagedata tag in DocBook. If both the width and scaledwidth attributes are specified in AsciiDoc, the scaledwidth tags precedence, so the DocBook output will only have the width attribute.

Image sizing recap

Image sizing attributes

Backend	Absolute size	Relative to original size	Relative to content width	Relative to page width
html	width=120 (assumed to be px)	Not possible	role=half-width	role=half-view-width
pdf	pdfwidth=100mm (or cm, in, pc, pt, px)	Not possible (support for the scale attribute is pending)	pdfwidth=80%	pdfwidth=50vw
docbook, pdf	scaledwidth=100mm (or cm, em, in, pc, pt, px)	scale=75	scaledwidth=50%	Not possible

Here’s an example of how you might bring these attributes together to control the size of an image in various output formats:

image::flower.jpg[Flower,640,480,pdfwidth=50%,scaledwidth=50%]

If the cascading behavior of the sizing attributes does not work for your use case, you might consider a document attribute to set the attribute that is suitable for the backend you are using. Consider the following example:

ifdef::backend-html5[] :twoinches: width=144 // using a role requires adding a corresponding rule to the CSS :full-width: role=full-width :half-width: role=half-width :half-size: role=half-size :thumbnail: width=60 endif::[] ifdef::backend-pdf[] :twoinches: pdfwidth=2in // NOTE use pdfwidth=100vw to make the image stretch edge to edge :full-width: pdfwidth=100% :half-width: pdfwidth=50% // NOTE scale is not yet supported by the PDF converter :half-size: pdfwidth=50% :thumbnail: pdfwidth=20mm endif::[] ifdef::backend-docbook5[] :twoinches: scaledwidth=2in :full-width: scaledwidth=100% :half-width: scaledwidth=50% :half-size: scale=50 :thumbnail: scaledwidth=20mm endif::[]

Then you can specify the image to be half the width of the content area using the following syntax:

image::image.jpg[{half-width}]

In addition to providing consistency across your document, this technique will help insulate you from future changes. For a more detailed example, see this thread on the discussion list.

Add Link to Image Specify Image Format