jurlstify
URL typesetting with line-break opportunities — the url.sty port for Typst

English | 中文

English

A Typst package that ports LaTeX’s url.sty line-breaking logic. In justified paragraphs, bare URLs either overflow the margin or force ugly gaps into the surrounding text. jurlstify inserts break opportunities at the same character classes as url.sty (/, ?, &, :, etc.) so Typst’s line-breaker can wrap URLs naturally without touching word spacing elsewhere in the paragraph.

Features

• url.sty-compatible break classes — breaks after . / ? & # : and more, matching \UrlBreaks / \UrlBigBreaks / \UrlNoBreaks
• Hyphen control — breaks after - are suppressed by default (like url.sty); enable with hyphens: true
• Font inheritance — defaults to auto (inherits body font), avoiding the metric mismatch that monospace causes in CJK text
• Stretch mode — opt-in stretch: true lets URL-internal lines align to the right margin in justified paragraphs
• Soft-hyphen fallback — opt-in every: N inserts invisible soft hyphens every N chars within unbroken letter/digit runs, visible only when the line actually breaks there
• Three usage modes — standalone jurlstify(), hyperlink wrapper jurl(), and document-level show rule jurlstify-links()
• Fully customisable — override break character lists, font, size, color, and hyphen interval per call

Quick Start

#import "@preview/jurlstify:0.1.0": jurlstify, jurl, jurlstify-links

// Render a URL string with break opportunities
#jurlstify("https://example.com/very/long/path?query=value&more=stuff#fragment")

// Clickable link — same breaking, wrapped in link()
#jurl("https://example.com/very/long/path?query=value&more=stuff#fragment")

// Apply automatically to every link() in the document
#show: jurlstify-links.with()
#link("https://example.com/automatically/handled")

API Reference

jurlstify(url, ..options) — core function

Renders url as inline content with Unicode break opportunities at url.sty-compatible positions.

// Inherit body font, break at / ? & : etc.
#jurlstify("https://example.com/path?a=1&b=2")

// Allow hyphen breaks
#jurlstify("https://my-very-long-sub-domain.example.org/path", hyphens: true)

// Justify URL-internal lines to the right margin
#jurlstify("https://example.com/long/path", stretch: true)

// Insert a soft hyphen every 8 chars in long unbroken runs
#jurlstify("https://example.com/averylongpathsegmentwithnobreaks", every: 8)

// Monospace font (classic url.sty look)
#jurlstify("https://example.com/path",
  font: ("DejaVu Sans Mono", "Menlo", "Consolas", "Courier New"))

// Custom color and size
#jurlstify("https://example.com/path", fill: blue, size: 9pt)

jurl(dest, display: none, ..options) — hyperlink wrapper

Renders a clickable hyperlink whose visible text is formatted by jurlstify. Accepts all the same keyword options.

#jurl("https://example.com/very/long/path")
#jurl("https://example.com/very/long/path", display: "example site")
#jurl("https://example.com/path", hyphens: true, fill: blue)

jurlstify-links(..options, body) — show-rule helper

Document-level show rule that makes every #link("http://…") (where body equals destination) automatically use jurlstify. Links with explicit display content (#link(dest, "click here")) are left untouched.

// Declare once near the top of your document
#show: jurlstify-links.with()

The homepage is #link("https://example.com/very/long/path").  // auto-formatted
See #link("https://example.com", "the docs") for details.     // untouched

Pass options to apply them document-wide:

#show: jurlstify-links.with(hyphens: true, fill: blue)

Default Break Characters

Notes on Justification

jurlstify inserts U+200B (ZERO WIDTH SPACE) at break positions — zero width, not stretchable, faithfully mirroring url.sty’s zero-stretch muskips. A line consisting entirely of URL characters may end slightly short of the right margin.

Enable stretch: true for invisible-but-stretchable word spaces; the paragraph justifier will then align URL-only lines to the right margin at the cost of small visible gaps at break points.

Break quality depends on Typst’s optimizer. jurlstify only inserts declarative markers; improvements to Typst’s engine automatically improve output.

License

MIT License — see LICENSE for details.

中文

将 LaTeX url.sty 的换行逻辑移植到 Typst 的排版包。在两端对齐的段落中，裸露的 URL 要么溢出页边距，要么迫使周围文字产生大块空白。jurlstify 在与 url.sty 相同的字符类（/、?、&、: 等）后插入换行机会，使 Typst 的断行器能在这些位置自然换行，而不影响段落其余部分的字间距。

功能特性

• url.sty 兼容断点 — 在 . / ? & # : 等字符处断行，对应 \UrlBreaks / \UrlBigBreaks / \UrlNoBreaks
• 连字符控制 — 默认抑制 - 处的换行（与 url.sty 一致）；可通过 hyphens: true 开启
• 字体继承 — 默认 auto，继承正文字体，避免等宽字体在中文段落中造成字距错位
• 拉伸模式 — 可选 stretch: true，让整行 URL 也能对齐两端对齐段落的右边距
• 软连字符兜底 — 可选 every: N，在连续字母/数字段每隔 N 个字符插入不可见的软连字符，仅在该处实际换行时才显示为 -
• 三种使用方式 — 独立函数 jurlstify()、超链接包装器 jurl()、文档级 show rule jurlstify-links()
• 完全可定制 — 可按需覆盖断点字符列表、字体、字号、颜色和软连字符间隔

快速上手

#import "@preview/jurlstify:0.1.0": jurlstify, jurl, jurlstify-links

// 渲染带换行机会的 URL 字符串
#jurlstify("https://example.com/very/long/path?query=value&more=stuff#fragment")

// 可点击超链接，同样支持换行
#jurl("https://example.com/very/long/path?query=value&more=stuff#fragment")

// 全局 show rule：让文档中所有 link() 自动使用 jurlstify
#show: jurlstify-links.with()
#link("https://example.com/automatically/handled")

API 参考

jurlstify(url, ..options) — 核心函数

将 url 渲染为行内内容，在与 url.sty 兼容的位置插入 Unicode 换行机会。

// 继承正文字体，在 / ? & : 等处断行
#jurlstify("https://example.com/path?a=1&b=2")

// 允许连字符处断行
#jurlstify("https://my-very-long-sub-domain.example.org/path", hyphens: true)

// 使纯 URL 行对齐右边距
#jurlstify("https://example.com/long/path", stretch: true)

// 每隔 8 个字符插入软连字符，处理长段无断点路径
#jurlstify("https://example.com/averylongpathsegmentwithnobreaks", every: 8)

// 等宽字体（经典 url.sty 风格）
#jurlstify("https://example.com/path",
  font: ("DejaVu Sans Mono", "Menlo", "Consolas", "Courier New"))

// 自定义颜色与字号
#jurlstify("https://example.com/path", fill: blue, size: 9pt)

jurl(dest, display: none, ..options) — 超链接包装器

渲染可点击的超链接，可见文字由 jurlstify 格式化。支持与 jurlstify 相同的所有关键字选项。

#jurl("https://example.com/very/long/path")
#jurl("https://example.com/very/long/path", display: "示例网站")
#jurl("https://example.com/path", hyphens: true, fill: blue)

jurlstify-links(..options, body) — show rule 辅助函数

文档级 show rule，让所有 body 与目标相同的 #link("http://…") 自动使用 jurlstify 断行。有显式显示内容的链接（如 #link(dest, "点击这里")）不受影响。

// 在文档顶部声明一次
#show: jurlstify-links.with()

项目主页为 #link("https://example.com/very/long/path")。   // 自动格式化
详见 #link("https://example.com", "文档")。                // 不受影响

全局传入选项：

#show: jurlstify-links.with(hyphens: true, fill: blue)

默认断点字符

关于两端对齐的说明

jurlstify 在断点位置插入 U+200B（零宽空格）——宽度为零且不可拉伸，忠实还原了 url.sty 的零伸缩粘连。因此，整行都是 URL 字符的行可能无法对齐右边距。

开启 stretch: true 可改为插入不可见但可拉伸的字间距，使段落排版器在纯 URL 行也能对齐右边距，代价是这些行的换行点处可能出现小间隙。

断行质量取决于 Typst 引擎的优化器。jurlstify 只插入声明式标记，Typst 引擎的改进会自动改善输出，无需修改本包。

许可

MIT 许可证 — 详见 LICENSE。