Ponydocs

Build content in Ponydocs

Download manual as PDF

Download topic as PDF

Create a table of contents

Once you've created a product, a version for the product, and a manual for that product, you can create and build a table of contents (TOC). The TOC file for a manual defines what topics belong to that manual.

To create a TOC for a new manual (one that doesn't exist yet in a given version), navigate to the Manual management page. To access the Manuals management page, use the following URL, substituting the server name for your own Ponydocs server in place of <yourponydocsserver>:

http://<yourponydocsserver>/Documentation:<product short name>:Manuals

This page displays a list of all the currently-defined manuals available for this product:

  • If a manual has a TOC in the version you're currently in, you'll see that manual's name as a link.
  • Any manuals that don't have a TOC in the version you're currently in will have a link beneath the manual name that says "Click manual to create TOC for current version".

Make sure that you have selected the version for which you want to create the TOC from the drop-down menu, and then click on the manual link from the Manuals management page. This creates an empty TOC definition page for the version you have selected from the drop-down.

This TOC will include the tag(s) the version(s) that this TOC applies to, they look like this:

[[Category:V:<short product name>:<version>]]

Don't edit these version tags by hand unless you know what you're doing. Keep the version tags at the bottom of the page and add your topics above them.

What's in a TOC?

TOC files contain three things (besides version tags): a manual description, chapter names, and topic names:

  • Manual description: This is the text that is shown with the manual title on the product's landing page.
  • Chapter name: This is an arbitrary text string. The chapter name is shown in the left-hand navigation between the groups of topics in each chapter. Chapter names can contain any ASCII character, since they are not included in any URL. You must have at least one chapter name in a TOC
  • Topic name: This is the string that will appear in the URL path for that topic (in addition to the product short name, manual short name, and version). Because the topic name is used in the URL, it can only contain alphanumeric characters, and any spaces you include will be removed when the topic is created. The topic name is what is used as the initial title and H1 of the topic (and is displayed in the left-hand navigation when you view the topic), but once the topic is created, you can edit the H1 and change it. At that point, you can use any characters you want in the H1, and your changes will be reflected in the left-hand navigation.

Things to know when creating and editing a TOC

  • Put the manual description at the top of the file.
  • Add chapter name as free text, they can contain any ASCII characters you like.
  • You must have at least one chapter name for the manual to display.
  • Add topic names under their respective chapter names.
  • Topic names can only contain alphanumeric characters, and spaces are removed when the TOC is saved and the file is created. You can't use question marks, colons, hash signs, or slashes in filenames, but you can add them back in in the H1 within the topic if needed
  • The same topic cannot appear more than once in a single TOC page.
  • Remember to use * in front of each topic you add--this is different from the versions and manuals list pages, and from the manual description.
  • Topics you add to the TOC file are created when you save the TOC file. Ponydocs will automatically create them and tag them with the correct version(s).

Syntax

The syntax for adding the manual description is:

{{#manualDescription:Manual Description}}

where "Manual Description" is the string of text you want displayed.

Note: You must add this to each version of the TOC for a given manual.

The syntax for topic names is:

* {{#topic:TopicName}}

As an example, the TOC for the Sparkly Unicorn Data User Manual might look like this:

{{#manualDescription:This manual introduces Sparkly Unicorn Data, a sparkle-based version of ponies. It explains what you need to do to get started, add ponies, hug, and share unicorns.}}

Introduction
* {{#topic:About Sparkly Unicorn Data}}
* {{#topic:Sparkly Unicorn Data FAQ}}
* {{#topic:Learn more and get help}}

Splunk concepts and how-tos
* {{#topic:Inputs and projects}}
* {{#topic:Sources and source types}}
* {{#topic:What Sparkly Unicorn Data does with your data}}

Before you start 
* {{#topic:About ponies}}
* {{#topic:Ways to get data into Sparkly Unicorn Data}}
* {{#topic:Sparkly Unicorn Data performance and sizing}}
* {{#topic:Information to have ready before you start}}

Get started
* {{#topic:Create and activate an account}}

Add data
* {{#topic:Add ponies over TCP or UDP}}
* {{#topic:Upload a unicorn}}
* {{#topic:Add ponies using the REST API}}
* {{#topic:Add ponies from a Webhook}}
* {{#topic:Pick a mane type}}
* {{#topic:Set the colors and sparkles}}

Manage, and share a unicorn
* {{#topic:Share your unicorn}}
* {{#topic:Troubleshoot a unicorn}}
* {{#topic:Delete ponies from a unicorn}}
PREVIOUS
Create a manual
  NEXT
Create and edit a topic

This documentation applies to the following versions of Ponydocs: 1.0


Comments

can content be shared between two manuals and how?

Aepshteyn
August 30, 2013

Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

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