You are viewing a degraded version of this page. Please use a supported browser for the best reading experience.

Images on Codex Press

Photography is an essential component to most articles and Codex goes to great lengths to make it easy to add and manipulate images on the platform. With the techniques described on this page, you’ll be able to create compelling layouts for your articles in minutes.

Uploading Images

Before uploading, it’s important to select a photograph of decent quality. You should add images at the highest possible resolution and Codex will downsize and compress them to web quality for devices of varying sizes and capabilities. While there’s no minimum or maximum quality, generally photographs should be a minimum of 1,500 pixels in at least one direction. Adding the highest resolution available will future-proof your stories for the not-too-distant future when we all have 8K monitors on our desks.

You should prefer JPEG format for your images, which will have filenames that end in “.jpg.” Images encoded in PNG format are also commonly used but they may be many times larger than JPEGs of similar quality due to their lossless compression format.

However, PNG is needed for images with transparency, because JPEG does not support an alpha channel in its encoding. Given the massive size of most PNG images, Codex will automatically convert them to JPEG if they do not have any transparency information. It is still recommended that you convert your own images prior to uploading, as they commonly have a small bit of transparency lurking that is not visibly apparent (preventing the automatic conversion).

Codex has a zero-step procedure for uploading images. Drag the file from your computer directly into the article you’re working on.

The zero-step upload procedure.

For photo-rich stories, it’s often helpful to upload many images at a time, giving you a selection to chose from as you design the page. Codex offers a media library inside every article, accessible on the right side of the editor.

From the media library, you may drag your image directly into the page. When you remove an image from the article it will reappear in the media library, ready to be added again.

Of course, if you’re creating an image gallery or something of the sort you may want to drop many images directly into the story and this also is an option.

Adding Classes to Control Image Size

The Codex editor will show all images in your story with no differentiation between them. This follows from the non-WYSIWYG philosophy of the platform.

When they are displayed for your readers, images default to the full width of the browser window. If you’re using one of the built-in themes, you’ll be able to apply classes like full-width and full-window, which fills both the width and height of the browser window. If you’re using a custom theme for your publication, developers on your team will provide similar utility classes for you to use.

If you notice that your image is not as large as you have set it, you may be hitting against some of the protections to prevent over-scaling and distortion of images. These protections may be circumvented with custom CSS or by uploading a larger image file.

There is one special image in every story which is the “cover” image, that travels with the story to be used in index pages and social media posts. By default this will be the first image or video in the article, however it may be overridden by adding the class cover to any other image in the article. If it’s added to a video, the image used will be the first frame.

Adding Captions and Text On Top Of Images

Click below your image to add a caption. Text on images will automatically use the <figcaption> element. (For an overview of HTML elements and how they should be used in Codex, refer to the editor documentation and the HTML reference.)

By default, the caption text will appear directly following the image. Built-in themes allow you to position text above an image with a .before class. If you’d like to have the caption appear beside an image, you may add the class .caption-side to the image element.

Adding text on top of images in web pages is surprisingly tricky — and especially so across the multitude of devices in use by your readers. This is one of the areas where Codex supplements web standards with tools that let writers and producers create quality designs without writing code.

First, let’s take a look at why this is a problem. On smaller screens, images obviously must shrink down from their desktop size. However, they do not shrink at the same rate as the text around them, which must remain large enough to be legible.

This means that the gorgeous pixel-perfect layouts we see all the time in print are typically not achievable, or even desirable, online. In some circumstances, text can be scaled evenly with images, but these cases are rare because it disrupts the natural hierarchy of typography on the page, changing the ratio of headlines to body text that’s consistent between articles.

Since we can’t be precise in placing text on images, it leaves us with the daunting position of simultaneously designing for every screen size and aspect ratio in use — practically speaking, every size and aspect ratio imaginable.

There are many existing approaches to this problem. Some platforms solve it by simply not allowing text on images. Others do it with a formulaic approach that obscures photographs with gradients or a dark overlay.

Codex takes a no-compromise approach to this problem: providing a visual solution to this visual problem. To add your text on top of an images, you can drag a paragraph or block of several elements on top of an image. Then, use the “positioned” setting to enable visually positioning it.

These text overlays are automatically responsive. If the text does not fit inside the box supplied, it will be moved below the image where it can be safely legible. This means that you should think about the text box not as a method to precisely position the text but rather as a title-safe region where it will be legible. To that end, it’s best to make the box a large as possible so that when the image size is constrained on small screens, your text has room to grow.

Sometimes you’ll want to position the text inside that larger box, however. This can be done using utility classes that apply the proper CSS. The built-in themes provide the classes .content-bottom, .content-center, and .content-right.

As effective as this magazine effect may be, not every image is suitable for it. In particular, you’ll want to select images with one or more of the following characteristics.

It’s often possible to put text on an image that would otherwise be unsuitable for it by applying a treatment to the text, such as a background color, a stroke or a text shadow. This technique is something of a cudgel, however, and best avoided if you have the patience. That is, unless you’re making a meme poster, in which case it would be odd to do anything else.

Often, it will be faster or easier to position text on images repeatedly in the same position by using class names or custom CSS. Any block of text that is set with position: absolute; in CSS will appear inside the frame of the image.

Using one of the built-in themes, you will have the utility classes: .top, .right, .bottom, and .left.

Responsive Cropping

Another challenge of responsive design is making sure that images are large enough to be seen on mobile screens. Desktop screens typically have a landscape orientation while most people hold their phones in portrait, for comfort in the hand and for reading text. Fitting with the Codex precept of designing for all devices, the platform has tools built-in to make images look big and beautiful on mobile screens.

A crop is added in much the same ways as a text block, with a box on top of the image. The idea here is to select the part of the image that must never be cropped out at any screen size.

Just setting the crop is not enough, however. Images by default will use their natural aspect ratio, so you must add a class that expands the height, such as full-window. The built-in themes set a max-height property on all images to keep them from expanding larger than the browser window and this may have the effect of inducing a crop.

It’s important to emphasize that this is not cropping as it’s commonly employed in image editing programs. The crop is not always performed but is optionally performed using Javascript according to the layout of the page on any given screen. If you need to crop an image in all cases, you should do so before uploading it to Codex.

Holy Grail Layout Example

The techniques of positioned text and responsive cropping are designed to be combined for painless, magazine-style layouts.

In this example, we see how the Holy Grail layout example responds to different browser widths. The optional crop is outlined in red and the text box is show in green.

Codex will disable all Javascript, including the above image cropping, in older browsers. The latest versions of Chrome, Firefox, Safari, Edge and Internet Explorer up to version 10 are regarded as first-tier browsers that run with JavaScript enabled.

You can see how users on unsupported browsers will see your page by viewing it with the ?fallback URL parameter. So, for example, this page can be previewed in a fallback mode at https://codex.press/docs/images?fallback.

Thanks But I Don’t Need Your “Help”

Most articles will benefit from responsive cropping, adaptive text blocks and the other features built in to Codex figures. However, sometimes you need more control and experienced web designers may consider these tools an impediment to their existing techniques. While this is the default behavior for images (and videos) on Codex, it is easily circumvented by changing the tag name.

If you give an image in Codex the element <img>, a raw image is added to the resulting article. This also works for videos by giving them the <video> tag.

Similarly, it is often useful to use the background-image property of CSS, which provides a somewhat similar mechanism for cropping images to that described above. If you give an image on Codex any tag name that is not <figure> or <img>, it will be added to that element as a background image. This can be quite useful if you prefer to create layouts in CSS and you are comfortable setting your own breakpoints using media queries.

Images on Codex, including background images and <img> tags, are first loaded with very small thumbnails encoded in base 64, which are then replaced in Javascript with a source appropriate for their size on the page. This reduces the perceived (and actual) performance of the page by preventing large layout operations that move content around. Also, text on top of images will be immediately readable while the images load since they will have roughly the same background color. It also saves bandwidth charges because images are lazily loaded as they approach the viewport.

It is highly recommended that you not set CSS for the elements created inside a Codex-controlled <figure> element. Such behavior is not guaranteed to be supported and your stories may break at anytime.

Additionally, you should not reference image URLs directly in CSS or HTML as they also may change without notice at a later date.