dpSlate is an authoring tool that helps authors effectively communicate to an audience. Originally designed specifically to author API reference manuals, it has been expanded to create a wider selection of documents. As a result of enhancements to dpSlate, it can now be used to create many different types of documents including:
Overviews
Getting Started Guides
Tutorials
Technical Reference Manuals
Sample Apps
To accommodate the need to deal with different types of documents, dpSlate allows the document author to control the structure of how the document will be formatted. Each dpSlate document can have up to three different panels that the author can turn on or off as required:
Left Hand Panel - used for document meta-data such as a title page, document search, and table of contents.
Center Panel - used for the contents of the document.
Right Hand Panel - used for code samples and other technical reference materials.
Document with Left and Right Panel Turned On
dpSlate Document with all three panels on
When all three panels are turned on, the dpSlate document will look as shown. The three panels are for the document meta-data (left), body of the document, and supporting materials to the right.
Document with Right Panel Turned Off
dpSlate Document with two panels on
When the right panel is turned off, the supporting materials that were in the right hand panel are not brought into the center panel at the appropriate place. The left hand panel is not impacted.
Document with the Left Panel Turned Off
dpSlate Document with one panel on
.
When the left hand panel is turned off, the document becomes a single column document with the meta-data at the top and the body of the document below.
Getting Started with dpSlate
If you have a portal that is powered by dpEngine, dpSlate works automatically with dpEngine.
When you use dpEngine, your web portal content is stored in a version of a Git Repository called Bitbucket. Now with dpSlate an additional repository will be available to your team for your markdown files. You will be provided with access to Bitbucket for your portal's repositories. Your repositories will contain a number of folders that in turn contain the documents that will be published to your portal.
When you create a markdown file in your dpSlate repository under the site directory, the markdown will automatically be converted into dpSlate GSP and moved to the same location in your content respository.
The images that you wish to include into your dpSlate markdown document will be stored in the \static\images directory of the dpSlate repository. Once they are here, they will be automatically managed by dpSlate and dpEngine. We recommend that you also use the additional directory structures to help you better manage your images and files.
Editing a dpSlate/dpEngine Document
There are two ways to edit the Markdown for a dpSlate document hosted in dpEngine; you can either edit it locally using Git or you can edit it inside Bitbucket using a web browser.
When you edit the document locally, you will need to find the document markdown source in the \site folder tree in your local dpSlate Git repository. After you are done with the edit, you will commit and push the document to your dpSlate branch. After you have commited an automated process will build your markdown files in order to generate the gsp files, these generated files will be automatically commited to the stage branch of your dpEngine repository. You can use any of hundreds of different markdown editors to edit your dpSlate source documents.
The second method is to view the document using your browser. If you are an authorized Author or Editor for the document, you will see the following buttons on the document:
Edit - allows you to change the document. When you press the edit button, you will be redirected to the Bitbucket page in your browser with the corresponding page open. You simply change your markdown file and when you save it, your document will be converted and your browser will display the recently edited document.
Publish - allows you to publish your new document to your production environment. The Publish button is only available to those with the Editor role.
How dpSlate Works
dpSlate generates GSP documents from the Github Flavored Markdown (GFM) in a particular format that dpEngine wants. dpSlate software is written in Ruby and takes advantage of some popular Ruby software including Middleman, RedCarpet, and Rouge. The dpSlate software reads a .md (markdown) source-file and will output a .gsp file along with the accompanying Javascript and CSS files.
To get a consistent look and feel to your web documentation, you will want your authors to use the GFM tags in a particular to we get a common and look and feel.
Structure of a dpSlate Document
As you look at this document, you will notice that there are a couple of feature. First, to the left is the Table of Contents area. Next, in the center is the Body of the document, and to the Right (in the dark area) are code examples. Each of these elements have the following characteristics:
Table of Contents
The TOC panel on the left hand side of the panel is composed of the following elements starting at the top and moving to the bottom:
Title Page - At the very top, is the title of the document. If you've enabled the Title Page function, then an about link will be created and when clicked it will open up a title page and provide more information about the document.
Search Box - If search is enabled, a Search Box will appear above the Table of Contents. The Search Box is used to search the document looking for phrases of interest. The phrases are then highlighted in the Table of Contents.
The Table of Contents - The Table of Contents are automatically built if the feature has been turned on. By default, on the H1 is normally displayed. If a user selects a H1 item, the TOC will expand to display the H2 items underneath it. If the user selects a H2 item, the TOC will expand to display the H3 items underneath it. Directives are used to control the table of contents.
The TOC Footer - you can use this to store information at the bottom of the table of contents.
Document Body
The body of the document is found in the center panel and contains the main textual description of the API. It uses a number of different elements and features to communicate what the API actually does and these include:
Headers - these are titles of document section of which the H1 and H2 will automatically appear in the TOC
Paragraphs - these are simple paragraphs of text
Bold Text
Italicized Text
Inline Code Text
Tables
Bullet Lists
Number Lists
Hints - These are Green Highlighted Text
Warnings - These are Red Highlighted Text
Notes - These are Blue Highlighted Text
Links - HTML hyperlinks to external documents
Code Samples
The key part of the dpSlate format for API documentation is that code samples can be viewed alongside of the API call that they illustrate. Further sample code can be held simultaneously in several different programming languages (important for SOAP and REST API's). Because programmers tend to only work in a single language at a time, the dpSlate format accommodates this by having the programming language as a tab on the far right panel. Thus, the developer is able to choose a programming language and then use the documentation in that language without being distracted by any other language.
Sample code is anchored to either the H1 or H2 heading that they are inserted under; that is, they are placed under the Heading and will move up or down with the main text body. Code samples have the following elements that are used to control their placement:
Language - there is a tab for each language that is supported and specified in the header.
Code Annotations - these are highlighted areas that are not code but used to point out a code section.
Shared Code Samples - it is possible to make code that appears in all of the tabs.
A GitHub Flavored Markdown (GFM) source document is used to generate each of the dpSlate Documents that are presented on the portal. Each dpSlate GFM source document is a plain text document that starts with a Yet Another Markup Language (YAML) header that contains directives used to control how the document will be formatted. The YAML header starts and ends with a line that has three dashes, ---, that start in the first column of the line.
The YAML header contains directives that control how the document will look and appear when it is converted to a GSP. The directives consist of a YAML variable name, the directive, followed by a :. There are four types of YAML variables:
Boolean - booleans variables are used to turn things on or off using various keywords to represent true or false. YAML is flexible and the values for true and false are anything that kinda looks like a true or false. For example true can be represented by T, TRUE, Y, Yes, or ON independent of case while the values for false are similar and can be represented by F, FALSE, N, NO, or OFF regardless of case.
String - a string is either a string of text or quoted text. Text can be quoted either by a double, ", or single, ', quotation mark. Boolean keywords that are not in quotes might be interpreted as a boolean directive.
List - a list is a collection of items. The items in the list are strings that are also know as a “hash” or a “dictionary”. Directives that are lists consist of the directive followed by a number of lines that are indented and start with a dash, -, followed by a space.
Integer - a numerical value.
The valid dpSlate YAML document directives include:
Document Panels
A dpSlate document is made up of up to three panels which are turned on or off with the following directives:
leftPanel: is a boolean directive that is used to turn on the left hand panel. When turned on, the left hand panel will contain the title page, the document search box, the table of contents, and the ToC footer if each of them are turned on. If the leftPanel is turned off, then the items that should be included in the leftPanel are placed at the top of the center panel.
rightPanel: is a boolean directive that is used to turn on the right hand panel. When turned on, the right hand panel contains tabs for each programming language that has sample code associated with it. When the right hand panel is turned off, the code samples are inserted in-line in the center panel.
The Center Panel is always on and cannot be turned on or off.
Title Page
There are a number of variables that are used for display in the title page of the document. The Title Page is displayed at the very top of the document is the text "About this Document" which is a link. When the link is selected, the Title Page will open up and display information about the document from the variables in the header including:
titlePage: is a boolean that when set to true will turn on the Title Page feature.
title: text string that contains the name of the document. It is used for both in the Title Page and the <title> tag in the header of the resulting GSP page.
version: a text string used to display the current version of the document in both the Title Page and the TOC Footer (if both are turned on).
publisher: a text string that contains the name of the document publisher.
publisherAddress: a text string that contains the address of the publisher.
comments: a free text string that allows the author to put in information about the document that will help the reader understand the context.
In addition to these values that are set for the Title Page, the date that the document was "built" is displayed at the bottom of the "Title Page" as the "Published Date".
Turning on Language Tabs
The languageTab directive is used to create the programming language tabs that make up the right hand panel of a dpSlate document. The languageTab directive is a list and thus the languageTab statement is followed by one or more lines containing a statement that contains two blank spaces, a dash, the name of the language for use in encoding the document, an option ":", followed by an optional display name for the language.
The name of the language must be recognized by the system such that the display engine will automatically perform syntax highlighting on the code. The engine supports lots of different languages but the most common values used are:
c++:C++
c#:C#
css:CSS
html:HTML
json:JSON
java:Java
javascript:JavaScript
markdown:GFM
objective-c:Objective-C
perl:Perl
php: PHP
puppet:Puppet
python:Python
ruby:Ruby
shell
xml:XML
yaml:YAML
The Left Hand Panel
When turned on, the far left panel of a dpSlate document contains the title page, the document search box, and the Table of Contents. The title page is generated from the directives already discussed, the ToC is automatically generated from the Headers found in your GFM source document but it is controlled by the values you set for directives in the headers of your documents.
ToC Directives
There are a number of directives for controlling how the Table of Contents is presented. These are:
documentSearch: a boolean used to turn the document search feature on and off.
tocSelectors: this string is a comma list of the document elements that will be selected for inclusion into the table of contents. If the statement is missing, then the default value is "h1, h2, h3" which means that Headers 1, 2, and 3 will be included into the Table of Contents. If you were to choose "h2, h3, h4, h5" then the first level headers would be ignored and only the second, third, fourth, and fifth levels will be selected for inclusion into the Table of Contents.
tocAccordion: this is an integer value that is used to controlling the hiding (collapsing) of items in the table of contents. The value is set to how many heading levels should open by default (i.e., not be collpased). For example, number 6 will show everything in the Table of Contents since there are only 6 heading levels while the number 0 will hide all of the Table of Content entries until it is time for them to open. The entries in the Table of Contents that are initially hidden will open when you scroll into those headings and will then close again as you scroll out of them.
Default Directives
The YAML directives can be set at a site wide level for all of your documents. Thus, you can avoid typing in the same text for each of the directives for each document. This feature also allows you to set your site defaults for directives and then change them for all documents quickly. You do this by modifying the file at \source\_defaults.yml. This file contains all of the directives that you will see in your document and you can set them globally for your site. If you later define a directive in a specific document, the document value will overide the default value that you set.
Creating the Body of a dpSlate Document
Creating Headers
Headers are created by using one or more # characters starting in the first line of text within the GFM document. The sample to the right shows GFM that will result in a level 1, level 2, and level 3 headers. Only the level 1 and level 2 headers will appear in the Table of Contents. When you create sample code, it will anchor to a header.
On the right are a list of headers in markdown and below is how they will appear in the document:
For normal text, just type your paragraph on a single line.
This is some paragraph text. Exciting, no?
Make sure the lines above below your paragraph are empty.
Creating Formatted Text
Formatting Text in GFM
This text is **bold**, this is *italic*, and this is an
`
Inline code block in the main section.
`
You can also use underscores to create __bold__ or _italic_.
Finally, you can combine ***bold and italic***.
This text is bold, this is italic, and this is an
Inline code block in the main section.
You can also use underscores to create bold or italic.
Finally, you can combine bold and italic.
Strikethrough
Strikethrough allows you to show text that is ~~no longer relevant by using strikethrough~~
You can format text with a strikethrough by enclosing the text in double tildes, ~~. The example to the right becomes:
Strikethrough allows you to show text that is no longer relevant by using strikethrough
Creating Markdown Links
The Three Ways to Create GFM Links
Here's an inline link to [Google](http://www.google.com/).
Here's a reference-style link to [Google][1].
Here's a very readable link to [Yahoo!][yahoo].
[1]: http://www.google.com/
[yahoo]: http://www.yahoo.com/
There are three ways to write links in GFM. Each is easier to read than the last. The code to the right will generate the following:
Here's an inline link to Google.
Here's a reference-style link to Google.
Here's a very readable link to Yahoo!.
The link definitions can appear anywhere in the document -- before or after the place where you use them. The link definition names 1 and yahoo can be any unique string, and are case-insensitive; yahoo is the same as YAHOO.
The Markdown to the right shows how an image can be inserted, in this case, it is the DP Logo that is right above this. The text inside the square brackets, [DP Logo] will become the alt text for the image in the HTML alt= parameter.
Inserting Horizontal Rules
Sometimes you just need a Horizontal Rule (line) to convey something. GFM does this with either three or more consecutive Hyphens -, Asterisks *, or Underscores _.
Three or more...
---
Hyphens
***
Asterisks
___
Underscores
Three or more...
Hyphens
Asterisks
Underscores
Using HTML in Markdown
Definition list
Is something people use sometimes.
Markdown in HTML
Does *not* work **very** well. Use HTML tags.
You can also use raw HTML in your Markdown, and it'll mostly work pretty well.
Definition list
Is something people use sometimes.
Markdown in HTML
Does *not* work **very** well. Use HTML tags.
Creating a Table
GFM for Creating a Table
Table Header 1 | Table Header 2 | Table Header 3
-------------- | -------------: | :------------:
Row 1 col 1 | Row 1 col 2 | Row 1 col 3
Row 2 col 1 | Row 2 col 2 | Row 2 col 3
Slate uses PHP Markdown Extra style tables. The example to the right will create the table below.
Table Header 1
Table Header 2
Table Header 3
Row 1 col 1
Row 1 col 2
Row 1 col 3
Row 2 col 1
Row 2 col 2
Row 2 col 3
Notice the colons in the line underneath the header line. These are used align that columns of the table. A no colon or only a colon to the left will cause the column to align to the left. A colon to the right will cause the column to align right. And a colon to the left and the right will cause the column to center.
Perigee Capital LLC., 2300 Greenhill Drive, Suite 400, Round Rock, TX 78664, USA
dpSlate is Licensed under the Apache License, Version 2.0 (the License); you may not use this file except in compliance with the License. You may obtain a copy of the License on the site http://www.apache.org at /licenses/LICENSE-2.0. Unless required by applicable law or agreed to in writing, the dpSlate software distributed under the License is distributed on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. The Perigee Capital, DevelopProgram.com, DP.com, dpSlate, and the dp.com Logo are trademarks of Perigee Capital, LLC.
.
.