Skip to content

Writing Documentation

To read documentation, go to docs.civicrm.org for the most high-level list of all active documentation.

This page describes the details of the documentation systems within CiviCRM and how to contribute. We also have a more basic overview on how to contribute to this guide or the user guide.

Note: the wiki is not covered here

The wiki has historically been CiviCRM's documentation system but has been phased out as of 2017. The rest of this page describes MkDocs guides only and does not cover documentation processes that involve the wiki. No new documentation can be created on the wiki.

When to document

If you are contributing to core, updating documenting along with your changes is an important step to ensure the long-term usability and maintainability of CiviCRM.

Not all changes require documentation updates. Here are some guidelines:

  • Documentation should almost always accompany new features.
    • Keep in mind that some features are user-facing (and thus require new documentation in the User Guide) whereas some features are developer-facing (and thus require new documentation in the Developer Guide.)
  • Bug fixes will occasionally require documentation updates. Check existing docs to see what changes might be necessary.

Tip

Try writing documentation before writing your code! Then you have a way to organize your thoughts and measure whether the feature works.

If you are submitting a core pull request and would like to submit accompanying doc changes, please provide comments in both pull requests for cross reference. Your docs PR will not be merged until your core PR is merged first.

Guides in MkDocs

We are using MkDocs to produce guides. The content for each of these guides is written in markdown, stored in text files, and hosted in a repository on GitLab. Then, the guides are automatically published to docs.civicrm.org using our custom publishing system.

Versions

We no longer maintain version specfic documentation, we maintain evergreen documentation which always tracks the latest version of CiviCRM but, where appropriate indicates the version that new features and significant changes appeared in. For example:

From CiviCRM version 5.37.0 ReCAPTCHA configuration can be found at Administer -> Customise Data and Screens -> ReCAPTCHA. In earlier versions of CiviCRM this lived on the Miscellaneous Settings page.

If you're improving current documentation, please edit the master or main branch.

Languages

A guide can have multiple languages, and we use separate repositories for different languages. For example, you can click See all X editions and find the repositories for additional languages.

Contributing to documentation

We welcome contributions, small and large, to documentation!

Resources:

Before diving into editing, you may find helpful information within the following resources:

Submitting issues

The simplest way to help out is to describe a change that you think should be made by writing a new issue in the issue queue for the lab.civicrm.org guide you are reading. Then someone will see your issue and act on it, hopefully fast. Each guide has its own issue queue. First find the lab.civicrm.org repository of the guide, which can be found on their respective documentation guide (User Guide, SysAdmin Guide, Developer Guide) at the right corner of the navigation bar. On viewing lab.civicrm.org, click on "Issues". You will need an account on lab.civicrm.org to submit a new issue, but creating one is quick and free.

Editing through lab.civicrm.org

Please see the documentation for editing with Git in the CiviCRM User Guide.

Testing locally with MkDocs

The most advanced way to work on a guide is to use git to download all the markdown files to your computer, edit them locally, preview the changes with MkDocs, then use git to push those changes to your personal fork, and finally make a "pull request" on the main repository. This approach makes editing very fast and easy, but does require a bit of setup, and some knowledge of how git works.

  1. Obtain the source files for the guide you want to edit

    1. Find the repository on lab.civicrm.org (see the "Lab" link on the top right of screen of the documentation you are reading)
    2. Fork the repository on lab.civicrm.org.

    3. Clone your fork of the repository to your computer

      git clone https://lab.civicrm.org/YourUserName/civicrm-dev-docs.git
cd civicrm-dev-docs

  2. (optional) If you have Docker installed, then at this point you can run one of the following commands and then skip to the "View the guide locally ..." step below.

    1. For folks who have a full Docker for Windows / Mac / Linux environment, run this command:

      docker run --rm -v "$PWD:/docs" -p 8000:8000 -w /docs "mjcoltd/civicrm-docker-mkdocs" serve --dirtyreload -a 0.0.0.0:8000

      and skip to the "View the guide" step below. To update this docker image periodically, run the following before the command above.

    docker rmi mjcoltd/civicrm-docker-mkdocs

    1. For folks who have a legacy or "Home" operating system (Windows 7, 8.1, 10 Home Premium), the situation is a bit more complex. The same is true if you have implemented virtual machines on your system using Oracle VM VirtualBox or VMWare tools. These tools don't play well with native Windows HyperV virtualization. In any case, follow these steps:

      1. Check that GitHub folder is in the path: c:\Users\<username>\Documents\.... If it is, all is good; if not, move it there, and edit your GitHub configuration to reflect the changed location.
      2. Set up a Docker-Toolbox environment (which depends on Oracle VM VirtualBox), and check that it is functioning properly (Hello-world container works).
      3. Review the Docker-Toolbox instance in Oracle VM VirtualBox to ensure that it has the necessary port-forwarding configuration in place. If there is no HTTP port forwarding rule, add one that specifies: Name: HTTP, Protocol: TCP, Host IP: 127.0.0.1, Host Port: 8000, Guest IP (empty), Guest Port: 8000. If this configuration is not present, all attempts to open a browser session will receive a "connection refused" error.
      4. Run this command:

      docker run --rm -v "/c/Users/<username>/Documents/GitHub/civicrm-user-guide:/docs" -p 8000:8000 -w /docs mjcoltd/civicrm-docker-mkdocs serve --dirtyreload -a 0.0.0.0:8000
      and skip to the "View the guide locally ..." step below.

  3. Install pip (python package manager)

    • OS X: brew install python3
    • Debian/Ubuntu: sudo apt-get install python3-pip

  4. Install MkDocs, plus the Material theme and the Pygments syntax highlighter.

    sudo pip install mkdocs==1.0.4 mkdocs-material==4.6.3

  5. Serve a local copy of the guide with MkDocs

    1. Run:

      mkdocs serve
      • If you get [Errno 98] Address already in use then try using a different port with mkdocs serve -a localhost:8001

  6. View the guide locally in your browser at http://localhost:8000.

  7. Edit the markdown with an editor of your choice. As you save your changes mkdocs will automatically reprocess the page and refresh your browser.

  8. When you are happy with your edits, use git to commit and push your changes up to your fork. Then submit a pull request on lab.civicrm.org.

  9. Ctrl-C will stop the MkDocs server.

Adding a new page

  1. Make sure you are already set up to edit locally with MkDocs
  2. Decide where it should go in the menu. (Ask for advice in the documentation channel if you're unsure.)
  3. Add a menu location for the new page by adding a new line appropriately in mkdocs.yml.
    • Follow the pattern you see on other lines of this file to specify a title and a file location.
    • When setting the title, keep in mind that the same title will display in the menu and in the reader's browser tab title, so choose a title that's short but that also stands on its own to some extent.
    • Specify a location for the markdown file for your new page which follows the folder structure of the menu location you decided on.
  4. Add a new markdown file in the location specified by your new menu item and begin add content to it.
  5. If you're copying existing content from other sources (e.g. wiki, StackExchange, etc.) then follow the instructions for providing attribution

Moving pages

If you'd like to move a page, take the following steps:

(Before-hand) if you have changes to page content, then make those in a separate git commit.

  1. Move the file.
  2. Update mkdocs.yml with the new path to the page.
  3. Add a redirect rule to redirects/internal.txt.
    • Format is old/page/path new/page/path
    • Use the part of the path after the docs directory.
    • Don't use leading or trailing slashes
    • Don't use a .md extension
    • List the old path first and the new one second
    • Separate the paths with a space
  4. Run mkdocs serve and see if it gives you any warnings about broken hyperlinks. If it does, go fix those.

Note

Page redirection won't work locally (when previewing with mkdocs serve), but it will work once the guide is published on docs.civicrm.org. The redirection is implemented as part of our docs-publisher app.

Auto-generated documentation

Some guides may have auto-generated content, which is summarized here.

In the Developer Guide

This Developer Guide has an automatically-generated list of all hooks. To re-create this list, run the following command from the root level of the repository:

./bin/tools generate:hooks-list

Our editing workflow currently requires someone to manually run this command after and commit its changes whenever hooks files are edited.

Content attribution guidelines

All CiviCRM documentation content is licensed CC BY-SA 3.0. This means that if you want to copy content out of our docs and use it elsewhere, you're welcome to do so as long as your give attribution to the author.

How to obtain author information for content within our guides

This is relevant when you want to copy content out of our documentation books.

  1. Find the lab.civicrm.org repository for the book that contains the content you'd like to use. (There will usually be a link to this repository at the top right of ever page.)
  2. Navigate to the corresponding markdown file within lab.civicrm.org (it will match the URL path of the published content).
  3. Click on "Blame" to see detailed information about content authors, line, by line.

How to display attribution for content migrated into our books

The CiviCRM wiki and Stack Exchange also use the CC BY-SA 3.0 license, which is convenient because content is regularly migrated into our MkDocs guides from these sources. But to comply with the license, we must attribute the original content authors

When migrating content into our docs guides which requires attribution, display this attribution at the bottom of the page as follows:

## Credits

Some content from this page was migrated from other sources
and contributed by the following authors:

* Mickey Mouse
* Lisa Simpson
* Big Bird

Commit messages should also reference the URL of the original content.