Merge pull request #22 from seanmadsen/master

use hash syntax for headings, migrate "developer community" wiki page

Merge pull request #22 from seanmadsen/master
40f9155c · totten · GitHub · 8e9082f3 · f98f557e · 40f9155c
Commit 40f9155c authored 8 years ago by totten Committed by GitHub 8 years ago
--- a/docs/api/actions.md
+++ b/docs/api/actions.md
-API Actions
-===========
+# API Actions

 Most entities support the following actions:

-create
------
+## create

 Insert or update one record. (Note: If an `id` is specified, then an
 existing record will be modified.)

-delete
------
+## delete

 Delete one record. (Note: Requires an explicit `id`. Note: if you
 want to skip the 'recycle bin' for entities that support undelete (e.g.
 contacts) you should set `$param['skip_undelete'] => 1);`

-get
---
+## get

 Search for records

-getsingle
---------
+## getsingle

 Search for records and return the first or only match. (Note: This
 returns the record in a simplified format which is easy to use)

-getvalue
--------
+## getvalue
 Does a `getsingle` and returns a single value - you need to also set 
 `$param['return'] => 'fieldname'`.

-getcount
--------
+## getcount
 Search for records and return the quantity. (Note: In many cases in
 early versions queries are limited to 25 so this may not always be
 accurate)

-getrefcount
-----------
+## getrefcount

 Counts the number of references to a record

-getfields
---------
+## getfields

 Fetch entity metadata, i.e. the list of fields supported by the entity

-getlist
-------
+## getlist

 Used for autocomplete lookups by the
 [entityRef](https://wiki.civicrm.org/confluence/display/CRMDOC/EntityRef+Fields) widget

-getoptions
----------
+## getoptions

 Returns the options for a specified field e.g.
 ```php
@@ -76,8 +65,7 @@ array(
 )
 ```

-replace
-------
+## replace

 Replace an old set of records with a new or modified set of records.
 (For example, replace the set of "Phone" numbers with a different set of
@@ -86,12 +74,10 @@ Replace an old set of records with a new or modified set of records.
 Warning - REPLACE includes an implicit delete - use with care & test well 
 before using in productions

-<del>setvalue</del>
-------------------
+## <del>setvalue</del>

 **Deprecated.** Use the create action with the param 'id' instead.

-<del>update</del>
-----------------
+## <del>update</del>

 **Deprecated.** Use the create action with the param 'id' instead.
--- a/docs/api/chaining.md
+++ b/docs/api/chaining.md
-API Chaining
-============
+# API Chaining

 It is now possible to do two API calls at once with the first call feeding into
 the second. E.g. to create a contact with a contribution you can nest the

--- a/docs/api/general.md
+++ b/docs/api/general.md
-The CiviCRM API
-===============
+# The CiviCRM API

 CiviCRM has a stable comprehensive **API** (Application Programming
 Interface) that can be used to access and manage data in CiviCRM. The
@@ -19,8 +18,7 @@ The best place to begin working with the API is your own ***test*** install of
 CiviCRM, using the API explorer and the API parameter list.


-API explorer
------------
+## API explorer

 The API explorer gives you the possibility to actually
 try out the API in action and is available at
@@ -42,8 +40,7 @@ Try out the [API explorer on the demo site], *after you login as demo/demo*.
 [API explorer on the demo site]: http://drupal.sandbox.civicrm.org/civicrm/api/explorer


-API parameter list
------------------
+## API parameter list

 The API parameter list shows all available entities which
 can be manipulated by the API and is available at:
@@ -60,8 +57,7 @@ with the API and what parameters you can use to refine your get
 action or complete your create or update action.


-API Examples
------------
+## API Examples

 CiviCRM ships with API examples included in the distribution. You can
 find the examples specific to your installed version at:
@@ -71,8 +67,7 @@ find the examples specific to your installed version at:
 [Explore these examples on GitHub](https://github.com/civicrm/civicrm-core/tree/master/api/v3/examples)


-Changelog
---------
+## Changelog

 All important changes made to the API are be recorded on the wiki at:
 [API changes](https://wiki.civicrm.org/confluence/display/CRMDOC/API+changes)
--- a/docs/api/params.md
+++ b/docs/api/params.md
-API Parameters
-==============
+# API Parameters

 There are many parameters accepted by the CiviCRM API. Most parameters
 depend on the entity – for current details in your see the [API Explorer]
@@ -12,8 +11,7 @@ interface\#optionsparameters](https://wiki.civicrm.org/confluence/display/CRMDOC
 [API Explorer]: /api/general/#api-explorer
 [API examples]: /api/general/#api-examples

-sequential
----------
+## sequential

 -   **Action**: get
 -   **Type**: bool
@@ -42,8 +40,7 @@ Note that a single record is returned in this example - whenever a single
 record is returned the `entity_id` of that record should be in `$result['id']`


-options.limit
-------------
+## options.limit

 -   **Action**: get
 -   **Type**: int
@@ -66,8 +63,7 @@ civicrm_api('UFMatch','Get', array(
 ```


-options.offset
--------------
+## options.offset

 -   **Action**: get
 -   **Type**: int
@@ -89,8 +85,7 @@ civicrm_api('UFMatch','Get', array(
 ));
 ```

-options.sort
------------
+## options.sort

 -   **Action**: get
 -   **Type**: ??
@@ -110,8 +105,7 @@ civicrm_api3('Contact', 'get', array(
 ));
 ```

-options.reload
--------------
+## options.reload

 -   **Action**: create
 -   **Type**: bool
@@ -137,8 +131,7 @@ civicrm_api('Contact', 'create', array(
 ));
 ```

-options.match
-------------
+## options.match

 -   **Action**: create | replace
 -   **Type**: string | array
@@ -170,8 +163,7 @@ civicrm_api('contact', 'create', array(
 ));
 ```

-options.match-mandatory
-----------------------
+## options.match-mandatory

 -   **Action**: create | replace
 -   **Type**: string | array
@@ -204,8 +196,7 @@ civicrm_api('contact', 'create', array(
 ```


-Custom Data
-----------
+## Custom Data

 Custom data attached to entities is referenced by `custom_N` where `N` is
 the unique numerical ID for the custom data field.

--- a/docs/api/usage.md
+++ b/docs/api/usage.md
-API Usage
-=========
+# API Usage

 Every API call consists of three elements: the *entity*, *action*, and
 *parameters*.  For example, consider a few commonly-used entities along
@@ -58,8 +57,7 @@ array(
 return success in a different format.)


-PHP (civicrm_api3)
------------------
+## PHP (civicrm_api3)

 This is the most common way to call the API.

@@ -90,8 +88,7 @@ before using the API.  See the examples in [Bootstrap Reference].

 [Bootstrap Reference]: https://wiki.civicrm.org/confluence/display/CRMDOC/Bootstrap+Reference

-PHP (class.api.php)
-------------------
+## PHP (class.api.php)

 CiviCRM v3.4 introduced an object-oriented API client, `class.api.php`.
 This class be used locally or remotely to invoke APIs, as in:
@@ -116,8 +113,7 @@ If you call the API in the object oriented fashion, you do not have to
 specify 'version' as a parameter


-REST
----
+## REST

 For external services:

@@ -157,8 +153,7 @@ For more details, see [REST
 interface](http://wiki.civicrm.org/confluence/display/CRMDOC/REST+interface). 


-AJAX
----
+## AJAX

 ```javascript
 CRM.api3('entity', 'action', [params], [statusMessage]);
@@ -181,8 +176,7 @@ and
 [Same Origin Policy](http://en.wikipedia.org/wiki/Same_origin_policy). 
 To use it from an external site or application, see REST interface documentation.

-Smarty
------
+## Smarty

 ```smarty
 {crmAPI var="myContactList" entity="Contact" action="get" version="3" first_name="Alice" last_name="Roberts" }
@@ -195,8 +189,7 @@ actions don't make sense in this case.
 For more details, see
 [Smarty API interface](https://wiki.civicrm.org/confluence/display/CRMDOC/Smarty+API+interface).

-Command line
------------
+## Command line

 ### drush


--- a/docs/basics/community.md
+++ b/docs/basics/community.md
+# CiviCRM Developer Community
+
+Developers from around the globe use the following systems to communicate and
+collaborate:
+
+-   [CiviCRM.org](https://civicrm.org)
+    -   [Extensions](https://civicrm.org/extensions) publishing
+    -   [Blog posts](https://civicrm.org/blog/) by community members
+    -   [Events](https://civicrm.org/events) -
+        meetups, conferences, camps, sprints, webinars
+    -   [Job Board](https://civicrm.org/jobs) - Post and find paid work
+-   [Documentation](https://civicrm.org/documentation) including:
+    -   [User Guide](https://docs.civicrm.org/user/en/stable/)
+    -   [Developer Guide](https://docs.civicrm.org/dev/en/master/)
+        *(that you're reading now!)*
+-   [Mattermost](https://chat.civicrm.org) - Live discussion
+-   [Jira](https://issues.civicrm.org/jira) - Issue tracking
+-   [GitHub](https://github.com/civicrm) - Hosted git repositories
+-   [StackExchange](http://civicrm.stackexchange.com/) - Question & answer
+-   [Discussion Mailing Lists](https://lists.civicrm.org/lists/)
+-   [Newsletters](https://civicrm.org/civicrm/mailing/subscribe)
+-   Falling out of use
+    -   [Wiki] - still used for specs & recipes, *but documentation
+        [is moving][migration] to the guides listed above*
+    -   [IRC](http://irc.civicrm.org/) - #civicrm on irc.freenode.net
+        *but now mostly replaced by Mattermost*
+    -   [Forum](https://forum.civicrm.org/) - *now mostly replaced by
+        StackExchange*
+
+[wiki]: https://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+Documentation
+[migration]: https://wiki.civicrm.org/confluence/display/CRMDOC/Content+migration+from+wiki+to+Developer+Guide
+
+The developer community is full of friendly people, eager to welcome newcomers.
+Mattermost and in-person events are great starting points if you're looking to
+get involved!
+
--- a/docs/build.md
+++ b/docs/build.md
-Building CiviCRM
-================
+# Building CiviCRM

 TODO:


--- a/docs/customize.md
+++ b/docs/customize.md
-Customizing CiviCRM
-===================
+# Customizing CiviCRM

 TODO:


--- a/docs/develop.md
+++ b/docs/develop.md
-Developing CiviCRM
-==================
+# Developing CiviCRM

-Repositories
------------
+## Repositories

 CiviCRM is divided into a few repositories. This allows developers to work
 with different components, allows different teams to manage each component,
@@ -24,15 +22,13 @@ shell scripts, Drush & Drush make, or composer). The repositories are:
 -   [civicrm-l10n](https://github.com/civicrm/civicrm-l10n/) -
    Localization data.

-Obtaining a development build of CiviCRM
----------------------------------------
+## Obtaining a development build of CiviCRM

 The recommended method is to use
 [CiviCRM Buildkit](https://github.com/civicrm/civicrm-buildkit/) to build a
 CiviCRM codebase to develop with.

-Deprecated instructions
-----------------------
+## Deprecated instructions

 Previous methods for obtaining a CiviCRM source build are documented at
 [Deprecated Developer Processes](develop-deprecated.md).
--- a/docs/documentation.md
+++ b/docs/documentation.md
 # Writing Documentation

-[CiviCRM.org/documentation](https://civicrm.org/documentation) has a nice high-level list of all active documentation.
+[CiviCRM.org/documentation](https://civicrm.org/documentation) has a nice
+high-level list of all active documentation.
+
+## Wiki migration
+
+As of early 2017, developer documentation on the [wiki] is under
+active migration to mkdocs. If you are helping to migrate wiki pages, please
+read about the [migration process][migration] to ensure that you understand the
+workflow including the process of redirecting wiki pages to mkdocs.
+
+[migration]: https://wiki.civicrm.org/confluence/display/CRMDOC/Content+migration+from+wiki+to+Developer+Guide
+[wiki]: https://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+Documentation

 ## Guides in mkdocs

-We are using [mkdocs](http://www.mkdocs.org) to produce guides, and currently have the following two:
+We are using [mkdocs](http://www.mkdocs.org) to produce guides, and currently
+have the following two:

-* [User Guide](https://docs.civicrm.org/user/en/stable/)
-* [Developer Guide](https://docs.civicrm.org/dev/en/master/) *(which you are reading now!)*
+-   [User Guide](https://docs.civicrm.org/user/en/stable/)
+-   [Developer Guide](https://docs.civicrm.org/dev/en/master/) *(which you are
+    reading now!)*

-The content for each of these guides is written in markdown, stored in text files, and hosted on GitHub.
+The content for each of these guides is written in [markdown], stored in text
+files, and hosted on GitHub.

 ### How to edit

-For minor changes you can simply edit the markdown online using GitHub. However, for a better editing experience we highly recommend installing `mkdocs`:
+For minor changes you can simply edit the [markdown] online using GitHub.
+However, for a better editing experience we highly recommend installing
+`mkdocs` as follows.

 1.  Obtain the source files for the guide you want to edit
-    1. Find the repository on GitHub (e.g. here is [the repo for this guide](https://github.com/civicrm/civicrm-dev-docs))
-    1. Fork and clone locally. (For more help with Git and GitHub see [Git](git))
+    1.  Find the repository on GitHub (see bottom left of screen)
+    1.  Fork and clone locally.
 1.  Install mkdocs on your machine.
    1.  For Ubuntu

            sudo apt-get install python-pip python-wheel
            sudo pip install mkdocs

-    1.  For other platforms, follow instructions on [mkdocs.org](http://www.mkdocs.org)
+    1.  For other platforms, follow instructions on
+        [mkdocs.org](http://www.mkdocs.org)

 1. Launch a local copy of the guide
    1. Run:
@@ -32,25 +49,17 @@ For minor changes you can simply edit the markdown online using GitHub. However,
            cd civicrm-dev-docs
            mkdocs serve

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

    1. Go to `http://localhost:8000` to view

-1. Edit the [markdown](markdownrules) with an editor of your choice. As you save your changes `mkdocs` will automatically reprocess the page and refresh your browser.
-
-1. When you are happy with your edits use git to commit and push your chnanges then submit a  pull request on GitHub.
+1.  Edit the [markdown] with an editor of your choice. As you
+    save your changes `mkdocs` will automatically reprocess the page and
+    refresh your browser.

+1.  When you are happy with your edits, use git to commit and push your changes.
+    Then submit a  pull request on GitHub.

-### Formatting
-
-See [Markdown](markdownrules) for formatting syntax within mkdocs.
-
-
-## Wiki migration
-
-The [CiviCRM wiki](https://wiki.civicrm.org/confluence/display/CRMDOC/CiviCRM+Documentation) has lots of great info but is slowly falling out of use in favor of mkdocs.

-If you migrate content from the wiki to mkdocs, you may want to setup an HTTP redirect from the wiki
-(`https://wiki.civicrm.org/confluence/display/CRMDOC/{$x}`) to mkdocs (`https://docs.civicrm.org/dev/en/master/{$y}`).
-To do this, add a new row to the [redirects/wiki-crmdoc.txt](redirects/wiki-crmdoc.txt).
+[Markdown]: markdownrules.md
--- a/docs/extend-stages.md
+++ b/docs/extend-stages.md
-Extension Life cycle
-====================
+# Extension Life cycle

 The CiviCRM ecosystem is built on the belief that non-profit
 organizations can serve themselves best by collaborating in development of their
@@ -22,8 +21,7 @@ have a split role, e.g.
 The purpose of this document is to describe the process of publishing
 extensions through the CiviCRM ecosystem.

-Definitions
-----------
+## Definitions

 -   **Project Maturity**: Should we expect this to work for most users? Should
    we expect to work in 6 months?
@@ -75,8 +73,7 @@ Definitions
        test-results, style-checks, or cyclomatic complexity) are checked by a
        bot. (This is a high-tech, low-touch process.)

-Workflow
--------
+## Workflow

 The database on `civicrm.org` publishes information about available extensions,
 including maturity and stewardship. This is significant because it affects
@@ -108,8 +105,7 @@ Based on these rules, we can fill out a full table of the workflow:
 | Deprecated	| Official	| Informal Discussion	| The author announces intent to deprecate in a high-visibility medium. If discussion is persuasive and no alternative maintainer comes forward, a senior member of core team flags the project as official.	| Locate the extension on the website. View a block which says, "Install Instructions", which includes drush/wp-cli commands.


-Formal Review
-------------
+## Formal Review

 To designate an extension as *Stable*, someone must conduct a *Formal Review*
 and assess several criteria. As a rule of thumb, *Contributed* extensions are
@@ -142,8 +138,7 @@ subject to more stringent review (more criteria).
 | Support	| Publish documentation	| Suggested (Not Required)	| Required
 | Support	| Track issues in an open, public issue management system	| Suggested (Not Required)	| Required

-Benefits
--------
+## Benefits

 Based on a project's maturity and stewardship, it may be eligible to use
 resources from `civicrm.org`.

--- a/docs/extend.md
+++ b/docs/extend.md
-Creating CiviCRM Extensions
-===========================
+# Creating CiviCRM Extensions

 **CiviCRM Extensions** are packaged pieces of functionality that extend
 CiviCRM's out-of-the-box functionality, independent of CMS plaform.

--- a/docs/hook.md
+++ b/docs/hook.md
-How to use hooks
-================
+# How to use hooks

 TODO:

@@ -28,8 +27,7 @@ you're trying to do can be expressed with a sentence like this: "I want X to
 happen every time someone does Y."


-Using hooks with Drupal
-----------------------
+## Using hooks with Drupal

 In order to start using hooks with a Drupal-based CiviCRM installation, you or
 your administrator needs to do the following:
@@ -76,8 +74,7 @@ $user = user_save('',array(..));
 $config->inCiviCRM = FALSE;
 ```

-Using hooks with Joomla!
------------------------
+## Using hooks with Joomla!

 Hooks may be implemented in Joomla in two ways, depending on the version of
 CiviCRM and Joomla you are using. For sites running Joomla 1.5 with CiviCRM up
@@ -157,8 +154,7 @@ article](http://civicrm.org/blogs/mcsmom/hooks-and-joomla)
 Note the reference in the comments to a sample plugin which you can download
 and modify.

-Refine what you want to act upon
--------------------------------
+## Refine what you want to act upon

 When you create a hook, it will be called for all the types of entities. For
 instance, a civicrm\_post is called after the creation or modification of any
@@ -181,8 +177,7 @@ code for each hook within your test:
 if ($objectName == "Individual" && $op == "edit") {   // Your hook }
 ```

-Pitfalls of hooks
-----------------
+## Pitfalls of hooks

 Because you have little control over what CiviCRM passes to your hook function,
 it is very helpful to look inside those objects (especially `$objectRef`) to
@@ -190,8 +185,7 @@ make sure you're getting what you expect. A good debugger is indispensable here.
 See the Developer Tips & Tricks chapter at the end of this section for more
 information on setting up a debugger for your development environment.

-Examples of using hooks
-----------------------
+## Examples of using hooks

 Some example hooks follow.


--- a/docs/hookref-old.md
+++ b/docs/hookref-old.md
-Goals and background
--------------------
+## Goals and background

 -   This documents how to extend CiviCRM to meet your needs. CiviCRM
    uses hooks in a very similar manner to Drupal, primarily because
@@ -12,8 +11,7 @@ Goals and background
 -   See [CRM/Utils/Hook.php](http://svn.civicrm.org/civicrm/trunk/CRM/Utils/Hook.php)
    in CiviCRM for the source code that invokes these hooks.

-Implementing hooks
------------------
+## Implementing hooks

 -   In Drupal or CiviCRM, hooks can be implemented within a module or
    extension. In general, implement a hook by declaring a global
@@ -50,21 +48,18 @@ function my_plugin_pre_callback( $op, $objectName, $objectId, &$objectRef ) {
 As long as the plugin is active (or - if the code is in 'functions.php' - as long as your theme is active), this function will be called every time CiviCRM is about to save data to the database.


-For A CiviCRM (native) Extension
--------------------------------
+## For A CiviCRM (native) Extension

 -   See this page for [creating an extension and implementing hooks
    within it](https://wiki.civicrm.org/confluence/display/CRMDOC/Create+a+Module+Extension).

-For A Drupal Module
-------------------
+## For A Drupal Module

 -   See this page for [creating a module in Drupal](http://drupal.org/node/1074360) esp. the section on implementing hooks.
 -   For a working example, see the hook\_civicrm\_postProcess documentation below.
 -   You can also find examples in your CiviCRM install in [drupal/civitest.module.sample](http://svn.civicrm.org/civicrm/trunk/drupal/civitest.module.sample)

-For a Joomla Plugin
-------------------
+## For a Joomla Plugin

 -   See this page for [creating a Joomla plugin](http://docs.joomla.org/Plugin). Joomla plugins implement the
    observer design pattern.
@@ -72,8 +67,7 @@ For a Joomla Plugin
 -   Once created plugins may be packaged and installed with the Joomla installer or the files can be placed in the appropriate folder and installed with the discover method.
 -   See this [sample Joomla plugin for CiviCRM hooks](https://wiki.civicrm.org/confluence/display/CRMDOC/Example+Joomla+Plugin+for+implementing+hooks)

-For a WordPress Plugin
----------------------
+## For a WordPress Plugin

 -   For a detailed overview of the updated relationship between WordPress and CiviCRM, see the blog post [Working with CiviCRM 4.6 in WordPress](https://civicrm.org/blogs/haystack/working-civicrm-46-wordpress) on the CiviCRM website.
 -   In summary, as of CiviCRM 4.6 there is (almost) full compatibility with the WordPress actions and filters system.
@@ -99,8 +93,7 @@ add_filter( 'civicrm_pre', array( $this, 'my_callback_method', 10, 4 )

 For more details (as well as the exceptions to this rule) see the [blog post](https://civicrm.org/blogs/haystack/working-civicrm-46-wordpress) mentioned above.

-Inspecting hooks
----------------
+## Inspecting hooks

 The documentation about hooks can be somewhat abstract, and it sometimes
 helps to see interactively how the hooks run.
@@ -113,8 +106,7 @@ helps to see interactively how the hooks run.
    -   [Query Monitor](https://wordpress.org/plugins/query-monitor/)


-Example Drupal module for implementing hooks
---
+## Example Drupal module for implementing hooks
 I found it useful, when implementing hooks, to write wrapper code for most of them.  The [attached zip](http://wiki.civicrm.org/confluence/download/attachments/86213379/callhooks.zip?version=1&modificationDate=1372586243000&api=v2) file is an example Drupal module that illustrates this technique.  From the README file:

 This is just example code to implement custom hooks for CiviCRM.
@@ -132,8 +124,7 @@ To use:



-Example Joomla Plugin for implementing hooks
---
+## Example Joomla Plugin for implementing hooks

 This is a simple example of a plugin for Joomla that implements CiviCRM hooks. It consists of two file tabs.php and tabs.xml along with the blank index.html file which is considered good Joomla coding practice.

@@ -210,8 +201,7 @@ Tabs.xml

 You can make plugins that include multiple hooks or you can make separate plugins. What is appropriate will depend on the application.

-Setting and getting custom field values from within hooks
---
+## Setting and getting custom field values from within hooks

 To get a custom field ID given the custom field name and custom group name, you can use the following code:


--- a/docs/hooks-db.md
+++ b/docs/hooks-db.md
-All Available Hooks
-===================
+# All Available Hooks

 This page provides official documentation on the specifics of each hook
 available within CiviCRM.
@@ -7,8 +6,7 @@ available within CiviCRM.
 **This page is currently incomplete**. Info needs to be moved from this
 [wiki page](https://wiki.civicrm.org/confluence/display/CRMDOC/Hook+Reference)

-hook_civicrm_copy
-=================
+# hook_civicrm_copy

 This hook is called after a CiviCRM object (Event, ContributionPage, Profile) has been copied

@@ -25,8 +23,7 @@ hook_civicrm_copy( $objectName, &$object )
 ```


-hook_civicrm_custom
-===================
+# hook_civicrm_custom
 This hook is called AFTER the db write on a custom table

 * Parameters
@@ -81,8 +78,7 @@ function MODULENAME_civicrm_custom( $op, $groupID, $entityID, &$params ) {

 ```

-hook_civicrm_managed
-====================
+# hook_civicrm_managed

 This hook allows a module to declare a list of 'managed' entities using the CiviCRM API - a managed entity will be automatically inserted, updated, deactivated, and deleted in tandem with enabling, disabling, and uninstalling the module. The hook is called periodically during cache-clear operations.

@@ -130,8 +126,7 @@ function modulename_civicrm_managed(&$entities) {
 }
 ```

-hook_civicrm_merge
-==================
+# hook_civicrm_merge

 This hook allows modification of the data used to perform merging of duplicates. This can be useful if your custom module has added its own tables related to CiviCRM contacts.
 Availability
@@ -251,8 +246,7 @@ function civitest_civicrm_merge ( $type, &$data, $mainId = NULL, $otherId = NULL

 ```

-hook_civicrm_post
-=================
+# hook_civicrm_post

 This hook is called after a db write on some core objects.

@@ -369,8 +363,7 @@ function exampleSendEmailOnIndividual_civicrm_post($op, $objectName, $objectId,
 Once the files are in the directory, you need to login to Drupal admin, go to Modules and enable our new module and click Save. Now go and edit a contact and you should get an email!


-hook_civicrm_postSave_table_name
-================================
+# hook_civicrm_postSave_table_name

 This hook is called after writing to a database table that has an associated DAO. This includes core tables but not custom tables or log tables.

@@ -390,8 +383,7 @@ hook_civicrm_postSave_civicrm_contact($dao) {
 }
 ```

-hook_civicrm_pre
-================
+# hook_civicrm_pre

 This hook is called before a db write on some core objects. This hook does not allow the abort of the operation, use a form hook instead.

@@ -441,8 +433,7 @@ hook_civicrm_pre($op, $objectName, $id, &$params)
 ```


-hook_civicrm_referenceCounts
-============================
+# hook_civicrm_referenceCounts

 This hook is called to determine the reference-count for a record. For example, when counting references to the activity type "Phone Call", one would want a tally that includes:

@@ -492,8 +483,7 @@ function familytracker_civicrm_referenceCounts($dao, &$refCounts) {
 ```


-hook_civicrm_trigger_info
-=========================
+# hook_civicrm_trigger_info

 efine MYSQL Triggers. Using the hooks causes them not to clash with core or other extension triggers. They are compiled into one trigger with core triggers.


--- a/docs/index.md
+++ b/docs/index.md
-CiviCRM Developer Guide
-=======================
+# CiviCRM Developer Guide

 [CiviCRM](https://civicrm.org) is an open-source application. The code can be
 poked, prodded, twisted, and hacked. It can be customized, extended, and
@@ -16,8 +15,7 @@ The guide also includes detailed references for tools and subsystems
 of CiviCRM. These cover topics like the API and hook system and are intended
 for use by people that are familiar with CiviCRM development.

-Editing & reading offline
-------------------------
+## Editing & reading offline

 -   This documentation is made with mkdocs and
    [stored in GitHub](https://github.com/civicrm/civicrm-dev-docs)
@@ -25,8 +23,7 @@ Editing & reading offline
    for specific details on editing this documentation (and others using
    mkdocs). You can also learn how to read these docs off-line!

-Migration of content is in progress
-----------------------------------
+## Migration of content is in progress

 As of early 2017 we are actively working to migrate content from the [wiki] to
 this guide. Read more about this [migration process][migration], including how
@@ -35,8 +32,7 @@ to help out!
 [wiki]: http://wiki.civicrm.org/confluence/display/CRMDOC/Develop
 [migration]: https://wiki.civicrm.org/confluence/display/CRMDOC/Content+migration+from+wiki+to+Developer+Guide

-Other sources of information
------------------------------
+## Other sources of information

 As an open-source project, CiviCRM is managed by an international community of
 developers and activists. Help from these people can be found in the following

--- a/docs/markdownrules.md
+++ b/docs/markdownrules.md
-Markdown Syntax
-==============
+# Markdown Syntax

 Learning [Markdown](https://en.wikipedia.org/wiki/Markdown)
 language is useful for:
@@ -16,14 +15,8 @@ language is useful for:
 Markdown language is mostly consistent across these platforms, but some
 discrepancies do exist and should be noted below.

-Markdown has some redundant syntax (e.g. `*italic*` and `_italic_`).
-Within CiviCRM documentation we want consistent code, so we list
-***unapproved variants*** below to make it clear which syntax is preferred by
-CiviCRM, especially in large guides like this one. 

-
-Basics
------
+## Basics

 -   `*italics*`
 -   `**bold**`
@@ -31,18 +24,17 @@ Basics
 -   `~~strikethrough~~` *(GitHub/Mattermost/StackExchange)*
 -   `<del>strikethrough</del>` *(mkdocs)*

-***Unapproved variants:*** Underscores for `_italics_` and `__bold__` work. But
-please but use asterisks for consistency.
+Alternate syntax: Underscores for `_italics_` and `__bold__` also work on most
+platforms.


-Hyperlinks
----------
+## Hyperlinks

 -   A basic hyperlink

        Try [CiviCRM](https://civicrm.org) for your database.

-   With long URLs, the following syntax is better. 
+-   With long URLs, the following syntax is better.

        See [this issue][CRM-19799] for more details.

@@ -50,12 +42,11 @@ Hyperlinks

    -   The second line can be placed anywhere in the file.
    -   Optionally, if the link ID ("CRM-19799" in this case) is omitted, you
-        can use the link text ("this issue") to reference the link in the 
+        can use the link text ("this issue") to reference the link in the
        second line.


-Line breaks and whitespace
--------------------------
+## Line breaks and whitespace

 **Single line breaks** in markdown code are eliminated in display:

@@ -67,11 +58,9 @@ line.
 ```

 This makes it easy to avoid very long lines in markdown code. As a rule of
-thumb, **keep your markdown code free of lines longer than 80 characters**
+thumb, keep your markdown code free of lines longer than 80 characters
 where possible.

-Also, please **remove trailing whitespace** from the end of markdown code.
-
 **Double line breaks** create separate paragraphs:

 ```md
@@ -82,28 +71,26 @@ This is a second.
 ```


+## Headings

-Headings
--------
+```md
+# Heading 1

+## Heading 2

-```md
-Heading 1
-=========
+### Heading 3

-Heading 2
---------
+#### Heading 4
 ```

-***Unapproved variants:*** `# Heading 1` and `# Heading 2` also work. But please
-use `=` and `-` for consistency.
-
-For headings beyond 1 and 2, the `#` syntax is okay...
+Alternate syntax (only works for h1 and h2):

 ```md
-### Heading 3
+Heading 1
+=========

-#### Heading 4
+Heading 2
+---------
 ```

 ***Convention:*** Each page should have one and only one *Heading 1*,
@@ -111,9 +98,7 @@ which should be at the top of the page as a page title. Other headings within
 page content should be level 2 or greater.


-
-Lists
-----
+## Lists

 ### Unordered lists

@@ -124,32 +109,27 @@ Lists
 -   Then, a third.
 ```

-***Unapproved variants:***
+Alternate syntax:

 -   Unordered lists also recognize `*` and `+` as item delimiters.
-    But please use `-` for consistency.
 -   Markdown is somewhat flexible with the quantity and position of spaces when
-    making lists, but for consistency, please stick to the example above which
-    has: **1 dash, 3 spaces, then content**, and has **long lines beginning
-    with 4 spaces** so they line up nicely.
+    making lists, but using 3 spaces after the dash means that sub-lists look
+    nicer in code.


 ### Ordered lists

 ```md
 1.  Item
-2.  Item
-3.  Item
+1.  Item
+1.  Item
 ```

-***Unapproved variants:*** 
+Alternate syntax:

 -   Ordered lists items are automatically re-numbered sequentially upon display
-    which means all items can begin with `1`, but for the sake of consistency
-    with existing docs, please number your lists sequentially in code.
-   Similar to the comment above for unordered lists, please keep all list
-    content beginning 4 characters in, which means a digit character, a period,
-    then two spaces, then content.
+    which means all items can begin with `1`, or they can be ordered
+    sequentially in code.


 ### Nested lists
@@ -168,8 +148,7 @@ List items must be indented 4 spaces:
 ```


-Code
----
+## Code

 ### Inline code

@@ -201,7 +180,7 @@ BLOCK
 *Fenced code can use more backticks when necessary to represent code with
 3 backticks (which is what you'd see in the source for this page).*

-***Unapproved variants:*** For fenced code, the tilde `~` character also works
+Alternate syntax: For fenced code, the tilde `~` character also works
 in place of the backtick character but should be avoided for consistency.


@@ -245,15 +224,15 @@ A block of **"indented code"** with four spaces at the start of each line:
    `swift`, `tex`, `thor`, `v`, `vb`, `vbnet`, `vbs`, `vbscript`, `veo`,
    `xhtml`, `xml`, `xsl`, `yaml`, `zsh`
 -   Syntax highlighting cannot be forced for indented code.
-   Syntax highlighting is not available for inline code. 
+-   Syntax highlighting is not available for inline code.
 -   [Stack Exchange syntax highlighting][stack exchange syntax highlighting] is
    done differently.

 [stack exchange syntax highlighting]: http://stackoverflow.com/editing-help#syntax-highlighting

-### Code blocks within lists 
+### Code blocks within lists

-You can use **indented code within lists** by keeping a blank line 
+You can use **indented code within lists** by keeping a blank line
 above/below and indenting *4 spaces more than your list content*, like this:

 ```md
@@ -293,8 +272,7 @@ mkdocs**:



-Images
------
+## Images

 Images function mostly the same as hyperlinks, but preceded by an exclamation
 point and with alt text in place of the link text.
@@ -303,7 +281,7 @@ point and with alt text in place of the link text.
 ![Alt text](image.png)
 ```

-or 
+or

 ```md
 ![Alt text][id]
@@ -312,8 +290,7 @@ or
 ```


-Other markdown syntax
---------------------
+## Other markdown syntax

 -   [Tables] (to be avoided when possible)
 -   [Emojis] (great for Mattermost)
@@ -326,13 +303,12 @@ Other markdown syntax
 [Emojis]: http://www.webpagefx.com/tools/emoji-cheat-sheet/
 [Tables]: https://help.github.com/articles/organizing-information-with-tables

-External references
-------------------
+## External references

 -   [Mattermost markdown](https://docs.mattermost.com/help/messaging/formatting-text.html)
 -   [Stack Exchange markdown](http://stackoverflow.com/editing-help)
 -   [GitHub markdown](https://help.github.com/categories/writing-on-github/)
-   [Official markdown reference](https://daringfireball.net/projects/markdown/syntax) 
+-   [Official markdown reference](https://daringfireball.net/projects/markdown/syntax)
    (though somewhat difficult to read)


--- a/docs/requirements.md
+++ b/docs/requirements.md
-Development requirements
-========================
+# Development requirements

-Languages and Services
----------------------
+## Languages and Services

 -   Unix-like environment (Linux, OS X, or a virtual machine)
 -   [PHP v5.3+](http://php.net/)
@@ -12,8 +10,7 @@ Languages and Services
 -   Recommended: Apache HTTPD v2.2+
 -   Recommended: Ruby/Rake

-Command Line
------------
+## Command Line

 There are many ways to install MySQL, PHP, and other dependencies -- for
 example, `apt-get` and `yum` can download packages automatically; `php.net`
@@ -33,8 +30,7 @@ for MAMP).
 In subsequent steps, the download script will attempt to identify
 misconfigurations and display an appropriate message.

-Buildkit
--------
+## Buildkit

 The developer docs reference a large number of developer tools, such as
 `drush` (the Drupal command line), `civix` (the CiviCRM code-generator), and

--- a/docs/testing.md
+++ b/docs/testing.md
-Testing
-=======
+# Testing

 Testing in CiviCRM is done by a combination of human code review and testing
 as well as automated testing. Testing is done based on pull requests (PRs)
@@ -7,15 +6,13 @@ in [GitHub](https://github.com/civicrm/civicrm-core/pulls). Pull requests are
 code submitted in response to issues reported in
 [JIRA](https://issues.civicrm.org/), the issue tracking system for CiviCRM.

-Automated tests
---------------
+## Automated tests

 TO DO:

 -   http://wiki.civicrm.org/confluence/display/CRMDOC/Testing

-Manual testing
---------------
+## Manual testing

 When testing the process you should use is:

@@ -105,8 +102,7 @@ and issue is posted on [github.com/civicrm](http://github.com/civicrm).
 The GitHub post mentions the account names of everyone who has submitted a
 PR recently (so that they get a notification).

-Notifications
-------------
+## Notifications

 -   When opening a PR, submitter is pointed to the CiviCRM Core
    [contributing documentation](https://github.com/civicrm/civicrm-core/blob/master/.github/CONTRIBUTING.md)

--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -6,6 +6,7 @@ theme: readthedocs
 pages:
 - Home: index.md
 - Basics:
+  - Developer Community: basics/community.md
  - Requirements: requirements.md
  - Build: build.md
  - Customize: customize.md