Published on 2026-02-22

Bytefield Diagrams in Markdown

How to draft bytefields and bit-level protocol documentation.

Bytefield is a tool heavily utilized by systems and protocol engineers to describe network packet layouts, memory mappings, and register structures.

MarkdownToPrettyPDF lets you define Bytefield diagrams using text mapped to a bytefield fence.

Basic Syntax

Bytefield relies on a LaTeX-inspired DSL. You organize your layout by specifying rows, offsets, and bit boundaries.

syntax

(defattrs :bg-green {:fill "#a0ffa0"})
(defattrs :bg-yellow {:fill "#ffffa0"})
(defattrs :bg-pink {:fill "#ffb0a0"})
(defattrs :bg-cyan {:fill "#a0fafa"})
(defattrs :bg-purple {:fill "#e4b5fd"})

(align-left
  (draw-column-headers)

  (draw-box 8 :color "yellow" :span 2)
  (draw-box 8 :color "pink" :span 2)
  (draw-box 16 :color "cyan" :span 4)

  (draw-box "payload" :span 8)
)

Detailed Packet Description

For complex network packets like IPv4 headers, Bytefield thrives:

syntax

(draw-column-headers
  {:labels (range 32)})

(draw-box "Version" {:span 4})
(draw-box "IHL" {:span 4})
(draw-box "DSCP" {:span 6})
(draw-box "ECN" {:span 2})
(draw-box "Total Length" {:span 16})

(draw-box "Identification" {:span 16})
(draw-box "Flags" {:span 3})
(draw-box "Fragment Offset" {:span 13})

(draw-box "Time To Live" {:span 8})
(draw-box "Protocol" {:span 8})
(draw-box "Header Checksum" {:span 16})

(draw-box "Source IP Address" {:span 32})

(draw-box "Destination IP Address" {:span 32})

Bytefield diagrams explicitly describe standard protocol communication directly inside your markdown documentation instead of relying on ascii-art equivalents.