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 Semantic tag Hard-coded format Examples Comments
Error, success, and other system messages <systemoutput> 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:
"error":"HTTP 403 \"Forbidden\""
For guidance on writing system messages in a GUI, see Error and warning messages and Success messages in the UI text style guidelines.
Keyboard shortcuts No semantic tag No formatting Select Alt+N for Windows or *nix or Control+N for Mac. Don't include spaces in the shortcut. See Keyboard shortcuts for more information.
Measurements No semantic tag No formatting
  • 2 seconds

  • 5 days

  • 8 CPU

See Measurements for more information.
Topic titles and section headings No semantic tag Sentence-style capitalization See Pass values to the class constructor in the Splunk Developer Portal.See Naming guides, topics, and sections for more information.
Words that are offset from the meaning of your sentence No semantic tag Quotation marks Search for "Query tables" on the Microsoft website.  
Words that you want to emphasize No semantic tag No formatting Do not exceed your license limit. Don't use bold, italics, or all capital letters to emphasize a word.

Computer elements

Review the following table for formatting guidance on computer elements:

Element Semantic tag Hard-coded format Examples Comments
Directories, folders, repositories <filepath> Inline monospaced font
  • The $SPLUNK_HOME/bin/etc/apps folder
  • The \bin\etc\apps folder
  • The your domain folder
Start partial directories with a forward slash ( / ) for *nix or a backslash ( \ ) for Windows. Enclose any placeholder variables in angle brackets when hard-coding the formatting, and use the <varname> element when applying semantic tags.
Expressions <codeph> 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) <parmname>, all capital letters Inline monospaced font
  • OTEL_RESOURCE_ATTRIBUTE
  • SPLUNK_ACCESS_TOKEN=abc123token
  • Set the SPLUNK_ACCESS_TOKEN environment variable to abc123token.
When referencing an environment variable key alone, use <parmname> and format the key in all capital letters. For a key-value pair, wrap the key in <parmname> and the value in <codeph>.

  • On *nix, environment variables are in all capital letters and are case sensitive.

  • On Windows, environment variables are in all capital letters by convention, but are not case sensitive.

Environment variable (value) <codeph> Inline monospaced font
  • abc123token
  • service.name=otel-collector
  • SPLUNK_ACCESS_TOKEN=abc123token
  • Set the SPLUNK_ACCESS_TOKEN environment variable to abc123token.
When referencing an environment variable value alone, use <codeph> in its literal value. For a key-value pair, wrap the key in <parmname> and the value in <codeph>.
File extensions <filepath> Inline monospaced font
  • The .tgz extension

  • A text (.txt) file

 
File names <filepath> Inline monospaced font Navigate to the fields.conf file.  
File paths <filepath> Inline monospaced font
  • $SPLUNK_HOME/bin/splunkd
  • %SPLUNK_HOME%\bin\splunkd.exe
List both the *nix and Windows file paths, in that order.
File types No semantic tag No formatting
  • A text file
  • In JSON format
  • A PDF
 
Hosts and ports No semantic tag No formatting
  • http://localhost:8000
  • deployment name.splunkcloud.com
Enclose any placeholder variables in angle brackets when hard-coding the formatting, and use the <varname> element when applying semantic tags.
Menu paths <menucascade> Bold type for menu names
  • Select Settings > Data inputs.
  • Select File > Save as.
When hard-coding the formatting, use the word "then" or equivalent text to separate the names of menus.
Placeholder variables <varname> Angle brackets
  • http://hostname:port

  • host=your_hostname

Enclose any placeholder variables in angle brackets when hard-coding the formatting, and use the <varname> element when applying semantic tags.
Tags (HTML, XML) <codeph> Inline monospaced font
  • A <div> tag
  • The <dashboard> element
 
UI elements, including menu items, drop-down lists, buttons, panels, and dialog boxes <uicontrol> 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 <codeph> See the Comments column. Open https://prof.spacebridge.spl.mobi/health_check in a web browser. Include http:// or https:// and www. Don't capitalize any letters in the link.
User input in the UI <userinput> 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 Semantic tag Hard-coded format Examples Comments
Index names <parmname> Bold type Save the file in the main index.  
Input names <parmname> Bold type Select the myhost data input.  
Knowledge objects, such as fields, field values, event types, lookups, tags, alias, and data models <codeph> 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 <codeblock outputclass="search"> Search bar or monospaced font block See the following topics for search examples: For guidance on line breaks in search commands, see Formatting Splunk searches.
Search results <table outputclass="search"> Search table For a search result example, see untable.  
Source types <codeph> Inline monospaced font This entry defines the access_combined source type.  
SPL and SPL2 clauses No semantic tag All capital letters
  • 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 <cmdname> 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 Inline link with bold type Bold type Use geospatial lookups to return results that Splunk software can use to generate a choropleth map visualization. For guidance on Splexicon links, see Formatting links in Splunk documentation.
Tenant names <parmname> Bold type
  • Use the system tenant.
  • Find the getstartedtutorial01 tenant.
 
Token names <parmname> Bold type Update the access token.  
User roles and capabilities <parmname> 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 Semantic tag Hard-coded format Examples Comments
Attributes or settings <codeph> Inline monospaced font
  • httpport
  • enableSplunkWebSSL
 
Configuration files in text <codeblock> Monospaced font block See the following topics for configuration file examples:  
Configuration file names <filepath> No formatting Navigate to the fields.conf file.  
Configuration file parameters, arguments, and stanza names in text <codeph> Inline monospaced font
  • Set the maxDist value to 60 in the fields.conf file.
  • Edit the [splunktcp] stanza.
Enclose stanza names in square brackets.
Values <codeph> 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 Semantic tag Hard-coded format Examples Comments
A complete command <codeph> 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 <codeblock> Monospaced font block See the following topics for command line argument examples:  
Command line arguments in a paragraph <codeph> Inline monospaced font You can use the command line by entering ./splunk apply cluster-bundle in the CLI.  
Command names <cmdname> Inline monospaced font Run the btool command.  
Command options or parameters <option> Inline monospaced font with italics -u <username> Enclose any placeholder variables in angle brackets when hard-coding the formatting, and use the <varname> element when applying semantic tags.

REST API elements

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

Element Semantic tag Hard-coded format Examples
API names No semantic tag No 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 <parmname> Bold type Access the provisioner endpoint
Endpoint path <filepath> Inline monospaced font /system/provisioner/v1beta1/tenants
HTTP or REST API method type No semantic tag All capital letters Submit a GET request.
HTTP or REST API methods in use <codeblock> Monospaced font block 
GET /system/provisioner/v1beta1/tenants/
JSON bodies <codeblock> Monospaced font block For a JSON body example, see REST Custom Function.
Object names <parmname> Bold type the handle object
REST API requests and responses <codeblock> Monospaced font block For a REST API example, see Submit an app for inspection in the Splunk Developer Portal.
REST response body <codeblock> Monospaced font block For a REST response body example, see Submit an app for inspection in the Splunk Developer Portal.
Request parameter <codeph> Inline monospaced font "earliest_time": "-30m"
Returned REST response value <systemoutput> Inline monospaced font IACQlgX2dSVNz7HVDRA9StAm0j

Code elements

Review the following table for formatting guidance on code:

Element Semantic tag Hard-coded format Examples Comments
Arguments <codeph> Inline monospaced font Pass in arg1 as the argument for the param1 parameter and arg2 as the argument for the param2 parameter.  
Classes <codeph> Inline monospaced font The MyClass class Capitalize class names with medial capitals.
Code elements and usage <codeph> Inline monospaced font
  • Use operators such as +, !=, and AND.
  • Use keywords such as if, else, and return tags such as <div/>.
 
Code examples <codeblock> Monospaced font block See the following topics for code examples:  
Constants No semantic tag All capital letters DEBUG_STREAMEVENTS  
Function names <parmname> Bold type Pass your arguments into the myFunction function.  
Functions in use <codeblock> Monospaced font block 
myFunction(arg1, arg2)
 
Hexadecimal numbers No semantic tag All capital letters for alphabetical characters
  • #FF0000
  • 0xFF0000
  • %FF0000
  • U+FF0000
 
HTTP status codes <codeph> Inline monospaced font
  • 4xx
  • 503: Service too busy
Use a lowercase "x" to represent a range.
Methods <codeph> Inline monospaced font The myMethod method  
Metrics <codeph> 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 <parmname> Bold type This function accepts 2 parameters, param1 and param2.  
Placeholder variables <varname> Angle brackets Open the /etc/apps/your_app_name/appserver/ folder. Enclose placeholder variables in angle brackets regardless if you're using hard-coded formatting.
Property names <parmname> Bold type Add the stanza to your file using the setupview property.  
Properties in use <codeblock> Monospaced font block For an example of a property in use, see Configure the Java agent for Splunk Observability Cloud.  
Simple XML elements <codeph> Inline monospaced font Find the <title>all</title> element.  
Simple XML source code for dashboards <codeblock> Monospaced font block For an example of Simple XML source code, see Editing Simple XML.  
User-created values <userinput> Bold type The value of the myStr parameter is hello.