Formatting reference

Applying consistent text formatting improves readability and helps users locate information in Splunk documentation. Follow these formatting conventions for semantic tags and hard-coded text.

Applying formatting to elements in text assists readers in their understanding of that text. Using consistent text formatting also helps readers scan text for the information they're looking for. Depending on whether you're using semantic tags as you write or if you're hard-coding text, follow these formatting conventions when you write Splunk documentation.

Documentation elements

Review the following table for formatting guidance on documentation elements:

Element Format Examples
Error, success, and other system messages

For semantic tags, use <systemoutput>.

For hard-coded text, use inline monospaced font or monospaced font block, depending on message length.
  • An error message such as Invalid input value means the add-on was unable to generate a certificate.
  • When you view the logs in the install_directory/var/log/edge.log file on the host machine, the following error message appears:
CODE 
"error":"HTTP 403 \"Forbidden\""

Keyboard shortcuts

No semantic tag or formatting.

Don't include spaces in the shortcut.
  • Select Alt+N for Windows.
  • Select *nix or Control+N for Mac.
Measurements No semantic tag or formatting.
  • 2 seconds

  • 5 days

  • 8 CPU
Words that are offset from the meaning of your sentence

No semantic tag or formatting.

Encase in quotation marks.		 Search for "Query tables" on the Microsoft website.
Words that you want to emphasize

Don't use bold, italics, or all capital letters to emphasize a word.

 Do not exceed your license limit.
For additional guidance about documentation elements, see the following pages:

Computer elements

Review the following table for formatting guidance on computer elements:

Element Format Examples
Directories, folders, repositories

For semantic tags, use <filepath>.

For hard-coded text, use inline monospaced font.

If using a placeholder variable in the file path, format the placeholder variable following the guidance later in this table.
  • The $SPLUNK_HOME/bin/etc/apps folder
  • The \bin\etc\apps folder
  • The your domain folder
Expressions

For semantic tags, use <codeph>.

For hard-coded text, use inline monospaced font.
  • Ensure delay > 10 evaluates to True.
  • The following regular expression defines valid identifiers for the scheme: [0-9a-zA-Z][0-9a-zA-Z_-]*.
Environment variable (key)

Use all capital letters.

For semantic tags, use <codeph>.

For hard-coded text, use inline monospaced font.
  • OTEL_RESOURCE_ATTRIBUTE
  • SPLUNK_ACCESS_TOKEN=abc123token
  • Set the SPLUNK_ACCESS_TOKEN environment variable to abc123token.
Environment variable (value)

For semantic tags, use <codeph>.

For hard-coded text, use inline monospaced font.
  • abc123token
  • service.name=otel-collector
  • SPLUNK_ACCESS_TOKEN=abc123token
  • Set the SPLUNK_ACCESS_TOKEN environment variable to abc123token.
File extensions

For semantic tags, use <filepath>.

For hard-coded text, use inline monospaced font.
  • The .tgz extension

  • A text (.txt) file
File names

For semantic tags, use <filepath>.

For hard-coded text, use inline monospaced font.

 Navigate to the fields.conf file.
File paths

List both the *nix and Windows file paths, in that order.

For semantic tags, use <filepath>.

For hard-coded text, use inline monospaced font.
  • $SPLUNK_HOME/bin/splunkd
  • %SPLUNK_HOME%\bin\splunkd.exe
File types No semantic tag or formatting.
  • A text file
  • In JSON format
  • A PDF
Hosts and ports No semantic tag or formatting.
  • http://localhost:8000
  • deployment name.splunkcloud.com
Menu paths

For semantic tags, use <menucascade>.

For hard-coded text, use bold type and the word "then" or equivalent text to separate the names of the menus.
  • Select Settings > Data inputs.
  • Select File > Save as.

  • Select File, then select Save as.
Placeholder variables

For semantic tags, use <varname>, unless in a monospaced code block.

For monospaced code blocks or hard-coded text, use angle brackets.
  • http://hostname:port
  • CODE 
    host=<your_hostname>
Tags (HTML, XML)

For semantic tags, use <codeph>.

For hard-coded text, use inline monospaced font.
  • A <div> tag
  • The <dashboard> element
UI elements, including menu items, drop-down lists, buttons, panels, and dialog boxes

For semantic tags, use <uicontrol>.

For hard-coded text, use bold type.
  • In the Set Source Type step of the Add Data guided setup, select Timestamp.
  • In the Name field, enter your name.
URIs, URLs

Include http:// or https:// and www. Don't capitalize any letters in the link.

For semantic tags, use <codeph> if a link isn't required.

 Open https://prof.spacebridge.spl.mobi/health_check in a web browser.
User input in the UI

For semantic tags, use <userinput>.

For hard-coded text, use bold type.
  • For the Destination field, enter ca_counties.
  • In the Title field, enter Top recipients by mailer.

Splunk-specific elements

Review the following table for formatting guidance on Splunk-specific elements:

Element Format Examples
Index names

For semantic tags, use <parmname>.

For hard-coded text, use bold type.
  • Save the file in the main index.

  • Save the file in the main index.
Input names

For semantic tags, use <parmname>.

For hard-coded text, use bold type.
  • Select the myhost data input.

  • Select the myhost data input.
Knowledge objects, such as fields, field values, event types, lookups, tags, alias, and data models

For semantic tags, use <codeph>.

For hard-coded text, use inline monospaced font.
  • The default field index identifies the index in which the event is located.
  • The IP address uses the mainoffice tag.
  • The default interval for the recording unit duration is 20 ms.
Searches

For semantic tags, use <codeblock outputclass="search"> .

For hard-coded text, use the search bar or monospaced font block.

For guidance on including line breaks in search commands, see Formatting Splunk searches.

 See the following topics for search examples:
Search results

For semantic tags, use <table outputclass="search">.

For hard-coded text, use a search table.

 For a search result example, see untable.
Source types

For semantic tags, use <codeph>.

For hard-coded text, use inline monospaced font.

 This entry defines the access_combined source type.
SPL and SPL2 clauses

Use all capital letters.

No semantic tag or formatting.
  • Use the WHERE clause to filter results.
  • The SPL2 from command has these clauses: FROM, JOIN, WHERE, GROUP BY, SELECT, ORDER BY, LIMIT, and OFFSET.
SPL and SPL2 commands, elements, functions, and macros

For semantic tags, use <cmdname>.

For hard-coded text, use inline monospaced font.
  • Enter | inputlookup ca_county_lookup to test your geospatial lookup.
  • Use the geom command to perform the lookup.
  • Use the apply function.
  • Include a custom metrics index in the itsi_im_metrics_indexes search macro.
Splexicon links

Use an inline link with bold type.

For guidance on Splexicon links, see Formatting links in Splunk documentation.

 Use geospatial lookups to return results that Splunk software can use to generate a choropleth map visualization.
Tenant names

For semantic tags, use <parmname>.

For hard-coded text, use bold type.
  • Use the system tenant.
  • Find the getstartedtutorial01 tenant.
Token names

For semantic tags, use <parmname>.

For hard-coded text, use bold type.
  • Update the access token.

  • Update the access token.
User roles and capabilities

For semantic tags, use <parmname>.

For hard-coded text, use bold type.
  • You need the admin role to configure the settings.
  • If the user holds the admin_all_objects capability, they can make changes to any object on the instance.

Configuration files

Review the following table for formatting guidance on configuration files:

Element Format Examples
Attributes or settings

For semantic tags, use <codeph>.

For hard-coded text, use inline monospaced font.
  • httpport
  • enableSplunkWebSSL
Configuration files in text

For semantic tags, use <codeblock>.

For hard-coded text, use a monospaced font block.

 See the following topics for configuration file examples:
Configuration file names

For semantic tags, use <filepath>.

For hard-coded text, inline monospaced font.

 Navigate to the fields.conf file.
Configuration file parameters, arguments, and stanza names in text

Enclose stanza names in square brackets.

For semantic tags, use <codeph>.

For hard-coded text, use inline monospaced font.
  • Set the maxDist value to 60 in the fields.conf file.
  • Edit the [splunktcp] stanza.
Values

For semantic tags, use <codeph>.

For hard-coded text, use inline monospaced font.
  • In the [settings] stanza, map httpport to 12800.
  • Set enableSplunkWebSSL=true.

Command-line interface (CLI) elements

Review the following table for formatting guidance on CLI elements:

Element Format Examples
A complete command

For semantic tags, use <codeph>.

For hard-coded text, use inline monospaced font.

 For a complete command example, see Manage secret storage using the Splunk REST API in the Splunk Developer Portal.
Command line arguments in a numbered list or longer than 1 line

For semantic tags, use <codeblock>.

For hard-coded text, use a monospaced font block.

 See the following topics for command line argument examples:
Command line arguments in a paragraph

For semantic tags, use <codeph>.

For hard-coded text, use inline monospaced font.

 You can use the command line by entering ./splunk apply cluster-bundle in the CLI.
Command names

For semantic tags, use <cmdname>.

For hard-coded text, use inline monospaced font.

 Run the btool command.
Command options or parameters

For semantic tags, use <option>.

For hard-coded text, use inline monospaced font.

If using a placeholder variable, format the variable following the guidance in Computer elements.
  • -u username
  • -u <username>

REST API elements

Review the following table for formatting guidance on REST API elements:

Element Format Examples
API names No semantic tag or formatting.
  • The collect2 API
  • You can securely store, update, retrieve, and delete secrets using the Splunk platform REST API.
  • Replace your token values, file path, and name of your app package in the Splunk AppInspect API.
Endpoint name

For semantic tags, use <parmname>.

For hard-coded text, use bold type.
  • Access the provisioner endpoint.

  • Access the provisioner endpoint.
Endpoint path

For semantic tags, use <filepath>.

For hard-coded text, use inline monospaced font.

 /system/provisioner/v1beta1/tenants
HTTP or REST API method type Use all capital letters. Submit a GET request.
HTTP or REST API methods in use

For semantic tags, use <codeblock>.

For hard-coded text, use a monospaced font block.
CODE 
GET /system/provisioner/v1beta1/tenants/
JSON bodies

For semantic tags, use <codeblock>.

For hard-coded text, use a monospaced font block.

 For a JSON body example, see REST Custom Function.
Object names

For semantic tags, use <parmname>.

For hard-coded text, use bold type.
  • the handle object

  • the handle object
REST API requests and responses

For semantic tags, use <codeblock>.

For hard-coded text, use a monospaced font block.

 For a REST API example, see Submit an app for inspection in the Splunk Developer Portal.
REST response body

For semantic tags, use <codeblock>.

For hard-coded text, use a monospaced font block.

 For a REST response body example, see Submit an app for inspection in the Splunk Developer Portal.
Request parameter

For semantic tags, use <codeph>.

For hard-coded text, use inline monospaced font.

 "earliest_time": "-30m"
Returned REST response value

For semantic tags, use <systemoutput>.

For hard-coded text, use inline monospaced font.

 IACQlgX2dSVNz7HVDRA9StAm0j

Code elements

Review the following table for formatting guidance on code:

Element Format Examples
Arguments

For semantic tags, use <codeph>.

For hard-coded text, use inline monospaced font.

 Pass in arg1 as the argument for the param1 parameter and arg2 as the argument for the param2 parameter.
Classes

Capitalize class names with medial capitals.

For semantic tags, use <codeph>.

For hard-coded text, use inline monospaced font.

 The MyClass class
Code elements and usage

For semantic tags, use <codeph>.

For hard-coded text, use inline monospaced font.
  • Use operators such as +, !=, and AND.
  • Use keywords such as if, else, and return tags such as <div/>.
Code examples

For semantic tags, use <codeblock>.

For hard-coded text, use a monospaced font block.

 See the following topics for code examples:
Constants Use all capital letters. DEBUG_STREAMEVENTS
Function names

For semantic tags, use <parmname>.

For hard-coded text, use bold type.
  • Pass your arguments into the myFunction function.
  • Pass your arguments into the myFunction function.
Functions in use

For semantic tags, use <codeblock>.

For hard-coded text, use a monospaced font block.
CODE 
myFunction(arg1, arg2)
Hexadecimal numbers Use all capital letters for alphabetical characters.
  • #FF0000
  • 0xFF0000
  • %FF0000
  • U+FF0000
HTTP status codes

Use a lowercase "x" to represent a range.

For semantic tags, use <codeph>.

For hard-coded text, use inline monospaced font.
  • 4xx
  • 503: Service too busy
Methods

For semantic tags, use <codeph>.

For hard-coded text, use inline monospaced font.

 The myMethod method
Metrics

For semantic tags, use <codeph>.

For hard-coded text, use inline monospaced font.

 A server cluster that has 100 host machines might report a single set of metrics named cpu.utilization, api.calls, and dropped.packets.
Parameter names

For semantic tags, use <parmname>.

For hard-coded text, use bold type.
  • This function accepts the param1 and param2 parameters.

  • This function accepts the param1 and param2 parameters.
Placeholder variables

For semantic tags, use <varname>, unless in a monospaced code block.

For monospaced code blocks or hard-coded text, use angle brackets.

Open the /etc/apps/your_app_name/appserver/ folder.

CODE 
/etc/apps/<your_app_name/appserver
Property names

For semantic tags, use <parmname>.

For hard-coded text, use bold type.
  • Add the stanza to your file using the setupview property.

  • Add the stanza to your file using the setupview property.
Properties in use

For semantic tags, use <codeblock>.

For hard-coded text, use a monospaced font block.

 For an example of a property in use, see Configure the Java agent for Splunk Observability Cloud.
Simple XML elements

For semantic tags, use <codeph>.

For hard-coded text, use inline monospaced font.

 Find the <title>all</title> element.
Simple XML source code for dashboards

For semantic tags, use <codeblock>.

For hard-coded text, use a monospaced font block.

 For an example of Simple XML source code, see Editing Simple XML.
User-created values

For semantic tags, use <userinput>.

For hard-coded text, use bold type.
  • The value of the myStr parameter is hello.
  • The value of the myStr parameter is hello.