Skip to main content
Recipe number 145

Cookbook · Chapter 11 · Comics & manga

Every kind of balloon on a lighthouse page

One comic page with speech, thought, whisper, shout, radio, caption, inner voice, editor's note and sound effects, each named in braces on its script line.

On this page
Genre
Comics
Output
Canvas · PDF
Postext
Tested with Postext 1.65.0
Needs ≥ 1.28.0 · postext-pdf ≥ 1.28.0
Licence
Updated 11 Oct 2026
Code MIT · Text CC BY 4.0
  • Trim 168 × 259 mm
  • 1 column
  • Comic Neue 9.5/13.5
  • Bangers
  • 2 pages
  • Level
  • Postext 1.65.0
  • Laid out in 621 ms
  • 142 lines of code

In short

A comic page about a storm rescue that uses every kind of speech balloon, with a letterer's style sheet that shows how each one is written in the script.

What you'll build

Page 7 of The Porthcove Light, a comic about a storm night at a lighthouse, with the letterer's style sheet in front of it. A trawler loses its engine, the keeper talks it in by radio, Maya waits with the cat, and in the morning the skipper thanks them. The page uses every kind of balloon Postext draws: speech, joined speech, thought, whisper, shout, radio, narration captions, an inner voice, an editor's note, a sound effect, an off-panel voice and a pinned balloon. The trim is an American comic book, 168 × 259 mm, and the page comes in ten languages.

This recipe answers

  • How do I show thought, whisper, shout and radio balloons?
  • How do I point a balloon's tail at the character who speaks?
  • How do I letter sound effects over the art?
  • How do I write speech balloons in Markdown?

The short answer

script.js · lines 46–71in full code
// A script line is `speaker{kind}: text`. The kinds are balloon styles: the engine ships
// speech, thought, whisper, shout, radio, caption, inner, note and sfx, and a style of the
// same id here changes only what it names. `caption`, `note` and `sfx` are reserved speakers.
const balloonStyles = [
  { id: 'speech', stroke: col('ink') }, // an oval, a curved tail to the mouth
  { id: 'thought', stroke: col('ink') }, // a cloud, bubbles to the head
  { id: 'whisper', stroke: col('ink') }, // a dashed outline, 0.9 × the type
  { id: 'shout', stroke: col('ink'), burstPoints: 16 }, // a burst, bold, 1.15 × the type
  { id: 'radio', stroke: col('ink') }, // a zig-zag outline and tail: a voice through a set
  { id: 'caption', fill: col('caption'), stroke: col('ink') }, // narration, butted to a corner
  { id: 'inner', fill: col('inner'), stroke: col('ink') }, // no tail, italic where it can be
  { id: 'note', fill: col('paper'), stroke: col('ink') }, // the editor's note, 0.8 × the type
  { id: 'sfx', fontFamily: SFX, color: col('accent'), haloColor: col('paper') }, // no balloon
];
const comics = {
  gutter: { horizontal: mm(4), vertical: mm(3) },
  panel: { borderWidth: pt(1), borderColor: col('ink'), background: col('paper') },
  lettering: { fontFamily: LETTERING, fontSize: pt(7.5), color: col('ink'), inset: mm(1) },
  balloonStyles,
  // A speaker's own style: every `skipper:` line comes through the radio unless it says not.
  cast: [{ id: 'skipper', balloonStyle: 'radio', name: t({ en: 'The skipper', es: 'El patrón',
    ca: 'El patró', zh: '船长', ar: 'الربّان', ja: '船長', pt: 'O capitão', fr: 'Le patron',
    de: 'Der Kapitän',
    it: 'Il capitano' }) }],
  runningHeads: true, // a comic page has no running head unless asked: here, its folio
};

One balloon style per kind, and a cast that gives the skipper his radio

Ingredients

Type
Comic Neue, Bangers, Zen Antique, Dela Gothic One, ZCOOL KuaiLe, ZCOOL QingKe HuangYou, Playpen Sans Arabic, Lalezar (SIL OFL 1.1)
Assets
  • bk-morning.jpg
  • bk-sea.jpg
  • bk-shout.jpg
  • bk-storm.jpg
  • bk-whisper.jpg
  • bk-window.jpg
  • Panel picture: the storm in the lamp room (Generated With Diffusion Models, original)
  • Panel picture: Maya and the cat under the desk (Generated With Diffusion Models, original)
  • Panel picture: the keeper shouting into the microphone (Generated With Diffusion Models, original)
  • Panel picture: the trawler in the storm (Generated With Diffusion Models, original)
  • Panel picture: Maya at the window (Generated With Diffusion Models, original)
  • Panel picture: the next morning on the rocks (Generated With Diffusion Models, original)

Method

#1 · Name the kind in the script line

The code is the short answer above. A line of the script is speaker{kind}: text, and the kind is the id of a balloon style. The nine built-in styles cover the usual kinds: an oval with a curved tail for speech, a cloud with bubbles for thought, a dashed outline for a whisper, a burst with a wedge tail for a shout, a jagged outline with a zigzag tail for a voice through a radio (balloon styles). A style in the config with the same id changes only what it names: here the stroke colour, the caption yellow and the burst's 16 points. caption, note and sfx are reserved speakers: narration boxes butted into a corner, the editor's note at 0.8 × the size, and display letters with no balloon.

The radio call: a caption, the skipper's radio balloon pointing at the set, the keeper's reply and the editor's note.

#2 · Point each tail at a speaker

script.js · lines 164–297in full code
// From the art manifest; fractions of each picture, the same in every language. `skipper` in
// the storm picture is the radio set, the voice's source; in the sea picture, his boat.
const ART = {
  'bk-storm': { width: 1100, height: 733, safeArea: { x: 0.05, y: 0.26, width: 0.52, height: 0.36 },
    anchors: [{ id: 'tomas', x: 0.3, y: 0.44, head: { x: 0.32, y: 0.33 },
      face: { x: 0.26, y: 0.29, width: 0.13, height: 0.21 } },
    { id: 'maya', x: 0.475, y: 0.47, head: { x: 0.48, y: 0.38 },
      face: { x: 0.43, y: 0.35, width: 0.09, height: 0.16 } },
    { id: 'skipper', x: 0.08, y: 0.52 }],
    avoid: [{ x: 0, y: 0.38, width: 0.18, height: 0.28 }],
    alt: t({ en: 'Storm at night in the lamp room: the keeper speaks into the radio microphone '
      + 'while Maya, wrapped in a blanket, listens.',
      es: 'Noche de tormenta en la sala de la linterna: el farero habla por el micrófono de la '
        + 'radio y Maya, envuelta en una manta, escucha.',
      ca: 'Nit de tempesta a la sala de la llanterna: el faroner parla pel micròfon de la ràdio i '
        + 'la Maya, embolicada amb una manta, escolta.',
      zh: '暴风雨之夜的灯室里,守塔人对着收音机的话筒说话,裹着毯子的玛雅在一旁听着。',
      ar: 'ليلة عاصفة في غرفة الفانوس: الحارس يتكلم في ميكروفون المذياع، ومايا الملتفّة ببطانية '
        + 'تصغي.',
      ja: '嵐の夜の灯室。灯台守が無線のマイクに話しかけ、毛布にくるまったマヤが耳をすます。',
      pt: 'Noite de tempestade na sala da lanterna: o faroleiro fala ao microfone do rádio e '
        + 'Maya, enrolada num cobertor, escuta.',
      fr: 'Nuit de tempête dans la chambre de la lanterne : le gardien parle dans le micro de '
        + 'la radio pendant que Maya, emmitouflée dans une couverture, écoute.',
      de: 'Sturmnacht im Laternenraum: Der Wärter spricht ins Mikrofon des Funkgeräts, während '
        + 'Maya, in eine Decke gewickelt, zuhört.',
      it: 'Notte di tempesta nella stanza della lanterna: il guardiano parla al microfono della '
        + 'radio e Maya, avvolta in una coperta, ascolta.' }) },
  'bk-whisper': { width: 1152, height: 1152,
    safeArea: { x: 0.36, y: 0.26, width: 0.44, height: 0.48 },
    anchors: [{ id: 'maya', x: 0.53, y: 0.47, head: { x: 0.52, y: 0.33 },
      face: { x: 0.41, y: 0.3, width: 0.19, height: 0.22 } },
    { id: 'biscuit', x: 0.625, y: 0.635, head: { x: 0.66, y: 0.57 },
      face: { x: 0.55, y: 0.5, width: 0.25, height: 0.22 } }],
    avoid: [],
    alt: t({ en: 'Under the desk, Maya whispers behind her hand to the frightened orange cat.',
      es: 'Bajo la mesa, Maya le susurra tapándose la boca al gato naranja asustado.',
      ca: 'Sota la taula, la Maya xiuxiueja tapant-se la boca al gat taronja espantat.',
      zh: '桌子底下,玛雅用手挡着嘴,对受惊的橘猫说悄悄话。',
      ar: 'تحت المكتب تهمس مايا من وراء يدها للقط البرتقالي الخائف.',
      ja: '机の下で、マヤが手で口をかくして、おびえたオレンジ色の猫にささやく。',
      pt: 'Debaixo da mesa, Maya cobre a boca com a mão e sussurra para o gato laranja '
        + 'assustado.',
      fr: 'Sous le bureau, Maya chuchote derrière sa main au chat roux effrayé.',
      de: 'Unter dem Schreibtisch flüstert Maya hinter vorgehaltener Hand der verängstigten '
        + 'roten Katze zu.',
      it: 'Sotto la scrivania, Maya sussurra dietro la mano al gatto rosso spaventato.' }) },
  'bk-shout': { width: 880, height: 1100, safeArea: { x: 0.22, y: 0.26, width: 0.46, height: 0.42 },
    anchors: [{ id: 'tomas', x: 0.48, y: 0.47, head: { x: 0.42, y: 0.33 },
      face: { x: 0.25, y: 0.28, width: 0.37, height: 0.32 } }],
    avoid: [{ x: 0.53, y: 0.43, width: 0.17, height: 0.27 }],
    alt: t({ en: 'Close-up of the keeper shouting into the microphone, lit from below by the '
      + 'radio dials.',
      es: 'Primer plano del farero gritando al micrófono, iluminado desde abajo por los diales de '
        + 'la radio.',
      ca: 'Primer pla del faroner cridant al micròfon, il·luminat des de baix pels dials de la '
        + 'ràdio.',
      zh: '守塔人对着话筒大喊的特写,收音机的刻度盘从下方照亮他的脸。',
      ar: 'لقطة قريبة للحارس يصرخ في الميكروفون، وأضواء لوحة المذياع تنيره من أسفل.',
      ja: 'マイクに向かって叫ぶ灯台守のアップ。無線機の目盛りの光が下から顔を照らす。',
      pt: 'Close do faroleiro gritando ao microfone, iluminado de baixo pelos mostradores do '
        + 'rádio.',
      fr: 'Gros plan sur le gardien qui crie dans le micro, éclairé par en dessous par les '
        + 'cadrans de la radio.',
      de: 'Nahaufnahme des Wärters, der ins Mikrofon schreit, von unten von den Skalen des '
        + 'Funkgeräts beleuchtet.',
      it: 'Primo piano del guardiano che grida nel microfono, illuminato dal basso dai '
        + 'quadranti della radio.' }) },
  'bk-sea': { width: 1200, height: 800, safeArea: { x: 0.1, y: 0.19, width: 0.37, height: 0.57 },
    anchors: [{ id: 'skipper', x: 0.28, y: 0.63 }, { id: 'sfx', x: 0.16, y: 0.36 }],
    avoid: [{ x: 0.13, y: 0.52, width: 0.24, height: 0.23 },
      { x: 0.85, y: 0.19, width: 0.08, height: 0.26 }],
    alt: t({ en: 'A small blue trawler heaves on storm waves at night; lightning on the left, the '
      + 'lighthouse beam on the right.',
      es: 'Un pesquero azul cabecea entre las olas de la tormenta; un rayo a la izquierda, el haz '
        + 'del faro a la derecha.',
      ca: 'Un pesquer blau capcineja entre les onades de la tempesta; un llamp a l’esquerra, el '
        + 'feix del far a la dreta.',
      zh: '夜里,一艘蓝色小渔船在暴风雨的浪头上颠簸;左边是闪电,右边是灯塔的光束。',
      ar: 'قارب صيد أزرق صغير يتقاذفه موج العاصفة ليلًا؛ برق على اليسار وشعاع المنارة على اليمين.',
      ja: '夜の嵐の波にもまれる青い小さな漁船。左に稲妻、右に灯台の光。',
      pt: 'Um pequeno barco pesqueiro azul jogado pelas ondas da tempestade à noite; um raio à '
        + 'esquerda, o facho do farol à direita.',
      fr: 'Un petit chalutier bleu tangue la nuit sur les vagues de la tempête ; un éclair à '
        + 'gauche, le faisceau du phare à droite.',
      de: 'Ein kleiner blauer Kutter schlingert nachts in den Wellen des Sturms; links ein '
        + 'Blitz, rechts der Strahl des Leuchtturms.',
      it: 'Un piccolo peschereccio blu sballottato di notte dalle onde della tempesta; un lampo a '
        + 'sinistra, il fascio del faro a destra.' }) },
  'bk-window': { width: 1000, height: 1000,
    safeArea: { x: 0.36, y: 0.27, width: 0.28, height: 0.33 },
    anchors: [{ id: 'maya', x: 0.49, y: 0.41, head: { x: 0.42, y: 0.3 },
      face: { x: 0.41, y: 0.33, width: 0.1, height: 0.13 } }],
    avoid: [{ x: 0.5, y: 0.33, width: 0.1, height: 0.17 },
      { x: 0.83, y: 0.45, width: 0.06, height: 0.08 }],
    alt: t({ en: 'Maya presses her hands and nose to the rainy window, staring out at the storm.',
      es: 'Maya pega las manos y la nariz al cristal mojado y mira la tormenta.',
      ca: 'La Maya enganxa les mans i el nas al vidre mullat i mira la tempesta.',
      zh: '玛雅把双手和鼻子贴在满是雨水的窗户上,望着外面的暴风雨。',
      ar: 'تلصق مايا يديها وأنفها بالزجاج المبلل وتحدّق في العاصفة.',
      ja: 'マヤが雨の窓に両手と鼻を押しつけ、嵐を見つめる。',
      pt: 'Maya cola as mãos e o nariz no vidro molhado e olha a tempestade.',
      fr: 'Maya colle les mains et le nez contre la vitre mouillée et regarde la tempête.',
      de: 'Maya drückt Hände und Nase gegen das regennasse Fenster und starrt hinaus in den '
        + 'Sturm.',
      it: 'Maya preme le mani e il naso contro il vetro bagnato e guarda la tempesta.' }) },
  'bk-morning': { width: 1000, height: 667,
    safeArea: { x: 0.33, y: 0.06, width: 0.42, height: 0.59 },
    anchors: [{ id: 'tomas', x: 0.565, y: 0.25, head: { x: 0.56, y: 0.15 },
      face: { x: 0.51, y: 0.13, width: 0.1, height: 0.17 } },
    { id: 'maya', x: 0.465, y: 0.29, head: { x: 0.45, y: 0.24 },
      face: { x: 0.41, y: 0.19, width: 0.09, height: 0.14 } },
    { id: 'biscuit', x: 0.685, y: 0.58, head: { x: 0.69, y: 0.55 },
      face: { x: 0.64, y: 0.51, width: 0.09, height: 0.11 } }],
    avoid: [{ x: 0.66, y: 0.08, width: 0.08, height: 0.12 },
      { x: 0.34, y: 0.14, width: 0.06, height: 0.08 }],
    alt: t({ en: 'Next morning on the sunny rocks, Maya, the keeper and the cat wave; the '
      + 'lighthouse stands behind them.',
      es: 'A la mañana siguiente, en las rocas al sol, Maya, el farero y el gato saludan; detrás '
        + 'está el faro.',
      ca: 'L’endemà al matí, a les roques al sol, la Maya, el faroner i el gat saluden; darrere '
        + 'hi ha el far.',
      zh: '第二天早上,阳光照着礁石,玛雅、守塔人和猫在挥手;灯塔立在他们身后。',
      ar: 'في الصباح التالي على الصخور المشمسة يلوّح مايا والحارس والقط، والمنارة خلفهم.',
      ja: '翌朝、日の当たる岩の上でマヤと灯台守と猫が手を振る。後ろに灯台が立つ。',
      pt: 'Na manhã seguinte, nas pedras ao sol, Maya, o faroleiro e o gato acenam; atrás deles '
        + 'está o farol.',
      fr: 'Le lendemain matin, sur les rochers au soleil, Maya, le gardien et le chat font signe '
        + 'de la main ; le phare se dresse derrière eux.',
      de: 'Am nächsten Morgen winken Maya, der Wärter und die Katze auf den sonnigen Felsen; '
        + 'hinter ihnen steht der Leuchtturm.',
      it: 'La mattina dopo, sugli scogli al sole, Maya, il guardiano e il gatto salutano con la '
        + 'mano; alle loro spalle si alza il faro.' }) },
};

Each picture carries anchors in fractions of the picture: the mouth a speech tail aims at, the head a thought aims at, the face no balloon may cover (speakers and anchors). The skipper is never drawn: his anchor in the storm picture is the radio set, in the sea picture his boat. When the speaker is not in the panel, tail=right (or left, top, bottom) runs the tail to that edge, and at="44% 22%" pins a balloon's centre to a point of the picture, so it stays there whatever the crop. Two lines in a row from one speaker join into one outline with one tail. left and right are sides of the picture, so the ten editions write the same line for the keeper in the sea panel, whose light stands at the right of the picture: tail=right, read from left to right or from right to left. start and end follow the reading direction of the page instead.

#3 · Give a character a voice of their own

The cast in the short answer gives every skipper: line the radio style, so the script never repeats {radio}. A line can still say otherwise: in the morning panel the skipper calls from his boat, skipper{speech tail=bottom}:, in an ordinary balloon whose tail runs off the foot of the panel.

#4 · Letter each edition in its own faces

script.js · lines 35–42in full code
// The engine's default lettering and sound-effect faces, but for Chinese two ZCOOL faces drawn
// for cartoons. content.<lang>.md holds the words under the same speaker ids.
const [LETTERING, SFX] = t({
  en: ['Comic Neue', 'Bangers'], es: ['Comic Neue', 'Bangers'], ca: ['Comic Neue', 'Bangers'],
  ja: ['Zen Antique', 'Dela Gothic One'], zh: ['ZCOOL KuaiLe', 'ZCOOL QingKe HuangYou'],
  ar: ['Playpen Sans Arabic', 'Lalezar'], pt: ['Comic Neue', 'Bangers'],
  fr: ['Comic Neue', 'Bangers'], de: ['Comic Neue', 'Bangers'], it: ['Comic Neue', 'Bangers'],
});

The same page comes in ten languages: content.<lang>.md holds only the words. The Japanese balloons are set vertically in Zen Antique and its sound effects in Dela Gothic One, the Arabic ones in Playpen Sans Arabic with Lalezar for the thunder. Italics and bold apply where the face has them: the inner voice is italic in English, upright in Japanese (lettering).

The whole recipe

Sandbox
// ═══ Postext Cookbook · Nº 145 · Every kind of balloon on a lighthouse page ═════════
// https://postext.dev/en/cookbook/balloon-kinds
// Code: MIT · Text: original (CC BY 4.0) · Pictures: generated with diffusion models
// Fonts: Comic Neue, Bangers and the faces of five editions (OFL) · Needs postext ≥ 1.28.0
//
// One comic page that uses every kind of balloon the engine draws, with a letterer's style
// sheet in front of it. Each line of the script names its speaker and, when it is not plain
// speech, its kind; the shape, the tail and the type follow from the balloon style.
import {
  buildDocument, withLoadedFonts, renderPageToCanvas, registerResourceImage, loadVerticalAlternates,
} from 'https://esm.sh/postext';
import { renderToPdf, decompressWoff2 } from 'https://esm.sh/postext-pdf';

const LANG = 'en'; // @lang: 'en' | 'es' | 'ca' | 'zh' | 'ar' | 'ja' | 'pt' | 'fr' | 'de' | 'it'
const RECIPE = 'balloon-kinds';

// ─── 1 · Design ─────────────────────────────────────────────────────────────
// #region palette: a storm at night, and the yellow of the captions
const palette = {
  ink: '#18202b', // panel borders, lettering and text: a blue-black
  accent: '#c2412d', // sound effects and the style sheet's labels
  caption: '#f3e3a8', // narration boxes
  inner: '#e4e8ee', // the inner voice: a cold grey-blue
  muted: '#5c6672', // folios and the imprint
  paper: '#fdfbf6',
};
const col = (id) => ({ hex: palette[id], model: 'hex', paletteId: id });
const colorPalette = [
  ...Object.entries(palette).map(([id, hex]) => ({ id, name: id, value: { hex, model: 'hex' } })),
  { id: 'main-color', name: 'accent (defaults)', value: { hex: palette.accent, model: 'hex' } },
];
// #endregion

// #region editions: six editions, each lettered in faces for its script
// The engine's default lettering and sound-effect faces, but for Chinese two ZCOOL faces drawn
// for cartoons. content.<lang>.md holds the words under the same speaker ids.
const [LETTERING, SFX] = t({
  en: ['Comic Neue', 'Bangers'], es: ['Comic Neue', 'Bangers'], ca: ['Comic Neue', 'Bangers'],
  ja: ['Zen Antique', 'Dela Gothic One'], zh: ['ZCOOL KuaiLe', 'ZCOOL QingKe HuangYou'],
  ar: ['Playpen Sans Arabic', 'Lalezar'], pt: ['Comic Neue', 'Bangers'],
  fr: ['Comic Neue', 'Bangers'], de: ['Comic Neue', 'Bangers'], it: ['Comic Neue', 'Bangers'],
});
// #endregion

// #region answer: one balloon style per kind, and a cast that gives the skipper his radio
// A script line is `speaker{kind}: text`. The kinds are balloon styles: the engine ships
// speech, thought, whisper, shout, radio, caption, inner, note and sfx, and a style of the
// same id here changes only what it names. `caption`, `note` and `sfx` are reserved speakers.

The composed script.js runs as it is: paste it into any page’s module script, or open the recipe on CodePen. Recipe folder on GitHub ↗ (opens in a new tab)

Variations

#Use a wavy balloon for a sick or weak voice

Any other id becomes a style of its own, laid over the speech balloon.

 const balloonStyles = [
+  { id: 'weak', shape: 'wavy', stroke: col('ink'), fontScale: 0.9 }, // maya{weak}: …
   { id: 'speech', stroke: col('ink') },

#Join two lines with a neck instead

-  lettering: { fontFamily: LETTERING, fontSize: pt(7.5), color: col('ink'), inset: mm(1) },
+  lettering: { fontFamily: LETTERING, fontSize: pt(7.5), color: col('ink'), inset: mm(1),
+    joinSameSpeaker: 'connector' },

Pitfalls

  • A pin is a point of the picture, kept whatever the crop. A sound effect pinned so near the edge that it would leave the panel (KRA-KOOM at at="16% 28%") is slid back inside, so it may sit a little off the point written.
  • An off-panel voice is lettered by the border its tail points to: the skipper's thanks, tail=bottom, sits at the foot of the morning panel although it is the panel's first line. Point the tail at the top border when such a line has to be read first.

Credits

Text
Original prose, CC BY 4.0
Images
  • Panel picture: the storm in the lamp room · Generated With Diffusion Models · original
  • Panel picture: Maya and the cat under the desk · Generated With Diffusion Models · original
  • Panel picture: the keeper shouting into the microphone · Generated With Diffusion Models · original
  • Panel picture: the trawler in the storm · Generated With Diffusion Models · original
  • Panel picture: Maya at the window · Generated With Diffusion Models · original
  • Panel picture: the next morning on the rocks · Generated With Diffusion Models · original
Fonts
Comic Neue (SIL OFL 1.1) · Bangers (SIL OFL 1.1) · Zen Antique (SIL OFL 1.1) · Dela Gothic One (SIL OFL 1.1) · ZCOOL KuaiLe (SIL OFL 1.1) · ZCOOL QingKe HuangYou (SIL OFL 1.1) · Playpen Sans Arabic (SIL OFL 1.1) · Lalezar (SIL OFL 1.1)
SandboxPDF