Writing Documentation
This page describes various markdown features that can be used within HAPI FHIR and Smile CDR documentation.
Most markdown syntax is supported by the renderer, including GitHub-Flavored-Markdown features.
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"
}
```
A URL snippet can be performed using any of the following styles:
```url http://try.smilecdr.com:8000/Patient?name=Darma ```
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 ```
```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 ```
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_earliestThreeByPathKeeperThen 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}}
```
By default, section IDs are generated using lowercased H1 text with whitespace replaced by -. For example:
# This is a sectionThis 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 sectionThis will result in the HTML:
<a name="my-section"/>
<h1>This is a section</h1>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"/>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"/> 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 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}}
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.