dpSlate User Guide

Overview

dpSlate is a static web site generation tool that is designed to work with dpEngine. It is used to generate static web pages from source that is held in its own git repository. Static site generation has performance advantages over dynamic content and since most technical documentation does not change from user to user, static pages load faster and are more responsive.

dpSlate has extensive formatting controls to allow the technical writer to create a wider selection of documents from various sources including:

Overviews
Getting Started Guides
Tutorials
Technical Reference Manuals
API Reference Manuals

How dpSlate Works

dpSlate uses a combination of Markdown, HTML, CSS, and YAML source files to generate HTML pages. These files are stored in a Git repository (located in Bitbucket - access provided by Constellant) and processed from the source into an HTML page that is hosted on the site. Processing the source will include building a static Table of Contents (ToC), a menu bar, and the column layout of the document. Many of these options are easily configurable by the Document Directives located in the corresponding YAML file(s) (_defaults.yml) and/or on the Markdown page header.

Creating and Editing Files

Once you have cloned your repository to your local drive (see Getting Set Up), you can create or edit the files located in that directory by using any text editor that supports Markdown. You can also make updates to the remote branch of the repository on Bitbucket without needing to use Git commands but these changes will not appear in your local until you conduct a git pull.

Creating or Editing a Folder or File

Conduct a git pull to pull in any changes from the remote repository that have occurred since your last pull
Navigate to the location of your repository on your local drive
To Create: Create a folder or file under the /site/docs/ directory using your file manager, text editor, or Git client.
- Markdown document pages must end in .md. It is a best practice within dpEngine to name your pages index.md.
- YAML files that contain Document Directives must be named _defaults.yml and located in or above the folder in which the document is located. More on Document Directives below.
To Edit: Open the file that you would like to edit using your file manager, text editor, or Git client.

Once you have made an update, save your file locally and then commit and push your local changes to the master branch of the Git repo using your terminal or Git client.

NOTE: There are many ways to push content in Git. Please use the one that you are most comfortable with. For more information on Git commands, see Git. An example of a series of commit and push commands is provided below.

$ git commit -m ''
// This will commit any updates to your local repo and add a comment to the commit. Your commit message can be added between the single quotes and should describe the updates that you made to the file.

$ git pull --rebase
// This will pull in any changes to the remote repository (master branch) into your local and then apply your updates on top of them. This is a best practice when there are several Users working within the same repository and will prevent merge conflicts.

$ git push origin master
// This will push the local commit to remote repository

Document Directives

Document directives are used to configure several aspects of your document and control how it is built when it is converted into HTML. Document directives consist of the YAML directive, followed by a :, and a variable. There are four types of YAML variables:

Boolean - Boolean 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, regardless of case; while the values for false are similar and can be represented by F, FALSE, N, NO, or OFF, regardless.
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.

Directives can be located:

As part of your .md page header as a section that is enclosed with three dashes ---.

---
title: "API Documentation"
tableOfContents: ON
tocAccordion: 1
tocSelectors: "h2,h3"
---

As a seperate _defaults.yml file within your directory or subdirectories

\source
    _defaults.yml - this file contains your site defaults for YAML directives. DO NOT EDIT.
     \global
         \docs
           _defaults.yml - this file contains default YAML directives the adjacent markdown file and everything below it

A combination of both options.

Out-of-the-box, your Slate repository will come with two predefined _defaults.yml files: one located in the root directory and another located inside of the /site/global/docs subdirectory. Please do not edit the root /_defaults.yml file.

You can add _defaults.yml file(s) within each subdirectory or you can keep it in one to help drive consistency in layout and function across your documentation. The directives closest to where the page is located will supersede higher level directives. For example, if there are directives defined both on the page and within a _defaults.yml in the same directory, the directives located on the page's header will take precedent over the /site/global/docs/_defaults.yml.

TIP: To ensure consistency between your documentation pages, it is a best practice to define as many directives as you can in the /site/global/docs/_defaults.yml file. By doing this, the directives will be inherited by every document below it. Going forward, the only directives that you will need to define would be page specific ones (such as title) and any other options you'd like to make to a specific page (such as tocSelectors).

Types of Document Directives

The YAML document directives include directives for:

Document Panel Control
Menu Bar
Left Panel
Language Tab Control
Content Control

Document Panel Control

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 toggle the left hand panel on/off. When turned on, the left hand panel will contain the menu bar and a Table of Contents (ToC). If the leftPanel is turned off, then the items will not be displayed. When the leftPanel is turned off, the rightPanel will also be turned off at the same time and the rightPanel directive will be ignored.
rightPanel: is a boolean directive that is used to toggle the right hand panel on/off. 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.

This version of dpEngine is not configured for the rightPanel view.

The Center Panel is always on and cannot be turned on or off.

leftPanel: ON
rightPanel: OFF

Menu Bar

dpSlate has a configurable menu bar on the left panel, located above the Table of Contents (ToC). This menu bar contains icon buttons that can be configured using directives. If the leftPanel is turned off, the Menu Bar will not appear.

The directives and icon buttons that make up the Menu Bar include:

titlePage is a boolean directive. If you've enabled the titlePage directive, an info button () will appear in the Menu Bar. When clicked, it will open a modal that will display a title page with information about your document. See Title Page Control for more on configuring the title page with directives.
```
titlePage: ON
```
documentSearch is a boolean directive. If you've enabled documentSearch, a search button () will appear in the Menu Bar. When clicked, it will toggle replace the Table of Contents (ToC) with a search text box that can be used to search with the current document. If any hits are found, then you can use the <<prev and next>> buttons to locate each occurrence of the searched text. To toggle back to the Table of Contents (ToC), click on the list button ().
```
documentSearch: ON
```
siteLinks is a list directive that uses title (string), link (string), and newTab (boolean) options to create a list of links. If you've created a siteLinks list, a link button () will appear in the Menu Bar. When clicked, it will open a modal with the list of links. If siteLinks are not configured, the link button will not appear. The newTab directive is used to determine if the link is opened in a new tab.
```
siteLinks:
  - title: "Google"
    link: "https://google.com"
    newTab: true
  - title: "Documentation"
    link: "/site/global/docs/"
    newTab: false
```
versionLinks is a list directive that like siteLinks, uses title (string), link (string), and newTab (boolean) options to create a list of links. If you've created a versionLinks list, a versions button () will appear in the Menu Bar. When clicked, it will open a modal with the list of version links. The newTab directive is used to determine if the link is opened in a new tab. If versionLinks are not configured, the link button will not appear.
```
    versionLinks:
     - title: "Version 1"
       link: "/site/global/docs/v1"
       newtab: false
     - title: "Version 2"
       link: "/site/global/docs/v2"
       newtab: false
```

Title Page Control

There are a number of directives that are used to display information within the title page of the document. The title page is displayed as a modal whenever the reader presses the button in the Menu Bar. The title page will display information about the document from the following variables:

titlePage is a boolean that when set to true will turn on the title page button within the Menu Bar.
title is a text string that contains the name of the document. It is used for both the title page and the <title> tag in the header of the HTML page.
version is a text string used to display the current version of the document.
copyright is a text string that contains the copyright statement for the document. Copyright statements should contain the word "Copyright", followed by the copyright symbol of ©, followed by the years that the work was first created and the year that it was last modified, and finished off with the phrase "All Rights Reserved."
publisher is a text string that contains the name of the document publisher.
publisherAddress is a text string that contains the address of the publisher.
comments is a free text string that allows the author to put in information about the document that will help the reader understand the context.

titlePage: ON
title: "API Documentation"
version: "v1"
copyright: "Copyright © 2013-2020. All Rights Reserved."
publisher: "Constellant"
publisherAddress: "11044 Research Blvd A525, Austin, TX 78759, USA"
comments: "The purpose of this document is to provide information regarding the Constellant API."

Left Panel

The left panel is used to house the page's Table of Contents (ToC), as well as the option to create a list of related documents and/or links, known as document collections. When Document Collections are configured, you see will each document or link within the left navigation, along with the current document's table of contents.

Table of Contents Control

dpSlate uses directives for controlling how the Table of Contents (ToC) in the left navigation is generated.

tocSelectors is a string of header elements that will be used to generate the document's table of contents. The list of header tags (h1,h2,h3) must be sequential. For example, you cannot define this value as "h1,h3" but can use "h2,h3".

Common patterns include: * "h1,h2,h3" - Allowing the natural progression of headers to create the ToC. * "h2,h3" - Allows you to keep <h1> outside of the taxonomy so that it can be used as a page header.

yaml tocSelectors: "h1,h2,h3"

tocAccordion is an integer value that is used to control the collapsing of items within the table of contents. This value is set based on how many heading levels should be open by default. For example, if you have tocSelectors set to three levels ("h1,h2,h3"), a setting of 3 will show everything in the table of contents when you arrive on the page since there are three heading levels. If you define the tocAccordion to 0, all of the levels will be initially collapsed and each will open when you scroll into those headings and will close again as you scroll out of them. yaml tocAccordion: 2

Document Collections

A documentCollection is a collection of related documents defined by a list of directives. Document Collections are used to group related documents or links together and present them on the left panel. Each list entry in the documentCollection will have its title appear within the left panel. The Table of Contents (ToC) of the current document will display as part of the document collection that it lives under. When you click on another document in the collection, that document will be opened and its Table of Contents (ToC) will be displayed in the left panel.

The documentCollection directive is made up of the following list directive items:

title is a string that contains the title of the document in the collection as it will be displayed in the left panel.
link is a string with the link to the document that will be opened when the title in the table of contents is clicked on by the User. The link should be the relative path to the document starting with /site/global/docs/. The end of the path should end with either the file name (without a file extension) or a / (the file name will default to index). For example, "/site/global/docs/mydoc" would not be valid since it does not end with a file name or a /. You can also place external links as the link value. If all of your links are located in the same directory, you can also use the baseUrl directive to shorten this path. See Document Collection Options for more.

  documentCollection:
    - title: "API Documentation"
      link: "/site/global/docs/apis/doc1/"
    - title: "API Documentation 2"
      link: "/site/global/docs/apis/doc2/"
    - title: "Constellant"
      link: "https://constellant.com"

TIP: You will typically want to share the documentCollection directive between all of the documents that make up the collection. As such, you may want to place these directives in the /site/global/docs/_defaults.yml file or a _defaults.yml file located in the subdirectory so that it can be shared by all of the documents located under it.

Multiple Document Collections

You can have several document collections nested within a document collection. To accomplish this, you must add a title and collection directive, followed by the nested document collection list. The collection is an indicator that there is an additional document collection that is nested under the defined documentCollection.

  documentCollection:
    - title: "Collection 1"
      collection:
        - title: "API Documentation"
          link: "/site/global/docs/apis/doc1/"
        - title: "API Documentation 2"
          link: "/site/global/docs/apis/doc2/"
    - title: "Collection 2"
      collection:
        - title: "SDK Documentation"
          link: "/site/global/docs/sdk/doc1/"
        - title: "SDK Documentation 2"
          link: "/site/global/docs/sdk/doc2/"

Document Collection Options

There are two additional optional directives for Document Collections:

tabs is a boolean that controls if tabs are created for multiple (nested) document collections. If enabled, the tabs will be displayed on the left panel, below the Menu Bar and above the Table of Contents (ToC). Each nested document collection will be presented as an individual tab. The title will be used as the tab name, with the collection underneath it appearing as the tabs' content.
```
documentCollectionOptions:
  tabs: ON
```
NOTE: If you use tabs, you must define a unique link directive for each title, formatted as an anchor tag. This can be any value, as long as it has safe characters for URLs (i.e. underscores, dashes are allowed; periods or spaces are not allowed).
```
documentCollection:
  - title: "Collection 1"
    link: "#Collection-1"
    collection:
      - title: "API Documentation"
        link: "/site/global/docs/apis/doc1/"
      - title: "API Documentation 2"
        link: "/site/global/docs/apis/doc2/"
  - title: "Collection 2"
    link: "#Collection-2"
    collection:
      - title: "SDK Documentation"
        link: "/site/global/docs/sdk/doc1/"
      - title: "SDK Documentation 2"
        link: "/site/global/docs/sdk/doc2/"
```
baseUrl is a string that denotes a base URL that will be added to the front of any relative links for your collection. This allows you to easily manage your document collections that exist in the same subdirectory. If you enable the baseUrl, you do not need a / to precede the link in the documentCollection.
```
documentCollectionOptions:
  baseUrl: "/site/global/docs/apis"

documentCollection:
      - title: "API Documentation"
        link: "doc1/"
      - title: "API Documentation 2"
        link: "doc2/"
```

Language Tab Control

The languageTab directive is used to create programming language tabs. These tabs will appear above the center content and allow the User to toggle between which code blocks they would like to see, assuming these are defined on the page.

The languageTab directive is a list that comprises of two parts: 1) the name of the language and 2) the display name for the language to use on the tab, separated by a :.

  languageTab:
    - yaml: YAML
    - html: HTML
    - markdown: Markdown

When you create a code block, you can specify more than one language. For example, you can specify ruby,python (without space breaks). This tells the processor that the sample code should be placed in both the ruby and the python tabs.

Only list the languages that you would like to have as tabs in your document. For each language that you list as a languageTab, dpSlate will automatically create the language tab regardless of if that language is used in the document. In order for each tab to work correctly, you must define the language on each code block (see dpFM Cheat Sheet) with your Markdown.

The name of the language must be recognized by the system in order to display the proper syntax highlighting on the code block. dpSlate supports many different languages, but the commonly used ones are:

c++: C++
c#: C#
css: CSS
html: HTML
json: JSON
java: Java
javascript: JavaScript
markdown: dpFM
objective-c: Objective-C
perl: Perl
php: PHP
puppet: Puppet
python: Python
ruby: Ruby
shell: Shell
xml: XML
yaml: YAML

Content Control

There are two directives for Content Control:

laTexMath is a boolean directive to turn on support for a powerful language for expressing mathematical expressions that will be rendered in typeset quality inside of your dpSlate document. When this is set to true, then your LaTeX math will be rendered.
```
laTexMath: ON
```
codeHighlight is a boolean directive that controls if you want to turn on the highlighting of sample code. When turned on, the system will highlight the syntax of the sample code using color according to the theme defined on the code block (see dpFM Cheat Sheet) with your Markdown.

You can control the theme that is applied in code highlighting using the codeHighlightTheme directive, which is a string. If you do not specify a codeHighlightTheme, then "agate" will be used as the default theme.

yaml codeHighlight: ON codeHighlightTheme: "agate"

You can view the themes at highlightjs.org. The list of valid themes is:

agate
androidstudio
arduino-light
arta
ascetic
atelier-cave-dark
atelier-cave-light
atelier-dune-dark
atelier-dune-light
atelier-estuary-dark
atelier-estuary-light
atelier-forest-dark
atelier-forest-light
atelier-heath-dark
atelier-heath-light
atelier-lakeside-dark
atelier-lakeside-light
atelier-plateau-dark
atelier-plateau-light
atelier-savanna-dark
atelier-savanna-light
atelier-seaside-dark
atelier-seaside-light
atelier-sulphurpool-dark
atelier-sulphurpool-light
atom-one-dark
atom-one-light
brown-paper
codepen-embed
color-brewer
darcula
dark
darkula
default
docco
dracula
far
foundation
github-gist
github
googlecode
grayscale
gruvbox-dark
gruvbox-light
hopscotch
hybrid
idea
ir-black
kimbie.dark
kimbie.light
magula
mono-blue
monokai-sublime
monokai
obsidian
ocean
paraiso-dark
paraiso-light
pojoaque
purebasic
qtcreator_dark
qtcreator_light
railscasts
rainbow
routeros
school-book
solarized-dark
solarized-light
sunburst
tomorrow-night-blue
tomorrow-night-bright
tomorrow-night-eighties
tomorrow-night
tomorrow
vs
vs2015
xcode
xt256
zenburn

Documentation

API

Community

dpSlate User Guide

Overview

How dpSlate Works

Creating and Editing Files

Creating or Editing a Folder or File

Document Directives

Types of Document Directives

Document Panel Control

Menu Bar

Title Page Control

Left Panel

Table of Contents Control

Document Collections

Multiple Document Collections

Document Collection Options

Language Tab Control

Content Control