Contribute to Mendix Docs

Last modified: October 24, 2024

Introduction

All Mendix documentation is open to the Mendix community, which means you can make changes and add to it in ways that you see necessary. Do you see a how-to that is inaccurate or a section of the Studio Pro Guide that needs to be updated? You can easily help us improve the documentation for the whole Mendix community!

All the Mendix documentation is stored in a GitHub repository. With a GitHub account, you can edit all existing documentation. You can also write a new how-to on an awesome topic of your choice and submit it. When making documentation changes, follow the Documentation Writing Guidelines.

To work on the documentation in GitHub, use Markdown. For details on this easy-to-use syntax, see the GitHub Guide to Mastering Markdown.

This how-to teaches you how to do the following:

  • Edit existing documentation in GitHub
  • Edit existing documentation locally and build local previews
  • Leave feedback on existing documentation
  • Create new documentation

Prerequisites

Before starting with this how-to, make sure you have completed the following prerequisites:

You can create and edit files directly online within GitHub, or outside GitHub using your preferred writing and committing tools.

In the Editing the Documentation and Previewing Changes Locally section below, you will also learn how to fork and clone the mendix/docs repository, edit documentation locally, and build local previews.

Editing the Documentation in GitHub

To edit existing documentation in GitHub, follow these steps:

  1. Click View on GitHub ( ) in the upper-right corner of the specific Mendix documentation page that you want to work on.

    The file of this doc opens on GitHub.

  2. Click Edit this file ( ) in the upper-right corner.

    • If you already have a fork of the development branch of the mendix/docs repository, the doc opens in a web editor.

    • If you do not have a fork yet, the following page opens and tells you need to fork the repository to propose changes. Click Fork this repository.

      The doc opens in a web editor.

  3. Make your changes in the editor. Make sure the changes align with our Documentation Writing Guidelines.

  4. Click Commit changes in the upper-right corner above the editor. The Propose changes dialog box opens.

  5. Enter a commit message, add more description if needed, and then click Propose changes.

    The Open a pull request page opens.

  6. Make sure the pull request uses our development branch as the base.

    For more information, see Creating a Pull Request and GitHub Standard Fork and Pull Request Workflow.

  7. Add a title for the pull request.

  8. Make sure that Allow edits by maintainers is selected.

  9. Click Create pull request.

The pull request is created. The Mendix Docs team will review the pull request as soon as possible. After the review and if there are no questions, the pull request will be published and you will be able to see the changes on the Mendix Docs site!

Editing the Documentation and Previewing Changes Locally

If you want to work outside GitHub, Mendix recommends using the following tools to contribute to the Mendix documentation:

You can clone a local copy of a forked repository, make documentation changes, and build local previews. To do so, follow these steps:

  1. Fork the development branch of the mendix/docs repository in GitHub. For more information, see Fork a repository in GitHub.

  2. Clone the forked repository using your preferred Git client, such as Visual Studio Code, GitHub Desktop, or Sourcetree:

    • Clone using Visual Studio Code:
      1. In Visual Studio Code, open the Command Palette (Ctrl + Shift + P, or Command + Shift + P on a Mac).
      2. Search for clone.
      3. Select Git: Clone.
      4. Enter the URL of the forked repository (example URL: https://github.com/YOUR-USERNAME/docs) and select a destination directory.
    • Or clone using GitHub Desktop:
      1. In GitHub Desktop, choose the option File > Clone Repository > URL.
      2. Enter the URL of the forked repository and select a destination directory.
    • Or clone using Sourcetree:
      1. In Sourcetree, click Clone.
      2. Enter the URL of the forked repository and select a destination directory.

    The repo is cloned into a folder called docs in the location you selected. You can rename it afterwards if you want to.

  3. Prepare the local repository with the Node package manager (npm) packages. You only need to do this once for this local repository. To do so, follow these steps:

    1. Download and install the Node.js LTS version (20.10 as of 2024). You do not need Chocolatey if that is offered.

    2. After the installation, make sure to verify the current Node.js version. You can do so by running the following command in a terminal: node -v.

    3. In the root directory of the local repository, run the following command in a terminal: npm install.

  4. Create a new branch from the local repository’s development branch and edit the documentation locally with your preferred editing tool. For example, you can open the local repository folder with Visual Studio Code, create a new branch from its development branch, find the file and make changes in the new branch. Remember to save your changes.

  5. To run a local version of site to preview your changes, in the root directory of the local repository, run the following command in a terminal: npm run build.

  6. Once the site is built, you see a table indicating how many pages have been created:

  7. Wait until the server is set up before you can see the site:

  8. To see the local site preview, go to http://localhost:1313/.

  9. Navigate in the left sidebar menu to the page that you just made changes to, and you can preview your changes locally!

  10. When the changes are ready to be submitted, stage and commit the changes using your preferred Git client, and create a pull request with the Mendix development branch as the base.

Leaving Feedback on the Documentation

If you find an issue with the documentation—whether it is a typo, a missing step, or a specific technical problem—we want to know about it so we can improve!

Click Leave Feedback ( ) in the upper-right corner of the screen.

Then you will be brought to our GitHub repo’s Issues page. Please include the following details in your feedback:

  • The document you are working with
  • A detailed description of what is wrong
  • Details on what can be improved or what the fix is, if applicable
  • Screenshots of your Mendix Platform usage, if applicable

We look at all feedback and take it seriously, and we will be in contact about how to resolve it.

Writing New Documentation

The sections below present the key steps in writing new documentation for Mendix.

Using a Template

To submit a new how-to or Studio Pro Guide page to the Mendix documentation, start with a Mendix documentation template:

Guidelines and Conventions

Follow these guidelines and conventions when writing:

  • Reference and use our Documentation Writing Guidelines
  • Make sure the Markdown file name reflects the title of the page (for example, if the page is titled “Create Your App,” the file name should be create-your-app.md)
  • Name the Markdown and image files in lower-case with a hyphen (-) between each word, and do not use spaces or any other symbols in the file name (for example, &), as these will not be accepted
  • When creating screenshots:
    • Make sure the resolution of your screen is 100% (or a multiple thereof) so that your images are sharp
    • Focus on the part of screen that contains the information you need so that the browser does not have to shrink the image when it displays it, and crop the image closely
    • Make sure the image file has a name that makes sense so it is easy to find it
    • Save the image as a .png (preferred), .jpg, or .gif file
    • Save the image file in a sub-folder in the attachments folder for the location of the document (this sub-folder should have the same name as the document file name you are working on)

Submitting Your Work

When you are ready to submit your work, follow these guidelines:

  • Commit new Markdown files via your preferred Git client or via the Create new file button in the Mendix GitHub repo (where you can copy-paste your text)
  • Commit new image files via your preferred Git client or via the Upload files button in the GitHub repo (where you can drag and drop your image files)

Finally, create a pull request that specifies the Mendix development branch as the base (for more information, see Creating a Pull Request).

Signing the Contributor License Agreement

The first time you make a contribution to the Mendix documentation (via a pull request), you need to sign the Contributor License Agreement for mendix/docs.

To access the license agreement, go to the Checks section of the pull request’s Conversation tab and click Details for license/cla.

This only needs to be done once.

Read More