Under maintenance

Heretto Help

Example Element (example)

The example element provides an example or supporting information that illustrates the concept explained in the topic.

The example element serves these primary purposes:

  • Illustrates concepts explained in the topic with practical examples

  • Provides supporting information to enhance comprehension

  • Demonstrates real-world applications of topic concepts

  • Reinforces learning through concrete illustrations and sample code

Key characteristics of the example element:

  • Can contain paragraphs, lists, tables, figures, and other general content elements

  • Should contain both the example, like sample code, and the text that describes the code

  • Can have an optional title element (use only one title per example)

  • Cannot be nested (example within an example)

  • Placement varies by topic type context

The example element usage varies by topic type context:

[General] Task Topics
  • Can only be added at the end of a topic within the taskbody

  • Can be used after structured task elements like steps or result

Concept Topics
  • Can be added anywhere inside the conbody element

  • Once an example is added to the body element, only additional examples or sections are allowed

Reference Topics
  • Can be added anywhere inside the refbody element

  • Once an example is added to the body element, only additional examples or sections are allowed

Use example to:

  • Provide practical illustrations of theoretical concepts

  • Show sample code with explanatory text

  • Give users concrete examples of implementation

  • Enhance understanding through real-world scenarios

Note:

In task topics, use example to provide supporting information for the entire task. To illustrate an example that applies to a specific step, use the step example element (stepxmp).

Guidelines for using example title element:

  • Use only one title per section (the DITA standard permits multiple title elements in the example element)

  • Place title before other content

  • Add new example elements rather than multiple titles within one example

  • In output, title is typically placed first regardless of XML placement

Figure 1. A sample example element with the surrounding context of a reference
Layer 1

The DITA source of the example element with the surrounding content of a reference topic:

<reference id="reference-7046">
    <title>GET Coffee Recipes Using the BrewMaster API</title>
    <shortdesc>Retrieve coffee recipes using GET requests with authentication, filtering, and response handling.</shortdesc>
    <prolog>
        <author translate="no" type="creator">Heretto User &lt;user@heretto.com&gt;</author>
        <metadata>
            <keywords><keyword>GET method</keyword><keyword>coffee recipes</keyword><keyword>API endpoints</keyword><keyword>REST API</keyword></keywords>
        </metadata>
    </prolog>
    <refbody>
        <section>
            <p>The BrewMaster API uses HTTP GET requests to retrieve coffee recipes without modifying server data. Use it to fetch all recipes, specific recipes by ID, or filter by brewing method and difficulty level.</p>
            <p>All requests require a Bearer token in the Authorization header and Accept/Content-Type headers set to application/json. The API supports query parameters for filtering and pagination.</p>
        </section>
        <example>
            <title>GET Request with Filtering and Sample Response</title>
            <p>This example shows a GET request with query parameters to filter recipes, followed by the expected JSON response:</p>
            <codeblock outputclass="language-http">GET /api/v1/coffee-recipes?method=pour-over&amp;difficulty=beginner&amp;limit=10 HTTP/1.1
Host: api.brewmaster.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...</codeblock>
            <p>Response:</p>
            <codeblock outputclass="language-json">{
  "status": "success",
  "data": {
    "recipes": [
      {
        "id": "recipe_001",
        "name": "Classic Pour Over",
        "method": "pour-over",
        "difficulty": "beginner",
        "prep_time_minutes": 5,
        "brew_time_minutes": 4,
        "servings": 1,
        "ingredients": {
          "coffee_grams": 22,
          "water_ml": 350,
          "grind_size": "medium-fine"
        }
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 15,
      "total_recipes": 147
    }
  }
}</codeblock>
            <p>This request retrieves up to ten pour-over coffee recipes suitable for beginners, with the response including detailed recipe information and pagination data for navigating through multiple pages of results.</p>
        </example>
    </refbody>
</reference>