A summary of CiviCRM's documentation infrastructure.

CiviCRM documentation is currently found in many different sources. Our long term vision is to have it all published at https://docs.civicrm.org/.

Documentation is organised into books, which are accessible at URLs as follows https://docs.civicrm.org/[name]/ By default, a URL in the above format will redirect to https://docs.civicrm.org/[name]/en/stable which shows the latest stable documentation in English.

Books may also be available in different lanaguages and have different editions (e.g. 4.6, 4.7) (which typically map to the version of CiviCRM that they are documenting.

The very latest documentation (which may be incomplete / unfinished) can be accessed at https://docs.civicrm.org/[name]/en/stable.

All CiviCRM documentation should be written in Markdown, following mkdocs conventions, and stored in a git repository, such as https://github.com/civicrm/civicrm-user-guide.

See https://civicrm.org/improve-documentation for how to get started contributing to our documentation. If you have any questions about how stuff works, or how to start contributing, please join the documentation mailing list and email the list with your question. We'll be very glad to help you get going.

Books are auto be updated when the corresponding branch is updated their repository. This is typically acheived by making edits and submitting a pull request. Any emails listed in the commits that are submitted as part of the pull request will receive an email with a summary of the update process.

If required, a book can be manually updated by calling a URL in the following format: https://docs.civicrm.org/admin/publish/{book}/{en}/{branch}.

• {book} the name of the book - as per configuration file in the conf/books directory.
• {lang} the language that you want to publish - as defined in the configuration file.
• {branch} the name of the branch that you want to publish - needs to be a branch in the repository for that language.

Books are defined with a Yaml configuration file, stored in the app/config/books/ directory of this repository.

The config file lists the languages that the book is available in, with a repository for each language. For each language, the configuration file defines:

• which edition of the book should be considered stable
• where to find the latest edits to the book
• a history of book editions of the book (these will be publicly listed at https://docs.civicrm.org/).

Note: the following steps are only useful and necessary for people looking after CiviCRM's documentation infrastructure.. If you are want to contribute to CiviCRM's documentation, there see Contributing to documentation above.

1. Ensure that that you have pip (for python) and composer (for php) installed..

2. Install mkdocs.

$ sudo pip install mkdocs

Note: Ensure that mkdocs is installed as root so that it can be accessed from the src/publish.php script (typically invoked as https://docs.civicrm.org/publish.php)

3. clone this repository to somewhere like /var/www/civicrm-docs

4. Run composer install

$ cd /var/www/civicrm-docs
$ composer install

5. Configure an nginx virtual host

$ cd /etc/nginx/sites-enabled
$ ln -s /var/www/civicrm-docs/app/config/nginx.conf civicrm-docs

6. Reload your nginx config and you should be up and running.

• A CiviCRM theme for documentatiom
• Create a better docs homepage
  • Inlcuding a history for each book based on book.yml file
• Future proof documentation structure
  • / - documentation home
  • /user/ - user documentation for core civicrm
  • /extensions/[extenstion_name] - documentation for extensions (probably mostly user focused, though with possible developer and system administrator sections)
  • /admin/ - system administrator documentation (installation, upgrades, email server configuration)
  • /dev/ - developer documentation
• Last but not least: migrate lots of documentation (e.g. our developer and sys administrator documentation)