Mobile user friendliness with code samples and Googles search console

05 Apr 2021 - tsp
Last update 16 Apr 2021
Reading time 8 mins

This is a pretty short blog post about a small nuance that might lead to a huge hit in your search ranking at the most popular search engine of today. And it was not as easy to discover the source of the problem like I’d wish it to be (for example having some kind of tooling that can even more pinpoint the complain of Google’s search console than the integrated validation tool does). We all know that Google is ranking pages by their quality so usually the typically approach to get a high ranking is:

But as one also knows the algorithm of Google also weights your webpages rank by user experience. This means:

Error messages by the search console

Basically there are four possible errors that are checked for mobile friendliness by the bot:

It’s also a good idea to regularly check back at the search console since sometimes behaviour might change even when your page stays pretty much the same.

Errors start rising after some change inside the validator

Let’s start to look at these points beginning from the last one:

Viewport declaration

This is the most simple things to do. Since mobile browsers sometimes try to mimic behaviour of desktop browsers - I have to admit that I personally do not understand why one would do this since the web is already specified to be device and viewport independent - they tend to provide a highly zoomed out virtual canvas mode for pages they think of being targeted not specially at mobile devices. This leads to virtually unreadable pages. I personally think this is a hack to try to support really bad web designs (like fixed with or pixel exact) which is something one shouldn’t do in the first place. To get out of this mode the viewport metatag exists. Basically one can set six properties.

The width property specifies the width of the virtual canvas. When targeting mobile devices - or in my opinion always - one should set this to device-width. The device-width corresponds to the width of the device visible screen area at 100% zoom. An accompanying property device-height for a height property exists but it’s usually a good idea to not use a height specification for the whole page when designing web pages - it’s a useful property when using toolkits such as Apache Cordova to design HTML5 based user interfaces for local mobile applications.

The properties initial-scale as well as maximum-scale and minimum-scale control the minimum and maximum zoom factor. An initial scale of 1 would set the zoom level to 100%. As usual one - in my opinion - should not limit the user to a given minimum or maximum value and just specify the initial scale to 100%. The last property should never be used for web pages - it’s the user-scalable value that could be set to no to prevent a user from zooming. Again this is totally useless for a web page but might again be interesting when designing HTML5 based user interfaces for local applications.

Usually this boils down to a single simple meta tag that sets initial scale to 1 and the virtual viewport width to device width:

<meta name="viewport" content="width=device-width, initial-scale=1">

Text too small to read

Obvious. Don’t have any text smaller than around 22px. Or in the best case don’t set any absolute font size. And don’t use font sizes less than 100% on mobile layouts. For some font variants like monospace you’ll have to increase the font size to around 120%.

Clickable elements are too close

Well this one is pretty basic. Usually mobile devices are operated by touch interfaces. If you have touchable elements too close to each other then the user might touch the wrong element by accident or have a hard time selecting your links. As a rule of thumb clickable elements should be at least 2-3 em wide and high as well as having additionally as much padding on all of their sides. It’s a good idea to also have at least 0.5-1 em margin on all sides of clickable elements too. This allows the user to clearly discriminate clickable components.

Content wider than the screen

This is pretty simple - if you have content that’s wider than the screen it breaks your layout. The user has to do horizontal scrolling. This is also the major problem when showing code samples and has also been a problem for this blog for a long term due to interesting behaviour of the mobile userfriendliness checker of Google.

Basically this blogs static page generator automatically generates static HTML pages out of markdown and other source formats. The layout uses nested pre and code tags. This is mainly done for some specific syntax highlighting behaviour if it’s enabled. To solve the problem of too wide content I basically set the overflow property of the pre element to overflow: auto;. This usually adds a scroll bar to the code block as soon as the window is too small - i.e. the code block and not the browser window have to be scrolled and thus too wide lines that are common in source code do not force the whole browser canvas to be wider or the content to span over the canvas.

Unfortunately this didn’t prevent the Google mobile usability checker to flag the page as having trouble with too wide content. This also triggered all other errors such as text to small to read and clickable elements are too close since I use some media queries inside of my stylesheets that only set specific margins (and some other stuff like a different collapsible navigation bar as well as non reduced font sizes for metadata, etc.) in case of a smaller width design - and since the code samples have been interpreted as being way wider than the viewport these media queries did not engage. Usually one should do this the other way round and use media queries to detect wider screens (i.e. mobile first) but since more than 90% of my pages visitors are using desktop systems I won’t do this. Update: It turns out google really requires a mobile first approach to correctly determine mobile friendliness of your layouts. So media queries have to detect wider screens, stylesheets have to target mobile screens primarily. Of course this might lead to problems with pages that are mainly used by desktop users using older browsers that still don’t support media queries.

So what was the source of the wide code samples? Basically the inner code tag. On the inspection tool it turned out that code has a default display style as inline and an overflow property of visible. The latter one triggered the wide screen. So the solution is as simple as it get’s - simply set the overflow or the overflow-x property to auto for all code tags inside of pre on mobile devices and force the display property to block:

pre.highlight code {
	display: block;
	overflow-x: auto;

The way it should look like

That basically solved the content-wider-than-screen-problem as well as all other problems that had been triggered by the media query that didn’t kick in as soon as lines had been wider.

This article is tagged:

Data protection policy

Dipl.-Ing. Thomas Spielauer, Wien (

This webpage is also available via TOR at http://rh6v563nt2dnxd5h2vhhqkudmyvjaevgiv77c62xflas52d5omtkxuid.onion/

Valid HTML 4.01 Strict Powered by FreeBSD IPv6 support