Formatting reference

Applying formatting to certain elements in text aids readers in their understanding of that text. Using consistent text formatting also helps readers scan text for the information they're looking for. Use these formatting conventions when you write Splunk documentation.

Documentation elements

Review the following table for formatting guidance on documentation elements:

Element	Hard-coded format	Semantic tag	Examples	Comments
Error messages	Inline monospaced font or monospaced font block, depending on length	<systemoutput>	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\""	See Error and warning messages for more information.
Keyboard shortcuts	No formatting	No semantic tag	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.
Manual names	Italics, headline-style capitalization	No semantic tag	See Managing connections in the Splunk Data Stream Processor in the Connect to Data Sources and Destinations with DSP manual.	See Manual names, topic titles, and section headings for more information.
Topic titles and section headings	Sentence-style capitalization	No semantic tag	See Pass values to the class constructor in the Splunk Developer Portal.	See Manual names, topic titles, and section headings for more information.
Words that are offset from the meaning of your sentence	Quotation marks	No semantic tag	Search for "Query tables" on the Microsoft website.
Words that you want to emphasize	No formatting	No semantic tag	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	Hard-coded format	Semantic tag	Examples	Comments
Directories, folders, repositories	No formatting	<filepath>	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 placeholder variables in angle brackets or use the <varname> element.
Expressions	Inline monospaced font	<codeph>	Ensure delay > 10 evaluates to True. The following regular expression defines valid identifiers for the scheme: [0-9a-zA-Z][0-9a-zA-Z_-]*
File extensions	No formatting	No semantic tag	A text (.txt) file A .tgz extension
File names	No formatting	<filepath>	Navigate to the fields.conf file.
File paths	No formatting	<filepath>	$SPLUNK_HOME/bin/splunkd %SPLUNK_HOME%\bin\splunkd.exe	List both the *nix and Windows file paths, in that order.
File types	All capital letters	No semantic tag	A TXT file In JSON format A PDF
Hosts and ports	No formatting	No semantic tag	http://localhost:8000 <deployment name>.splunkcloud.com	Enclose placeholder variables in angle brackets or use the <varname> element.
Menu paths	Bold type for menu names	<menucascade>	Select Settings, then Data inputs. Select File, then Save as.	When hard-coding the formatting, use the word "then" or equivalent text to separate the names of menus.
Placeholder variables	Angle brackets	<varname>	http://<hostname:port> host=<your_hostname>
Tags (HTML, XML)	Inline monospaced font	<codeph>	A <div> tag The <dashboard> element
UI elements, including menu items, drop-down lists, buttons, text entry fields, panels, and dialog boxes	Bold type	<uicontrol>	In the Set Source Type step of the Add Data guided setup, select Timestamp. In the Name field, enter your name.
URIs, URLs	See the Comments column	<url>	Open https://prod.spacebridge.spl.mobi/health_check in a web browser. Open port 443 outbound to prod.spacebridge.spl.mobi to allow the WebSocket connection.	Include http:// or https:// and www. Don't capitalize any letters in the link. Prevent fake links from rendering.
User input in the UI	Bold type	<userinput>	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	Hard-coded format	Semantic tag	Examples	Comments
Index names	Bold type	<parmname>	Save the file in the main index.
Input names	Bold type	<parmname>	Select the myhost data input.
Knowledge objects such as fields, event types, lookups, tags, aliases, and data models	Inline monospaced font	<codeph>	The default field index identifies the index in which the event is located. The IP address uses the mainoffice tag.
Searches	Search bar or monospaced font block	<codeblock> with outputclass attribute of "search"	See the following topics for search examples: collect in the Splunk Enterprise Search Reference manual Create a Splunk app and set properties in the Splunk Developer Portal	For guidance on line breaks in search tags, see Line breaks.
Search results	Search table	<table> with outputclass attribute of "search"	For a search result example, see untable in the Splunk Enterprise Search Reference manual.
Source types	Inline monospaced font	<codeph>	This entry defines the access_combined source type.
SPL and SPL2 clauses	All capital letters	No semantic tag	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	Inline monospaced font	<cmdname>	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	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	Bold type	<parmname>	Use the system tenant. Find the getstartedtutorial01 tenant.
Token names	Bold type	<parmname>	Update the access token.
User roles and capabilities	Bold type	<parmname>	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	Hard-coded format	Semantic tag	Examples	Comments
Attributes or settings	Inline monospaced font	<codeph>	httpport enableSplunkWebSSL
Configuration files in text	Monospaced font block	<codeblock>	See the following topics for configuration file examples: props.conf in the Splunk Enterprise Admin Manual Rules Engine properties reference in ITSI in the Splunk ITSI Event Analytics Manual Create a setup page for an app in Splunk Cloud Platform or Splunk Enterprise in the Splunk Developer Portal
Configuration file names	No formatting	<filepath>	Navigate to the fields.conf file.
Configuration file parameters, arguments, and stanza names in text	Inline monospaced font	<codeph>	Set the maxDist value to 60 in the fields.conf file. Edit the [splunktcp] stanza.	Enclose stanza names in square brackets.
Values	Inline monospaced font	<codeph>	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	Hard-coded format	Semantic tag	Examples	Comments
A complete command	Inline monospaced font	<codeph>	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	Monospaced font block	<codeblock>	See the following topics for command line argument examples: How to set configuration properties in Splunk UBA in Administer Splunk User Behavior Analytics Set a secret key on the deployer in the Splunk Enterprise Distributed Search manual
Command line arguments in a paragraph	Inline monospaced font	<codeph>	You can use the command line by entering ./splunk apply cluster-bundle in the CLI.
Command names	Inline monospaced font	<cmdname>	Run the btool command.
Command options or parameters	Inline monospaced font with italics	<option>	-u <username>	Enclose placeholder variables in angle brackets or use the <varname> element.

REST API

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

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

Code

Review the following table for formatting guidance on code:

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