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

When you are writing Splunk documentation, some parts of the written text, such as error messages and terms that you want a reader to search for, need to be distinguished from other parts of the sentence. Applying consistent text formatting for these elements helps a reader better understand the sentence and scan the information that they're looking for.

Element	How to format	Examples	Comments
Error messages	Quotation marks	If you see an error message such as "Invalid input value", the add-on was unable to generate a certificate with the provided information.
Keyboard shortcuts	No formatting	Select Alt+N for Windows or *nix or Control+N for Mac.	Don't include spaces in the shortcut.
Manual names	Italics, headline-style capitalization	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	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	Search for "Query tables" on the Microsoft website.

Computer elements

When written out in text, some computer elements, such as file structure components and location elements like hosts and ports, can be difficult to discern from other parts of the sentence. Addressing these elements in text as well as applying text formatting increases the readability and scannability of the text.

Element	How to format	Example	Comments
Directories, folders, repositories	No formatting	the $SPLUNK_HOME/bin/etc/apps folder the \bin\etc\apps folder	Start partial directories with a forward slash ( / ) for *nix or a backslash ( \ ) for Windows. Enclose placeholder variables in angle brackets.
Expressions	Inline monospaced font	Ensure delay > 10 evaluates to True. The following regular expression defines valid identifiers for the scheme name: [0-9a-zA-Z][0-9a-zA-Z_-]*
File extensions	No formatting	a text (.txt) file a .tgz extension
File names	No formatting	Navigate to the fields.conf file.
File paths	No formatting	~/bin/btool.exe C:\bin\btool.exe	List both the *nix and Windows file paths, in that order.
File types	All capital letters	a TXT file in JSON format a PDF
Hosts and ports	No formatting	http://localhost:8000	No formatting for the host or port itself. Enclose placeholder variables in angle brackets.
Placeholder variables	Angle brackets	http://<hostname:port> host=<your_hostname>
Tags (HTML, XML)	Inline monospaced font	a <div> tag the <dashboard> element
UI elements, including menu items, drop-down lists, buttons, text entry fields, panels, and dialog boxes	Bold type	Select Settings, then Data inputs. In the Set Source Type step of the Add Data guided setup, select Timestamp. In the Name field, enter your name.	Use the word "then" or equivalent text to separate the names of menus.
URIs, URLs	See the Comments column	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. It's okay to apply special formatting like inline monospaced font if that's how the authoring tool prevents the fake link from rendering.
User input in the UI	Bold type	For the Destination field, enter ca_counties. In the Title field, enter Top recipients by mailer.

Splunk-specific elements

There are components specific to Splunk software, such as indexes, knowledge objects, SPL commands, and so on, that take text formatting for ease of reading.

Element	How to format	Example
Index names	Bold type	Save the file in the main index.
Input names	Bold type	Select the myhost data input.
Knowledge objects such as fields, event types, lookups, tags, aliases, and data models	Inline monospaced font	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	See the following examples: collect in the Splunk Enterprise Search Reference manual. Create a Splunk app and set properties in the Splunk Developer Portal.
Search results	Search table	See the following example: untable in the Splunk Enterprise Search Reference manual.
Source types	Inline monospaced font	This entry defines the access_combined source type.
SPL commands, elements, functions, macros, and other search content	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	Bold type	Use geospatial lookups to return results that Splunk software can use to generate a choropleth map visualization.
Tenant names	Bold type	Use the system tenant. Find the getstartedtutorial01 tenant.
Token names	No formatting	Update your access token.
User roles and capabilities	No formatting	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

Splunk configuration files, or .conf files, are specific to the Splunk platform, and readers of Splunk documentation often need information about how to manage these files or edit settings within them. The following table shows how to format text about Splunk configuration files and the elements within them, such as stanzas, attributes, and values.

Element	How to format	Example	Comments
Attributes or settings	Inline monospaced font	httpport enableSplunkWebSSL
Configuration file names	No formatting	Navigate to the fields.conf file.
Configuration file parameters, arguments, and stanza names in a paragraph	Inline monospaced font	Set the maxDist value to 60 in the fields.conf file. Edit the [splunktcp] stanza.	Enclose stanza names in square brackets.
Configuration file stanzas	Monospaced font block	See the following 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.
Values	Inline monospaced font	In the [settings] stanza, map httpport to 12800. Set enableSplunkWebSSL=true.

Command-line interface (CLI) elements

Splunk documentation often covers tasks admins and developers must complete in the command-line interface and can include things they must enter in the CLI. Presenting CLI elements, such as commands, command names, and options and parameters, with text formatting can distinguish the elements from the rest of the text and aid in readability.

Element	How to format	Example	Comments
A complete command	Inline monospaced font	See the following examples: Manage secret storage using the Splunk REST API in the Splunk Developer Portal. Collect Linux data in the Splunk Observability documentation.
Command line arguments in a numbered list or longer than one line	Monospaced font block	See the following 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	You can also use the command line by entering ./splunk apply cluster-bundle in the CLI.
Command names	Inline monospaced font	Use the dedup command to remove identical events. Run the btool command.
Command options or parameters	Inline monospaced font	-u <username>	Enclose placeholder variables in angle brackets.

REST API

There are documentation formatting conventions for many REST API elements, like endpoints, methods, parameters, requests and responses, and so on. The following table shows formatting conventions for REST API elements in Splunk documentation, which align with industry trends for presenting written information about REST APIs.

Element	How to format	Example	Comments
API names	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.
Endpoints	Bold type for endpoint name, inline monospaced font for usage	the provisioner endpoint /system/provisioner/v1beta1/tenants the apps/local/<appname> endpoint apps/local/<appname>
HTTP methods	All capital letters, inline monospaced font, depending on use	Submit a GET request. GET /system/provisioner/v1beta1/tenants/	Enter the request name in all capital letters. When using a method and endpoint together, use inline monospaced font.
JSON bodies	Monospaced font block	See the following examples: Expand the methods in REST custom function in the REST API Reference for Splunk Phantom. Create detectors in the Splunk Observability documentation.
Object names	Bold type	the handle object
REST API methods	No formatting	Submit a GET request.	Enter the request name in all capital letters.
REST API requests and responses	Monospaced font block	See the following examples: Submit an app for inspection in the Splunk Developer Portal. Create detectors in the Splunk Observability documentation.
REST response body	Monospaced font block	See the following examples: Create detectors in the Splunk Observability documentation. Submit an app for inspection in the Splunk Developer Portal.
Request parameters	Inline monospaced font	"earliest_time": "-30m"
Returned REST response value	Inline monospaced font	IACQlgX2dSVNz7HVDRA9StAm0j

Code

When writing code, you must apply text formatting to a number of elements. Using consistent formatting helps separate the code elements from the rest of the text, aiding in readability and scannability. Use the following logic when formatting code.

Element	How to format	Example	Comments
Arguments	Inline monospaced font	Pass in arg1 as the argument for the param1 parameter and arg2 as the argument for the param2 parameter.
Classes	Bold type	The MyClass class	Capitalize class names.
Code elements and usage	Inline monospaced font	operators such as +, !=, and AND keywords such as if, else, and return tags such as <div/>
Code examples	Monospaced font block	See the following 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	DEBUG_STREAMEVENTS
Function names in code	Monospaced font block or inline monospaced font, depending on use	Pass your arguments into the myFunction function. For example: myFunction(arg1, arg2)	Most function names appear in code samples, where they are formatted as inline monospaced font in a sentence or within a code block when it stands apart as an example.
Hexadecimal numbers	All capital letters for alphabetical characters in the hexadecimal number	#FF0000 0xFF0000 %FF0000 U+FF0000
Methods	Bold type	The myMethod method
Parameters	Inline monospaced font	This function accepts two parameters, param1 and param2.
Placeholder variables	Angle brackets	Open the /etc/apps/<your_app_name>/appserver/ folder.
Properties	Monospaced font block or inline monospaced font, depending on use	See the following examples: See Configure the Java agent for Splunk Observability Cloud in the Splunk Observability documentation for an example of a property in a code block. Add the stanza to your file using the setupview property.	Most properties appear in code samples, where they are formatted as a monospaced font block. Use inline monospaced font when referring to a property in a sentence.
Simple XML elements	Inline monospaced font	Find the <title>all</title> element.
Simple XML source code for dashboards	Monospaced font block	See the following example: Simple XML Reference in the Splunk Enterprise Dashboards and Visualizations manual.
User-created values	Bold type	the value of the myStr parameter is hello