Writing Documentation

HAPI FHIR Documentation Guide

This page describes various markdown features that can be used within HAPI FHIR and Smile CDR documentation.

Markdown Support

Most markdown syntax is supported by the renderer, including GitHub-Flavored-Markdown features.

Multiline Snippets

We use Prism.JS to render multiline snippets. The syntax begins with ```[language] and ends with ```. See the list of languages here. Example:

```json
{
   "key": "value"
}
```

Embedding URLs

A URL snippet can be performed using any of the following styles:

Single Line URL

```url
http://try.smilecdr.com:8000/Patient?name=Darma
```

Multiple URLs

This style includes several URLs in a single box, which can be more readable than using several separate snippets.

```url
http://try.smilecdr.com:8000/Patient?name=Darma
http://try.smilecdr.com:8000/Patient?name=Pixel
http://try.smilecdr.com:8000/Patient?name=Kona
```

Single URLs broken up over multiple lines for readability

```url
http://try.smilecdr.com:8000/Patient
   ?name=Darma
   &birthDate=2017
```

You can also include an HTTP verb in URL snippets (the renderer will format the verb as a nice little box next to the URL, and won't include it in the <a> tag:

```url
PUT http://example.com/Patient/123
```

Embedding Snippets

To embed a code snippet that is sourced from a source file elsewhere in the codebase, first create a snippet comment in your source file somewhere, e.g.:

// START SNIPPET: livebundle_example_earliestThreeByPathKeeper
function earliestThreeByPathKeeper() {
	// This is the path we use to determine to find the date to pick the most recent one
	let pathToOrderDate = 'period.start';

	return LiveBundleKeeperFactory.newEarliestByPath(pathToOrderDate, 3);
}
// END SNIPPET: livebundle_example_earliestThreeByPathKeeper

Then in the docs, use the following syntax to include that snippet (using the path to the file relative to the root of the project):

```javascript
{{snippet:file:cdr-persistence/src/test/resources/example_livebundle_rules.js|livebundle_example_toggleBySearchKeeper}}
```

Manually Setting Section IDs

By default, section IDs are generated using lowercased H1 text with whitespace replaced by -. For example:

# This is a section

This will result in the HTML:

<a name="this-is-a-section"/>
<h1>This is a section</h1>

You can manually set the anchor name by adding a manual anchor name tag in your markdown, as follows:

<a name="my-section"/>

# This is a section

This will result in the HTML:

<a name="my-section"/>
<h1>This is a section</h1>

Referencing Enums

Use the following custom tag in order to get compile-time checking of enum values.

<cdr:enum cdr:class="com.company.EnumClassName" cdr:name="ENUM_VALUE"/>

Automatic Expiry / Failure

Sometimes it is useful to write a comment about how something is new and subject to change, but you don't want that comment to stick around forever. In this case you can create a little "time bomb" that will fail the docs generation after a few releases.

To do this add a tag like the following. Note that we drop the point release from the version, and that the build will fail as soon as the version is incremented to a minor version after the given string.

HAPI FHIR:

<cdr:fail cdr:afterVersion="4.2"/> 

Smile CDR:

<cdr:fail cdr:afterVersion="2020.08"/> 

Referencing Menus

When referencing navigating through menus, use the following syntax. The -> part will be transformed into a stylized chevron during rendering.

File -> Options -> Add File...

Example Tables

Example tables show a document or payload, with annotated sections highlighted.

See the JSON Encoding example here to see what this looks like: https://smilecdr.com/docs/fhir_standard/fhir_introduction.html#the-json-format

Example tables start with a line containing only {{START-EXAMPLE-TABLE}} followed by a line containing only ```.

They end with a line containing only ``` followed by a line containing only {{END-EXAMPLE-TABLE}}.

Within the document, annotated sections are demarcated by a line containing {{START-LABEL: some annotation text}} and ended by a line containing {{END-LABEL}}. If an annotated section is immediately followed by another annotated section, you can skip the END-LABEL line.

The following source shows an example:

{{START-EXAMPLE-TABLE}}
```
{
  "resourceType": "Observation",
  "id": "O1",
  "contained": [
{{START-LABEL: Contained Patient resource within Observation resource}}
    {
      "resourceType": "Patient",
      "id": "pat",
      "name": [ {
        "family": "Smith",
        "given": [ "John" ]
      } ], 
      "birthDate": "1980-07-22"
    } 
{{END-LABEL}}
  ],
  "subject": {
{{START-LABEL: Fragment reference to contained resource}}
    "reference": "#pat"
{{END-LABEL}}
  },
  "status": "final",
  "code": {
    "coding": [ {
      "system": "http://loinc.org",
      "code": "29463-7",
      "display": "Body Weight"
    } ]
  },
  "valueQuantity": {
    "value": 67.1,
    "unit": "kg",
    "system": "http://unitsofmeasure.org",
    "code": "kg"
  }
}
```
{{END-EXAMPLE-TABLE}}

Icons

The HAPI FHIR documentation website is built with stylesheets for fontawesome included. If you need to use an icon or emoji in the documentation (such as a checkbox) look up the corresponding class from the fontawesome website and include it inline in the markdown like so:

Some text here <i class="fas fa-angle-double-right"></i> and then more text.