diff --git a/plugins/tutor-contrib-paragon/README.rst b/plugins/tutor-contrib-paragon/README.rst index 85e0f23..aa336d6 100644 --- a/plugins/tutor-contrib-paragon/README.rst +++ b/plugins/tutor-contrib-paragon/README.rst @@ -1,151 +1,335 @@ -Paragon plugin for `Tutor `__ -########################################################### +.. _tutor_contrib_paragon: -Facilitates the generation and static hosting of Paragon-based CSS themes for Open edX Micro-Frontend (MFE) applications using `Paragon `__. +##################### +Tutor Paragon Plugin +##################### + +.. contents:: Table of Contents + :local: + +Introduction +============ + +What is the Tutor Paragon Plugin? +--------------------------------- + +The **Tutor Paragon Plugin** (`tutor-contrib-paragon`) enables developers and operators to compile Paragon design tokens into CSS themes using the Paragon CLI and serve those themes to Open edX Micro-Frontends (MFEs) via Tutor. + +It wraps the Paragon CLI build process, manages token source directories and output paths, and exposes compiled themes through Tutor's static hosting infrastructure. + +What problem does it solve? +--------------------------- + +This plugin simplifies MFE theme customization by: + +* Standardizing how Paragon tokens are compiled. +* Automatically placing output files in a consistent, hostable location. +* Enabling static delivery of CSS files for MFE consumption. +* Supporting tenant-based theme overrides with flexible configuration. + +Target Audience +--------------- + +* Open edX developers customizing MFE themes. +* Operators managing theming at scale. +* Designers experimenting with visual tokens in real-time environments. + +Prerequisites +============= + +* A working Tutor environment with Docker. +* Familiarity with Paragon design tokens and MFE architecture. +* Basic understanding of Tutor’s plugin system and configuration management. +* Tutor Plugin MFE installed and enabled. + + +Version Compatibility +===================== + +To use this plugin, ensure you're running compatible versions of Open edX and its dependencies: + +* **Paragon >= 23** +* **Open edX "Teak" release (Tutor >= 20)** +* **Tutor >= 20** + +**πŸ’‘ Note:** + Design token functionality is available starting from Paragon v23 and the Open edX "Teak" release. + While the plugin is expected to support future versions (e.g., Tutor 21+), major releases may introduce breaking changes. + + + +**⚠️ Warning:** + As of now, the plugin's `pyproject.toml` specifies: + +:: + + tutor>=19.0.0,<21.0.0 + +This constraint may be relaxed once upstream changes in `tutor-mfe` are released: + * https://github.com/overhangio/tutor-mfe/pull/267 + * https://github.com/overhangio/tutor-mfe/pull/264 -This plugin provides a local folder structure to manage **design token-based theme source files** (see `Paragon Design Tokens `__) and compile them into CSS, enabling flexible customization of Open edX MFEs via Tutor. Installation -************ +============ -.. code-block:: bash +**πŸ’‘ Note:** + A future version may be available via PyPI. For now, use the development installation method. - pip install git+https://github.com/openedx/openedx-tutor-plugins.git#subdirectory=plugins/tutor-contrib-paragon +Development Install +------------------- -For development: +Clone the repository and install in editable mode: .. code-block:: bash + git clone https://github.com/openedx/openedx-tutor-plugins.git cd openedx-tutor-plugins/plugins/tutor-contrib-paragon pip install -e . -Enable the plugin: +Enable the Plugin +----------------- + +Use Tutor to enable the plugin: .. code-block:: bash tutor plugins enable paragon -Directory Structure -******************* - -The plugin will create the following structure inside your Tutor environment: +Verify Installation +------------------- -.. code-block:: +Check that the plugin is listed and enabled: - tutor/env/plugins/paragon/ - β”œβ”€β”€ theme-sources/ # Place your Paragon-based theme folders here (e.g., theme-xyz/) - └── compiled-themes/ # Output CSS files are generated here and ready for static hosting +.. code-block:: bash -Only themes listed in `PARAGON_ENABLED_THEMES` will be compiled. + tutor plugins list | grep paragon -Themes placed in `theme-sources/` are compiled into CSS using `Paragon's theme build process `_. The resulting CSS files in `compiled-themes/` are intended to be served statically and can be linked using the `PARAGON_THEME_URLS` setting. +Build the Paragon Image +----------------------- -This structure is optimized for design token–based themes (see `Paragon Design Tokens `__), but it is also flexible. If site operators need to include small amounts of additional CSS (not handled via tokens), we recommend doing so via extensions in the theme source directory, so they are included during the Paragon buildβ€”rather than manually editing the compiled output. +Before compiling tokens, build the Docker image used by the plugin: -.. note:: +.. code-block:: bash - A link to the official Open edX or Paragon documentation will be added here once it is published. + tutor images build paragon-builder Configuration -************* +============= + +Core Plugin Settings +-------------------- + +All configuration variables are defined via Tutor: + ++----------------------------+--------------------------------------------------------------+-------------------------------+ +| Variable | Description | Default Value | ++============================+==============================================================+===============================+ +| `PARAGON_THEMES_PATH` | Base path for theme sources and compiled output | `env/plugins/paragon/themes` | ++----------------------------+--------------------------------------------------------------+-------------------------------+ +| `PARAGON_THEMES` | List of theme folders to compile and serve | `['light', 'dark']` | ++----------------------------+--------------------------------------------------------------+-------------------------------+ +| `MFE_HOST_EXTRA_FILES` | Whether to serve compiled themes via Tutor’s MFE web server | `true` | ++----------------------------+--------------------------------------------------------------+-------------------------------+ -All configuration variables can be overridden via `tutor config save`: +Sample Configuration +-------------------- .. code-block:: yaml - PARAGON_THEME_SOURCES_PATH: "env/plugins/paragon/theme-sources" - PARAGON_COMPILED_THEMES_PATH: "env/plugins/paragon/compiled-themes" - PARAGON_ENABLED_THEMES: - - theme-1 - - theme-2 - PARAGON_SERVE_COMPILED_THEMES: true - PARAGON_BUILDER_IMAGE: "paragon-builder:latest" + PARAGON_THEMES_PATH: "{{ TUTOR_ROOT }}/env/plugins/paragon/themes" + PARAGON_THEMES: + - light + - dark + MFE_HOST_EXTRA_FILES: true -You may customize paths or theme names to suit your deployment. +Theme Directory Structure +------------------------- + +.. code-block:: text + + {{ TUTOR_ROOT }}/env/plugins/paragon/themes/ + β”œβ”€β”€ core/ # Shared base design tokens + β”œβ”€β”€ light/ # Light theme tokens + └── dark/ # Dark theme tokens + +Only themes listed in `PARAGON_THEMES` will be compiled and served. The `core/` directory is required and provides base styles shared across all themes. Usage -***** +===== -Prerequisites -------------- +Build All Themes +---------------- -- A built Paragon CLI image: +To compile all themes listed in `PARAGON_THEMES`: - .. code-block:: bash +.. code-block:: bash - tutor images build paragon-builder + tutor local do paragon-build-tokens -- The ``PARAGON_THEME_SOURCES_PATH`` directory structured as follows: +Build Specific Themes +--------------------- - .. code-block:: text +To compile only selected themes: - / - β”œβ”€β”€ core/ - β”‚ └── ... (token files) - └── themes/ - β”œβ”€β”€ light/ # example theme variant - β”‚ └── ... (light theme token files) - └── dark/ # example theme variant - └── ... (dark theme token files) +.. code-block:: bash - In this structure: + tutor local do paragon-build-tokens --themes light,dark - - The ``core/`` directory contains base design tokens common across all themes. - - The ``themes/`` directory contains subdirectories for each theme variant (e.g., ``light``, ``dark``), each with tokens specific to that theme. +Pass Additional CLI Options +--------------------------- -Building Themes ---------------- +You can pass extra options to the Paragon CLI: + +.. code-block:: bash + + tutor local do paragon-build-tokens --paragon-option value + +Output +------ + +Compiled CSS files (minified `.min.css`) are written to: +{{ TUTOR_ROOT }}/env/plugins/paragon/themes//.min.css + +Static Hosting +============== + +If `MFE_HOST_EXTRA_FILES` is set to `true`, the plugin: + +* Leverages the static file hosting capability provided by the `tutor-mfe` plugin to serve the compiled CSS files. +* Makes the themes accessible via standard static URLs for use in LMS and MFEs. + +Example URLs: + +* Local LMS: `http://apps.local.openedx.io/static/paragon/themes/light/light.min.css` +* Dev server: `http://localhost:/static/paragon/themes/dark/dark.min.css` + +Each theme listed in `PARAGON_THEMES` is automatically exposed for use in MFEs. + +Updating Theme Configuration +============================ + +If you make changes to the theme list or other plugin variables, follow these steps to apply them correctly: -Invoke the build process via Tutor: +1. **Save the new configuration** + +Use `tutor config save --set` to update your variables. For example: .. code-block:: bash - tutor local do paragon-build-tokens [OPTIONS] + tutor config save --set PARAGON_THEMES='["light", "dark"]' -For more information about available options, refer to the `Paragon CLI documentation `__. +2. **Restart the development environment** -Examples --------- +After saving the configuration, restart Tutor to apply the changes: .. code-block:: bash - # Compile all themes listed in PARAGON_ENABLED_THEMES - tutor local do paragon-build-tokens + tutor dev stop + tutor dev start - # Compile only specific themes - tutor local do paragon-build-tokens --themes theme-1,theme-2 +3. **Verify the changes** - # Pass any other Paragon CLI options as needed - tutor local do paragon-build-tokens --paragon-option value +Check that the new themes are compiled and served correctly: -Output ------- +.. code-block:: bash -Artifacts will be written to the directory specified by ``PARAGON_COMPILED_THEMES_PATH`` (default: ``env/plugins/paragon/compiled-themes``). + tutor local do paragon-build-tokens -Troubleshooting -*************** +Loading Base Paragon Styles +=========================== + +By default, this plugin serves theme-specific CSS files. Micro-Frontends (MFEs) typically include the base Paragon styles (e.g., ``core.min.css``) bundled within their own build. This can lead to users downloading the same base Paragon CSS multiple times as they navigate between different MFEs, impacting performance. + +To improve first-load performance and reduce redundant downloads, you can configure your MFEs to load shared base Paragon styles instead. + +Ways to use shared base styles: + +Option 1: Use jsDelivr CDN +-------------------------- + +You can configure your MFEs to load base Paragon styles directly from the `jsDelivr CDN `_. This is often the simplest approach. + +Configure your MFE settings (likely via ``MFE_CONFIG`` in Tutor) to use the jsDelivr URL for the base styles. You can use the ``$paragonVersion`` wildcard to ensure the MFE loads the correct version dynamically. -- **No custom themes built or only default tokens generated** - Ensure that your custom theme directories exist under ``PARAGON_THEME_SOURCES_PATH`` and that their names exactly match those in ``PARAGON_ENABLED_THEMES`` or passed via ``--themes``. If no custom tokens are found, Paragon will fall back to its built-in defaults. +* Example URL using the wildcard:: -- **Themes are not picked up when using --themes:** - The value for ``--themes`` must be a comma-separated list (no spaces), e.g. ``--themes theme-1,theme-2``. + https://cdn.jsdelivr.net/npm/@openedx/paragon@$paragonVersion/dist/core.min.css +* (Alternatively, you can specify a fixed version like ``23.1.0`` if needed:: -- **Write permission denied** - Verify that Docker and the Tutor process have write access to the path defined by ``PARAGON_COMPILED_THEMES_PATH``. Adjust filesystem permissions if necessary. + https://cdn.jsdelivr.net/npm/@openedx/paragon@23.1.0/dist/core.min.css -- **Error: "Expected at least 4 args"** - This occurs when the build job is invoked directly inside the container. Always run via Tutor: +**πŸ’‘ Note:** + Using jsDelivr involves loading resources from an external CDN. Consider network policies and data privacy requirements before implementing this approach. - .. code-block:: bash +Option 2: Host Your Own Base Styles +----------------------------------- - tutor local do paragon-build-tokens [OPTIONS] +You can host the base Paragon styles yourself using this plugin's static file hosting capability (via ``MFE_HOST_EXTRA_FILES``). + +1. Obtain the base Paragon CSS file (typically ``core.min.css``) for the version(s) used by your MFEs. + +**πŸ’‘ Note:** + MFEs within the same Open edX release typically use the same major version of Paragon, but minor versions might differ. You can check the version for an MFE by inspecting its ``package.json`` file or running ``npm list @openedx/paragon`` within an MFE directory. + +2. Place the base CSS file(s) into your ``PARAGON_THEMES_PATH`` directory. You have two main options for structuring this: + + * **Host a single version:** If all your MFEs can use the same version (e.g., the latest minor of a major version like ``23.4.0``), place it once:: + + {{ TUTOR_ROOT }}/env/plugins/paragon/themes/ + └── core/ + └── 23.4.0/ # A single, chosen version + └── core.min.css + + * **Host multiple versions:** To support MFEs using different Paragon versions, create a directory structure for each required version:: + + {{ TUTOR_ROOT }}/env/plugins/paragon/themes/ + └── core/ + β”œβ”€β”€ 23.1.0/ # Version for MFE A + β”‚ └── core.min.css + β”œβ”€β”€ 23.4.0/ # Version for MFE B, C + β”‚ └── core.min.css + └── ... (other versions as needed) + + +3. Configure your MFEs to load the base styles from the plugin's static URL. + +* **Using a single version (Recommended):** + If you host only one version of the base styles, hardcode that version in the URL within your `MFE_CONFIG` settings. + + Example URL:: + + http:///static/paragon/themes/core/23.4.0/core.min.css + + Replace `` with your actual LMS domain (e.g., `apps.local.openedx.io`). + +* **Using multiple versions or the wildcard:** + To support MFEs using different Paragon versions, configure the URL in `MFE_CONFIG` using the `$paragonVersion` placeholder. + + Example URL:: + + http:///static/paragon/themes/core/$paragonVersion/core.min.css + + Ensure all versions requested by your MFEs are present in your hosted directory structure. + +**πŸ’‘ Note:** + When hosting your own base styles, ensure the versions match those expected by your MFEs. Using a single, compatible version is often sufficient for standard MFEs from the same Open edX release. For advanced configurations like version wildcards, refer to the `frontend-platform theming documentation `_. + +Additional Resources +-------------------- + +For more detailed information on MFE theming and loading external styles, refer to the `frontend-platform theming documentation `_. + +Troubleshooting +=============== -- **Other issues** - Re-run the build with ``--verbose`` to obtain detailed logs and identify misconfigurations or missing files. +* **Themes not compiled**: Ensure theme folders exist and match names in `PARAGON_THEMES`. +* **Permission errors**: Verify Docker and Tutor have write access to the themes directory. +* **Missing core tokens**: Ensure the `core/` folder exists and contains valid token files. +* **Error: "Expected at least 4 args"**: Always run builds via `tutor local do`, not inside containers. +* **Other issues**: Re-run with `--verbose` for detailed logs. License -******* +======= -This software is licensed under the terms of the AGPLv3. +This software is licensed under the terms of the **AGPLv3**.