.dex Format Specification

Frontmatter

Every .dex file starts with YAML frontmatter delimited by ---. The frontmatter contains metadata about the document.

---
docex: "0.4.0"
title: "The Effects of Social Media on Sleep Quality"
authors:
  - name: "Alex Chen"
  - name: "Jordan Park"
keywords: "social media, sleep quality, screen time"
subject: "Health Psychology"
---

Field	Description
docex	Version of the .dex format (required)
title	Document title
authors	List of author names
keywords	Document keywords
subject	Document subject

Headings

Headings use Markdown-style # syntax. The number of # characters indicates the heading level. An optional paragraph ID can appear at the end in {id:XXXX} format.

# Title (Heading 1) {id:BABCF972}

## Introduction {id:A1B2C3D4}

### Data Collection {id:E5F6A7B8}

#### Sub-subsection {id:C9D0E1F2}

Heading levels 1 through 6 are supported, matching HTML <h1> through <h6> and Word's Heading 1 through Heading 6 styles.

Paragraphs

Paragraphs are wrapped in {p} / {/p} tags. The optional id: attribute is a stable paragraph identifier that survives other edits.

{p id:7AF60E6B}
This is a paragraph of text. It can contain inline formatting,
tracked changes, and footnote references.
{/p}

The paragraph ID is a hex string assigned by Word (via the w14:paraId attribute). When you edit a .dex file, keep the IDs intact so that docex can match paragraphs back to the original .docx structure.

Inline formatting

Formatting uses curly-brace tags that wrap the formatted text.

Syntax	Renders as	Word equivalent
{b}bold text{/b}	bold text	Bold
{i}italic text{/i}	italic text	Italic
{u}underlined{/u}	underlined	Underline
{sup}superscript{/sup}	superscript	Superscript
{sub}subscript{/sub}	subscript	Subscript

Tags can be nested:

{b}{i}bold and italic{/i}{/b}
{u}{b}underlined bold{/b}{/u}

Extended formatting

Beyond the basic bold/italic/underline tags, .dex supports additional character formatting that maps to Word's extended run properties.

{strike}strikethrough{/strike}
{dstrike}double strikethrough{/dstrike}
{size 28}14pt text{/size}           (value in half-points)
{smallcaps}Small Caps{/smallcaps}
{caps}ALL CAPS{/caps}
{hidden}hidden text{/hidden}
{u double}double underline{/u}
{u wave}wave underline{/u}

Syntax	Renders as	Word equivalent
{strike}text{/strike}	strikethrough	Strikethrough
{dstrike}text{/dstrike}	double strikethrough	Double Strikethrough
{size N}text{/size}	Sized text	Font size (N = half-points, so 28 = 14pt)
{smallcaps}text{/smallcaps}	Small Caps	Small Caps
{caps}text{/caps}	ALL CAPS	All Caps
{hidden}text{/hidden}	(not visible)	Hidden text

Underline types

The {u} tag accepts an optional type parameter. When no type is specified, single is assumed.

{u}default single underline{/u}
{u double}double underline{/u}
{u wave}wavy underline{/u}
{u dotted}dotted underline{/u}

Type	Description
single	Single underline (default)
double	Double underline
dotted	Dotted underline
dottedHeavy	Heavy dotted underline
dash	Dashed underline
dashLong	Long-dash underline
dashLongHeavy	Heavy long-dash underline
dotDash	Dot-dash underline
dotDotDash	Dot-dot-dash underline
wave	Wavy underline
wavyHeavy	Heavy wavy underline
wavyDouble	Double wavy underline
thick	Thick underline
words	Underline words only (not spaces)

Font, color, and highlight

These tags preserve the exact font face, text color, and highlight color from the original Word document.

{font "Times New Roman"}text in Times{/font}
{font "Arial"}{b}bold Arial text{/b}{/font}

{color FF0000}red text{/color}
{color 0000FF}blue text{/color}

{highlight yellow}highlighted{/highlight}
{highlight cyan}cyan highlight{/highlight}

Tag	Value format	Examples
{font "name"}	Font family name in quotes	"Times New Roman", "Arial", "Jokerman"
{color XXXXXX}	6-digit hex color (no #)	FF0000 (red), 0000FF (blue)
{highlight name}	Word highlight color name	yellow, cyan, magenta, red, green, darkYellow

All three can be combined and nested with other formatting:

{font "Ravie"}{color 990000}{u}{b}Very fancy text{/b}{/u}{/color}{/font}

Comments and replies

Comments appear as block elements after the paragraph they are anchored to.

{comment id:0 by:"The Intern" date:"2024-05-13T22:00:00.000Z"}
WHO WROTE THIS???
{/comment}

Replies are threaded under their parent comment:

{comment id:1 by:"Reviewer 2" date:"2026-03-15T10:00:00Z"}
This section needs a citation for the claim about effect sizes.
{/comment}

{reply id:2 parent:1 by:"Alex Chen" date:"2026-03-16T14:00:00Z"}
Added Johnson 2022 and Williams 2020.
{/reply}

Attribute	Description
id:N	Unique comment identifier (integer)
by:"Name"	Author of the comment
date:"ISO8601"	Timestamp of the comment
parent:N	(Replies only) ID of the parent comment

Comment anchors

Comments can be anchored to specific text within a paragraph using inline {comment-start} and {comment-end} markers. The id attribute links the markers to the corresponding comment block.

{p id:ABC123}
We address the {comment-start id:0}regulatory gap{comment-end id:0} in governance.
{/p}

{comment id:0 by:"Reviewer 2"}
Clarify what you mean here.
{/comment}

The {comment-start id:X} and {comment-end id:X} markers wrap the exact text the comment is anchored to. The id links them to the {comment} block that contains the comment text. This preserves Word's precise comment anchoring so that the yellow highlight appears on the correct span of text after round-tripping.

Tracked changes (del/ins)

Tracked changes appear inline within paragraphs. Deletions use {del} and insertions use {ins}.

{p id:7AF60E6B}
We analyzed {del id:17 by:"Research Assistant" date:"2026-03-18T14:39:03Z"}12,847 records{/del}{ins id:18 by:"Research Assistant" date:"2026-03-18T14:39:03Z"}12,847 records extracted from the research dataset{/ins} during the study period.
{/p}

A replacement is a {del} immediately followed by an {ins} with the same author and date.

Tag	Word display	Meaning
{del ...}text{/del}	text	Deleted text (strikethrough)
{ins ...}text{/ins}	text	Inserted text (added)

Attributes are the same as comments: id:N, by:"Name", date:"ISO8601".

Move tracking

When text is moved from one location to another with Track Changes enabled, Word records both the source and destination. The .dex format preserves this with {movefrom} and {moveto} tags.

{p id:1A2B3C4D}
{movefrom id:1 by:"Author" date:"2026-03-18"}moved text{/movefrom}
{/p}

{p id:5E6F7A8B}
{moveto id:2 by:"Author" date:"2026-03-18"}moved text{/moveto}
{/p}

Tag	Word display	Meaning
{movefrom ...}text{/movefrom}	moved text	Original location (text was moved away)
{moveto ...}text{/moveto}	moved text	New location (text was moved here)

Attributes are the same as tracked changes: id:N, by:"Name", date:"ISO8601".

Format change tracking

When formatting (but not text) is changed with Track Changes enabled, Word records the revision. The .dex format uses {fmtchange} for this.

{p id:9C0D1E2F}
{fmtchange by:"Author" date:"2026-03-18"}text with changed formatting{/fmtchange}
{/p}

The tag wraps the text whose formatting was modified. The actual formatting (bold, italic, font, etc.) is represented by the normal inline formatting tags inside or around the {fmtchange}. Attributes are the same as other tracked changes: id:N (optional), by:"Name", date:"ISO8601".

Tables

Tables use a combination of a header tag and pipe-delimited rows (similar to Markdown tables).

{table style:TableGrid cols:3}
| Study | N | Effect Size |
|---|---|---|
| Smith 2023 | 342 | d = 0.45 |
| Lee 2022 | 289 | d = 0.38 |
| Garcia 2021 | 156 | d = 0.52 |
{/table}

Attribute	Description
style:name	Word table style (e.g., TableGrid, plain)
cols:N	Number of columns

The first row is treated as the header. The separator row (|---|---|---|) is required.

Figures

Figures preserve the image reference, dimensions, and alt text from the original .docx.

{figure id:3A7F2B1C rId:rId5 src:"word/media/image1.png" width:5486400emu height:3657600emu alt:"Forest plot"}
Figure 1. Forest plot showing effect sizes across studies.
{/figure}

Attribute	Description
id:XXXX	Paragraph ID
rId:rIdN	Relationship ID linking to the image file
src:"path"	Path to the image within the .docx zip
width:Nemu	Width in English Metric Units
height:Nemu	Height in English Metric Units
alt:"text"	Alt text for the image

The text between the tags is the figure caption.

Footnotes

Footnotes appear inline at the point of reference. The footnote text is included between the tags.

{p id:7E011118}
The strategic alignment of our core competencies{footnote id:2}Citation needed. Actually, everything needs a citation.{/footnote} has resulted in a net-positive disruption.
{/p}

The id:N attribute is the footnote number. When compiled back to .docx, the footnote is placed in the footnotes.xml part and a reference is inserted at the correct position.

Endnotes

Endnotes work similarly to footnotes, but are collected at the end of the document (or end of a section). An inline reference marks the endnote location, and the definitions appear in a dedicated block.

{p id:3A4B5C6D}
We found significant results{endnote id:1}.
{/p}

{endnotes}
{endnote-def id:1}
See the supplementary materials for the complete dataset.
{/endnote-def}
{/endnotes}

Tag	Description
{endnote id:N}	Inline endnote reference (placed at the point of reference in text)
{endnotes}...{/endnotes}	Block containing all endnote definitions
{endnote-def id:N}...{/endnote-def}	Individual endnote definition (the id links back to the inline reference)

Line, column, and page breaks

Several types of breaks are supported as standalone tags.

{br}                    Soft line break (Shift+Enter in Word)
{colbreak}              Column break
{pagebreak}             Page break

Tag	Word XML	Description
{br}	<w:br/>	Soft line break within a paragraph (like Shift+Enter)
{colbreak}	<w:br w:type="column"/>	Column break (forces text to the next column)
{pagebreak}	<w:br w:type="page"/>	Page break (forces text to the next page)

The {br} tag is inline and can appear within a paragraph. The {pagebreak} and {colbreak} tags typically appear on their own line.

Bookmarks

Bookmarks mark named locations in the document that can be referenced by hyperlinks, cross-references, and field codes.

{bookmark-start id:1 name:"_Ref123"}
This text is bookmarked.
{bookmark-end id:1}

Attribute	Description
id:N	Unique bookmark identifier (integer)
name:"text"	Bookmark name (used for cross-references; names starting with _ are auto-generated by Word)

Bookmarks can span multiple paragraphs. The {bookmark-start} and {bookmark-end} markers do not need to be in the same paragraph.

Hyperlinks

Hyperlinks come in two forms: relationship-based (external URLs) and bookmark-based (internal cross-references).

{link rId:rId5}Click here{/link}           (relationship-based)
{link anchor:"_Ref123"}See above{/link}    (bookmark-based)

Attribute	Description
rId:rIdN	Relationship ID pointing to an external URL (defined in document.xml.rels)
anchor:"name"	Internal bookmark name to link to

The text between the tags is the visible link text. A hyperlink uses either rId or anchor, not both.

Symbols

Special symbol characters from fonts like Symbol or Wingdings are represented with the {sym} tag.

{sym F0B7}              Symbol character (hex char code)

The value is a hexadecimal character code. This maps to <w:sym w:char="F0B7"/> in Word XML. The font for the symbol is typically inherited from the run properties.

Tabs

Tab characters are preserved as literal tab characters (\t) in .dex text. They map to <w:tab/> elements in the Word XML.

{p id:1A2B3C4D}
Name	Score	Grade
Alice	95	A
Bob	87	B+
{/p}

Each tab stop in the original document is represented by one tab character in the .dex file. Tab stop positions and alignment are defined as part of paragraph or style properties in the original .docx.

Paragraph properties

Paragraphs can carry detailed formatting properties as attributes on the {p} tag. These map to the <w:pPr> element in Word XML.

{p id:ABC align:center style:"Quote" indent-left:720 spacing-line:360 list-id:1 list-level:0 bidi keepnext}
This paragraph has properties.
{/p}

Attribute	Value	Description
align	left, center, right, both	Paragraph alignment (both = justified)
style	"StyleName"	Named paragraph style
indent-left	twips	Left indent (1440 = 1 inch)
indent-right	twips	Right indent
indent-first	twips	First-line indent
indent-hanging	twips	Hanging indent
spacing-line	twips or value	Line spacing (360 = 1.5 lines when spacing-rule is auto)
spacing-before	twips	Space before paragraph
spacing-after	twips	Space after paragraph
spacing-rule	auto, exact, atLeast	Line spacing rule
list-id	integer	Numbering definition ID (links to list definition)
list-level	integer	List nesting level (0-based)
bidi	(flag)	Right-to-left paragraph direction
keepnext	(flag)	Keep with next paragraph (prevents page break between)

Flag attributes (bidi, keepnext) are present when the property is enabled and absent when disabled. All other attributes use key-value syntax.

Field codes

Word field codes (page numbers, cross-references, tables of contents, etc.) are represented with {field} tags. The field instruction appears in quotes, and the current cached result is the text between the tags.

{field "PAGE"}3{/field}
{field "HYPERLINK \"https://example.com\""}Example{/field}
{field "TOC \\o \"1-3\""}Table of Contents{/field}

Component	Description
Field instruction	The quoted string after {field (e.g., "PAGE", "TOC \\o \"1-3\"")
Field result	The text between {field ...} and {/field} (the cached display value)

Field codes are preserved for lossless round-tripping. The result text is what Word displays; the instruction tells Word how to compute it. Escaped quotes within the instruction use \".

Content controls (SDT)

Structured document tags (SDTs) represent content controls such as bibliographies, tables of contents, and form fields.

{sdt "Bibliography"}bibliography content{/sdt}

Attribute	Description
Tag name (quoted string)	The SDT tag or alias identifying the content control type

The text between the tags is the content of the control. Content controls are commonly used by Word for auto-generated structures like bibliographies and cover pages.

Headers and footers

Document headers and footers are represented as named blocks with a reference to their source XML file.

{header file:"header1.xml"}
Header text content
{/header}

{footer file:"footer1.xml"}
Footer text content
{/footer}

Tag	Description
{header file:"name.xml"}	Page header (maps to a header part in the .docx)
{footer file:"name.xml"}	Page footer (maps to a footer part in the .docx)

The file attribute identifies which header/footer XML part this corresponds to. The text between the tags can contain the same inline formatting, paragraphs, and other elements as the document body.

Math equations

Math equations from Word's equation editor are represented with a {math} tag. The raw OOXML math markup is base64-encoded for lossless round-tripping, while the text between the tags provides a human-readable approximation.

{math data:BASE64ENCODED}x = y + z{/math}

Component	Description
data:BASE64	Base64-encoded OOXML math XML (<m:oMath>...</m:oMath>)
Text content	Human-readable representation of the equation

The data attribute ensures that the equation can be perfectly reconstructed when compiling back to .docx. The visible text is an approximation for readability when editing the .dex file.

Text boxes

Text boxes (floating or inline) are represented with {textbox} tags.

{textbox}Content inside a text box{/textbox}

The content between the tags can include paragraphs, inline formatting, and other block elements just like the document body. Text boxes map to Word's <w:txbxContent> elements.

Ruby text (phonetic guides)

Ruby text provides phonetic annotations above base text, commonly used in East Asian languages.

{ruby base:"漢字"}かんじ{/ruby}

Component	Description
base:"text"	The base text being annotated
Text content	The ruby (phonetic) annotation displayed above the base

This maps to Word's <w:ruby> element. The base text is displayed at normal size and the ruby text appears as a smaller annotation above it.

Embedded objects

Embedded OLE objects (Excel sheets, Visio diagrams, etc.) are represented with the {object} tag.

{object type:"Excel.Sheet.12"}

Attribute	Description
type:"ProgID"	The OLE program identifier for the embedded object

The actual object data is stored in the .docx package as a binary part. The {object} tag preserves the reference for round-tripping.

Soft and non-breaking hyphens

Special hyphen characters are preserved as their Unicode equivalents in .dex text.

Character	Unicode	Description
Soft hyphen	U+00AD	Invisible hyphen that only appears at line breaks. Maps to <w:softHyphen/>.
Non-breaking hyphen	U+2011	Hyphen that prevents a line break. Maps to <w:noBreakHyphen/>.

These characters are not visible in most text editors but are preserved during round-tripping to maintain the document's hyphenation behavior.

Section properties

Section-level formatting (margins, page size, orientation, columns) appears at the end of the document or between sections. The basic form specifies only margins:

{section margins:"1440 1440 1440 1440"}

The extended form supports the full range of section properties:

{section type:continuous orient:landscape pgw:15840 pgh:12240 cols:2 colspace:720 margins:"1440,1440,1440,1440,720,720,0" pgstart:1}

Attribute	Value	Description
type	nextPage, continuous, evenPage, oddPage	Section break type
orient	portrait, landscape	Page orientation
pgw	twips	Page width (12240 = 8.5 inches)
pgh	twips	Page height (15840 = 11 inches)
cols	integer	Number of columns
colspace	twips	Space between columns
margins	"top,right,bottom,left,header,footer,gutter"	Page margins in twips (comma-separated; the short form "T R B L" with spaces is also accepted)
pgstart	integer	Starting page number for the section

All values are in twips (1/1440 of an inch). For example, 1440 equals 1 inch and 720 equals 0.5 inches.

Escaping

Since curly braces { and } are used for tags, literal braces in document text must be escaped with a backslash.

{p id:ABC123}
The function signature is f\{x\} = x + 1.
{/p}

Escape	Produces
\{	{
\}	}
\\	\