From 310ed54852ab2856f5d7143bef6db6721b8f3c80 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mar=C3=ADa=20De=20Los=20=C3=81ngeles=20Aguilar?= <110115438+maguilarUXUI@users.noreply.github.com> Date: Thu, 24 Jul 2025 16:46:11 -0500 Subject: [PATCH 1/6] docs: Rewrite and improve plugin documentation Updated structure, added version info, improved examples and linked external docs. --- plugins/tutor-contrib-paragon/README.rst | 337 +++++++++++++++++------ 1 file changed, 259 insertions(+), 78 deletions(-) diff --git a/plugins/tutor-contrib-paragon/README.rst b/plugins/tutor-contrib-paragon/README.rst index 85e0f23..6757b98 100644 --- a/plugins/tutor-contrib-paragon/README.rst +++ b/plugins/tutor-contrib-paragon/README.rst @@ -1,151 +1,332 @@ -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 +##################### -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. +.. contents:: Tabla de Contenidos + :local: + +Introduction +============ + +What is the Tutor Paragon Plugin? +--------------------------------- + +The Tutor Paragon Plugin (``tutor-contrib-paragon``) enables developers and operators to compile design tokens into CSS themes using the Paragon CLI and serve those themes to Open edX Micro-Frontends (MFEs) via Tutor. + +This plugin introduces a wrapper around the Paragon CLI build process, managing token source directories and output paths, and exposing compiled themes through Tutor's static hosting infrastructure. + +What problem does it solve? +--------------------------- + +This plugin simplifies the theme customization process across MFEs 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. +* Allowing 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 +============= + +* Working Tutor environment with Docker. +* Familiarity with Paragon design tokens and MFE architecture. +* Basic understanding of Tutor plugin system and configuration management. + +Version Compatibility +===================== + +To use the Tutor Paragon Plugin, ensure you are running compatible versions of the Open edX platform and its dependencies: + +* **Paragon 23+** +* **Open edX "Teak" release (or Tutor 20+)** +* **Tutor 20+** + +.. note:: + Design tokens functionality, which this plugin relies on, is available starting from Paragon version 23 and the Open edX "Teak" release (which corresponds to Tutor version 20). Using this plugin with earlier versions may result in compatibility issues or missing features. Installation -************ +============ -.. code-block:: bash +.. note:: + A future version of this plugin may be available for installation via PyPI. For now, please use the development installation method below. - pip install git+https://github.com/openedx/openedx-tutor-plugins.git#subdirectory=plugins/tutor-contrib-paragon +Development Install +------------------- -For development: +Clone the repo 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 -******************* +Verify Installation +------------------- + +You should see something like: -The plugin will create the following structure inside your Tutor environment: +.. code-block:: text -.. code-block:: + paragon 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 +If the plugin appears as 'enabled', it's ready to use. +Ensure the plugin is listed in Tutor: -Only themes listed in `PARAGON_ENABLED_THEMES` will be compiled. +.. code-block:: bash -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. + tutor plugins list -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. +Build the Paragon Image +----------------------- -.. note:: +Before compiling tokens, build the image used by the plugin: - A link to the official Open edX or Paragon documentation will be added here once it is published. +.. code-block:: bash + + tutor images build paragon-builder Configuration -************* +============= + +Core Plugin Settings +-------------------- + +All configuration variables are defined via Tutor: -All configuration variables can be overridden via `tutor config save`: +* ``PARAGON_THEME_SOURCES_PATH``: Location of your token input folders. +* ``PARAGON_COMPILED_THEMES_PATH``: Output folder for generated CSS. +* ``PARAGON_ENABLED_THEMES``: List of themes to compile. +* ``PARAGON_SERVE_COMPILED_THEMES``: Whether to host the compiled files. + +Sample Configuration +-------------------- .. code-block:: yaml - PARAGON_THEME_SOURCES_PATH: "env/plugins/paragon/theme-sources" - PARAGON_COMPILED_THEMES_PATH: "env/plugins/paragon/compiled-themes" + PARAGON_THEME_SOURCES_PATH: "{{ TUTOR_ROOT }}/env/plugins/paragon/theme-sources" + PARAGON_COMPILED_THEMES_PATH: "{{ TUTOR_ROOT }}/env/plugins/paragon/compiled-themes" PARAGON_ENABLED_THEMES: - - theme-1 - - theme-2 + - light + - dark PARAGON_SERVE_COMPILED_THEMES: true - PARAGON_BUILDER_IMAGE: "paragon-builder:latest" -You may customize paths or theme names to suit your deployment. +Theme Directory Structure +------------------------- + +.. code-block:: text + + theme-sources/ + ├── core/ + │ └── base tokens + └── themes/ + ├── light/ + └── dark/ + +The ``core`` directory contains shared design tokens. Each theme in ``themes/`` is compiled into separate CSS files. Usage -***** +===== -Prerequisites +Compiling Themes +---------------- + +This plugin wraps the ``npx paragon build-tokens`` command. To compile themes: + +.. code-block:: bash + + tutor local do paragon-build-tokens + +By default, it uses the themes defined in ``PARAGON_ENABLED_THEMES``. + +Options +------- + +The Tutor Paragon plugin acts as a wrapper for the Paragon CLI. It forwards any flags or options you provide directly to the underlying ``paragon build-tokens`` command. This means you can use all the options available in the `Paragon CLI documentation `_. + +Common options include: + +* ``--themes``: comma-separated list of themes to compile. +* ``--paragon-option``: pass any custom flag to Paragon CLI. + +For a complete list of available flags and their descriptions, please refer to the `Paragon CLI documentation `_. + +Examples +-------- + +.. code-block:: bash + + tutor local do paragon-build-tokens --themes light,dark + +Output +------ + +CSS files will be placed in: + +``{{ TUTOR_ROOT }}/env/plugins/paragon/compiled-themes//theme.css`` + +These are served statically when ``PARAGON_SERVE_COMPILED_THEMES`` is enabled. + +.. note:: + + If no themes are configured, the plugin falls back to Paragon's built-in light theme. + +Integration with MFEs +===================== + +Serving CSS Themes +------------------ + +.. note:: + + The plugin hosts only the **minified versions** of the CSS files generated by Paragon. These files have the ``.min.css`` extension (e.g., ``.min.css``). + +In development, use localhost directly because there is no reverse proxy: + +``http://localhost:8000/static/paragon/.min.css`` + +In production, the LMS and Caddy proxy handle requests automatically, so the files are served at: + +``https:///static/paragon/.min.css`` + +Compiled themes are available at: + +* **Development:** ``http://localhost:8000/static/paragon/.min.css`` +* **Production:** ``/static/paragon/.min.css`` + +Using in MFEs ------------- -- A built Paragon CLI image: +Include the CSS link in your MFE HTML shell: + +.. code-block:: html + + + +Multi-Tenant Support +-------------------- - .. code-block:: bash +The plugin is designed to support multi-tenant environments. The core configuration can be overridden on a per-tenant basis, allowing for different themes to be served to different tenants. Specific integration details with tenant management systems (like ``eox-tenant``) will be documented separately. - tutor images build paragon-builder +Testing and Validation +====================== -- The ``PARAGON_THEME_SOURCES_PATH`` directory structured as follows: +To verify that everything works: - .. code-block:: text +1. Build tokens: ``tutor local do paragon-build-tokens`` +2. Start the environment: ``tutor local start -d`` +3. Open the URL: ``http://localhost:8000/static/paragon/light.min.css`` +4. If the CSS loads in the browser, hosting is working correctly. - / - ├── core/ - │ └── ... (token files) - └── themes/ - ├── light/ # example theme variant - │ └── ... (light theme token files) - └── dark/ # example theme variant - └── ... (dark theme token files) +Verify Output +------------- + +After building, check this directory: + +.. code-block:: bash + + ls {{ TUTOR_ROOT }}/env/plugins/paragon/compiled-themes/ - In this structure: +You should see: - - 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. +* ``core.css`` +* ``.min.css`` -Building Themes +Verbose Logging --------------- -Invoke the build process via Tutor: +Run with: .. code-block:: bash - tutor local do paragon-build-tokens [OPTIONS] + tutor local do paragon-build-tokens --verbose + +Troubleshooting +=============== -For more information about available options, refer to the `Paragon CLI documentation `__. +No Custom Tokens Built +---------------------- -Examples --------- +Check that the theme directory names match ``PARAGON_ENABLED_THEMES``. Paragon will fall back to its default theme if none are found. + +Themes Not Compiled +------------------- + +Use ``--themes`` with no spaces: .. code-block:: bash - # Compile all themes listed in PARAGON_ENABLED_THEMES - tutor local do paragon-build-tokens + tutor local do paragon-build-tokens --themes theme-1,theme-2 - # Compile only specific themes - tutor local do paragon-build-tokens --themes theme-1,theme-2 +Permission Denied +----------------- - # Pass any other Paragon CLI options as needed - tutor local do paragon-build-tokens --paragon-option value +Ensure Docker and Tutor can write to the paths. -Output ------- +"Expected at least 4 args" Error +-------------------------------- -Artifacts will be written to the directory specified by ``PARAGON_COMPILED_THEMES_PATH`` (default: ``env/plugins/paragon/compiled-themes``). +Only run builds with: -Troubleshooting -*************** +.. code-block:: bash + + tutor local do paragon-build-tokens + +Contributing +============ + +Repository +---------- -- **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. +The main repository for this plugin is located at: https://github.com/openedx/openedx-tutor-plugins/tree/main/plugins/tutor-contrib-paragon -- **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``. +Local Development +----------------- -- **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. +Clone the repo and install in editable mode: -- **Error: "Expected at least 4 args"** - This occurs when the build job is invoked directly inside the container. Always run via Tutor: +.. code-block:: bash + + git clone https://github.com/openedx/openedx-tutor-plugins.git + cd openedx-tutor-plugins/plugins/tutor-contrib-paragon + pip install -e . - .. code-block:: bash +PR Process +---------- - tutor local do paragon-build-tokens [OPTIONS] +1. Fork the repository. +2. Create a feature branch. +3. Submit a pull request. +4. Follow project guidelines and include tests where applicable. -- **Other issues** - Re-run the build with ``--verbose`` to obtain detailed logs and identify misconfigurations or missing files. +License and Credits +=================== License -******* +------- + +This plugin is licensed under the AGPLv3. + +Credits +------- -This software is licensed under the terms of the AGPLv3. +Developed by edunext, with inspiration from Tutor and Paragon tooling. +For issues or support, open a GitHub issue or contact the maintainers. From 8aae9409cd729c26713ee619b9c5893449da68c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mar=C3=ADa=20De=20Los=20=C3=81ngeles=20Aguilar?= <110115438+maguilarUXUI@users.noreply.github.com> Date: Tue, 26 Aug 2025 14:44:34 -0500 Subject: [PATCH 2/6] docs: Update README.rst to reflect latest plugin configuration and structure This commit updates the Tutor Paragon Plugin documentation to align with recent code changes and the approach outlined in the original proposal. --- plugins/tutor-contrib-paragon/README.rst | 264 ++++++----------------- 1 file changed, 69 insertions(+), 195 deletions(-) diff --git a/plugins/tutor-contrib-paragon/README.rst b/plugins/tutor-contrib-paragon/README.rst index 6757b98..2526323 100644 --- a/plugins/tutor-contrib-paragon/README.rst +++ b/plugins/tutor-contrib-paragon/README.rst @@ -4,7 +4,7 @@ Tutor Paragon Plugin ##################### -.. contents:: Tabla de Contenidos +.. contents:: Table of Contents :local: Introduction @@ -13,56 +13,58 @@ Introduction What is the Tutor Paragon Plugin? --------------------------------- -The Tutor Paragon Plugin (``tutor-contrib-paragon``) enables developers and operators to compile design tokens into CSS themes using the Paragon CLI and serve those themes to Open edX Micro-Frontends (MFEs) via Tutor. +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. -This plugin introduces a wrapper around the Paragon CLI build process, managing token source directories and output paths, and exposing compiled themes through Tutor's static hosting infrastructure. +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 the theme customization process across MFEs by: +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. -* Allowing tenant-based theme overrides with flexible configuration. +* 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. +* Open edX developers customizing MFE themes. +* Operators managing theming at scale. +* Designers experimenting with visual tokens in real-time environments. Prerequisites ============= -* Working Tutor environment with Docker. -* Familiarity with Paragon design tokens and MFE architecture. -* Basic understanding of Tutor plugin system and configuration management. +* 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 the Tutor Paragon Plugin, ensure you are running compatible versions of the Open edX platform and its dependencies: +To use this plugin, ensure you're running compatible versions of Open edX and its dependencies: * **Paragon 23+** * **Open edX "Teak" release (or Tutor 20+)** * **Tutor 20+** .. note:: - Design tokens functionality, which this plugin relies on, is available starting from Paragon version 23 and the Open edX "Teak" release (which corresponds to Tutor version 20). Using this plugin with earlier versions may result in compatibility issues or missing features. + Design token functionality is available starting from Paragon 23 and Open edX "Teak". Earlier versions may not be compatible. Installation ============ .. note:: - A future version of this plugin may be available for installation via PyPI. For now, please use the development installation method below. + A future version may be available via PyPI. For now, use the development installation method. Development Install ------------------- -Clone the repo and install in editable mode: +Clone the repository and install in editable mode: .. code-block:: bash @@ -82,23 +84,16 @@ Use Tutor to enable the plugin: Verify Installation ------------------- -You should see something like: - -.. code-block:: text - - paragon enabled - -If the plugin appears as 'enabled', it's ready to use. -Ensure the plugin is listed in Tutor: +Check that the plugin is listed and enabled: .. code-block:: bash - tutor plugins list + tutor plugins list | grep paragon Build the Paragon Image ----------------------- -Before compiling tokens, build the image used by the plugin: +Before compiling tokens, build the Docker image used by the plugin: .. code-block:: bash @@ -112,221 +107,100 @@ Core Plugin Settings All configuration variables are defined via Tutor: -* ``PARAGON_THEME_SOURCES_PATH``: Location of your token input folders. -* ``PARAGON_COMPILED_THEMES_PATH``: Output folder for generated CSS. -* ``PARAGON_ENABLED_THEMES``: List of themes to compile. -* ``PARAGON_SERVE_COMPILED_THEMES``: Whether to host the compiled files. ++----------------------------+--------------------------------------------------------------+-------------------------------+ +| 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` | ++----------------------------+--------------------------------------------------------------+-------------------------------+ Sample Configuration -------------------- .. code-block:: yaml - PARAGON_THEME_SOURCES_PATH: "{{ TUTOR_ROOT }}/env/plugins/paragon/theme-sources" - PARAGON_COMPILED_THEMES_PATH: "{{ TUTOR_ROOT }}/env/plugins/paragon/compiled-themes" - PARAGON_ENABLED_THEMES: + PARAGON_THEMES_PATH: "{{ TUTOR_ROOT }}/env/plugins/paragon/themes" + PARAGON_THEMES: - light - dark - PARAGON_SERVE_COMPILED_THEMES: true + MFE_HOST_EXTRA_FILES: true Theme Directory Structure ------------------------- .. code-block:: text - theme-sources/ - ├── core/ - │ └── base tokens - └── themes/ - ├── light/ - └── dark/ + {{ TUTOR_ROOT }}/env/plugins/paragon/themes/ + ├── core/ # Shared base design tokens + ├── light/ # Light theme tokens + └── dark/ # Dark theme tokens -The ``core`` directory contains shared design tokens. Each theme in ``themes/`` is compiled into separate CSS files. +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 ===== -Compiling Themes +Build All Themes ---------------- -This plugin wraps the ``npx paragon build-tokens`` command. To compile themes: +To compile all themes listed in `PARAGON_THEMES`: .. code-block:: bash tutor local do paragon-build-tokens -By default, it uses the themes defined in ``PARAGON_ENABLED_THEMES``. +Build Specific Themes +--------------------- -Options -------- +To compile only selected themes: -The Tutor Paragon plugin acts as a wrapper for the Paragon CLI. It forwards any flags or options you provide directly to the underlying ``paragon build-tokens`` command. This means you can use all the options available in the `Paragon CLI documentation `_. - -Common options include: +.. code-block:: bash -* ``--themes``: comma-separated list of themes to compile. -* ``--paragon-option``: pass any custom flag to Paragon CLI. + tutor local do paragon-build-tokens --themes light,dark -For a complete list of available flags and their descriptions, please refer to the `Paragon CLI documentation `_. +Pass Additional CLI Options +--------------------------- -Examples --------- +You can pass extra options to the Paragon CLI: .. code-block:: bash - tutor local do paragon-build-tokens --themes light,dark + tutor local do paragon-build-tokens --paragon-option value Output ------ -CSS files will be placed in: - -``{{ TUTOR_ROOT }}/env/plugins/paragon/compiled-themes//theme.css`` - -These are served statically when ``PARAGON_SERVE_COMPILED_THEMES`` is enabled. - -.. note:: - - If no themes are configured, the plugin falls back to Paragon's built-in light theme. - -Integration with MFEs -===================== - -Serving CSS Themes ------------------- - -.. note:: - - The plugin hosts only the **minified versions** of the CSS files generated by Paragon. These files have the ``.min.css`` extension (e.g., ``.min.css``). - -In development, use localhost directly because there is no reverse proxy: - -``http://localhost:8000/static/paragon/.min.css`` - -In production, the LMS and Caddy proxy handle requests automatically, so the files are served at: - -``https:///static/paragon/.min.css`` - -Compiled themes are available at: - -* **Development:** ``http://localhost:8000/static/paragon/.min.css`` -* **Production:** ``/static/paragon/.min.css`` - -Using in MFEs -------------- - -Include the CSS link in your MFE HTML shell: - -.. code-block:: html - - - -Multi-Tenant Support --------------------- - -The plugin is designed to support multi-tenant environments. The core configuration can be overridden on a per-tenant basis, allowing for different themes to be served to different tenants. Specific integration details with tenant management systems (like ``eox-tenant``) will be documented separately. - -Testing and Validation -====================== - -To verify that everything works: - -1. Build tokens: ``tutor local do paragon-build-tokens`` -2. Start the environment: ``tutor local start -d`` -3. Open the URL: ``http://localhost:8000/static/paragon/light.min.css`` -4. If the CSS loads in the browser, hosting is working correctly. - -Verify Output -------------- - -After building, check this directory: +Compiled CSS files (minified `.min.css`) are written to: +{{ TUTOR_ROOT }}/env/plugins/paragon/themes//.min.css -.. code-block:: bash - - ls {{ TUTOR_ROOT }}/env/plugins/paragon/compiled-themes/ +Static Hosting +============== -You should see: +If `MFE_HOST_EXTRA_FILES` is set to `true`, the plugin: -* ``core.css`` -* ``.min.css`` +* 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. -Verbose Logging ---------------- +Example URLs: -Run with: - -.. code-block:: bash +* Local LMS: `http://local.openedx.io/static/paragon/themes/light/light.min.css` +* Dev server: `http://localhost:/static/paragon/themes/dark/dark.min.css` - tutor local do paragon-build-tokens --verbose +Each theme listed in `PARAGON_THEMES` is automatically exposed for use in MFEs. Troubleshooting =============== -No Custom Tokens Built ----------------------- - -Check that the theme directory names match ``PARAGON_ENABLED_THEMES``. Paragon will fall back to its default theme if none are found. - -Themes Not Compiled -------------------- - -Use ``--themes`` with no spaces: - -.. code-block:: bash - - tutor local do paragon-build-tokens --themes theme-1,theme-2 - -Permission Denied ------------------ - -Ensure Docker and Tutor can write to the paths. - -"Expected at least 4 args" Error --------------------------------- - -Only run builds with: - -.. code-block:: bash - - tutor local do paragon-build-tokens - -Contributing -============ - -Repository ----------- - -The main repository for this plugin is located at: https://github.com/openedx/openedx-tutor-plugins/tree/main/plugins/tutor-contrib-paragon - -Local Development ------------------ - -Clone the repo 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 . - -PR Process ----------- - -1. Fork the repository. -2. Create a feature branch. -3. Submit a pull request. -4. Follow project guidelines and include tests where applicable. - -License and Credits -=================== +* **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 plugin is licensed under the AGPLv3. - -Credits -------- +======= -Developed by edunext, with inspiration from Tutor and Paragon tooling. -For issues or support, open a GitHub issue or contact the maintainers. +This software is licensed under the terms of the **AGPLv3**. From 00aee00dd54a8cebec6ccda81e61505c1ae7e78c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mar=C3=ADa=20De=20Los=20=C3=81ngeles=20Aguilar?= <110115438+maguilarUXUI@users.noreply.github.com> Date: Wed, 3 Sep 2025 14:18:27 -0500 Subject: [PATCH 3/6] docs: Add configuration update steps for theme hosting Clarifies when to use tutor config save, tutor dev stop, and tutor dev start when updating theme variables. Adds step-by-step instructions to the documentation under the Static Hosting section. --- plugins/tutor-contrib-paragon/README.rst | 32 +++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/plugins/tutor-contrib-paragon/README.rst b/plugins/tutor-contrib-paragon/README.rst index 2526323..838d335 100644 --- a/plugins/tutor-contrib-paragon/README.rst +++ b/plugins/tutor-contrib-paragon/README.rst @@ -186,11 +186,41 @@ If `MFE_HOST_EXTRA_FILES` is set to `true`, the plugin: Example URLs: -* Local LMS: `http://local.openedx.io/static/paragon/themes/light/light.min.css` +* 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: + +1. **Save the new configuration** + +Use `tutor config save --set` to update your variables. For example: + +.. code-block:: bash + + tutor config save --set PARAGON_THEMES='["light", "dark"]' + +2. **Restart the development environment** + +After saving the configuration, restart Tutor to apply the changes: + +.. code-block:: bash + + tutor dev stop + tutor dev start + +3. **Verify the changes** + +Check that the new themes are compiled and served correctly: + +.. code-block:: bash + + tutor local do paragon-build-tokens + Troubleshooting =============== From 24bec46c8578dabde76be08bdbc379efb7557aa8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mar=C3=ADa=20De=20Los=20=C3=81ngeles=20Aguilar?= <110115438+maguilarUXUI@users.noreply.github.com> Date: Mon, 15 Sep 2025 15:30:56 -0500 Subject: [PATCH 4/6] docs: add section on loading shared base Paragon styles and clarify version compatibility MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit improves the documentation by: - Adding a new section titled “Loading Base Paragon Styles” to guide site operators on how to optimize performance by using shared styles. - Clarifying version compatibility in the “Version Compatibility” section. --- plugins/tutor-contrib-paragon/README.rst | 74 ++++++++++++++++++++++-- 1 file changed, 70 insertions(+), 4 deletions(-) diff --git a/plugins/tutor-contrib-paragon/README.rst b/plugins/tutor-contrib-paragon/README.rst index 838d335..2d52052 100644 --- a/plugins/tutor-contrib-paragon/README.rst +++ b/plugins/tutor-contrib-paragon/README.rst @@ -48,12 +48,17 @@ Version Compatibility To use this plugin, ensure you're running compatible versions of Open edX and its dependencies: -* **Paragon 23+** -* **Open edX "Teak" release (or Tutor 20+)** -* **Tutor 20+** +* **Paragon >= 23** +* **Open edX "Teak" release (Tutor >= 20)** +* **Tutor >= 20** .. note:: - Design token functionality is available starting from Paragon 23 and Open edX "Teak". Earlier versions may not be compatible. + + Design token functionality is available starting from Paragon version 23 and the Open edX "Teak" release (which corresponds to Tutor version 20). While the plugin is expected to support future versions (e.g., Tutor 21+), major releases may introduce breaking changes. Compatibility will be updated as needed. + +.. 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 (see `overhangio/tutor-mfe#267 `_ and `overhangio/tutor-mfe#264 `_). Installation ============ @@ -221,6 +226,67 @@ Check that the new themes are compiled and served correctly: tutor local do paragon-build-tokens +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. + +1. Determine the ``@openedx/paragon`` version used by your MFEs (e.g., by checking the MFE's ``package.json`` or running ``npm list @openedx/paragon`` within an MFE directory). +2. Configure your MFE settings (likely via ``MFE_CONFIG`` in Tutor) to use the jsDelivr URL for the base styles. + * Example URL: ``https://cdn.jsdelivr.net/npm/@openedx/paragon@23.1.0/dist/core.min.css`` + * (Replace ``23.1.0`` with the actual version used by your MFEs). + +.. note:: + Using jsDelivr involves loading resources from an external CDN. Consider network policies and data privacy requirements before implementing this approach. + +Option 2: Host Your Own Base Styles +----------------------------------- + +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. +2. Place the base CSS file(s) into your ``PARAGON_THEMES_PATH`` directory. A common structure might be: + .. code-block:: text + + {{ TUTOR_ROOT }}/env/plugins/paragon/themes/ + └── core/ + └── 23.1.0/ # Use the actual Paragon version + └── core.min.css + +3. Configure your MFEs to load the base styles from the plugin's static URL. + * Example URL (based on the structure above): ``http:///static/paragon/themes/core/23.1.0/core.min.css`` + * Replace ```` with your actual LMS domain (e.g., ``apps.local.openedx.io``). + * Update your MFE configuration (for example, by setting ``MFE_CONFIG["PARAGON_THEME_URLS"]`` in your Tutor settings) to point to this URL. **This URL must be placed under the ``"default"`` key within the ``"core"`` section.** + * Example configuration snippet: + + .. code-block:: python + + MFE_CONFIG["PARAGON_THEME_URLS"] = { + "core": { + "urls": { + "default": "http:///static/paragon/themes/core/23.1.0/core.min.css" + }, + }, + # ... other configurations for variants + } + +.. note:: + When hosting your own base styles, ensure the versions match those expected by your MFEs. Using a single, compatible version (e.g., the latest minor of the major version used) is often sufficient if you are using 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 =============== From 5c347cb6155f0aef232957615b7fc43ef5bea08e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mar=C3=ADa=20De=20Los=20=C3=81ngeles=20Aguilar?= <110115438+maguilarUXUI@users.noreply.github.com> Date: Tue, 16 Sep 2025 15:13:55 -0500 Subject: [PATCH 5/6] docs: improve formatting for GitHub compatibility and clarity --- plugins/tutor-contrib-paragon/README.rst | 111 +++++++++++++++-------- 1 file changed, 72 insertions(+), 39 deletions(-) diff --git a/plugins/tutor-contrib-paragon/README.rst b/plugins/tutor-contrib-paragon/README.rst index 2d52052..c0bfdc9 100644 --- a/plugins/tutor-contrib-paragon/README.rst +++ b/plugins/tutor-contrib-paragon/README.rst @@ -52,19 +52,29 @@ To use this plugin, ensure you're running compatible versions of Open edX and it * **Open edX "Teak" release (Tutor >= 20)** * **Tutor >= 20** -.. note:: +**💡 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. - Design token functionality is available starting from Paragon version 23 and the Open edX "Teak" release (which corresponds to Tutor version 20). While the plugin is expected to support future versions (e.g., Tutor 21+), major releases may introduce breaking changes. Compatibility will be updated as needed. -.. 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 (see `overhangio/tutor-mfe#267 `_ and `overhangio/tutor-mfe#264 `_). +**⚠️ 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 + Installation ============ -.. note:: - A future version may be available via PyPI. For now, use the development installation method. +**💡 Note:** + A future version may be available via PyPI. For now, use the development installation method. Development Install ------------------- @@ -238,14 +248,18 @@ 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. +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. + +* Example URL using the wildcard:: -1. Determine the ``@openedx/paragon`` version used by your MFEs (e.g., by checking the MFE's ``package.json`` or running ``npm list @openedx/paragon`` within an MFE directory). -2. Configure your MFE settings (likely via ``MFE_CONFIG`` in Tutor) to use the jsDelivr URL for the base styles. - * Example URL: ``https://cdn.jsdelivr.net/npm/@openedx/paragon@23.1.0/dist/core.min.css`` - * (Replace ``23.1.0`` with the actual version used by your MFEs). + ``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:: -.. note:: + ``https://cdn.jsdelivr.net/npm/@openedx/paragon@23.1.0/dist/core.min.css`` + +**💡 Note:** Using jsDelivr involves loading resources from an external CDN. Consider network policies and data privacy requirements before implementing this approach. Option 2: Host Your Own Base Styles @@ -254,33 +268,52 @@ Option 2: Host Your Own Base Styles 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. -2. Place the base CSS file(s) into your ``PARAGON_THEMES_PATH`` directory. A common structure might be: - .. code-block:: text - - {{ TUTOR_ROOT }}/env/plugins/paragon/themes/ - └── core/ - └── 23.1.0/ # Use the actual Paragon version - └── core.min.css - -3. Configure your MFEs to load the base styles from the plugin's static URL. - * Example URL (based on the structure above): ``http:///static/paragon/themes/core/23.1.0/core.min.css`` - * Replace ```` with your actual LMS domain (e.g., ``apps.local.openedx.io``). - * Update your MFE configuration (for example, by setting ``MFE_CONFIG["PARAGON_THEME_URLS"]`` in your Tutor settings) to point to this URL. **This URL must be placed under the ``"default"`` key within the ``"core"`` section.** - * Example configuration snippet: - - .. code-block:: python - - MFE_CONFIG["PARAGON_THEME_URLS"] = { - "core": { - "urls": { - "default": "http:///static/paragon/themes/core/23.1.0/core.min.css" - }, - }, - # ... other configurations for variants - } - -.. note:: - When hosting your own base styles, ensure the versions match those expected by your MFEs. Using a single, compatible version (e.g., the latest minor of the major version used) is often sufficient if you are using standard MFEs from the same Open edX release. For advanced configurations like version wildcards, refer to the `frontend-platform theming documentation `_. + +**💡 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 -------------------- From 8a24b4a0d2b00096af1377d4868785147ee1f1ab Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mar=C3=ADa=20De=20Los=20=C3=81ngeles=20Aguilar?= <110115438+maguilarUXUI@users.noreply.github.com> Date: Tue, 23 Sep 2025 16:29:36 -0500 Subject: [PATCH 6/6] docs: improve README.rst - Hide ( `` ) --- plugins/tutor-contrib-paragon/README.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/tutor-contrib-paragon/README.rst b/plugins/tutor-contrib-paragon/README.rst index c0bfdc9..aa336d6 100644 --- a/plugins/tutor-contrib-paragon/README.rst +++ b/plugins/tutor-contrib-paragon/README.rst @@ -254,10 +254,10 @@ Configure your MFE settings (likely via ``MFE_CONFIG`` in Tutor) to use the jsDe * Example URL using the wildcard:: - ``https://cdn.jsdelivr.net/npm/@openedx/paragon@$paragonVersion/dist/core.min.css`` + 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:: - ``https://cdn.jsdelivr.net/npm/@openedx/paragon@23.1.0/dist/core.min.css`` + https://cdn.jsdelivr.net/npm/@openedx/paragon@23.1.0/dist/core.min.css **💡 Note:** Using jsDelivr involves loading resources from an external CDN. Consider network policies and data privacy requirements before implementing this approach.