diff --git a/.all-contributorsrc b/.all-contributorsrc index ab3259cf..cc454f07 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -122,6 +122,79 @@ "contributions": [ "doc" ] + }, + { + "login": "fee-sah-yor", + "name": "fisayo~", + "avatar_url": "https://avatars.githubusercontent.com/u/101174144?v=4", + "profile": "https://github.com/fee-sah-yor", + "contributions": [ + "doc" + ] + }, + { + "login": "pedaars", + "name": "Aaron Pedwell", + "avatar_url": "https://avatars.githubusercontent.com/u/11647950?v=4", + "profile": "https://pedaars.co.uk", + "contributions": [ + "doc" + ] + }, + { + "login": "adiati98", + "name": "Ayu Adiati", + "avatar_url": "https://avatars.githubusercontent.com/u/45172775?v=4", + "profile": "https://adiati.com", + "contributions": [ + "doc", + "review" + ] + }, + { + "login": "beneyalraj", + "name": "Abi beniyal", + "avatar_url": "https://avatars.githubusercontent.com/u/42829681?v=4", + "profile": "https://github.com/beneyalraj", + "contributions": [ + "doc" + ] + }, + { + "login": "favour-chibueze", + "name": "Favour Chibueze ", + "avatar_url": "https://avatars.githubusercontent.com/u/46398983?v=4", + "profile": "https://github.com/favour-chibueze", + "contributions": [ + "review" + ] + }, + { + "login": "adi-ray", + "name": "Aditya Ray", + "avatar_url": "https://avatars.githubusercontent.com/u/96347576?v=4", + "profile": "https://www.adityaray.xyz", + "contributions": [ + "doc" + ] + }, + { + "login": "ashwini2k6", + "name": "Ashwini Kumar", + "avatar_url": "https://avatars.githubusercontent.com/u/217481134?v=4", + "profile": "https://github.com/ashwini2k6", + "contributions": [ + "doc" + ] + }, + { + "login": "Lokesh9106", + "name": "Lokesh9106", + "avatar_url": "https://avatars.githubusercontent.com/u/231150390?v=4", + "profile": "https://github.com/Lokesh9106", + "contributions": [ + "doc" + ] } ], "contributorsPerLine": 7, diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 00000000..1f1f0525 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,609 @@ +# Contributing to Mautic user documentation + +Contributions are always welcome, no matter how large or small, or at whatever skill level you are. Before contributing, please read the [Code of Conduct](https://mautic.org/code-of-conduct/) and follow the directions in this guide. + +--- + +## Table of contents + +- [Communication expectation](#communication-expectation) +- [Issues](#issues) +- [Pull requests (PRs)](#pull-requests-prs) + - [Before submitting a PR](#before-submitting-a-pr) + - [Submitting a PR](#submitting-a-pr) + - [After submitting a PR](#after-submitting-a-pr) +- [Contributing workflow](#contributing-workflow) + - [Forking the repository](#forking-the-repository) + - [Clone the repository](#clone-the-repository) + - [Create a new branch](#create-a-new-branch) + - [Ensure the correct base branch](#ensure-the-correct-base-branch) + - [Ways to create a new branch](#ways-to-create-a-new-branch) + - [Push changes to the remote repository](#push-changes-to-the-remote-repository) + - [Create a PR](#create-a-pr) +- [Getting started](#getting-started) + - [1. On GitHub](#1-on-github) + - [2. GitHub Codespaces](#2-github-codespaces) + - [Setting up a codespace](#setting-up-a-codespace) + - [Live preview on codespace](#live-preview-on-codespace) + - [3. Local development](#3-local-development) + - [Prerequisite](#prerequisite) + - [Setting up local environment](#setting-up-local-environment) +- [Working with links](#working-with-links) + - [Create a new link](#create-a-new-link) + - [Check broken links](#check-broken-links) +- [Working with Vale](#working-with-vale) +- [Credit](#credit) + +--- + +## Communication expectation + +1. Always leave a detailed description in the pull request (PR). Leave nothing ambiguous for the reviewers. +2. Provide screenshots for visual changes. +3. Always review your code first. Be sure to run the project locally and test it thoroughly before requesting a review. +4. Communicate in the GitHub repository first before Slack. Whether it's in the issue or the PR, keeping the lines of communication open and visible to everyone on the team helps everyone around you. + +## Issues + +- When you contribute to the project for the first time, please consider checking the [good first issue](https://github.com/mautic/user-documentation/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) or [help wanted](https://github.com/mautic/user-documentation/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22help%20wanted%22) labels. + +- If you wish to work on an open issue, please comment on the issue, and a maintainer will assign it to you. + + If an issue isn't assigned, it's assumed to be available for anyone to work on. So, ensure that you're assigned to an issue **before** beginning work to avoid conflicts. + + **Note:** Please don't ask maintainers to assign you to another issue before you have finished working on yours and created a PR. + +- Please don't ask maintainers to assign you to an issue that already has someone assigned to it. If the assigned issue hasn't been addressed for a while and you're interested in working on it, leave a comment on the issue to ask about its status and progress. + +- Did you spot a typo, missing instructions, or have an idea for enhancing the Mautic User Documentation? You can [create an issue](https://github.com/mautic/user-documentation/issues/new/choose) to address it. + + However, the Education Team needs to triage the issue before you can work on it. If you wish to work on the issue you submitted, please inform and tag the `@mautic/education-team-leaders` in the comment. + +## Pull requests (PRs) + +PRs are always welcome. However, before working on changes, you must ensure that **you are assigned** to an existing issue and **link your work to the issue in your PR**. + +### Before submitting a PR + +1. Ensure that you work on your changes in a new branch on your fork. Create one branch for each task you work on. +2. Run and check your changes locally. Ensure that everything functions as intended. + +### Submitting a PR + +1. Ensure that you address one issue in one PR. If you work on multiple issues, work on them separately and create one PR to address each issue. +2. Make sure you give clear information about your changes in your PR: + + - **A title**. The PR title must describe your changes. For example: `Convert Marketer section into RST`. + - **A description**. A clear description can help PR reviewers understand what kind of changes you made in your PR. It's always good to walk through the process of how a reviewer can test your changes. + - **A related issue**. [Link the issue number](https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue) that you worked on and add a keyword of 'Closes', 'Fixes', or 'Resolves' in front of it. For example, `Closes #123`, `Fixes #234`, etc. You can find the issue number right next to the issue's title. Linking the issue number automatically closes your issue once your PR gets merged. + +3. Provide screenshots for visual changes if necessary. + +> [!TIP] +> +> Refer to [PR #369](https://github.com/mautic/mautic-community-handbook/pull/369) in the Mautic Community Handbook for an example of a well-documented PR. + +### After submitting a PR + +1. Ensure that all checks pass. If you see the linting build or prose failed, try to debug and fix it until all of them pass. If you have questions or need help, feel free to tag the `@mautic/education-team-leaders` in the comment. +2. Please don't DM maintainers on Slack to review or ask feedback and questions about your PR. + + If you'd like feedback or ask questions about your PR, tag `@mautic/education-team-leaders` in the comment of your PR or use the `#t-education` channel on Slack. That way, not only maintainers, but the community can help you get unstuck. The team always gets a notification whenever there is an incoming PR. If you haven't received a review within a week, you can tag them in the PR comments to ask for an estimated review time. + +3. Keep your branch up to date while waiting for review. +4. Respond and address the reviewer's feedback. Please don't request a review until you've addressed all feedback. + +## Contributing workflow + +In this section, you can find the contributing workflow and best practices for contributing to this project. + +### Forking the repository + +Forking this repository is the first step you need to take before proceeding. Forking means making a copy of a repository to your GitHub account. + +To fork this repository: + +1. In the main page of [mautic/user-documentation](https://github.com/mautic/user-documentation), click the 'Fork' button at the top. + + ![Fork button on GitHub](../assets/images/fork_button_github.png) + +2. Choose your username in the 'Owner *' dropdown menu. **Don't select an organization here. Always choose your personal account**; otherwise, maintainers can't collaborate and fix things for you on your PR. + + ![Choose fork owner on GitHub](../assets/images/choose_fork_owner_github.png) + +3. Uncheck the option of 'Copy the DEFAULT-BRANCH-NAME branch only' because later on, you want to be able to clone multiple branches. + +4. Click the green 'Create fork' button at the bottom. + + ![An uncheck state option to copy only default branch and a create fork button on GitHub](../assets/images/uncheck_option_and_create_fork_button_github.png) + +### Clone the repository + +After you forked the repository, you need to clone it. Cloning means making a copy of a repository in your local environment. In this case, you want to clone your forked repository. + +> [!IMPORTANT] +> +> The Mautic User Documentation contains multiple branches that represent specific versions of Mautic. You should clone each branch into its own dedicated folder and make your changes within the appropriate folder. +> +> So, for example, when you need to make documentation changes for Mautic versions 6 and 7, clone the branch `6.0` and save it in a folder, then clone the branch `7.0` and save it in a separate folder. You can name the folder anything you want, but it's best to reflect the branch name. For example, use names like `user-docs-6`, `user-docs-7`, and so on. + +Follow the steps below to clone your forked repository: + +1. Click your avatar on the top right. +2. Click 'Repositories'. + + ![Repositories option from a dropdown menu on GitHub](../assets/images/repositories_option_github.png) + +3. Open your forked user-documentation repository. The URL should have your username. For example: `https://github.com/YOUR-GITHUB-USERNAME/user-documentation`. +4. Click the green 'Code' button on top. +5. Select 'HTTPS' and copy the URL. + + ![Highlight of code button, copy symbol, and HTTPS tab on GitHub](../assets/images/code_button_https_tab_github.png) + +6. In your terminal, go to your local directory where you want to save this project. +7. Run the `git clone` command specifying the branch and folder name, and hit Enter: + + ```bash + git clone --branch BRANCH-NAME https://github.com/YOUR-GITHUB-USERNAME/user-documentation FOLDER-NAME + ``` + + Here are some examples: + + ```bash + git clone --branch 5.2 https://github.com/YOUR-GITHUB-USERNAME/user-documentation user-docs-5 + git clone --branch 6.0 https://github.com/YOUR-GITHUB-USERNAME/user-documentation user-docs-6 + git clone --branch 7.0 https://github.com/YOUR-GITHUB-USERNAME/user-documentation user-docs-7 + ``` + +### Create a new branch + +Before making changes, ensure that you create a new branch and work on it. You don't want to directly work on the default — such as `main` — or any other base branch, because you won't be able to work on lots of things at the same time. If you make all those changes on one branch, it's not possible to separate them out and only merge one change at a time. + +#### Ensure the correct base branch + +Before you create a new branch, you must ensure that you're on the branch that you need to base your changes on. Here's how to do it: + +1. In the bottom left of your VS Code, look at the branch tab — it has a git branch symbol with a branch name. It should indicate the branch from which you need to base your changes. + + ![Branch tab at the bottom left of VS Code](../assets/images/bottom_branch_tab_vscode.png) +    +2. If you're not on the correct branch, click the branch tab and select the correct branch from the dropdown menu at the top. + + If you prefer to switch it from the terminal, run the command below: + + ```bash + git switch BRANCH-NAME + ``` + +#### Ways to create a new branch + +There are two ways to create a new branch: + +1. **With Git Source Control in VS Code** + + Working with [Git source control](https://code.visualstudio.com/docs/sourcecontrol/overview?originUrl=%2Fdocs%2Fsourcecontrol%2Fintro-to-git) in VS Code is more comfortable if you're not technical and prefer a Graphical User Interface (GUI) over a terminal. + + To create a new branch with Git source control: + + 1. Click the branch tab — it has a git branch symbol with a branch name — at the bottom left of your VS Code. It opens a dropdown menu at the top. + + 2. Click 'Create new branch...' + + ![Create a new branch option in a dropdown menu on VS Code](../assets/images/create_a_new_branch_vscode.png) + + 3. Type the branch name with anything you like. Preferably, it reflects your changes, for example, `fix-typo`. + + 4. Hit enter. + +2. **On terminal** + + If you prefer working with the terminal, run the following command: + + ```bash + git checkout -b YOUR-BRANCH-NAME + ``` + +### Push changes to the remote repository + +If you have finished with your changes, you can push them to the remote repository to create a PR. Push means moving your commits from your local to the remote repository. + +There are two ways to push your changes to the remote repository: + +1. **With Git Source Control in VS Code** + + 1. On the left panel, click the 'Source Control' — resembles the git branches icon. + + ![Source control icon on VS Code](../assets/images/git_source_control_vscode.png) + + 2. Click the '+' icon next to the name of the file to move it to the 'stage' phase. It means you're adding this file as 'ready' to commit. + + 3. After you add all the files that you want to commit, add a commit message describing the changes you made. For example, `fix broken links`. + + 4. Click the 'Commit' button. + + ![Highlight plus icon to stage files, commit message input, and commit button at Source Control at VS Code](../assets/images/stage_and_commit_source_control_vscode.png) + + 5. Click the 'Publish Branch', which opens a dropdown menu. + + ![Publish branch button on source control at VS Code](../assets/images/publish_branch_button_github.png) + + 6. Select `origin: `. + + ![Highlight origin remote repository in a dropdown menu on Source Control at VS Code](../assets/images/select_remote_repo_dropdown_menu_source_control_vscode.png) + +2. **On terminal** + + 1. Run `git status`. It provides you with file paths of the files you've worked on. You can later copy these paths for the next step. + 2. Add the file path(s) that hold your changes to the 'stage' phase by running this command: + + ```bash + git add file-path-1 file-path-2 + ``` + + 3. Commit your changes with this command: + + ```bash + git commit -m "your message" + ``` + + Change `your message` to briefly describe your changes. For example, `fix broken links`. + + 4. Push your changes to the remote repository: + + ```bash + git push -u origin YOUR-BRANCH-NAME + ``` + +### Create a PR + +Once you've pushed your changes, you are ready to create a PR. To do so: + +1. Go to [https://github.com/mautic/user-documentation](https://github.com/mautic/user-documentation) and click the green button that prompts you to create a PR. + +2. **This step is crucial.** Each branch contains documentation for a specific version of Mautic. You must base your PR on the branch that corresponds to the version you are modifying. If you don't, your changes may apply to the wrong version of the documentation. For instance, if you're making updates for the documentation version `7.0`, you must base your PR on the `7.0` branch. + + At the top, you should see several dropdown menus: 'base repository', 'base', 'head repository', and 'compare'. + + Click the 'base: BRANCH-NAME'. It should open a dropdown menu. Select the base branch to the branch that your PR modifies. + + ![Highlight of PR base branch on GitHub](../assets/images/change_pr_base_branch_github.png) + +3. Fill in the PR template. Please read the "[Submitting a PR](#submitting-a-pr)" section for all the information you need to include in your PR for the reviewers. + +4. Submit it for review. + +## Getting started + +This project is built with [Sphinx](https://www.sphinx-doc.org/en/master/) and hosted on the [Read the Docs platform](https://readthedocs.org). The contents are written in [reStructuredText (RST)](https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html). + +There are three ways to work on changes for the Mautic User Documentation: + +1. Directly on GitHub +2. With [GitHub Codespaces](https://github.com/features/codespaces) on your browser +3. With code editor, such as [VSCode](https://code.visualstudio.com/), on your local machine — **recommended** + +### 1. On GitHub + +Making changes directly on GitHub is suitable for minor changes, such as fixing a typo. For bigger and more complex changes, please use GitHub Codespaces or work locally. + +To work directly on GitHub, follow the steps below: + +1. Click the 'Edit on GitHub' button on the top right of the page where you noticed the mistake. It takes you to the correct resource on GitHub. + + ![Screenshot of community handbook with a red box highlighting the Edit on GitHub button](../assets/images/edit-on-github.png) + +2. Click the edit button — which resembles a pencil — and make the necessary changes. + + ![Screenshot of community handbook with a red box highlighting the Edit on GitHub button](../assets/images/edit-button-github.png) + +3. Follow the instructions to commit the changes. +4. Select to commit to a new branch. Call the branch something relative to what you are updating. +5. [Create a PR](#create-a-pr). Read the "[Submitting a PR](#submitting-a-pr)" section about all info that you need to include in your PR. + +### 2. GitHub Codespaces + +Using GitHub Codespaces enables you to spin up the project in the cloud quickly. For a smooth process, use the Chrome or Firefox browser to work with Codespaces. + +
+ Tips to maximize free tier of Codespaces + +
+

To maximize your free tier of Codespaces, you can set the default idle timeout. To do so:

+
    +
  1. Click your avatar on the top right.
    2. +
  2. Click 'Settings'.
    3. +
  3. At the left bar, under 'Code, planning, and automation', click 'Codespaces'.
    4. +
  4. Find 'Default idle timeout'.
    5. +
  5. Set the idle time, and click 'Save'.
    6. +
+ +

You can also shut down your codespace whenever you've finished working by following these steps:

+
    +
  1. Close your codespace.
    2. +
  2. Go to https://github.com/codespaces.
    3. +
  3. Scroll down and you should see a list of your Codespaces.
    4. +
  4. Click the three dots icon at the codespace that you'd like to shut down.
    5. +
  5. Click 'Stop codespace'.
    6. +
+
+ +#### Setting up a codespace + +1. [Fork](#forking-the-repository) this repository to your own GitHub account. +2. Go to your forked repository on GitHub. +3. Click the branch dropdown menu on the top left and select the branch you need to base your changes on. For example, if you need to update documentation for Mautic version 7, switch to `7.0`. + + ![Highlight branch dropdown menu on GitHub](../assets/images/switch_branch_github.png) + +4. Click the green 'Code' button and select the 'Codespaces' tab. +5. Click the green 'Create codespace on BRANCH-NAME' or '+' button to create a new codespace. Codespace automatically sets up the project and opens Visual Studio Code. + + ![Highlight Codespaces tab, plus icon, and Create codepace on main at GitHub](../assets/images/codespaces_tab_github.png) + +6. Wait until the codespace finishes building. Once it's finished, the build prompt closes, the README preview opens — you can close this preview, and the `postCreateCommand` runs. Please wait until it finishes doing its job. + + ![Screenshot of postCreateCommand running in terminal](../assets/images/postcreatecommand-on-terminal.png) +7. [Create a new branch](#create-a-new-branch) to work on your changes. + + **Info:** Once you create a new branch, it automatically switches to your new branch. If you haven't seen the branch changes in your terminal, run `git status`, and you should see your branch name. + +8. All contents of the Mautic Community Handbook are available in the `docs/` directory. In your terminal, navigate to the `docs/` directory with `cd docs`. +9. Find the folder and file that you need to work on. +10. Work on your changes and use the [live preview](#live-preview-on-codespace) to view and test your changes in real-time. +11. Ensure that the changes you made follow Mautic's style guide by running the Vale lint. Please read the "[Working with Vale](#working-with-vale)" section to use Vale. + +#### Live preview on codespace + +1. Ensure that you're in the `docs/` directory. +2. Run `make html`. It generates the `build` folder. + + **Tip:** If you get `make: *** No rule to make target 'html'. Stop.` error message after running the `make html` command, you should check if you're in the correct directory. You must be in the `docs/` directory to run this command. +3. Click the preview button — resembles a book and a magnifying glass — at the top to trigger Esbonio, a tool used for live preview. A tab opens, but the preview won't work. You can safely close this tab. + + ![Highlight preview button on the top bar of VS Code on codespace](../assets/images/preview_button_vscode_codespace.png) + +4. At the bottom panel, click the 'Ports' tab. +5. Click the globe icon to open the live preview in your browser. Now you can see the project in real-time on localhost. + + ![Highlight port tab and globe icon to open preview in browser at VS Code on codespace](../assets/images/port_and_open_browser_vscode_codespace.png) + +
+ +
+ Troubleshooting live preview + +
+

Troubleshooting #1

+

If you can't see your changes in the live preview, try refreshing the page.

+ +

Troubleshooting #2

+

If refreshing doesn't work, try to:

+
    +
  1. Delete the build folder in the root.
    2. +
  2. Delete the build folder in the docs directory.
    3. +
  3. Refresh your codespace browser.
    4. +
  4. Ensure that you're in the docs/ directory.
    5. +
  5. Follow the steps in the Live Preview on Codespace section.
    6. +
+ +

Troubleshooting #3

+

If the above steps fail:

+
    +
  1. Close VS Code and the live preview browsers.
    2. +
  2. Go to https://github.com/codespaces.
    3. +
  3. At the bottom, you should see a list of your codespaces.
    4. +
  4. Click the three dots icon on the right of your project's codespace.
    5. +
  5. Click 'Stop codespace'.
    6. +
  6. Re-open the codespace by clicking its name.
    7. +
  7. Follow the steps in the Live Preview on Codespace section.
    8. +
+
+ +
+ +> [!TIP] +> +> - Always refresh the page to view the new changes you have applied. +> - All commands only work within the `docs/`directory. If you're unable to run a command, verify that you're in the correct directory. +> - Read the "[Troubleshooting live preview](#troubleshooting-live-preview)" section if you encounter any issues with the live preview in the codespace. + +
+ +If you're ready to push your changes to the remote repository and create a PR, please read the "[Push changes to the remote repository](#push-changes-to-the-remote-repository)" and "[Create a PR](#create-a-pr)" sections. + +### 3. Local development + +#### Prerequisite + +To work locally, you first need to install these on your machine: + +1. **VS Code (recommended) or your preferred IDE** + + If you haven't, [download and install VS Code](https://code.visualstudio.com/download) on your computer. + +2. **DDEV** + + Mautic uses [DDEV](https://ddev.com) to simplify local development and testing of documentation updates. Go to the [Get Started](https://ddev.com/get-started/) page on their website for instructions to install DDEV on your local machine. + + **For Windows users**: you can install and run DDEV on [traditional Windows](https://ddev.readthedocs.io/en/stable/#system-requirements-traditional-windows). However, using [Windows Subsystem for Linux 2 (WSL2)](https://learn.microsoft.com/en-us/windows/wsl/about) gives you faster and better performance. If you're new to WSL, follow the instructions on the [DDEV blog](https://ddev.com/blog/watch-new-windows-installer/) to install and set up WSL and DDEV. + +3. **Vale** + + Mautic uses [Vale](https://vale.sh/) to maintain style guide consistency across the docs. Go to the "[Install](https://vale.sh/docs/install)" page on the official docs to install Vale on your computer. + +4. **GitHub CLI (Optional)** + + You can [download and install GitHub CLI](https://cli.github.com/) on your computer if you'd like. It could save you time to work on your GitHub workflow with GitHub CLI, particularly if you want to assist with code reviews. + +#### Setting up local environment + +1. [Fork](#forking-the-repository) this repository to your own GitHub account. +2. Go to your forked repository on GitHub. +3. [Clone](#clone-the-repository) your forked repository. +4. Navigate into the project directory by running: + + ```bash + cd user-documentation + ``` + +5. [Create a new branch](#create-a-new-branch) to work on your changes. +6. Start the DDEV environment with this command: + + ```bash + ddev start + ``` + +7. Go to the `docs/` directory: + + ```bash + cd docs + ``` + +8. Find the folder and file that you want to work on. +9. Make changes and ensure that the changes you made follow Mautic's style guide by running the Vale lint. Please read the "[Working with Vale](#working-with-vale)" section to use Vale. Use the live preview to ensure everything works as intended in real time. +10. Build the project by running: + + ```bash + ddev build-docs + ``` + +11. Run the below command to view your changes live on your browser: + + ```bash + ddev launch + ``` + + DDEV uses the folder name as the project name. This command automatically opens your browser and navigates to `https://FOLDER-NAME.ddev.site/`. + +
+ +> [!TIP] +> +> - Every time you make changes, run `ddev build-docs` and refresh the page in your browser to see the changes. +> - If you don't see the configuration take effect, run `ddev restart` to restart the project. + +
+ +If you're ready to push your changes to the remote repository and create a PR, please read the "[Push changes to the remote repository](#push-changes-to-the-remote-repository)" and "[Create a PR](#create-a-pr)" sections. + +## Working with links + +In this section, you can find the commands that you need for working with links. Ensure that you're in the `docs/` directory to work with these commands. + +### Create a new link + +When you need to add a link, you can do so by running the command below — depending on where you work on your changes — in the terminal. + +If you work with Codespaces: + +```bash +make link +``` + +If you work locally with DDEV: + +```bash +ddev exec make link +``` + +Then input the answer to all prompts: + +- **Enter a Unique Link Name:** The name of the link. +- **Enter the link text the user sees:** The link that appears on the website. +- **Enter the URL:** The link URL. +- **Enter the .py file name (use_lower_case_and_underscore of link name):** The name of the file. + +
+ +> [!TIP] +> Ensure that all entries are clear and general so that anyone working with this project can easily search and reuse them. + +
+ +Here's an example: + +```bash +Enter a Unique Link Name: User Documentation +Enter the link text the user sees: User Documentation +Enter the URL: https://docs.mautic.org/ +Enter the .py file name (use_lower_case_and_underscore of link name): mautic_user_docs +``` + +### Check broken links + +When there's a broken link, the build fails. Therefore, ensure that there are no broken links. You can check the links by following the instructions below, depending on where you work on your changes, in the terminal. + +If you work with Codespaces: + +```bash +make checklinks +``` + +If you work locally with DDEV: + +```bash +ddev exec make checklinks +``` + +You should see a list of links. Find the broken link and fix it. Here's an example of a broken link: + +![Example of a broken link with error message: (contributing/contributing_docs_rst: line 198) broken https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html#add-link-make-command - 404 Client Error: Not Found for url: https://sublime-and-sphinx-guide.readthedocs.io/en/latest/references.html](../assets/images/broken_link_example.png) + +## Working with Vale + +Your changes must follow Mautic's style guide. To ensure that the changes are consistent with the style guide, in your terminal: + +1. Ensure that you're in the `docs/` directory. + + If you're not, and assuming you're in the project's root, you can run this command: + + ```bash + cd docs + ``` + +2. Run Vale: + + ```bash + vale folder_name/file_name.rst + ``` + +3. Look at the errors, warnings, and suggestions. +4. Address all of them and rerun Vale to ensure they pass the checks. +5. If you're sure that the style is good but Vale still gives suggestions, you can wrap the sentence in `.. vale off` and `.. vale on` statements. Here's an example: + + ```rst + .. vale off + + Regarding assets like JavaScript and CSS, the source files are loaded instead of concatenated, minified files. This way, the changes in those files will be directly visible when refreshed. If you want to see the change in the production environment, run this command: + + .. vale on + ``` + + If the suggestion targets a specific point in a list, you first need to ensure that the entire list adheres to the style guide. Then, wrap the whole list in the `.. vale off` and `.. vale on` statements as example below: + + ```rst + .. vale off + + * All PRs are made against the ``c.x`` branch in the first instance, for instance, ``5.x``. + * If the PR should be merged in an earlier release than the next major release of Mautic, duplicate the PR against the relevant ``a.b`` branch for bug fixes - for example, ``5.0`` - or ``a.x`` branch for features and enhancements - for example, ``5.x``. + * Backwards compatibility breaking changes can only be released in a major version, so they should only ever be made against the ``c.x`` branch, such as, ``5.x``. + + .. vale on + ``` + +
+ +> [!IMPORTANT] +> +> - Ensure that you wrap the sentences that you'd like Vale to skip with both `.. vale off` and `.. vale on` statements, in order. Failing to do so results in Vale lint skipping the rest of the contents. +> - Don't add statements to skip lint, unless necessary. If you're uncertain, it's best not to wrap them in the statements and let the team review and provide suggestions. + +
+ +## Credit + +These contributing guidelines are adapted from [OpenSource-Communities/intro](https://github.com/OpenSource-Communities/intro/blob/main/contributing/CONTRIBUTING.md) repository. + +--- + +Thank you for contributing to the improvement of the Mautic User Documentation. diff --git a/.github/ISSUE_TEMPLATE/01_documentation_fix.yml b/.github/ISSUE_TEMPLATE/01_documentation_fix.yml new file mode 100644 index 00000000..22805d8a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/01_documentation_fix.yml @@ -0,0 +1,52 @@ +name: 📝 Documentation Fix +description: Point out an error or suggest a change in the documentation. +title: "[DOCS]:" +labels: ["documentation", "needs-triage"] +body: + - type: markdown + attributes: + value: | + Thanks for helping improve the Mautic User Documentation! Please fill out the details below so we can fix it. + + - type: textarea + id: description + attributes: + label: Description + description: Please describe what is inaccurate, missing, or confusing in the documentation. + placeholder: "e.g., The UI for General settings in page X is out of date." + validations: + required: true + + - type: textarea + id: doc-link + attributes: + label: Relevant Documentation URL + description: Please provide a link to the exact documentation page that needs to be updated. + placeholder: "e.g., hhttps://docs.mautic.org/page-to-fix" + + - type: dropdown + id: willingness-to-pr + attributes: + label: Are you willing to help us fix this by making a pull request? + description: Contributing a pull request is the fastest way to get this fixed. + options: + - "— Select an option —" + - "No" + - "Yes" + - "Yes, but I need help" + validations: + required: true + + - type: textarea + id: suggestions + attributes: + label: Suggestions (Optional) + description: How do you suggest the documentation could be fixed or improved? + placeholder: "e.g., I think the screenshot on page X should be updated to reflect the new UI." + + - type: textarea + id: screenshots + attributes: + label: Screenshots or Screen Recordings (Optional) + description: To help us understand the issue visually, please attach any relevant images or recordings. + placeholder: "Drag and drop the files here." \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/02_feature_request.yml b/.github/ISSUE_TEMPLATE/02_feature_request.yml new file mode 100644 index 00000000..e730e8ed --- /dev/null +++ b/.github/ISSUE_TEMPLATE/02_feature_request.yml @@ -0,0 +1,38 @@ +name: 🌱 Feature Request +description: Request a new feature or enhancement. +title: "[FEAT]:" +labels: ["enhancement", "needs-triage"] +body: + - type: markdown + attributes: + value: | + Thanks for suggesting a new feature for the Mautic User Documentation! Please fill out the details below to help us understand and prioritize it. + + - type: textarea + id: description + attributes: + label: Description + description: Please provide a clear and concise description of the feature you would like to see. + placeholder: "e.g., I'd like to be able to edit the documentation directly on GitHub. This would be useful because..." + validations: + required: true + + - type: dropdown + id: willingness-to-pr + attributes: + label: Are you willing to help us add this feature this by making a pull request? + description: Contributing a pull request is the fastest way to get this fixed. + options: + - "— Select an option —" + - "No" + - "Yes" + - "Yes, but I need help" + validations: + required: true + + - type: textarea + id: suggestions + attributes: + label: Suggestions (Optional) + description: How do you suggest this feature should be implemented? + placeholder: "e.g., A user could click the edit button on the documentation page to make changes." \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/03_bug_report.yml b/.github/ISSUE_TEMPLATE/03_bug_report.yml new file mode 100644 index 00000000..899aaf93 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/03_bug_report.yml @@ -0,0 +1,55 @@ +name: 🐛 Technical Bug Report +description: Did you find a bug with the documentation system or automations? Create a report to help us improve. +title: "[BUG]:" +labels: ["bug", "needs-triage"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to report a technical bug within the Mautic User Documentation! Please fill out the details below to help us understand and resolve it. + + - type: textarea + id: description + attributes: + label: Description + description: Provide a clear and concise description of the bug. Include steps to reproduce the behavior, the expected result, and the actual result. + placeholder: "e.g., Running make html command didn't build the docs. Steps to reproduce: 1. Go to the /docs directory. 2. Run make html command. 3. Nothing happens." + validations: + required: true + + - type: dropdown + id: willingness-to-pr + attributes: + label: Are you willing to help us fix this by making a pull request? + description: Contributing a pull request is the fastest way to get this fixed. + options: + - "— Select an option —" + - "No" + - "Yes" + - "Yes, but I need help" + validations: + required: true + + - type: textarea + id: suggestions + attributes: + label: Suggestions (Optional) + description: How do you suggest this bug could be fixed? + placeholder: "e.g., I think changing X to Y would solve the issue." + + - type: textarea + id: environment + attributes: + label: Environment + description: | + Please provide details about your environment where the bug occurred. + - OS/Platform + - Browser & Version + placeholder: "e.g., Windows 11, Chrome v125" + + - type: textarea + id: screenshots + attributes: + label: Screenshots or Screen Recordings (Optional) + description: To help us understand the issue visually, please attach any relevant images or recordings. + placeholder: "Drag and drop the files here." \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..7fe979d6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,7 @@ +contact_links: + - name: Mautic Community Support + url: https://forum.mautic.org/ + about: Please ask questions around Mautic product here. + - name: Report a bug for the Mautic product + url: https://github.com/mautic/mautic/issues + about: Please create an issue to report a bug in the Mautic product here. \ No newline at end of file diff --git a/.github/holopin.yml b/.github/holopin.yml new file mode 100644 index 00000000..3ac10f0b --- /dev/null +++ b/.github/holopin.yml @@ -0,0 +1,11 @@ +organization: mautic +holobytes: + - evolvingStickerId: cmg9s1kkz0046l204bc2k5k7e + icon: avocado + alias: hacktoberfest-2025 + +# First time contributor badge +stickers: + - id: cmc38nn5r166207icbleca9jp + name: First Contribution + alias: first-contribution \ No newline at end of file diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..adb8f19a --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,37 @@ +## Description + + + + + + +## Linked issue + + + + + + +## Screenshots or screen recordings + + \ No newline at end of file diff --git a/README.md b/README.md index ffd3aefb..3b50254c 100644 --- a/README.md +++ b/README.md @@ -2,137 +2,17 @@ # Mautic user documentation -This repository hosts the end-user documentation for Mautic on the [Read the Docs platform][ReadTheDocs]. Whenever a PR is merged, changes are deployed immediately to https://docs.mautic.org/. - -## Migration of end-user docs to Read the Docs - -We aim to move all aspects of the end-user documentation to Read the Docs. - -For more background, our end goal, and to let us know if you want to help, please join the Education Team channel (#t-education) on Slack (get an invite at https://mautic.org/slack). Thanks in advance! - -## Local development setup - -There are two ways to set up your local environment: - -### 1. With DDEV (recommended) - -Mautic uses [DDEV](https://ddev.com) to simplify local development and testing of documentation updates. - -Go to the [Get Started](https://ddev.com/get-started/) page for instructions to install DDEV on your local machine. - ---- - -> [!NOTE] -> **For Windows users**: You can install and run DDEV on [traditional Windows](https://ddev.readthedocs.io/en/stable/#system-requirements-traditional-windows). However, it's recommended that you use [Windows Subsystem for Linux 2 (WSL2)](https://learn.microsoft.com/en-us/windows/wsl/about) for faster and better performance. -> -> If you're new to WSL, follow the instructions on the [DDEV blog](https://ddev.com/blog/watch-new-windows-installer/) to install and set up WSL and DDEV. - ---- - -After you've installed DDEV, follow these steps: - -1. [Fork and clone](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo) this repository to your local machine. -2. Navigate into the project directory by running: - - ```bash - cd user-documentation - ``` -3. Start the DDEV environment with this command: - - ```bash - ddev start - ``` -4. After making changes to documentation files, you need to build the updated docs by running: - - ```bash - ddev build-docs - ``` -5. Run the below command to view your changes live on your browser: - - ```bash - ddev launch - ``` - - This automatically opens your browser and navigates to `https://user-documentation.ddev.site/`. - - **Note:** You must ensure that your changes work as expected. Every time you make changes, run `ddev build-docs` and refresh the page in your browser to see the changes. - -> [!TIP] -> If you don't see the configuration take effect, run `ddev restart` to restart the project. - -### 2. With Sphinx (Python application) - -- [RST Syntax Cheatsheet][RST Cheatsheet] -- [Sphinx Demo][Sphinx Demo] -- [Sphinx Syntax][Sphinx Template] - -The following provides instructions for how to build docs locally for visualization without pushing to the remote: - -1. Install [Python 3](https://www.python.org/downloads/) for your OS if not already installed -2. Install Sphinx `pip install sphinx` -3. Install sphinx-rtd-theme `pip install sphinx-rtd-theme` -4. Install MyST Parser `pip install myst_parser` -5. CD into the docs directory `cd [path to this repo]/docs` -6. Run `make html` - - This will generate HTML in `docs/build/html`. Setup a web server with the web root as `docs/build/html` or open `docs/build/html/index.html` in a browser. - -#### Vale - -Before pushing, run Vale and address suggestions and errors as applicable. -1. Install [`vale`][Vale] -2. `vale .` - -#### PhpStorm/PyCharm File Watcher - -You can automatically build changes to rst files using a file watcher. -1. Go to Preferences -> Tools -> File Watchers -> + button -> custom -2. Configure the watcher as presented in the screenshot - -Screen Shot 2021-10-06 at 15 52 06 - -## Generating translations files - -Currently, we manually create the translation files necessary for Transifex to inform translators that there are changes to the content. - -To do this, run the following at the command line after following the steps to build the documentation locally. - -1. Run the command in the `/docs` folder `sphinx-build -b gettext . docs_translations` -2. Commit the files created with your pull request - +This repository hosts the User Documentation for Mautic on the [Read the Docs platform][ReadTheDocs]. Whenever a PR is merged, changes are deployed immediately to [https://docs.mautic.org/](https://docs.mautic.org/). [ReadTheDocs]: [RTD badge URL]: [RTD URL]: -[RST Cheatsheet]: -[Sphinx Template]: -[Sphinx Demo]: -[Vale]: -## Making a PR +## Contributing 🤝 -To make a small change to the base language files for the documentation, use the 'edit file' button on the documentation and commit your changes. This creates a new Pull Request. +All kinds of contributions are encouraged. For complete information on how to contribute to the Mautic user documentation repository, please read the [Contributing Guidelines](.github/CONTRIBUTING.md). -To make more complex changes, follow the steps below: - -1. Install a code editor. [Visual Studio Code](https://code.visualstudio.com) is recommended as it automatically installs all the extensions you need. -2. Install [GitHub CLI](https://cli.github.com/) which simplifies Git commands. -3. Create a working folder on your local computer. -4. Open a terminal and navigate to that folder using the command `cd `. -5. Fork the `mautic/user-documentation` repository on GitHub by clicking on the fork button at the top right. -6. Once forked, if you know your way around Git and you are writing documentation for something which is specific to the latest version of Mautic, you should branch from `main`. - - If you are writing documentation for a feature which is coming in a future release - for example, `5.0` - then branch off the relevant branch for that release, which should generally speaking match the branch used in the main `mautic/mautic` repository, for example, `5.x`. -7. Type `gh repo clone [your-forked-repo-name]/user-documentation` to clone your forked repository to your local computer. -8. Open the folder `user-documentation` that is created in your editor. -9. At the bottom left of your screen, you will see the default branch called `main` is showing as your active branch. Click this, and a box will appear at the top of the page allowing you to 'create a new branch'. Type a name which relates to the work you plan to do. -10. Make your desired changes by editing the files, which you can locate on the left pane. -11. Use the Source Control icon on the menu on the left to view changed files. Click the plus icon next to them to 'stage' them for committing. This lets you save and describe changes in chunks, making it easier to reverse specific changes in the future. -12. If editing text, ensure to run necessary commands to update files for translations on Transifex and include those updates in your PR. -13. Commit all your changes, then click the 'Publish Branch' button. This action might prompt you to create a fork of the repository if not done earlier. -14. Under the Source Control icon, navigate to the 'Branches' section. Find your branch, hover over the 'Create pull request' icon, and click it. -15. This action will direct you to the GitHub web interface where you can add an appropriate title and description for your proposed changes. -16. If reviewers request changes, switch back to the branch (as explained in step 9). Implement the necessary changes and follow steps 11-14 again. After updating, commit, and push your changes, then notify the reviewer to check the updated content. +All contributors are required to abide by our [Code of Conduct](https://mautic.org/code-of-conduct/). ## Contributors ✨ @@ -159,6 +39,16 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d Markus Heinilä
Markus Heinilä
📖 CPweb
CPweb
👀 Renato Heeb
Renato Heeb
📖 + fisayo~
fisayo~
📖 + + + Aaron Pedwell
Aaron Pedwell
📖 + Ayu Adiati
Ayu Adiati
📖 👀 + Abi beniyal
Abi beniyal
📖 + Favour Chibueze
Favour Chibueze
👀 + Aditya Ray
Aditya Ray
📖 + Ashwini Kumar
Ashwini Kumar
📖 + Lokesh9106
Lokesh9106
📖 diff --git a/assets/images/bottom_branch_tab_vscode.png b/assets/images/bottom_branch_tab_vscode.png new file mode 100644 index 00000000..16cdebfa Binary files /dev/null and b/assets/images/bottom_branch_tab_vscode.png differ diff --git a/assets/images/broken_link_example.png b/assets/images/broken_link_example.png new file mode 100644 index 00000000..e0d1c02d Binary files /dev/null and b/assets/images/broken_link_example.png differ diff --git a/assets/images/change_pr_base_branch_github.png b/assets/images/change_pr_base_branch_github.png new file mode 100644 index 00000000..9fdea63c Binary files /dev/null and b/assets/images/change_pr_base_branch_github.png differ diff --git a/assets/images/choose_fork_owner_github.png b/assets/images/choose_fork_owner_github.png new file mode 100644 index 00000000..ac8fdd1e Binary files /dev/null and b/assets/images/choose_fork_owner_github.png differ diff --git a/assets/images/code_button_https_tab_github.png b/assets/images/code_button_https_tab_github.png new file mode 100644 index 00000000..9a4ba739 Binary files /dev/null and b/assets/images/code_button_https_tab_github.png differ diff --git a/assets/images/codespaces_tab_github.png b/assets/images/codespaces_tab_github.png new file mode 100644 index 00000000..8b107288 Binary files /dev/null and b/assets/images/codespaces_tab_github.png differ diff --git a/assets/images/create_a_new_branch_vscode.png b/assets/images/create_a_new_branch_vscode.png new file mode 100644 index 00000000..6cefdbf7 Binary files /dev/null and b/assets/images/create_a_new_branch_vscode.png differ diff --git a/assets/images/edit-button-github.png b/assets/images/edit-button-github.png new file mode 100644 index 00000000..02908439 Binary files /dev/null and b/assets/images/edit-button-github.png differ diff --git a/assets/images/edit-on-github.png b/assets/images/edit-on-github.png new file mode 100644 index 00000000..807e5b77 Binary files /dev/null and b/assets/images/edit-on-github.png differ diff --git a/assets/images/fork_button_github.png b/assets/images/fork_button_github.png new file mode 100644 index 00000000..25bf0300 Binary files /dev/null and b/assets/images/fork_button_github.png differ diff --git a/assets/images/git_source_control_vscode.png b/assets/images/git_source_control_vscode.png new file mode 100644 index 00000000..8c6c658f Binary files /dev/null and b/assets/images/git_source_control_vscode.png differ diff --git a/assets/images/port_and_open_browser_vscode_codespace.png b/assets/images/port_and_open_browser_vscode_codespace.png new file mode 100644 index 00000000..c6951cca Binary files /dev/null and b/assets/images/port_and_open_browser_vscode_codespace.png differ diff --git a/assets/images/postcreatecommand-on-terminal.png b/assets/images/postcreatecommand-on-terminal.png new file mode 100644 index 00000000..6abb3b8e Binary files /dev/null and b/assets/images/postcreatecommand-on-terminal.png differ diff --git a/assets/images/preview_button_vscode_codespace.png b/assets/images/preview_button_vscode_codespace.png new file mode 100644 index 00000000..cb51477f Binary files /dev/null and b/assets/images/preview_button_vscode_codespace.png differ diff --git a/assets/images/publish_branch_button_github.png b/assets/images/publish_branch_button_github.png new file mode 100644 index 00000000..4a69ca23 Binary files /dev/null and b/assets/images/publish_branch_button_github.png differ diff --git a/assets/images/repositories_option_github.png b/assets/images/repositories_option_github.png new file mode 100644 index 00000000..619b4140 Binary files /dev/null and b/assets/images/repositories_option_github.png differ diff --git a/assets/images/select_remote_repo_dropdown_menu_source_control_vscode.png b/assets/images/select_remote_repo_dropdown_menu_source_control_vscode.png new file mode 100644 index 00000000..80ac4329 Binary files /dev/null and b/assets/images/select_remote_repo_dropdown_menu_source_control_vscode.png differ diff --git a/assets/images/stage_and_commit_source_control_vscode.png b/assets/images/stage_and_commit_source_control_vscode.png new file mode 100644 index 00000000..bff652bb Binary files /dev/null and b/assets/images/stage_and_commit_source_control_vscode.png differ diff --git a/assets/images/switch_branch_github.png b/assets/images/switch_branch_github.png new file mode 100644 index 00000000..7459a8b0 Binary files /dev/null and b/assets/images/switch_branch_github.png differ diff --git a/assets/images/uncheck_option_and_create_fork_button_github.png b/assets/images/uncheck_option_and_create_fork_button_github.png new file mode 100644 index 00000000..2c790c46 Binary files /dev/null and b/assets/images/uncheck_option_and_create_fork_button_github.png differ diff --git a/docs/builders/email_landing_page.rst b/docs/builders/email_landing_page.rst index dd159286..dcccbcce 100644 --- a/docs/builders/email_landing_page.rst +++ b/docs/builders/email_landing_page.rst @@ -132,7 +132,7 @@ Custom fonts From Mautic 5.x you can extend the Style Manager > Typography > Fonts list to include custom fonts. -.. image:: images/editorfonts.jpg +.. image:: images/editorfonts.png :width: 280 :alt: Screenshot of the Fonts in Style Manager > Typography diff --git a/docs/builders/images/editorfonts.jpg b/docs/builders/images/editorfonts.jpg deleted file mode 100644 index efb859d6..00000000 Binary files a/docs/builders/images/editorfonts.jpg and /dev/null differ diff --git a/docs/builders/images/editorfonts.png b/docs/builders/images/editorfonts.png new file mode 100644 index 00000000..e74f9c52 Binary files /dev/null and b/docs/builders/images/editorfonts.png differ diff --git a/docs/builders/images/editoroverview.png b/docs/builders/images/editoroverview.png index a1b01cbd..d6c5919b 100644 Binary files a/docs/builders/images/editoroverview.png and b/docs/builders/images/editoroverview.png differ diff --git a/docs/campaigns/creating_campaigns.rst b/docs/campaigns/creating_campaigns.rst index bdca0f6a..e98458fc 100644 --- a/docs/campaigns/creating_campaigns.rst +++ b/docs/campaigns/creating_campaigns.rst @@ -53,8 +53,7 @@ To begin creating Campaigns, perform the following steps: - **Allow Contacts to restart the Campaign** - Click the toggle switch to allow Contacts to restart the Campaign if you're building a Campaign for a recurring message - for example birthdays, subscriptions - or transactional operations - for example activity notifications, updating data. Enabling this option allows Contacts to go through the same Campaign multiple times. - **Active** - Click the toggle switch to turn the Campaign on or off. Ensure that you don't activate a Campaign until you're actually ready for it to go live. You can also schedule to activate or deactivate a Campaign at a future date by selecting a time and date. -#. Click **Launch Campaign Builder** to start building your Campaign, and add at least one event. For information about how to use the - Campaign Builder, see :doc:`/campaigns/creating_campaigns`. +#. Click **Launch Campaign Builder** to start building your Campaign, and add at least one event. For information about how to use the Campaign Builder, see :doc:`/campaigns/campaign_builder`. #. After adding events to your Campaign, close the Campaign Builder and click **Save & Close** to save your changes. diff --git a/docs/campaigns/images/campaign-decisions.gif b/docs/campaigns/images/campaign-decisions.gif index 25881042..f892c05c 100644 Binary files a/docs/campaigns/images/campaign-decisions.gif and b/docs/campaigns/images/campaign-decisions.gif differ diff --git a/docs/campaigns/images/campaign-events.png b/docs/campaigns/images/campaign-events.png index 7c50e9f7..77bbc090 100644 Binary files a/docs/campaigns/images/campaign-events.png and b/docs/campaigns/images/campaign-events.png differ diff --git a/docs/campaigns/images/campaign-sources.png b/docs/campaigns/images/campaign-sources.png index 1e6fb662..4ab74a5c 100644 Binary files a/docs/campaigns/images/campaign-sources.png and b/docs/campaigns/images/campaign-sources.png differ diff --git a/docs/campaigns/images/clone-campaign-event.png b/docs/campaigns/images/clone-campaign-event.png index c7d8e5c3..a5e88a25 100644 Binary files a/docs/campaigns/images/clone-campaign-event.png and b/docs/campaigns/images/clone-campaign-event.png differ diff --git a/docs/campaigns/images/multi-source-campaign.png b/docs/campaigns/images/multi-source-campaign.png index 74a9d234..dcc3dd97 100644 Binary files a/docs/campaigns/images/multi-source-campaign.png and b/docs/campaigns/images/multi-source-campaign.png differ diff --git a/docs/campaigns/images/new-campaign.png b/docs/campaigns/images/new-campaign.png index 32a7474d..781f2b25 100644 Binary files a/docs/campaigns/images/new-campaign.png and b/docs/campaigns/images/new-campaign.png differ diff --git a/docs/campaigns/images/paste-cloned-event-modal.png b/docs/campaigns/images/paste-cloned-event-modal.png index f73da4a3..7d6bfc07 100644 Binary files a/docs/campaigns/images/paste-cloned-event-modal.png and b/docs/campaigns/images/paste-cloned-event-modal.png differ diff --git a/docs/campaigns/images/send-email-delay-options.png b/docs/campaigns/images/send-email-delay-options.png index 9895121d..c6f4d225 100644 Binary files a/docs/campaigns/images/send-email-delay-options.png and b/docs/campaigns/images/send-email-delay-options.png differ diff --git a/docs/components/assets.rst b/docs/components/assets.rst index 4d9bf05e..3a286915 100644 --- a/docs/components/assets.rst +++ b/docs/components/assets.rst @@ -46,7 +46,7 @@ UTM parameters appended to the download link means that UTM data is available in .. code-block:: php -``/asset/{id}:{name}?utm_source=test&utm_medium=test&utm_campaign=test&utm_id=test&utm_term=test&utm_content=test`` + /asset/{id}:{name}?utm_source=test&utm_medium=test&utm_campaign=test&utm_id=test&utm_term=test&utm_content=test .. vale off diff --git a/docs/components/forms.rst b/docs/components/forms.rst index 9eca46ef..9678abe9 100644 --- a/docs/components/forms.rst +++ b/docs/components/forms.rst @@ -259,7 +259,6 @@ The Behavior tab helps marketers to improve the experience for the visitor compl - **Show when value exists**: if Mautic knows the Contact and they're tracked, when a value exists for a field Mautic hides the field when this setting is No. This prevents the Contact answering the same question multiple times. You may want to display the field even if it's already known when you want to ensure you have the most up to date information about the Contact. - **Show after X submissions**: this allows the marketer to show certain fields only when the Contact has submitted the Form a specified number of times. Enter a value between ``1`` and ``200``. When left undefined, the field shows every time the Contact views the Form. The goal is to minimize the number of fields shown to the Contact, so it's recommended to hide fields if it's not necessary to verify the values. - **Auto-fill data**: this allows you to pre-populate Contact data with known Contacts where the information exists in the Contact profile. Auto-fill works with Mautic Landing Pages, and data won't pre-populate when placing the Form anywhere else. Even if you're hiding this field, you may wish to turn on auto-fill to ensure saving of the information with the Form submission. -- **Read only**: activate this setting to lock auto-filled fields with existing Contact information, preventing any edits by Contacts. This ensures that the data submitted with the Form remains accurate and consistent, especially for critical details like Email addresses. Enable this option together with Auto-fill data to stop Contacts from changing essential information during Form submission. Field order ----------- diff --git a/docs/components/images/assets/asset_create.png b/docs/components/images/assets/asset_create.png index 93bb6fea..7ac09d4e 100644 Binary files a/docs/components/images/assets/asset_create.png and b/docs/components/images/assets/asset_create.png differ diff --git a/docs/components/images/assets/asset_settings.png b/docs/components/images/assets/asset_settings.png index f6c6501f..e8211659 100644 Binary files a/docs/components/images/assets/asset_settings.png and b/docs/components/images/assets/asset_settings.png differ diff --git a/docs/conf.py b/docs/conf.py index cb73a4b8..cf6aa548 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -49,6 +49,16 @@ html_static_path = ['css'] +# GH Edit button + +html_context = { + "display_github": True, # Integrate GitHub + "github_user": "mautic", # Username + "github_repo": "user-documentation", # Repository name + "github_version": "5.2", # Branch name + "conf_py_path": "/docs/", # Path in the repository to conf.py +} + # -- Options for HTML output # The theme to use for HTML and HTML Help pages. See the documentation for @@ -74,13 +84,17 @@ r"https://support.twilio.com/*", # This is a demo URL and should not be checked r"https://api-ssl.bitly.com/*", - #This domain blocks the checker. + # This domain blocks the checker (403 Client Error). r"https://linuxize.com/*", # The GitHub Search UI requires users to be authenticated with session cookies, which we can't set up programmatically r"https://github.com/search*", # Requires authentication. r"https://www.maxmind.com/en/accounts/current*", - # The URLs below broken and should be replaced by working ones. - r"https://staffwww.fullcoll.edu/sedwards/Nano/NanoKeyboardCommands.html", - r"https://blog.maxmind.com/search-results*" + # 403 client error from these domains + r"https://www.maxmind.com/en/home", + r"https://www.maxmind.com/en/geolite2/signup", + r"https://support.maxmind.com/hc/en-us/search*", + r"https://dev.mysql.com/doc/refman/5.7/en/regexp.html", + # 400 client error from this domain + r"https://developers.facebook.com/products/facebook-login/", ] diff --git a/docs/configuration/command_line_interface.rst b/docs/configuration/command_line_interface.rst index aaf15aa4..b81fce05 100644 --- a/docs/configuration/command_line_interface.rst +++ b/docs/configuration/command_line_interface.rst @@ -161,9 +161,6 @@ These are the commands you may need to use in relation to your Mautic instance. * - ``mautic:segments:update`` - Update Contacts in smart Segments based on new Contact data. - ``mautic:segments:rebuild`` - * - ``mautic:segments:stat`` - - Outputs table of all Segments and whether they are being used in Campaigns, Emails, other Segments, Form actions and SMS. Useful to detect Segments that can be deleted to save resources on rebuilds. - - * - ``mautic:theme:json-config`` - Converts Theme config to JSON from PHP - diff --git a/docs/configuration/images/shortener-bitly.png b/docs/configuration/images/shortener-bitly.png index 9bbc46fe..53cc3699 100644 Binary files a/docs/configuration/images/shortener-bitly.png and b/docs/configuration/images/shortener-bitly.png differ diff --git a/docs/css/theme.css b/docs/css/theme.css index 3c275f8f..d015e230 100644 --- a/docs/css/theme.css +++ b/docs/css/theme.css @@ -12,4 +12,8 @@ a { .wy-menu-vertical a, .wy-side-nav-search>a { color: #ffffff; -} \ No newline at end of file +} + +.wy-side-nav-search .version-switch select option { + color: #404040; +} diff --git a/docs/dashboard/images/dashboard-date-filters.png b/docs/dashboard/images/dashboard-date-filters.png index bf96ea4e..d366bd1a 100644 Binary files a/docs/dashboard/images/dashboard-date-filters.png and b/docs/dashboard/images/dashboard-date-filters.png differ diff --git a/docs/links/linux_file_folder_ownership.py b/docs/links/linux_file_folder_ownership.py index d7df5bb8..cace5001 100644 --- a/docs/links/linux_file_folder_ownership.py +++ b/docs/links/linux_file_folder_ownership.py @@ -2,6 +2,6 @@ link_name = "Linux file and folder ownership documentation" link_text = "file and folder ownership" -link_url = "https://www.thegeekdiary.com/understanding-basic-file-permissions-and-ownership-in-linux/" +link_url = "https://www.digitalocean.com/community/tutorials/how-to-set-permissions-linux" link.xref_links.update({link_name: (link_text, link_url)}) diff --git a/docs/links/maxmind_ccpa.py b/docs/links/maxmind_ccpa.py index bcf4b540..9142e62e 100644 --- a/docs/links/maxmind_ccpa.py +++ b/docs/links/maxmind_ccpa.py @@ -2,6 +2,6 @@ link_name = "MaxMind website" link_text = "MaxMind website" -link_url = "https://blog.maxmind.com/search-results?q=ccpa" +link_url = "https://support.maxmind.com/hc/en-us/search?utf8=%E2%9C%93&query=ccpa" link.xref_links.update({link_name: (link_text, link_url)}) \ No newline at end of file diff --git a/docs/links/nano_kb_commands.py b/docs/links/nano_kb_commands.py index c69b4d1d..0b615e98 100644 --- a/docs/links/nano_kb_commands.py +++ b/docs/links/nano_kb_commands.py @@ -2,6 +2,6 @@ link_name = "Nano keyboard commands" link_text = "Nano keyboard commands" -link_url = "https://staffwww.fullcoll.edu/sedwards/Nano/NanoKeyboardCommands.html" +link_url = "https://www.nano-editor.org/dist/latest/cheatsheet.html" link.xref_links.update({link_name: (link_text, link_url)}) diff --git a/docs/links/transifex.py b/docs/links/transifex.py index 5676c8ae..be1f5013 100644 --- a/docs/links/transifex.py +++ b/docs/links/transifex.py @@ -2,6 +2,6 @@ link_name = "Transifex" link_text = "Transifex" -link_url = "https://www.transifex.com/mautic/mautic/" +link_url = "https://explore.transifex.com/mautic/mautic/" link.xref_links.update({link_name: (link_text, link_url)}) diff --git a/docs/links/transifex_language_list.py b/docs/links/transifex_language_list.py index e794d370..4b576555 100644 --- a/docs/links/transifex_language_list.py +++ b/docs/links/transifex_language_list.py @@ -2,6 +2,6 @@ link_name = "transifex-language-list" link_text = "list of languages" -link_url = "https://www.transifex.com/mautic/mautic/" +link_url = "https://explore.transifex.com/mautic/mautic/" link.xref_links.update({link_name: (link_text, link_url)}) diff --git a/docs/plugins/amazon.rst b/docs/plugins/amazon.rst index 9ca92d49..9d38e8a8 100644 --- a/docs/plugins/amazon.rst +++ b/docs/plugins/amazon.rst @@ -58,22 +58,23 @@ With the bucket details and a user with the correct credentials, it's time to se 1. Go to **Settings** > **Plugins** 2. Click the **Amazon S3** Plugin. 3. Click the **install/upgrade Plugins**, if you don't see the Amazon S3 Plugin. -4. Enter the **ID**, secret from your user, and the bucket name. +4. Toggle the **Active** switch button to enable the Plugin. +5. Enter the **ID**, secret from your user, and the bucket name. .. image:: images/amazon-enabled.png :width: 400 :align: center :alt: Screenshot of Amazon Integration Form -5. Enter the **bucket location** as configured in Amazon S3. -6. Click **Save** to save your changes -7. Click the next tab, **Features**, to ensure that the option to use a cloud provider for Assets is selected. +6. Enter the **bucket location** as configured in Amazon S3. +7. Click **Save** to save your changes +8. Click the next tab, **Features**, to ensure that the option to use a cloud provider for Assets is selected. .. image:: images/amazon-features.png :alt: Screenshot of Amazon Integration Form -8. Click **Save & Close**, and refresh the Plugins page - the Amazon S3 Plugin icon will be in color rather than ``Grayscale``, indicating that it's active. +9. Click **Save & Close**, and refresh the Plugins page - the Amazon S3 Plugin icon will be in color rather than ``Grayscale``, indicating that it's active. When you upload an Asset to your S3 bucket you can select it by creating a new Asset and choosing Remote Files > S3. diff --git a/docs/plugins/images/amazon-enabled.png b/docs/plugins/images/amazon-enabled.png index cd03fef7..32d333c6 100644 Binary files a/docs/plugins/images/amazon-enabled.png and b/docs/plugins/images/amazon-enabled.png differ diff --git a/docs/plugins/images/amazon-features.png b/docs/plugins/images/amazon-features.png index a3be107f..c070cdf0 100644 Binary files a/docs/plugins/images/amazon-features.png and b/docs/plugins/images/amazon-features.png differ diff --git a/docs/plugins/images/hubspot-plugin.png b/docs/plugins/images/hubspot-plugin.png index aedacb46..1c8f631e 100644 Binary files a/docs/plugins/images/hubspot-plugin.png and b/docs/plugins/images/hubspot-plugin.png differ diff --git a/docs/plugins/images/plugins.png b/docs/plugins/images/plugins.png index 48589b1e..4c3773fb 100644 Binary files a/docs/plugins/images/plugins.png and b/docs/plugins/images/plugins.png differ diff --git a/docs/plugins/images/twilio-messaging-service-id-mautic.png b/docs/plugins/images/twilio-messaging-service-id-mautic.png index 8fe0a4c6..92b58022 100644 Binary files a/docs/plugins/images/twilio-messaging-service-id-mautic.png and b/docs/plugins/images/twilio-messaging-service-id-mautic.png differ diff --git a/docs/plugins/images/vtiger-mautic-enabled.png b/docs/plugins/images/vtiger-mautic-enabled.png new file mode 100644 index 00000000..73319834 Binary files /dev/null and b/docs/plugins/images/vtiger-mautic-enabled.png differ diff --git a/docs/plugins/images/vtiger-mautic-features.png b/docs/plugins/images/vtiger-mautic-features.png index 6d2052e9..c865b8a8 100644 Binary files a/docs/plugins/images/vtiger-mautic-features.png and b/docs/plugins/images/vtiger-mautic-features.png differ diff --git a/docs/plugins/images/vtiger-mautic.png b/docs/plugins/images/vtiger-mautic.png index 0f302200..07306759 100644 Binary files a/docs/plugins/images/vtiger-mautic.png and b/docs/plugins/images/vtiger-mautic.png differ diff --git a/docs/plugins/social_login.rst b/docs/plugins/social_login.rst index 8a74985d..bee48839 100644 --- a/docs/plugins/social_login.rst +++ b/docs/plugins/social_login.rst @@ -1,4 +1,3 @@ - Social login ############ @@ -26,13 +25,13 @@ Before you can use social login, each social media Plugin needs authorization. H :width: 400 :alt: Screenshot of a callback URL input field. -2. **Add Your API Keys**: copy the API Key - Client Key - and API Secret - Client Secret - from the social platform. Paste these keys into the relevant fields in the Mautic Plugin configuration.``` +2. **Add Your API Keys**: copy the API Key - Client Key - and API Secret - Client Secret - from the social platform. Paste these keys into the relevant fields in the Mautic Plugin configuration. .. image:: images/API_key.png :width: 400 :alt: Screenshot of an API Key input field. -1. **Authorize the Plugin**: in the Mautic Plugin configuration, click **Authorize**. You must **turn on** the Plugin - do this by toggling the option to “Yes”. Finally, save your configuration to complete the setup. +3. **Authorize the Plugin**: in the Mautic Plugin configuration, click **Authorize**. You must **turn on** the Plugin - do this by toggling the option to “Yes”. Finally, save your configuration to complete the setup. .. Tip:: You can manage each social network under its respective tab in Mautic's Plugin settings. Make sure each network is fully authorized by adding the required API credentials. @@ -54,7 +53,7 @@ Having configured the social Plugins, you can add social login buttons to your M .. note:: Only the buttons for Plugins you've authorized work in the Form. Ensure you've configured all Integrations correctly for a smooth User experience. -Step 3: configuring features and mapping Contact fields``` +Step 3: configuring features and mapping Contact fields ******************************************************* After configuration and authorization of the Plugin, you can customize how Mautic handles the incoming social profile data. Under the **Contact Field Mapping** tab in the Plugin settings, map the fields from the User's social profile - for example Email, Name - to the appropriate Mautic Contact fields. diff --git a/docs/plugins/vtiger.rst b/docs/plugins/vtiger.rst index f85aa93b..81644b25 100644 --- a/docs/plugins/vtiger.rst +++ b/docs/plugins/vtiger.rst @@ -51,7 +51,14 @@ Configure the Vtiger CRM Plugin If you want to use the Plugin, you have to activate it. -1. Set the *Active* switch to **Yes**. +1. Toggle the **Active** switch button to enable the Plugin. + +.. image:: images/vtiger-mautic-enabled.png + :alt: Screenshot of Vtiger Mautic Integration + :width: 500 + :align: center + +| 2. In the **Features tab** is Push Contacts to this Integration checkbox and it's checked by default. diff --git a/docs/points/images/points-action.png b/docs/points/images/points-action.png index 7caaa8e8..51e183f7 100644 Binary files a/docs/points/images/points-action.png and b/docs/points/images/points-action.png differ diff --git a/docs/points/images/points-trigger.png b/docs/points/images/points-trigger.png index 1aa50203..7b29cc22 100644 Binary files a/docs/points/images/points-trigger.png and b/docs/points/images/points-trigger.png differ diff --git a/docs/points/images/send-an-email-to-user.png b/docs/points/images/send-an-email-to-user.png index 3b77c11a..d18c837d 100644 Binary files a/docs/points/images/send-an-email-to-user.png and b/docs/points/images/send-an-email-to-user.png differ diff --git a/docs/points/images/trigger-events.png b/docs/points/images/trigger-events.png index efbbdbd7..c71e617f 100644 Binary files a/docs/points/images/trigger-events.png and b/docs/points/images/trigger-events.png differ diff --git a/docs/troubleshooting/file_ownership_permissions.rst b/docs/troubleshooting/file_ownership_permissions.rst index f4693b9f..57b9007b 100644 --- a/docs/troubleshooting/file_ownership_permissions.rst +++ b/docs/troubleshooting/file_ownership_permissions.rst @@ -18,17 +18,20 @@ File and folder permissions specify who and what can read, write, modify, and ac User ==== + A User is the owner of the file. By default, the person who created a file becomes its owner. Hence, a User is also sometimes called an **owner**. Group ===== + A Group can contain multiple Users. All Users belonging to a Group have the same access permissions to the file. Groups simplify permissions - all Users in a specific Group inherit the permissions assigned to that Group, rather than having to assign permissions to each User individually. Other ===== + Any other User who has access to a file comes into 'Other', meaning they have neither created the file, nor belong to a Group that owns the file. Practically, this means 'the rest of the world'. Hence, this is also referred to as **permissions for the world**. -Linux distinguishes between these three User types to prevent Users accessing, editing, or deleting files they shouldn't be able to change. Read more about :xref:`Linux file and folder ownership documentation` +Linux distinguishes between these three User types to prevent Users accessing, editing, or deleting files they shouldn't be able to change. Read more about :xref:`Linux file and folder ownership documentation`. Permissions and ownership settings are critical to ensuring the security of your server and Mautic instance, so it's important to get them right. If your files don't have the appropriate permissions in place, it's easier for hackers to intrude on your files and gain access to your Mautic instance. Setting your file permissions correctly may not save you from all attacks, but it helps make your Mautic instance a bit more secure. @@ -39,7 +42,7 @@ Mautic needs access to read and write files in the Mautic directory to enable ce Problems with permissions and ownership generally occur because: -* You've uploaded Mautic or made changes to files and folders as a different User to the one that Mautic uses to run - for example you uploaded files using an FTP account with the username ``bob`` but your web server executes scripts as a User called ``www-data``. +* You've uploaded Mautic or made changes to files and folders as a different User to the one that Mautic uses to run - for example you uploaded files using an FTP account with the username ``bob`` but your web server executes scripts as a User called ``www-data`` * The User that Mautic uses to run doesn't have the appropriate permissions on the files and folders - for example, ``bob`` isn't able to create directories, or read files * You ran an update as a different User to that which Mautic uses to run - resulting in some files and folders having their ownership changed @@ -50,11 +53,13 @@ Resetting the permissions of your files and folders requires running some comman Solution for hosting providers that offer cPanel access ======================================================= + A script to fix permissions & ownership, on files & directories, for cPanel accounts. You could ask your hosting provider to run that script to reset the permissions to the correct values. Find this handy script here: :xref:`cPanel fix permissions script`. Identifying the problem ======================= -Log into your server using SSH, and change to the Mautic directory using the command + +Log into your server using SSH, and change to the Mautic directory using the command: .. code:: bash @@ -96,7 +101,7 @@ To find out which User Apache is running as, run the following command and take ps aux | grep apache2 -Use this information to find the Groups with the following command +Use this information to find the Groups with the following command: .. code:: bash