
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: |
|
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 | $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 |
a TXT file in JSON format |
|
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 |
|
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. |
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 |
Searches | Search bar or monospaced font block | See the following examples:
|
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 |
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
|
|
Configuration files in text | Monospaced font block | See the following pages for examples of configuration files referenced in Splunk documentation:
|
|
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 |
Enclose stanza names in square brackets. |
Values | Inline monospaced font | In the [settings] stanza, map httpport to 12800 .Set |
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:
|
|
Command line arguments in a numbered list or longer than one line | Monospaced font block | See the following examples:
|
|
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 |
|
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. |
|
Endpoints | Bold type for endpoint name, inline monospaced font for usage | the provisioner endpoint
|
|
HTTP or REST API methods | All capital letters, inline monospaced font, depending on use | Submit a GET request.
|
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:
|
|
Object names | Bold type | the handle object | |
REST API requests and responses | Monospaced font block | See the following examples:
|
|
REST response body | Monospaced font block | See the following examples:
|
|
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 | Inline monospaced font | The MyClass class
|
Capitalize class names. |
Code elements and usage | Inline monospaced font | operators such as + , != , and AND
keywords such as |
|
Code examples | Monospaced font block | See the following examples:
|
|
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 |
|
HTTP status codes | Inline monospaced font | 4xx
|
Use a lowercase "x" to represent a range. |
Methods | Inline monospaced font | 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:
|
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
|
PREVIOUS Capitalization |
NEXT Line breaks |
This documentation applies to the following versions of Splunk® Style Guide: current
Feedback submitted, thanks!