Warm-ink technical PDFs
Typesets technical writing as a PDF with one reading column and a wide margin column,
tracked-caps headings, a humanist serif for prose and Computer-Modern math. It shares its
colors and type with the warm-ink-ml-figures skill; use that skill for any real diagram
and \input its .tikz file here.
Write original text. Summarize sources in your own words and cite them; do not copy passages or re-create figures from them.
Page design
- Two columns with different jobs. A 322bp reading column carries the argument. A 166bp margin column carries figure captions, definitions and asides. Nothing in the margin is required to follow the argument.
- Quiet hierarchy. The title is tracked bold caps over one italic taupe line and a hairline rule. Section heads are small tracked caps. There is no third level in a short document.
- Captions lead with a claim.
Figure 1 | Title.in bold, then one or two sentences on what to notice. Small figures sit in the column with the caption beside them; plates span both columns with the caption beneath. - Color ties text to pictures. When a figure gives a concept a color, color that
symbol in the prose and equations too (
{\color{mkRed}c_t}). One hue per concept, andmkRedfor the single key quantity. - Plain furniture. Code sits on a cream field with a hairline frame. Tables have a taupe caps header and one rule. Callouts are a flat warm-grey box. No shadows, no colored bars, no boxed equations.
- Air. Ragged bottom, no paragraph indent, 7.5bp between paragraphs, and white space left empty instead of filled.
Writing for this layout
- Open with the claim in two or three sentences, before any section head.
- One idea per section, and a section title that names the idea.
- Put a figure or equation next to the first sentence that needs it.
- Move anything a reader could skip into an aside.
- End with a table of the numbers and a
Sourcescallout.
Workflow
- Outline and facts. List the sections and every number with its source.
- Figures. Make diagrams with the figures skill (or a few lines of TikZ for a bar or
strip) and save each as
fig-<name>.tikz. - Write into the skeleton below.
- Compile twice.
xelatex -interaction=nonstopmode -halt-on-error doc.tex, two passes; margin notes and references settle on the second. Grep the log forOverfull. - Look at every page.
pdftoppm -r 80 -png doc.pdf pageand read the PNGs. Check for asides that collide, a listing or callout split across pages, a last page holding only a line or two, and floats that landed far from their text. Fix and recompile. - Deliver the PDF and say where the facts came from.
Setup: save these two files next to your .tex
mlink.sty (colors, type, TikZ vocabulary; identical to the one in the figures skill):
% mlink.sty -- "warm ink" design system: colors, type and TikZ vocabulary.
% Compile with XeLaTeX (or LuaLaTeX). Usage: \usepackage{mlink}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{mlink}[2026/11/13 v1.1 warm-ink design system, core]
\RequirePackage{amsmath}
\RequirePackage{fontspec}
\RequirePackage{unicode-math}
\RequirePackage{xcolor}
\RequirePackage{tikz}
\usetikzlibrary{arrows.meta,calc,positioning,fit,backgrounds,decorations.pathreplacing}
% ---------------------------------------------------------------- 1. COLOR
% Neutrals: a warm near-black for words, one taupe for all structure.
\definecolor{mkInk}{HTML}{231F20} % body text, key numerals
\definecolor{mkTaupe}{HTML}{948979} % every structural line, arrow, label
\definecolor{mkTaupeDk}{HTML}{6F665A} % small text that must stay legible
\definecolor{mkTaupeLt}{HTML}{C3BBB1} % inactive / background marks
\definecolor{mkTaupePl}{HTML}{E6E1DA} % callout fills, table bands
\definecolor{mkPaper}{HTML}{F6F3EE} % panel wash
\definecolor{mkCream}{HTML}{EFE5D1} % highlight wash
\definecolor{mkCode}{HTML}{FEFDF8} % code background
% Signals: saturated, used one-per-concept and repeated in math + caption.
\definecolor{mkRed}{HTML}{ED1C24}
\definecolor{mkOrange}{HTML}{F26522}
\definecolor{mkGold}{HTML}{D9A441}
\definecolor{mkGreen}{HTML}{0EA14B}
\definecolor{mkTeal}{HTML}{27A299}
\definecolor{mkCyan}{HTML}{00AEEF}
\definecolor{mkBlue}{HTML}{1B78B5}
\definecolor{mkIndigo}{HTML}{4A54AB}
\definecolor{mkPurple}{HTML}{7F3F98}
\definecolor{mkMagenta}{HTML}{EC008C}
\definecolor{mkSlate}{HTML}{3B576E}
% Muted solids for filled compute blocks (white text sits on these).
\definecolor{mkSage}{HTML}{7FA77F}
\definecolor{mkSteel}{HTML}{566B84}
% Viridis, 10 stops: the only colormap. Use for tensors, never for categories.
\definecolor{mkV0}{HTML}{440154}\definecolor{mkV1}{HTML}{482878}
\definecolor{mkV2}{HTML}{3E4A89}\definecolor{mkV3}{HTML}{31688E}
\definecolor{mkV4}{HTML}{26828E}\definecolor{mkV5}{HTML}{1F9E89}
\definecolor{mkV6}{HTML}{35B779}\definecolor{mkV7}{HTML}{6DCD59}
\definecolor{mkV8}{HTML}{B4DE2C}\definecolor{mkV9}{HTML}{FDE725}
% ---------------------------------------------------------------- 2. TYPE
% Humanist serif for prose, grotesque sans for labels, Computer-Modern-style
% math on purpose: the contrast makes equations read as "the math layer".
\defaultfontfeatures{Ligatures=TeX}
\IfFontExistsTF{TeX Gyre Pagella}{\setmainfont{TeX Gyre Pagella}}{}
\IfFontExistsTF{Inter}{%
\setsansfont{Inter}[Scale=0.88]%
\newfontfamily\mkSemi{Inter SemiBold}[Scale=0.88]%
\newfontfamily\mkBold{Inter Bold}[Scale=0.88]%
}{%
\setsansfont{TeX Gyre Heros}[Scale=0.9]%
\newfontfamily\mkSemi{TeX Gyre Heros Bold}[Scale=0.9]%
\newfontfamily\mkBold{TeX Gyre Heros Bold}[Scale=0.9]%
}
\IfFontExistsTF{DejaVu Sans Mono}{\setmonofont{DejaVu Sans Mono}[Scale=0.8]}{}
\setmathfont{Latin Modern Math}
% Text atoms. Optional argument is a color.
\newcommand\mkL[2][mkTaupe]{{\mkSemi\fontsize{5.8}{7.2}\selectfont
\addfontfeature{LetterSpace=7}\color{#1}\MakeUppercase{#2}}} % LABEL
\newcommand\mkT[2][mkInk]{{\mkSemi\fontsize{7}{8.6}\selectfont\color{#1}#2}} % Name
\newcommand\mkN[2][mkTaupeDk]{{\rmfamily\itshape\fontsize{6.6}{8.2}\selectfont\color{#1}#2}} % note
\newcommand\mkD[2][mkTaupe]{{\fontsize{5.9}{7}\selectfont\color{#1}$#2$}} % 128x64
\newcommand\mkF[2][mkTaupeDk]{{\fontsize{6.8}{8.2}\selectfont\color{#1}$#2$}} % small formula
\newcommand\mkM[2][mkInk]{{\fontsize{8}{9.6}\selectfont\color{#1}$#2$}} % math
\newcommand\mkBig[2][mkInk]{{\fontsize{15}{16}\selectfont\color{#1}$#2$}} % hero numeral
% ---------------------------------------------------------------- 3. TIKZ
\tikzset{
mk canvas/.style={x=1bp,y=1bp,line cap=butt,line join=miter,
every node/.style={inner sep=0pt,outer sep=0pt}},
% strokes: .3 hairline / .5 default / .75 emphasis / 1.1 hero
mk line/.style={draw=mkTaupe,line width=.5bp},
mk hair/.style={draw=mkTaupe,line width=.3bp},
mk arrow/.style={mk line,-{Triangle[length=3.3bp,width=2.9bp]},shorten >=.5bp},
mk flow/.style={mk arrow,rounded corners=3.5bp},
mk leader/.style={draw=mkTaupe,line width=.3bp,dash pattern=on .7bp off 1.1bp},
mk dash/.style={draw=mkTaupe,line width=.4bp,dash pattern=on 2.1bp off 2.1bp},
mk tone/.style={draw=#1,-{Triangle[length=3.3bp,width=2.9bp,fill=#1]}},
% boxes
mk box/.style={draw=mkTaupe,line width=.5bp,rounded corners=2.5bp,fill=white,
inner xsep=4bp,inner ysep=3bp,align=center},
mk solid/.style={fill=#1,draw=none,rounded corners=3bp,text=white,
inner xsep=5bp,inner ysep=4bp,align=center},
mk tint/.style={fill=#1!9,draw=#1,line width=.5bp,rounded corners=2.5bp,
inner xsep=4bp,inner ysep=3bp,align=center},
mk chip/.style={fill=#1,rounded corners=1.4bp,text=white,inner xsep=2.6bp,
inner ysep=1.9bp,font=\mkSemi\fontsize{6.2}{7}\selectfont},
mk tag/.style={fill=#1,rounded corners=1bp,text=white,inner xsep=2bp,
inner ysep=1.2bp,font=\mkBold\fontsize{4.4}{5}\selectfont},
% operators on a wire
mk op/.style={circle,draw=mkTaupe,line width=.5bp,fill=white,minimum size=8.4bp},
mk plus/.style={mk op,path picture={\draw[mkTaupe,line width=.5bp]
(path picture bounding box.west)--(path picture bounding box.east)
(path picture bounding box.south)--(path picture bounding box.north);}},
mk times/.style={mk op,path picture={\draw[mkTaupe,line width=.5bp]
(path picture bounding box.south west)--(path picture bounding box.north east)
(path picture bounding box.north west)--(path picture bounding box.south east);}},
mk brace/.style={draw=mkTaupe,line width=.4bp,decorate,
decoration={brace,amplitude=2.6bp,raise=1.5bp}},
}
% Dashed group with a label that interrupts the top edge.
% \mkgroup[color]{name}{x1,y1}{x2,y2}{Label}
\newcommand\mkgroup[5][mkTaupe]{%
\draw[mk dash,draw=#1,rounded corners=5bp] (#3) rectangle (#4);
\path (#3) rectangle (#4) node[pos=0] (#2-sw) {} node[pos=1] (#2-ne) {};
\node[anchor=west,fill=white,inner xsep=3bp,inner ysep=1bp]
at ($(#2-sw|-#2-ne)+(9bp,0)$) {\mkL[#1]{#5}};}
% Tensor strip: a row of viridis cells, length proportional to sqrt(dim).
% \mkstrip{name}{x}{y}{dim}{seed} (x = left edge, y = vertical centre)
\newlength\mkcw \setlength\mkcw{2.2bp} % cell width
\newlength\mkch \setlength\mkch{8bp} % cell height
\newcommand\mkstripscale{0.74}
\newcommand\mkstrip[5]{%
\pgfmathtruncatemacro\mk@n{max(2,round(\mkstripscale*4*sqrt(\the\numexpr#4/16\relax)*1bp/\mkcw))}%
\pgfmathsetseed{#5}%
\foreach \mk@i in {1,...,\mk@n}{%
\pgfmathtruncatemacro\mk@c{min(9,max(0,round(4.4+2.1*rand+1.9*rand*rand*rand)))}%
\fill[mkV\mk@c] ($(#2,#3)+({(\mk@i-1)*\mkcw},-.5\mkch)$) rectangle ++(\mkcw+.05bp,\mkch);}%
\node[anchor=west,minimum width=\mk@n\mkcw,minimum height=\mkch] (#1) at (#2,#3) {};}
% Stat: hero numeral over a small label. \mkstat{x}{y}{671\text{B}}{total parameters}
\newcommand\mkstat[4]{%
\node[anchor=base west] at (#1,#2) {\mkBig{#3}};
\node[anchor=base west] at ($(#1,#2)+(0,-9.5bp)$) {\mkL{#4}};}
% White ground + bounding box. Put first in every figure so the SVG is opaque.
% \mkpaper{x1,y1}{x2,y2}
\newcommand\mkpaper[2]{\useasboundingbox (#1) rectangle (#2);\fill[white] (#1) rectangle (#2);}
\endinput
mlinkdoc.sty (the page design):
% mlinkdoc.sty -- "warm ink" page design for technical PDFs. Needs mlink.sty.
% Compile with XeLaTeX, twice. Usage: \usepackage{mlinkdoc} options: book | letter | a4
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{mlinkdoc}[2026/11/13 v1.1 warm-ink document layer]
\newcommand\mk@paper{book}
\DeclareOption{book}{\renewcommand\mk@paper{book}}
\DeclareOption{letter}{\renewcommand\mk@paper{letter}}
\DeclareOption{a4}{\renewcommand\mk@paper{a4}}
\ProcessOptions\relax
\RequirePackage{mlink}
\RequirePackage{geometry,fancyhdr,titlesec,caption,marginnote,booktabs,
listings,enumitem,graphicx,array,colortbl,ragged2e,microtype}
\RequirePackage[most]{tcolorbox}
\newcommand\mk@pw{630bp}\newcommand\mk@ph{810bp}
\def\mk@tmp{letter}\ifx\mk@paper\mk@tmp \renewcommand\mk@pw{612bp}\renewcommand\mk@ph{792bp}\fi
\def\mk@tmp{a4}\ifx\mk@paper\mk@tmp \renewcommand\mk@pw{595bp}\renewcommand\mk@ph{842bp}\fi
% One reading column plus a wide margin column for captions and asides.
\geometry{paperwidth=\mk@pw,paperheight=\mk@ph,left=64bp,textwidth=322bp,
marginparsep=26bp,marginparwidth=166bp,top=86bp,bottom=78bp,
headsep=30bp,footskip=34bp,includemp=false}
\newlength\mkfullwidth
\setlength\mkfullwidth{\dimexpr\textwidth+\marginparsep+\marginparwidth\relax}
\color{mkInk}
\renewcommand\normalsize{\fontsize{10}{14.2}\selectfont}\normalsize
\setlength\parindent{0pt}\setlength\parskip{7.5bp}
\linespread{1}\frenchspacing\raggedbottom
% running head: tracked caps left, folio right
\newcommand\mkrunning{}
\pagestyle{fancy}\fancyhf{}\renewcommand\headrulewidth{0pt}
\fancyhfoffset[R]{\dimexpr\marginparsep+\marginparwidth\relax}
\fancyhead[L]{\mkL[mkInk]{\mkrunning}}
\fancyhead[R]{\rmfamily\fontsize{8.5}{10}\selectfont\thepage}
\fancypagestyle{plain}{\fancyhf{}}
% Title block: \mktitle{Title}{italic subtitle}
\newcommand\mktitle[2]{%
{\mkBold\fontsize{15}{18}\selectfont\addfontfeature{LetterSpace=11}%
\MakeUppercase{#1}\par}\vspace{1bp}%
{\itshape\fontsize{11}{14}\selectfont\color{mkTaupe}#2\par}\vspace{5bp}%
{\color{mkInk}\hrule height .5bp}\vspace{9bp}}
\titleformat{\section}{\mkBold\fontsize{9.5}{12}\selectfont
\addfontfeature{LetterSpace=10}}{\thesection.}{5bp}{\MakeUppercase}
\titlespacing*{\section}{0pt}{16bp}{3bp}
\titleformat{\subsection}{\mkSemi\fontsize{8}{10}\selectfont\color{mkTaupe}
\addfontfeature{LetterSpace=8}}{}{0pt}{\MakeUppercase}
\titlespacing*{\subsection}{0pt}{11bp}{1bp}
% captions: bold lead-in, "Figure 1 | Title." Set small, in the margin or below.
\DeclareCaptionLabelSeparator{mkbar}{\ \textbar\ }
\captionsetup{font={small},labelfont=bf,labelsep=mkbar,justification=RaggedRight,
singlelinecheck=false,skip=6bp}
\renewcommand\small{\fontsize{8}{10.6}\selectfont}
\renewcommand\footnotesize{\fontsize{7.4}{9.6}\selectfont}
\renewcommand\footnoterule{\vspace{4bp}{\color{mkInk}\hrule width 70bp height .4bp}\vspace{4bp}}
% margin aside (caption-sized, ragged) and margin figure caption
\renewcommand*\marginfont{\small\RaggedRight}
\newcommand\mkaside[2][0pt]{\marginnote{#2}[#1]}
% figure in the text column, caption in the margin: \begin{mkfigure}{caption}...\end{mkfigure}
\newenvironment{mkfigure}[2][0pt]{\par\addvspace{6bp}\refstepcounter{figure}%
\marginnote{\textbf{Figure \thefigure\ \textbar}\ #2}[#1]\noindent\ignorespaces}
{\par\addvspace{6bp}}
% full-width figure spanning text + margin, caption below
\newenvironment{mkwide}[1][t!]{\begin{figure}[#1]\noindent\hbox to\textwidth\bgroup
\begin{minipage}{\mkfullwidth}}{\end{minipage}\hss\egroup\end{figure}}
% pull quote in the margin
\newcommand\mkquote[3][0pt]{\marginnote{{\itshape\fontsize{8.6}{11.6}\selectfont
\color{mkTaupeDk}``#2''\par}\vspace{2bp}{\hfill\mkL{#3}}}[#1]}
% callout box
\newtcolorbox{mkcallout}[1][]{enhanced,colback=mkTaupePl!60,colframe=mkTaupePl!60,
boxrule=0pt,arc=2.5bp,left=9bp,right=9bp,top=7bp,bottom=7bp,
fontupper=\small\RaggedRight,title={#1},coltitle=mkInk,attach title to upper={\par\vspace{1bp}},
fonttitle=\mkBold\fontsize{7}{9}\selectfont\addfontfeature{LetterSpace=10}\MakeUppercase}
% code: cream field, hairline frame, small mono
\lstset{basicstyle=\ttfamily\fontsize{7.2}{9.6}\selectfont\color{mkInk},
backgroundcolor=\color{mkCode},frame=single,rulecolor=\color{mkTaupePl},
framerule=.5bp,framesep=6bp,xleftmargin=7bp,xrightmargin=7bp,
commentstyle=\color{mkTaupe}\itshape,keywordstyle=\color{mkBlue},
stringstyle=\color{mkGreen!80!black},numberstyle=\color{mkTaupe},
showstringspaces=false,columns=fullflexible,keepspaces=true,
aboveskip=8bp,belowskip=6bp,breaklines=true}
% tables: taupe caps header, one rule, generous rows
\newcommand\mkth[1]{\mkL{#1}}
\renewcommand\arraystretch{1.25}
\arrayrulecolor{mkTaupe}
\setlength\heavyrulewidth{.5bp}\setlength\lightrulewidth{.4bp}
\setlist{itemsep=1bp,topsep=2bp,leftmargin=14bp}
\endinput
Document skeleton
\documentclass{article}
\usepackage{mlinkdoc} % options: [letter] or [a4]; default is 630 x 810 bp
\renewcommand\mkrunning{Project \textperiodcentered\ short title}
\begin{document}
\thispagestyle{fancy}
\mktitle{Title in a few words}{One italic line that says what the reader will learn}
Opening paragraph: the claim, in plain words.%
\mkaside{\textbf{Margin lead-in.} Asides, definitions and figure captions live out here.}
\section{First idea}
Prose with math colored to match the figure: ${\color{mkRed}c_t} = W h_t$.
\begin{mkfigure}{\textbf{Caption title.} What to notice, in one or two sentences.}
\begin{tikzpicture}[mk canvas]
\fill[mkTaupeLt] (0,14) rectangle (280,23); \fill[mkRed] (0,0) rectangle (40,9);
\node[anchor=base west] at (285,15.5) {\mkM{7.0}};
\node[anchor=base west] at (45,1.5) {\mkM[mkRed]{1.0}};
\end{tikzpicture}
\end{mkfigure}
\noindent\begin{minipage}{\linewidth}
\begin{lstlisting}[language=Python]
def f(x): # code sits on a cream field
return x + 1
\end{lstlisting}
\end{minipage}
\begin{tabular}{@{}p{140bp}>{\raggedleft\arraybackslash}p{60bp}@{}}
\mkth{Quantity} & \mkth{Value}\\ \midrule
Layers & 12\\ Width & 768\\
\end{tabular}
\begin{mkcallout}[Takeaway]
One or two sentences the reader should leave with.
\end{mkcallout}
% full-width figure across text + margin:
% \begin{mkwide}[p]\centering\resizebox{\mkfullwidth}{!}{\input{fig.tikz}}
% \caption{\textbf{Title.} Sentence.}\end{mkwide}
\end{document}
Components:
| Need | Use |
|---|---|
| Paper size | \usepackage[letter]{mlinkdoc} or [a4]; default is 630 x 810 bp |
| Running head | \renewcommand\mkrunning{..} |
| Title block | \mktitle{Title}{italic subtitle} |
| Margin aside | \mkaside[offset]{\textbf{Lead-in.} text} |
| Margin pull quote | \mkquote[offset]{quote}{source} |
| Column figure, caption in margin | \begin{mkfigure}[offset]{caption} .. \end{mkfigure} |
| Plate across both columns | \begin{mkwide}[p] .. \caption{..} \end{mkwide} at \mkfullwidth |
| Code | lstlisting, wrapped in a minipage if short |
| Table header cell | \mkth{Quantity} with \midrule beneath |
| Callout | \begin{mkcallout}[Title] .. \end{mkcallout} |
| Small caps label, note, math atoms | \mkL, \mkN, \mkM from mlink.sty |
Pitfalls
- One pass leaves margin notes in the wrong place. Always run two.
- Put
%after an\mkaside{..}that precedes text, or the next line starts with a stray space. - A
pfloat declared mid-section takes the next whole page; declare a plate just before the section that discusses it, and say "next page" only after checking where it landed. - Column figures are numbered in source order together with plates, so declare them in the order they appear.
- Keep table widths under 322bp including column gaps, or the table pushes into the margin.
- Callouts do not break across pages; keep them short.
- A plate drawn 600bp wide is scaled to about 86% at
\mkfullwidth; check small labels. - Use XeLaTeX. LuaLaTeX also works where
luaotfloadis installed. Fonts fall back automatically; do not hard-code them.
Checklist before delivering
- Every number traced to a source, with a
Sourcescallout at the end. - No
Overfulllines in the log; no orphaned last page. - Asides and captions sit beside the text they belong to and do not overlap.
- Colors in prose and equations match the figures.
- Every page rendered and inspected.