Arabic Documents

Arabic Documents

Produce Arabic and bilingual documents that read as native Arabic work — fit to hand to officials, teams, or customers — across HTML, DOCX, PPTX, and PDF.

The One Principle

> Never fix Arabic layout visually. Fix it structurally.

Most broken Arabic output sets alignment (align right) instead of direction (RTL base). Alignment only moves the block; base direction governs punctuation placement, bracket mirroring, bullet position, and mixed-text order. Set direction correctly at the container level and ~80% of defects disappear on their own.

Three structural guarantees carry everything:

1. Base direction = RTL on every container (paragraph, list, cell, text box) — never

alignment-only.

1. Isolate embedded runs (Latin words, numbers, URLs) so they can't reorder surrounding

Arabic or split bracket pairs.

1. Use a bidi/shaping-compliant renderer (Unicode Bidi Algorithm + Bracket Pairing

Algorithm + OpenType shaping).

Workflow

For every Arabic/bilingual document, run these four steps in order:

1. Gather options

• format: html | docx | pptx | pdf
• locale: levantine | gulf | egyptian | maghrebi | msa-neutral (affects month names, habits)
• numeralPolicy: eastern | western | context-aware (see references/numerals.md)
• tashkeel: on | off (on for poetry, names, certificates; off for body prose)
• docType: letter | report | certificate | invitation | cv | contract | presentation | record

If the user hasn't specified, pick sensible defaults and state them; don't block on trivia.

2. Normalize the content (format-free)

Apply, in this order — details in references/punctuation.md and references/bidi-and-direction.md:

• Substitute Arabic punctuation for Latin: ، ؛ ؟ » « (not , ; ? " ").
• Apply the numeral policy as a final pass (so it can be flipped without editing content).
• Isolate every Latin/number/URL/email/code run (` in HTML, FSI…PDI ⁨…⁩` elsewhere).
• Un-flip any inherited pre-flipped brackets — brackets must be in logical order (…),

never manually reversed )…(.

• Apply locale month names for any dates (references/locales.md).
• Treat proper names (esp. family names) and tashkeel as sacred tokens — never alter.

3. Render with structural direction

Emit base direction at the container level for the chosen format — never alignment alone. See references/per-format.md for the exact mechanism per format and for lists/tables. Embed a vetted Arabic font (references/fonts.md). For PDF, always route through a BPA-compliant engine (HTML→Chromium/WeasyPrint), never a shaping-blind PDF library.

4. Validate before delivering

Run the checklist in references/validation.md. Any 🔴 failure blocks the artifact — fix and re-render rather than shipping. 🟡 items are native-feel warnings worth resolving.

Brackets — the most misunderstood part

• There is no separate "Arabic parenthesis." ( ) [ ] « » are mirrored

characters: same code point, glyph flips in RTL.

• Always type in logical order — opening first, closing second. Never pre-flip.

Pre-flipped )…( breaks on copy-paste and double-inverts in correct renderers.

• Inverted brackets = a direction/pairing failure, not a character problem. Either the

base direction is wrong, or a bracketed Latin/number run isn't isolated. Fix those two.

• Distinct Arabic ornamental brackets exist only for Quranic markers: ﴾ ﴿.

Definition of Done

RTL base on every container · Arabic punctuation glyphs · isolated Latin/number runs · consistent policy-correct numerals · lists (marker-right, indent-left, in-policy numbering, correct nesting) · tables (columns right→left, cells RTL, numeric columns handled) · brackets in logical order mirroring correctly · proper shaping with an embedded Arabic font, no tofu · correct locale month names · generous line-height, no kashida rivers, display headings · copy-paste yields clean Unicode.

Reference files

• references/bidi-and-direction.md — UBA/BPA, base direction, isolation, mirroring
• references/punctuation.md — Arabic punctuation substitution table
• references/numerals.md — numeral policy and digit tables
• references/locales.md — month names and per-region conventions
• references/fonts.md — vetted fonts and embedding notes
• references/per-format.md — per-format enforcement (HTML/DOCX/PPTX/PDF), lists, tables
• references/validation.md — the pass/fail checklist (🔴 blocks, 🟡 warns)
• examples/golden-fixtures.md — regression strings that must render correctly everywhere

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mamounjamous
• Source: mamounjamous/arabic-documents-skill
• License: MIT

Install and usage instructions live in the source repository linked above.