Fixing Mobile Page Layouts
Some webpages are too damn hard to read on my phone, like this one:

Squint harder
The font is tiny, the page is wide, and the text is wrapping at a weird place. I must read these on my phone like a PDF: scrolling in and panning along each line.01
This post is my guide to fixing these issues. Itâs aimed at folks like me who arenât quite web developers, but blog or run small sites that could use a little fine-tuning.
Contents
Permalink to âContentsâ-
How to Fix Common Problems â Four tricks I use to fix pages.
-
Walkthroughs â Tutorials of repairing pages.
Disclaimer: Iâm not a web developer. I have no idea what Iâm doing, really.
How to Fix Common Problems
Permalink to âHow to Fix Common Problemsâ1. Set the Viewport
Permalink to â1. Set the ViewportâDoes the page look like a desktop site zoomed way out? You might need to tell web browsers to render the web page at the actual deviceâs width.02 Add this HTML tag:
<meta
name="viewport"
content="width=device-width, initial-scale=1"
>
In action, this makes the following change:


Now the text renders into a more reasonable area. This makes the font look bigger and the lines wrap much earlier. But the page still has a problem thatâs making the text only take up half the page. Something is too wide.
2. Scroll Over-Wide Elements
Permalink to â2. Scroll Over-Wide ElementsâOver-wide elements are easy to miss even from your phone, because your phone might mask them with a horizontal scroll bar. If you accidentally scroll right, though, youâll fly off the content.


→ Agh!
Once you notice this happens, you can pinch to zoom out and survey the mess. Some element is probably too wide. Find the culprit.


Left: zoomed out. Right: the problem child.
Ah ha. In this case, itâs text in <pre>
blocks. We can add some simple CSS to limit their width.
pre {
max-width: 100%;
overflow-x: scroll;
}
This solves it. Hereâs the before and after.


No more scroll bar, and the width is correct. This section is a bit weird because of overly wide indentation. Hereâs the same result on body text.


What About Bigger Screens?
Permalink to âWhat About Bigger Screens?âThis article is only about making pages look better on mobile. I try not to break anything for larger screens, but naively applying some of these changes will make desktop layouts more cramped.
Left: For mobile devices, everything must adhere to the body width to avoid making the page scroll horizontally; individual wide elements can scroll on their own.
Center: For larger screens, we can keep the same strategy as with mobile displays and clip everything to the body region, but wide elements will still need to scroll.
Right: If we instead let wide elements spill outside the body area when there is room on larger displays, they wonât need to be scrolled.
When thereâs more screen space, it probably makes sense to let larger elements take up more room rather than clipping them and making them scroll horizontally. Consider housing wide content in containers that can break out from the body text.
3. Typographic Cleanup
Permalink to â3. Typographic CleanupâThere are a few bits of low hanging fruit that will make a page go from functional to comfortably readable. (Donât worry, Iâm not going to make the text annoyingly light gray or anything.)
-
Margins. Content should have a bit of breathing room, but not waste real estate.
-
Font size. Text be readable without squinting, but not so big to cause short line lengths.
-
Line height. Picking around
1.5
is a standard typography trick for body text and helps with readability.
We can apply all these changes to our running example.


4. Test on Your Actual Phone
Permalink to â4. Test on Your Actual PhoneâThis last trick is the most important and also the easiest to skip. Believe me, I forget to do it, too. But thereâs no getting around it.03
Yes, test it using your browserâs pretend Iâm a phone mode first. But to this day, Iâve never made a page where I didnât find something to change when I actually looked at it on my phone. Itâs easier to recognize bad proportions on the physical device you glue to your poor eyeballs all day.
Furthermore, sometimes the browser simulators are just plain wrong. In fact, our running example is exactly one such case. I describe this more in the walkthrough below.
Walkthroughs
Permalink to âWalkthroughsâClick on any picture to jump to the walkthrough for fixing the mobile layout on that page.
Disclaimer: Iâm nitpicking microscopic stylistic issues on these ages for the sake of illustration. Their actual content is largely fascinating, technical, and well-written. I humbly offer these example fixes because I like what the authors are doing and would like to enjoy it even more on my phone.
Git Best Practices
Permalink to âGit Best PracticesâThis is the site that I used as the running example for the first section. This page is called Commit Often, Perfect Later, Publish Once: Git Best Practices. The page looks like this on my phone:

Now, I canât be too hard on the designer.04 First, the page is from 2012âancient Internet history.
Second, itâs actually kind of hard to tell this was going to happen. Normally, I would guess that they simply didnât test it using developer tools. But if you ask Chrome and Safari what the page should look like on an iPhone X, they both say, âjust fine:â


This is annoying, because it means we have to debug on the phone itself. No problem, just download the page, whip up a python -m http.server
, find the laptopâs local IP address with ifconfig | grep 192
, and point the olâ telephone to 192.168.0.xxx:8000
. Weâre in.
Fixing it
Permalink to âFixing itâThese fixes are exactly the ones I describe in detail in the first section, so Iâll run through them quickly.
First, we adjust the viewport (fix #1).
<meta
name="viewport"
content="width=device-width, initial-scale=1"
>
Then, we stop <pre>
-formatted blocks from stretching out the page width (fix #2).
pre {
max-width: 100%;
overflow-x: scroll;
}
For the final tweaks (fix #3), we apply:
-
Narrower margins. We donât need that much of a buffer on our phones. Iâll take it from
3em
â1em
.05 -
Bigger font size. Itâs just in the squint-y range for me.
16px
â18px
. -
Taller line height. The usual
normal
â1.5
.
Apply them all, hereâs the before/after.


Hooray, super readable!
Extra credit: typography
Permalink to âExtra credit: typographyâIf we wanted to, one last thing Iâd tweak is the indentation, which is so comically large as to end up taking up nearly half the screen width (really only glaring on an actual phone, AKA (fix #4):

⌠but eh, Iâd say weâve done enough for one evening. Letâs call it an exercise for the reader.
Poissonâs Equation
Permalink to âPoissonâs EquationâThis page is called Poissonâs Equation is the Most Powerful Tool not yet in your Toolbox. The pageâs viewport seems good, but you can accidentally scroll to the right, revealing a bigger page and likely overly wide elements (fix #2).


Left: the default view on pageload. Right: Zooming out to the page's true width after noticing horizontal scrollbars.
If we scroll down, we can see the worst offenders are, again, over-wide <pre>
regions for code. They are already the correct width, but when their content overflows, it spills out.


We can fix these,
pre {
overflow-x: scroll;
}
⌠but rendered math is still an issue. Like the <pre>
chunks, theyâre also set to a good width, but spill out.


The math chunks are all in <div>
s with the CSS class math
, so we can just add another selector to our rule:
pre, .math {
overflow-x: scroll;
}
And with that, weâve tamed the over-wide elements and the page displays nicely.

Extra credit: code and scrollbars
Permalink to âExtra credit: code and scrollbarsâIf I were to add finishing touches, the two things Iâd tweak would be the code and math.
The font size for code blocks is bigger than it needs to be (fix #3) and lacks syntax highlighting. If we make those two changes and then reduce the indentation from four to two spaces, we can even fit all the code without any scrollingâwe just need to wrap two of the comments.


Aside: This was another place where it was instrumental to check on my physical phone (fix #4). Only there did I notice the code font was so large, and only there could I verify that it was still readable after reducing the font size.
The second aspect Iâd improve is the math displayâor more generally, the remaining elements that are have their own horizontal scroll bars because of their width.
When possible, itâs nice to have your content fit inside the display so people donât have to scroll horizontally to see it. But itâs not always worth the effort to make that happen. I think typeset math is one of those occasions. Itâs enough work just to make LaTeX display your math nicely, let alone making a version that fits on portrait-sized mobile screen.
But when we do have content that needs scrolling, I think itâs good to show people that scrolling is available. In other words, to show them when an element has the scrolling affordance. Showing content thatâs cut off is a hint, but this isnât reliable unless calculated explicitly, as the content might be cut off in a way that doesnât reveal thereâs more to see.
As I mentioned above, Appleâs browser seems to go out of its way to hide scroll bars. Even when they appear because you accidentally found something scrollable, they vanish a bit later. Can we make sure that our extra wide content has scroll bars them?
In short, I couldnât robustly figure this out. Using the ::-webkit-scrollbar
CSS selector, I could get really big chonky ones to always appear on Chrome, but not using Safari on my phone. Mozilla says this feature isnât standardized yet, but that it should work on Safari and all iOS browsers đ¤ˇââď¸


Left: no scrollbars still on my phone. Right: I could get big ugly ones on Chrome on my desktop.
F#
Permalink to âF#âThis page is called F# Is The Best Coding Language Today. Once again, a good viewport, but an over-wide <pre>
code block. Jeez, what is it with these code blocks?


Left: After loading the page, noticing it's got a horizontal scroll bar, and zooming out. Right: The culprit code block.
Two oddities with this one:
-
Not only is the code overly wide, but the left part is also cut off and canât be revealed. Not sure how that one happened.
-
The page becomes a broken, un-styled mess when I download it to make tweaks. Iâm guessing itâs blocking some CSS from being loaded.
Because of 2., I only made minimal tweaks in the browserâs developer tools to fix things (fix #2).
/* Attached these to the <figure> element,
the literal root of figurative evil. */
max-width: 100%;
/* Once again, you'd want to tweak font
sizes for desktop vs mobile. */
font-size: 14px;


Fixed view of the top of the page (left), and the code block (right).
This fixes the page and makes the code readable. Hooray!
Extra credit
Permalink to âExtra creditâNothing else major here, but I would wrap the comments in the code earlier so we could get rid of horizontal scrolling entirely. The URL, which would be hard to wrap, could simply be moved outside of the code.
Hydroponic
Permalink to âHydroponicâThis page is called Automated Hydroponic System Build. In a crazy turn of events, đ¨ itâs not code in a <pre>
block this time! đ¨ This page actually contains pretty huge chunks of code, but they all obey the body width. Whatâs the issue, then?


An overly long URL, yeeted into the comments by none other than the author himself. Bummer.
In fact, thereâs a different comment from another person that includes a URL that would also stretch the page (fix #2). This means that any commenter can break the mobile page layout đą
I checked out the source, and saw each comment has class="comment-body"
. So if we simply add the CSS:
.comment-body {
overflow-wrap: break-word
}
⌠then everything is groovy.


Diffusion Models
Permalink to âDiffusion ModelsâThis page is called What are Diffusion Models? This time, itâs pesky math again, stretching a good viewport too wide.


We can tell MathJax to stay in its lane (fix #2) by adding the CSS:
.MathJax_Display {
overflow-x: scroll;
}
⌠and the page is back in its box.


Footnotes
In hindsight, Safariâs Reader View almost completely solves this (for web pages, not PDFs). So I should just use that more. But it does mess up content on some pages, which you wonât know is happening while youâre reading it, and, you know, *waves hands* fixing stuff is fun etc. âŠď¸
âActualâ deviceâs width is already a simplification, because screens have pretend pixels (e.g., âoh hey, Iâm 375 x 812â) and actual pixels (e.g., âshh Iâm actually 1125 x 2436 lolâ). As usual, to read way more than you wanted to about this check out Mozillaâs docs on the viewport meta tag. âŠď¸
I was in vague denial that everyone who visited my website would be on a desktop. Then I added some basic analytics. Nope, mostly phones. âŠď¸
I was writing âauthorâ until I realized, oh yeah, this is a design issue, and, like it or not, self-publishing on the web a designer of us all makes. âŠď¸
Keep in mind for a real project weâd probably have the measurements change based on the screen size using CSS media queries. âŠď¸