Product Selector

Fusion 5.9
    Fusion 5.9

    Code samples and terminal formatting

    Use code format for most things involving code. Use backticks (`) in Asciidoc to mark up inline code formatting.

    Examples include parameters, values, and command line syntax.

    The contents of this article provide a summary of the topic. This article is not exhaustive. Consult the Google Developer Documentation Style Guide resources at the end of this article for more information.

    When to avoid code format

    Do not use code format for the following items unless they are otherwise part of an existing command or code sample:

    • Field values

    • Names of HTTP requests such as GET, POST, DELETE, and PUT

    • File formats such as ZIP, PNG, or CSV

    • Allowed or disallowed characters in a request or response

    The following examples illustrate when to use code format.

    Recommended

    ✅ Success codes are returned in the 2xx range, client error codes are returned in the 4xx range, and so on.

    Not recommended

    ✘ The ID for this job. Used in the API to reference this job. Allowed characters: a-z, A-Z, dash (-) and underscore (_). Type: string

    Short code samples

    Occasionally it’s necessary to include code samples in the documentation. Code samples may show API response and request bodies, terminal input and output, and JSON requests and responses, among other things.

    Format code samples in Asciidoc with the following sample:

    [source,language]
----
Your code body goes here.
----

    Replace language with the appropriate language. Use json for JSON queries. Use bash for terminal input. Use [source,] if no language is clear.

    When necessary, indent code with spaces. Do not indent with tabs.

    Long code samples

    You can hide long code samples with code snippets so they do not take up an entire page. A user can click the placeholder text to expand and hide the code sample.

    Do not hide API requests under long code samples. If necessary, use a placeholder for a long value, such as the Springboard access token, to shorten the full API request.

    Consider whether you need to use a long code sample at all. If an API response repeats a lot of the same fields and values, then showing all the values in the response isn’t helpful. Shorten the response when possible before using a code snippet.

    For responses and code samples that still take up significantly more than the length of a page on a large monitor, consider hiding it.

    To collapse a code sample, copy and paste the following sample into your document. Replace the text in between the ==== with your code sample, including any syntax if necessary.

    [.lw-details]
.Click to see the response. This text is customizable.
[%collapsible]
====
[source,json]
----
Replace this text with your lengthy code sample.
----
====

    The following collapsible result displays the result of the preceding sample. The user can click the same text to hide the response.

    Click to see the response. This text is customizable. 
    Replace this text with your lengthy code sample.

    Resources

    The Google Developer Documentation Style Guide has several resources on code samples and terminal format.