How ethereum/remix-ide works
Project Type & Purpose
• Type: Static documentation site (Sphinx + Read-the-Docs).
• Purpose: Provide user/developer documentation for the Remix IDE platform, with internationalization (i18n) support, theme customization, and a plugin-centric docs structure.
File Structure
• Top level
• .readthedocs.yaml – RTD build configuration
• README.md – high-level instructions
• docs/ – Sphinx documentation source
• Inside docs/
• conf.py – Sphinx config (extensions, theme, JS/CSS includes)
• .rst / .md content files – user-facing docs
• _static/ – CSS & JS overrides for theming
• _build/ – generated output (HTML, gettext catalogs)
• locale/ – .po/.pot translation files
• Makefile/make.bat – build scripts
• requirements.txt – Python dependencies
• CI & Translation
• crowdin.yml – Crowdin sync configuration
• Locale directories under docs/locale/… for supported languages
Important README Insights
• Build steps use a Python venv with sphinx, sphinx_rtd_theme, myst-parser.
• Custom theming is applied via CSS (fonts.css, tokens.css, custom.css) and JS (constants.js, utils.js, loaders.js, initialize.js).
• Hosting is on Read-the-Docs with a badge & configuration; local testing via python3 -m http.server.
• Translators use Crowdin; do not edit .po/.pot locally.
Main Components
A. Developer Workstation
• Python Virtual Environment (venv)
• Git & GitHub repo clone
• Editor/IDE
B. Source Repository (GitHub)
• docs/ directory (content + config + static + locale)
• CI config (.readthedocs.yaml, crowdin.yml)
C. Build Toolchain
• Sphinx Parser & Builder
• Extensions: myst-parser, sphinx_rtd_theme
• Makefile / make html
D. Static Asset Pipeline
• CSS & JS overrides in _static/
• Transpiled / copied by Sphinx into _build/html/_static/
E. Internationalization
• .pot extraction into docs/_build/gettext/
• .po files under docs/locale/<lang>/LC_MESSAGES/
• Crowdin synchronizes translations back into repo
F. Output Artifacts
• HTML files under docs/_build/html/
• Served locally via http.server or remotely on Read-the-Docs
G. External Services
• Read-the-Docs build servers
• Crowdin (translation management)
• Optional: GitHub Actions or other CI for PR checks
Relationships & Interactions
• Developer → GitHub: push/pull content & config
• GitHub → Read-the-Docs: pushes trigger RTD build via .readthedocs.yaml
• Sphinx Builder (local or RTD)
• Reads docs/* (content + conf.py)
• Applies CSS/JS from _static/
• Generates HTML & gettext catalogs
• Crowdin ↔ docs/locale/*:
• Crowdin pulls new .pot files
• Translators update .po on Crowdin
• Crowdin pushes new .po back into repo
• Final HTML → Web UI (remix-ide.readthedocs.io)
Important Architectural Patterns & Principles
• Static Site Generation (SSG) via Sphinx
• Separation of concerns:
• Content (.md/.rst) vs theming (CSS/JS) vs configuration (conf.py)
• I18n pipeline extracted & managed externally
• Plugin-centric docs: each doc module loosely maps to a Remix plugin or feature
• Arrowheads indicating data flow (push, pull, build output)