Splunk® Style Guide

Splunk Style Guide

Acrobat logo Download manual as PDF


The guidelines in the Splunk Style Guide establish best practices for writing technical documentation. Search docs.splunk.com to find documentation related to Splunk products.
Acrobat logo Download topic as PDF

Formatting links in Splunk documentation

Use a hyperlink to cross-reference other topics in Splunk documentation or to connect the reader to other Splunk materials, such as content from Splunk Blogs, Splunk Answers, or Splunk Education. Before you include any links in your documentation, familiarize yourself with the guidance in Best practices for including links.

Go to the corresponding section for formatting details and examples of the type of link you want to include:

Code repositories

Format links to code repositories as follows. See Links to third-party websites for more information about linking to outside resources.

Type of code repository Include this information in the sentence Example
Splunk-owned repository Hyperlink the name of the Splunk-owned repository and name the site on which it's located. To capture logs from your resources and applications, see the Splunk Distribution of OpenTelemetry Collector on GitHub.


See Environment Variable Config Source in GitHub to copy the configuration YAML file.

Third-party repository Include the name of the repository and spell out the full URL as the hyperlink. Install the fluent-plugin-systemd plugin for systemd journal log collection. See https://github.com/fluent-plugin-systemd/fluent-plugin-systemd/blob/master/README.md on GitHub.

Documentation or parts of a manual

Format links to Splunk documentation or parts of a manual as follows:

Part of Splunk documentation Include this information in the sentence Example
A Splunk product Link to the documentation home page for that product. For information about Splunk Cloud Platform, see the Splunk Cloud Platform documentation.
A manual Link to the first topic of the manual. Use the manual name as the display name for the link. Italicize the manual name. To learn about getting data into Splunk Enterprise, see Getting Data In.
A chapter in a manual Link to the first topic in the chapter. Use the name of the chapter as the display name for the link and include the word "chapter" after the link. To learn about configuring timestamps, see the Configure timestamps chapter.
A topic or subheading in the same manual When linking to a topic or subheading that's in the same manual, use the full topic or subheading name. Don't include the name of the manual. Linking to a topic in the same manual:

Linking to a subheading in the same manual:

A topic or subheading in a different manual When linking to a topic or subheading in a different manual that's in the same product, use the full topic or subheading name. After the link, include the manual name in italics. Linking to a topic in a different manual:

Linking to a subheading in a different manual:

A topic or subheading in a different product manual When linking to a topic or subheading in a manual that's in a different product, use the full topic or subheading name. Include the product name before the manual name.


If the page title or manual name refers to the product name, you don't need to include the product name twice. Italicize the manual name.

Linking to a topic in a different product manual:

Linking to a subheading in a different product manual:

Splunk Developer Portal documentation When linking to Splunk Developer Portal documentation from another documentation site, include the name of the site so that the reader knows they are going to a different site.


When cross-linking within Splunk Developer Portal documentation, don't include the site name unless it's part of the page title.

Linking from Splunk platform docs on docs.splunk.com:

Linking from a Splunk Developer Portal page to another:

Splunk Observability documentation When linking to Splunk Observability documentation from another documentation site, include the name of the site so that the reader knows they are going to a different site.


When linking within Splunk Observability documentation, don't include the site name unless it's part of the page title.

It's okay to clarify whether you're linking to user or developer documentation when you link between the 2 Observability sites.

Linking from Splunk platform docs on docs.splunk.com:

Linking from a Splunk Observability user documentation page to another:

Linking from Splunk Observability developer docs:

Splunk Cloud Platform and Splunk Enterprise manuals from app documentation When the target of a link is different for Splunk Cloud Platform and Splunk Enterprise, display the links for both products in a bulleted list.
A configuration file topic If the name of the topic you're linking to is also a configuration file, don't use monospace formatting in the display text for the link. See limits.conf in the Admin Manual.

Downloads

Format links to these types of downloads as follows:

Type of download Include this information in the sentence Example
Splunkbase download Use the name of the download as the display text for the link. Download the Splunk Add-on for Microsoft Cloud Services from Splunkbase.
Download from the Splunk website Use the name of the Splunk website download as the display text for the link. Download the Splunk Universal Forwarder for your operating system from the Splunk website.


Download Splunk Enterprise from Free Trials and Downloads on the Splunk website.

Download files Use the file name or document name as the display name of the link. Download the tutorialdata.zip file.


Download the Machine Learning Toolkit Quick Reference Guide.

Splexicon entries

Link only to Splunk-specific terms that your audience might be unfamiliar with, and include the link at the first instance of the term you want to define. Bold the Splexicon term. See the following examples:

  • You must configure the receiving port on the peer.
  • The universal forwarder collects data from a data source or another forwarder and sends it to a different forwarder or a deployment.

Splunk Answers

Use the name of the page as the display text for the link. Mention that the link directs to Splunk Answers. See the following example:

See Questions related to All Apps and Add-ons on Splunk Answers.

Splunk Blogs

Use the name of the blog post as the display text for the link. Mention that the link directs to Splunk Blogs. See the following example:

See the Splunk Blogs post Data Sherlock: The Change of Perspective.

Splunk product UIs

You can link directly from Splunk documentation to some Splunk product UIs. Include links to Splunk product UIs only in task steps.

When linking to a Splunk product UI, include the direct link to the page first, followed by the steps a user can take to navigate to the page on their own. Don't replace the navigational steps to a product page with a link to the product page. Give the reader the option to either select the link or navigate on their own.

When creating a link to a page in the UI, use the name of the page as the display text for the link, whether the link is to a guided setup or page, and the name of the product using the following format:

Open the <page name in UI> <guided setup or page> in <product name>.

See the following example:

Open the Amazon Web Services guided setup in Splunk Observability Cloud.

Here is the example in the context of a task step:

  1. Log in to Splunk Observability Cloud.
  2. Open the Amazon Web Services guided setup in Splunk Observability Cloud.
    Optionally, you can manually navigate to the Amazon Web Services guided setup:
    1. On the left navigation menu, select Data Management.
    2. Select Add Integration to open the Integrate Your Data page.
    3. On the Integrate Your Data page, select the tile for Amazon Web Services.

Splunk Support Portal

Link to the Splunk Support Portal pages, which are owned by Splunk Customer Success. See the following examples:

To file a ticket on the Splunk Support Portal, see the Splunk Support Portal.
If you have a support contract, file a case using the Splunk Support Portal. See the Splunk Support Portal.

Splunk videos

Use the name of the video as the display text for the link. Provide a brief description of the video. See the following example:

Watch this Splunk Education video, Creating a Custom Search Command with the Python SDK, to see a high-level view of how custom search commands work, and build an example using the Splunk Python SDK.

Third-party websites

Splunk documentation sometimes links to pages outside of the documentation or a Splunk website. Before linking to a third-party website, determine whether your link is an essential or supplemental link. See Best practices for linking to third-party websites for more information.

Type of third-party link Include this information in the sentence Example
Essential third-party link Spell out the full URL without any capital letters. Include "http://www" or "https://www" and remove the trailing slash at the end of the URL. Install the fluent-plugin-systemd plugin for systemd journal log collection. See https://github.com/fluent-plugin-systemd/fluent-plugin-systemd/blob/master/README.md on GitHub.


Create a Splunk On-Call webhook by following the steps in https://help.victorops.com/knowledge-base/rest-endpoint-integration-guide.

Supplemental third-party link Avoid creating deep links to pages outside of Splunk sites. Consider how you can direct users to information if you think they need assistance finding it, such as giving the reader a search term and a website name. Enclose the search term in quotation marks. Search for "Query tables" on the Microsoft website.


For details, see "Connecting to WMI Remotely Starting with Vista" on the Microsoft website.

Last modified on 23 October, 2023
PREVIOUS
Best practices for including links 		  NEXT
Best practices for linking to third-party websites

This documentation applies to the following versions of Splunk® Style Guide: current

Was this documentation topic helpful?


You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters