#Interface: GukhanmunOptions

Full set of options passed to GukhanmunFactory.load (or the top-level load function) to configure a Gukhanmun instance.

All fields are optional. When a preset is specified it supplies defaults; individual fields override those defaults. When no preset is given, "ko-kr" is implicitly used.

#Properties

#collapseRedundantParens?

readonly optional collapseRedundantParens?: boolean

Whether to collapse redundant parenthetical reading annotations. Defaults to true.

When enabled, an explicit gloss such as 庫間(곳간) or 곳간(庫間) is recognised, the redundant parenthetical is removed, and the annotation is shown in both scripts in every render mode. A parenthetical that pins an alternative reading (for example 數字(수자)) overrides the dictionary reading for that occurrence. A parenthetical that is a definition rather than a reading (for example 庫間(물건을 간직하여 두는 곳)) is left untouched.

---

#dictionaries?

readonly optional dictionaries?: readonly FileDictionarySource[]

Ordered list of dictionary sources. Sources are queried in order; earlier entries take precedence. When omitted (or empty), only the fallback Unihan character map is used (no bundled dictionaries).

JavaScript presets do not automatically include bundled dictionary data. To use the Standard Korean Language Dictionary, add @gukhanmun/stdict-fst or @gukhanmun/stdict-cdb explicitly. To use Open Korean Dictionary categories, add @gukhanmun/opendict-fst or @gukhanmun/opendict-cdb explicitly.

#See

DictionarySource

---

#directives?

readonly optional directives?: Directives

Per-hanja rendering directives that override dictionary marks.

#See

Directives

---

#firstOccurrenceWindow?

readonly optional firstOccurrenceWindow?: ContextWindow

Context window for first-occurrence filtering. The FirstOccurrenceFilter middleware clears requireHanja / requireHangul on repeated occurrences of the same word within this window, so the gloss appears only the first time. Defaults to "off" (filter disabled) in both presets.

#See

ContextWindow

---

#homophoneDetection?

readonly optional homophoneDetection?: HomophoneDetection

Strategy that decides which readings count as homophones needing a hanja gloss. Defaults to "context-local", which glosses a reading only when a different-meaning homophone appears within homophoneWindow. Use "dictionary-wide" to also gloss readings shared by other dictionary entries.

#See

HomophoneDetection

---

#homophoneWindow?

readonly optional homophoneWindow?: ContextWindow

Context window for homophone disambiguation. The HomophoneMarker middleware sets homophone = true on annotations whose hangul reading collides within this window. Defaults to "per-block".

#See

ContextWindow

---

#html?

readonly optional html?: HtmlOptions

HTML-specific preservation rules. Ignored for non-HTML input formats.

#See

HtmlOptions

---

#initialSoundLaw?

readonly optional initialSoundLaw?: boolean

Whether to apply the Korean initial sound law (頭音法則) to fallback phonetic readings. Defaults to true for "ko-kr" and false for "ko-kp".

Note: dictionary entries are assumed to encode the correct reading already; this flag only affects the character-by-character fallback path.

---

#numerals?

readonly optional numerals?: NumeralStrategy

How runs of hanja numerals are converted. Defaults to "hangul-phonetic".

#See

NumeralStrategy

---

#originalGloss?

readonly optional originalGloss?: OriginalGloss

How glosses are rendered when rendering is "original". Ignored for all other render modes. Defaults to "parens".

#See

OriginalGloss

---

#preset?

readonly optional preset?: Preset

Named configuration preset. Defaults to "ko-kr".

#See

Preset

---

#recovery?

readonly optional recovery?: Recovery

Error recovery policy for HTML scanning. Defaults to "strict". Ignored for non-HTML input formats.

#See

Recovery

---

#rendering?

readonly optional rendering?: RenderMode

How annotations are rendered into output text or markup. Defaults to "hangul-only".

#See

RenderMode

---

#segmentation?

readonly optional segmentation?: Segmentation

Hanja-span segmentation algorithm. Defaults to "lattice".

#See

Segmentation