Overview
Quick Start
Bash
git clone https://github.com/nxxxsooo/mdx2apple.git
cd mdx2apple
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
# Install Dictionary Development Kit separately if needed:
git clone https://github.com/ikey4u/macddk.git \
"$HOME/Library/Developer/Dictionary-Development-Kit"
python mdx2apple.py /path/to/dictionary.mdx \
--output ./output/my-dictionary \
--keep-resources --install
Features
- Automated Pipeline - One command to convert, compile, and install
- Complete Content - Keeps definitions, examples, translations, idioms and parts of speech
- Aliases and Homographs - Resolves chained redirects while preserving separate records
- Pronunciation and Images - Native audio controls and expandable illustrations
- Oxford Dark Mode - Readable text, IPA, translations, links and reference boxes
- Separate Metadata - Full names, compact tab labels, publisher, copyright and conversion credits
Challenges Solved
- CSS display:block - Fixed missing entry visibility
- Content Loss - Replaced selective HTML extraction with complete record preservation
- Large Resource Sets - Builds outside the resource directory, avoiding shell argument limits
- Source References - Adapts valid dictionary links and reports missing supplemental content
Updating
Limitations
- Original dictionary scripts are not executed; script-dependent behavior may need an adapter.
- Missing source audio and supplemental articles cannot be reconstructed.
- Audio codecs and system Look Up behavior depend on the native host. WebKit playback checks do not guarantee identical behavior in every host.
- Dictionary files are supplied by the user and are not included in the repository.
