Insight Vault

Quartz Mobile Long Title Overflow Troubleshooting

3 min read

Symptom

On a mobile-width Quartz page, a long document title or table-of-contents entry can protrude outside the right side of the viewport.

The issue can be especially confusing when the left Explorer or right Table of Contents appears to be closed, but part of a long label still remains visible.

Causes

The root problem is not that the title is too long. The root problem is that some UI containers do not fully defend against long strings.

This vault stores the document title in frontmatter as title. Quartz renders that value through the article-title plugin as an h1.article-title.

Quartz’s base styles already apply overflow-wrap: break-word to common text elements such as p, a, and li, but the separately rendered .article-title needs its own long-text wrapping rule.

The Table of Contents plugin also has a separate collapsed-state problem. Its collapsed state reduces the parent flex height, but it does not fully remove the .toc-content element from layout with display: none. If a long TOC item overflows horizontally, part of it can remain visible even when the TOC looks closed.

The mobile Explorer has a similar hidden-state edge case. In the collapsed state, Quartz moves .explorer-content left with translateX(-100vw) and sets the parent content to visibility: hidden. Because the page body has horizontal padding, the translated panel can still leave a small strip inside the viewport. Some Explorer descendants, especially .folder-outer.open, also set visibility: visible, so a descendant can become visible even while the parent panel is meant to be hidden.

Why Shortening the Title Is the Wrong Fix

In this vault, a title is metadata that helps recover the meaning of the document later.

Obsidian-style notes often use titles that are precise questions, distinctions, or troubleshooting labels. Shortening a title only to satisfy a mobile layout can make the document harder to identify and reuse.

The better rule is: preserve the semantic title, and make the UI handle long titles safely.

Applied Fix

The fix lives in quartz/styles/custom.scss, not in .quartz/ plugin cache code.

.article-title,
.page-title,
.page-title a,
article h1,
article h2,
article h3,
.toc-content a,
.explorer-content a,
.folder-title {
  max-width: 100%;
  overflow-wrap: anywhere;
  word-break: normal;
}
 
.folder-container,
.folder-container div,
.folder-container div > button,
.toc-content li {
  min-width: 0;
}
 
.toc-content.collapsed {
  display: none;
}
 
@media all and (max-width: 800px) {
  body .explorer.collapsed > .explorer-content {
    transform: translateX(calc(-100vw - 2rem));
    transition: none;
    visibility: hidden;
    pointer-events: none;
  }
 
  body .explorer.collapsed > .explorer-content .folder-outer.open {
    visibility: hidden;
  }
}

This does four things:

  1. It allows article titles, page titles, TOC links, Explorer links, and folder names to wrap inside the viewport.
  2. It prevents flex children from preserving a content-based minimum width that can push text outside the layout.
  3. It fully hides collapsed TOC content so long TOC items cannot leak out of the closed area.
  4. It moves the collapsed mobile Explorer fully outside the viewport and prevents visible Explorer descendants from leaking through the hidden parent.

Diagnostic Checklist

When a similar issue appears, separate these questions:

  • Does the final DOM state overflow the viewport?
  • Is the closed component actually hiding its content, or only reducing its height?
  • Does a hidden parent contain descendants that reset visibility to visible?
  • Is the long string hard for the browser to break naturally, such as a kebab-case file name, code identifier, URL, or long English phrase?
  • Is a flex or grid child refusing to shrink because of its default min-width: auto behavior?

This is a layout problem, not a title metadata problem.

Graph View