/

Code blocks

APIdocs can highlight code blocks in your documentation using Highlight.js.

To mark a block-level code fragment for highlighting, use the pre tag with the data-language attribute defining the language of the contents. See the Highlight.js list of supported languages for the attribute values to use.

Simple code blocks

The following pre code block is marked as one containing JavaScript: 

<pre data-language="js">api.schedule(function(done) {
  performCalculations();
  done();
}, "when-idle");</pre>

The block will be rendered as:

api.schedule(function(done) {
  performCalculations();
  done();
}, "when-idle");

Figure code blocks

To make a code block stand out more, you can enclose it in a figure and provide a figcaption. The search engine will index the caption and tag it as a code example in search results.

The following figure:

<figure id="scheduling">
  <pre data-language="js">api.schedule(function(done) {
  performCalculations();
  done();
}, "when-idle");</pre>
  <figcaption>
    Scheduling long-running calculations to run in background.
  </figcaption>
</figure>

will be rendered as:

api.schedule(function(done) {
  performCalculations();
  done();
}, "when-idle");
Scheduling long-running calculations to run in background.

Additionally, if you add an id attribute to your figure, the figure will be available as a special entity in search results. You can test this by typing sched in the search box above.

Embedding external files

Use the embed tag with the src attribute to embed text from an external file: 

<embed src="./examples/code.java">

API docs resolves the path to the embedded file relatively to the HTML file the embed tag appears in.

When embedding fragments of real code, it may be useful to hide certain lines. See the code annotations section for special comments you can use to achieve that.

Selecting code fragments

In some cases you may want to embed only a fragment of an external file. To do so, add special fragment start and end markers to the external file along with a fragment identifier that you will later provide to the embed tag.

Fragment markers have the following syntax:

  • fragment-start{frag_id}: start of the fragment with identifier frag_id,

  • fragment-end{frag_id}: end of the fragment with identifier frag_id.

You can place the markers in the comment sections specific to the language you're embedding. 

// fragment-start{replace}
const VARIABLE_WITH_DELIMITER_REGEX = /%(\w+)%/g;
exports.replaceVariables = (html, replacer) => {
  return html.replace(VARIABLE_WITH_DELIMITER_REGEX,
    (match, name, offset) => replacer(name, offset));
};
// fragment-end{replace}

// fragment-start{validate}
const VARIABLE_REGEX = /^\w+$/;
exports.validateVariables = variables => {
  // Validate variable names
  const offending = Object.keys(variables).filter(v => !VARIABLE_REGEX.test(v));

  if (offending.length > 0) {
    throw "Variable names must match [A-Za-z0-9_], offending names: "
      + offending.join(", ") + ".";
  }
};
// fragment-end{validate}

exports.createMapReplacer = map => {
  return name => map[name];
};
Definition of two code fragments identified as replace and validate.

When embedding the external file using the pre tag, specify the identifier of the fragment to embed using the data-fragment attribute: 

<embed src="variables.js" data-fragment="validate">

Please note the following issues when embedding fragments:

  • One fragment can consist of multiple non-overlapping sections of code. Just use the same fragment identifier in multiple start and end markers.

  • Lines containing fragment markers nested inside a fragment are removed. This ensures that markers of nested fragments are not transferred to your documentation.

  • You can use highlighting annotations inside the fragments you embed.

Embedding JSON fragments via JSON paths

Embedding JSON files is a bit more problematic because the syntax used to provide fragments (C-style comments) violates JSON specification. To embed a subset of a JSON file, use jsonpath to point at the nodes that should be included: 

<embed src="input-file.json" data-jsonpath="$.foo.bar">

When a subset of keys of an object pointed to by json path is needed, use the non-standard syntax extension to enumerate those keys after the path: trailing curly braces with a comma-delimited strings or regular expressions which enumerate allowed keys. For example this block would include the object at $.foo.bar but limit it to only the baz, bar or anything that is prefixed with prop keys. 

<embed src="input-file.json" data-jsonpath="$.foo.bar{'baz', 'bar', /^prop.+/}">

Please note the following:

  • An array of nodes returned for the provided json path is converted into a sequence of pre blocks - each json path node corresponding to one pre block.

  • The JSON file is reformatted using the default JSON.stringify(..., null, " ") function. There is no way to insert the file in its original formatting.

Variables in file paths

You can use variables inside the file paths you specify in the src attribute of the embed tag. This may help to externalize paths of the folders containing files to embed.

Assuming that the CODE_EXAMPLES variable is defined to contain the path to the directory with files to embed, you can reference it like this: 

<embed src="%​CODE_EXAMPLES%/api.js">
Sanitize your variables.

APIdocs does not verify the file paths you provide in the src attribute. Make sure they don't and can't reference any sensitive data in your system.

Code annotations

You can use special comments in both in-line and embedded code to highlight and hide individual lines or ranges of lines.

The following special comments are supported:

  • highlight-line: highlights the current line;

  • highlight-next-line: highlights the next line, removes the line containing the comment;

  • highlight-range{4-7}: highlights lines 4–7, line 1 is the next line; removes the line containing the comment;

  • hide-line: hides the current line,

  • hide-next-line: hides the next line,

  • hide-range{2-4}: hides lines 2–4, line 1 is the next line.

Use comment syntax specific to the language to place annotation comments. The following code comments: 

<pre data-language="css">/** highlight​-range{5-7} */
p {
  margin-top: 1rem; /** highlight​-line */
}

strong {
  font-weight: bold;
}

article {
  /** highlight​-next-line */
  max-width: 40rem;
}

/** hide​-next-line */
.hack { overflow: hidden; }
/** hide​-range{1-4} */
.bug {
  display: none;
}

.warning { color: red }</pre>

produce the following code block:

p {
  margin-top: 1rem;
}

strong {
  font-weight: bold;
}

article {
  max-width: 40rem;
}

.warning { color: red }

Common indent removal

APIdocs will by default remove the indentation that is common to all lines of the included or embedded code block. This makes it easier to preserve proper formatting of the documentation source code and the external source code you embed.

If for some reason you'd like to preserve the common indentation, set the the data-preserve-common-indent attribute to true: 

<embed src="example.js" data-preserve-common-indent="true">

New line removal

APIdocs by default removes leading and trailing new lines of the code block you embed. This strips unnecessary margins from the embed blocks.

To preserve leading and trailing new lines, set the the data-preserve-leading-and-trailing-newlines attribute to true: 

<embed src="example.js" data-preserve-leading-and-trailing-newlines="true">