Community寫作與編輯github.com

warm-ink-technical-pdf

Typeset technical PDFs (briefs, explainers, reports, paper notes) in the warm-ink style with LaTeX, using a reading column, margin notes, colored math, code and tables.

warm-ink-technical-pdf 是什麼?

warm-ink-technical-pdf is a Claude Code agent skill that typeset technical PDFs (briefs, explainers, reports, paper notes) in the warm-ink style with LaTeX, using a reading column, margin notes, colored math, code and tables.

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/pbamotra/claude-skills/tree/HEAD/skills/warm-ink-technical-pdf

Installed? Explore more 寫作與編輯 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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

  1. 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.
  2. 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.
  3. 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.
  4. 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, and mkRed for the single key quantity.
  5. 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.
  6. 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 Sources callout.

Workflow

  1. Outline and facts. List the sections and every number with its source.
  2. 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.
  3. Write into the skeleton below.
  4. Compile twice. xelatex -interaction=nonstopmode -halt-on-error doc.tex, two passes; margin notes and references settle on the second. Grep the log for Overfull.
  5. Look at every page. pdftoppm -r 80 -png doc.pdf page and 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.
  6. 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:

NeedUse
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
Codelstlisting, 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 p float 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 luaotfload is installed. Fonts fall back automatically; do not hard-code them.

Checklist before delivering

  • Every number traced to a source, with a Sources callout at the end.
  • No Overfull lines 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.

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

相關技能