mautic · RCheesley · Jun 26, 2023 · Aug 17, 2022 · Aug 17, 2022 · Aug 18, 2022
diff --git a/.all-contributorsrc b/.all-contributorsrc
@@ -0,0 +1,71 @@
+{
+  "files": [
+    "README.md"
+  ],
+  "imageSize": 100,
+  "commit": false,
+  "commitConvention": "angular",
+  "contributors": [
+    {
+      "login": "gustavokennedy",
+      "name": "Gustavo Kennedy Renkel",
+      "avatar_url": "https://avatars.githubusercontent.com/u/98914036?v=4",
+      "profile": "http://overall.cloud",
+      "contributions": [
+        "translation"
+      ]
+    },
+    {
+      "login": "zaharovrd",
+      "name": "Roman",
+      "avatar_url": "https://avatars.githubusercontent.com/u/8171816?v=4",
+      "profile": "http://www.youradman.com",
+      "contributions": [
+        "translation"
+      ]
+    },
+    {
+      "login": "tomekkowalczyk",
+      "name": "Tomasz Kowalczyk",
+      "avatar_url": "https://avatars.githubusercontent.com/u/39382654?v=4",
+      "profile": "http://adevo.pl",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "kukis2107",
+      "name": "kukis2107",
+      "avatar_url": "https://avatars.githubusercontent.com/u/60287846?v=4",
+      "profile": "https://github.com/kukis2107",
+      "contributions": [
+        "translation"
+      ]
+    },
+    {
+      "login": "putzwasser",
+      "name": "putzwasser",
+      "avatar_url": "https://avatars.githubusercontent.com/u/26040044?v=4",
+      "profile": "https://github.com/putzwasser",
+      "contributions": [
+        "review"
+      ]
+    },
+    {
+      "login": "Moongazer",
+      "name": "Moongazer",
+      "avatar_url": "https://avatars.githubusercontent.com/u/1685510?v=4",
+      "profile": "https://github.com/Moongazer",
+      "contributions": [
+        "doc"
+      ]
+    }
+  ],
+  "contributorsPerLine": 7,
+  "skipCi": true,
+  "repoType": "github",
+  "repoHost": "https://github.com",
+  "projectName": "user-documentation",
+  "projectOwner": "mautic",
+  "commitType": "docs"
+}
diff --git a/README.md b/README.md
@@ -1,4 +1,7 @@
 [![Documentation Status][RTD badge URL]][RTD URL]
+<!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section -->
+[![All Contributors](https://img.shields.io/badge/all_contributors-6-orange.svg?style=flat-square)](#contributors-)
+<!-- ALL-CONTRIBUTORS-BADGE:END -->
 
 [![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/mautic/user-documentation)
 
@@ -49,4 +52,30 @@ You can automatically build changes to rst files using a file watcher.
 [RST Cheatsheet]: <https://github.com/ralsina/rst-cheatsheet/blob/master/rst-cheatsheet.rst>
 [Sphinx Template]: <https://github.com/readthedocs/sphinx_rtd_theme/tree/master/docs/demo>
 [Sphinx Demo]: <https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/structure.html>
-[Vale]: <https://docs.errata.ai/vale/install>
+[Vale]: <https://docs.errata.ai/vale/install>
+## Contributors ✨
+
+Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
+
+<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+<table>
+  <tbody>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="http://overall.cloud"><img src="https://avatars.githubusercontent.com/u/98914036?v=4?s=100" width="100px;" alt="Gustavo Kennedy Renkel"/><br /><sub><b>Gustavo Kennedy Renkel</b></sub></a><br /><a href="#translation-gustavokennedy" title="Translation">🌍</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="http://www.youradman.com"><img src="https://avatars.githubusercontent.com/u/8171816?v=4?s=100" width="100px;" alt="Roman"/><br /><sub><b>Roman</b></sub></a><br /><a href="#translation-zaharovrd" title="Translation">🌍</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="http://adevo.pl"><img src="https://avatars.githubusercontent.com/u/39382654?v=4?s=100" width="100px;" alt="Tomasz Kowalczyk"/><br /><sub><b>Tomasz Kowalczyk</b></sub></a><br /><a href="https://github.com/mautic/user-documentation/commits?author=tomekkowalczyk" title="Documentation">📖</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/kukis2107"><img src="https://avatars.githubusercontent.com/u/60287846?v=4?s=100" width="100px;" alt="kukis2107"/><br /><sub><b>kukis2107</b></sub></a><br /><a href="#translation-kukis2107" title="Translation">🌍</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/putzwasser"><img src="https://avatars.githubusercontent.com/u/26040044?v=4?s=100" width="100px;" alt="putzwasser"/><br /><sub><b>putzwasser</b></sub></a><br /><a href="https://github.com/mautic/user-documentation/pulls?q=is%3Apr+reviewed-by%3Aputzwasser" title="Reviewed Pull Requests">👀</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/Moongazer"><img src="https://avatars.githubusercontent.com/u/1685510?v=4?s=100" width="100px;" alt="Moongazer"/><br /><sub><b>Moongazer</b></sub></a><br /><a href="https://github.com/mautic/user-documentation/commits?author=Moongazer" title="Documentation">📖</a></td>
+    </tr>
+  </tbody>
+</table>
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+
+<!-- ALL-CONTRIBUTORS-LIST:END -->
+
+This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html
@@ -1,2 +1,2 @@
 {% extends "!layout.html" %}
-{% set css_files = css_files + ["_static/tablefix.css"] %}
+{% set css_files = css_files + ["_static/tablefix.css"] + ["_static/theme.css"] %}
diff --git a/docs/builders/creating_themes.rst b/docs/builders/creating_themes.rst
@@ -3,4 +3,140 @@
 Creating Themes
 ###############
 
-.. vale on
+.. vale on
+
+:xref:`MJML` allows marketers to create and maintain beautiful and responsive Themes for Mautic easily.
+
+.. vale off
+
+Why use email Themes?
+*********************
+
+Purpose of a Theme
+==================
+
+.. vale on
+
+The GrapesJS builder makes it possible to insert HTML code and edit it in a 'What You See Is What You Get' (WYSIWYG) environment.
+
+A Theme can feature a wide variety of predefined blocks and sections reflecting the desired Email design - a template from which to start.
+
+By choosing a Theme, you can create beautiful Emails very efficiently.
+
+.. vale off
+
+Modifying legacy Themes
+=======================
+
+.. vale on
+
+The GrapesJS Builder checks the Theme configuration file before listing the available Themes, to determine which are compatible with the Builder.
+
+Since :xref:`Mautic 3` a new line defines the compatible Builders:
+
+File name: config.json
+
+.. code-block:: json
+
+    {
+        "name": "Great Theme",
+        "author": "Mr. Robot",
+        "authorUrl": "https://mautic.org",
+        "builder": "grapesjsbuilder",
+        "features": [
+            "email"
+        ]
+    }
+
+With the builder/s defined, the Theme shows in the Theme selection page.
+
+If you wish to support more than one Builder, specify them in an array: ``"builder": ["legacy", "grapesjsbuilder"],``
+
+.. vale off
+
+Creating a Theme from scratch
+*****************************
+
+.. vale on
+
+HTML markup
+===========
+
+It's possible to use HTML for Themes, and the GrapesJS builder offers basic WYSIWYG editing capabilities.
+
+Once converted into HTML, however, the structure is table based, and the blocks are hard to move around. For this reason, MJML Themes are preferable.
+
+MJML markup
+===========
+
+The MJML language allows the creation of blocks which can be freely moved around in the editor, changing the layout fundamentally without coding.
+
+In order to harness the power of MJML, you must code the whole Theme in MJML.
+
+The best place to do so is the online editor at :xref:`MJML`.
+
+Documentation on using sections, columns, and blocks is available in the :xref:`MJML Documentation`
+
+.. vale off
+
+Head Components
+===============
+
+.. vale on
+
+At present, Mautic won't process the ``<mj-head>`` tags. None of the ``<mj-attribuites>`` run, so you have to do all styling inline.
+
+.. vale off
+
+Body Components
+===============
+
+.. vale on
+
+At present, Mautic processes most ``<mj-body>`` components.
+
+**Tested elements** are: mj-button, mj-column, mj-divider, mj-image, mj-navbar, mj-section, mj-spacer, mj-text
+
+.. vale off
+
+Image Asset relative URLs
+=========================
+
+.. vale on
+
+Images have to refer to the Themes folder the following way: 
+
+``<mj-image src="{{ getAssetUrl('Themes/'~Theme~'/assets/imagename.ext', null, null, true) }}" alt="logo" align="center" width="105px" padding="10px 0"></mj-image>``
+
+File structure
+
+.. code-block:: 
+
+    name.zip
+    ├── assets
+    │   ├── image1.ext
+    │   └── image2.ext
+    ├── html
+    │   ├── email.html.twig
+    │   ├── email.mjml.twig
+    │   ├── base.html.twig
+    │   └── message.html.twig
+    ├── config.json
+    └── thumbnail.png
+
+Steps to save the Theme package
+===============================
+
+Once your design in MJML is finalized, go through the following steps to create the Theme package:
+
+* Save your images in the Assets folder.
+
+* Save your MJML in the ``html`` folder as ``email.mjml.twig`` AND ``email.html.twig``.
+
+* Use the ``base.html.twig`` and ``message.html.twig`` files from the basic Theme or make your changes there.
+
+* Save your ``config.json`` as described previously
+
+* Create a thumbnail -  use the dimensions of 400px wide, 600px high.
+
+* Compress the contents of the folder as a Zip file - ensure that the files and folders aren't within a sub-folder in the Zip file.
diff --git a/docs/builders/email_landing_page.rst b/docs/builders/email_landing_page.rst
@@ -127,6 +127,35 @@ If you search through the list of available Themes, the new MJML Themes ``Brienz
 
 To learn more about creating Themes please :doc:`check the documentation</builders/creating_themes>`. 
 
+Custom fonts
+************
+
+From Mautic 5.x you can extend the Style Manager > Typography > Fonts list to include custom fonts.
+
+.. image:: images/editorfonts.jpg
+  :width: 280
+  :alt: Screenshot of the Fonts in Style Manager > Typography
+
+You define options as elements of the ``'editor_fonts'`` array in the local configuration file - in most cases located in ``app/config/local.php``. The font should have a unique name and a valid CSS style URL. See example below:
+
+.. code-block:: php
+
+    <?php
+    // Example local.php
+    'editor_fonts' => array(
+        '0' => array(
+            'name' => 'Smokum',
+            'font' => 'Smokum, cursive',
+            'url' => 'https://fonts.googleapis.com/css2?family=Smokum&display=swap'
+        ),
+        '1' => array(
+            'name' => 'Sofia',
+            'font' => 'Sofia, sans-serif',
+            'url' => 'https://fonts.googleapis.com/css?family=Sofia'
+        )
+    ),
+
+
 Reporting bugs
 ***************
 

diff --git a/docs/builders/images/editorfonts.jpg b/docs/builders/images/editorfonts.jpg
diff --git a/docs/channels/utm_tags.rst b/docs/channels/utm_tags.rst
@@ -39,12 +39,12 @@ The following table lists the Google Analytics UTM tags:
      - Description
    * - Campaign Source
      - The referring source of the web activity. It indicates the social network, search engine, newsletter name, or any other specific source driving the traffic.  
-        * Examples: facebook, twitter, blog, newsletters
+        * Examples: ``facebook``, ``twitter``, ``blog``, ``newsletters``
         * UTM code: utm_source
-        * Sample code: utm_source=facebook
+        * Sample code: ``utm_source=facebook``
    * - Campaign Medium
      - UTM tags - Mautic Documentation
-         * Examples: cpc, organic_social
+         * Examples: ``cpc``, ``organic_social``
          * UTM code: utm_medium
          * Sample code: utm_medium=paid_social
    * - Campaign Name

diff --git a/docs/components/assets.rst b/docs/components/assets.rst
@@ -35,6 +35,15 @@ Navigate to Components > Assets. Mautic lists any Assets you have previously cre
 
 You create Assets by uploading local resources on your computer, or by locating the Asset from a remote storage host such as Amazon S3. There are limitations by size due to the settings of your server - any such restriction may display as a warning message in the file upload section.
 
+Add UTM to Asset
+~~~~~~~~~~~~~~~~~~
+UTM parameters appended to the download link means that UTM data is available in the resource download Report.
+
+.. code-block:: php
+
+``/asset/{id}:{name}?utm_source=test&utm_medium=test&utm_campaign=test&utm_id=test&utm_term=test&utm_content=test``
+
+
 .. vale off
 
 Uploading an Asset
@@ -93,7 +102,7 @@ Instead of uploading a file from your computer, you can either provide a link to
 .. vale off
 
 Viewing an Asset
-~~~~~~~~~~~~~~~~
+================
 
 .. vale on
 
@@ -111,7 +120,7 @@ To ensure that Contacts are providing you with valid Email addresses for high-va
 .. vale off
 
 Editing an Asset
-~~~~~~~~~~~~~~~~
+================
 
 .. vale on
 
@@ -120,12 +129,13 @@ You can edit an Asset by clicking on the 'edit' button while viewing the Asset,
 .. vale off
 
 Deleting an Asset
-~~~~~~~~~~~~~~~~~
+=================
 
 .. vale on
 
 It's possible to delete an Asset by clicking on the 'delete' button while viewing the Asset, or by selecting the arrow next to the checkbox for the Asset, and selecting 'delete'. Mautic displays a confirmation screen, prompting confirmation that you wish to delete the Asset.
 
 .. warning:: 
     Once deleted, you can't retrieve an Asset, and statistics relating to the number of downloads for that Asset are no longer be available. Contact Points accumulated as a result of accessing the resource remain. It's recommended where possible to unpublish Assets which are no longer in use - in future there may be an archive feature.
+
 
diff --git a/docs/conf.py b/docs/conf.py
@@ -58,3 +58,16 @@
 
 # -- Options for EPUB output
 epub_show_urls = 'footnote'
+
+# Please add links here that do not pass the "make checklinks" check.
+# A little context on the reason for ignoring is greatly appreciated!
+
+linkcheck_ignore = [
+    # Anchors are picked up as broken
+    r"https://docs.mautic.org/en/setup/cron-jobs#webhooks",
+    r"https://contribute.mautic.org/contributing-to-mautic/tester#setting-up-a-local-testing-environment",
+    # Twilio blocks the checker domain-wide.
+    r"https://support.twilio.com/*",
+    # This is a demo URL and should not be checked
+    r"https://api-ssl.bitly.com/*",
+]