Getting Started

Introduction

Each site has two Git repositories that are hosted on Bitbucket (access provided by Constellant), [CLIENT]_slate and [CLIENT]_content. These repositories determine what content is shown on each site. The _content repository has two branches: stage and master. The stage branch contains all of the resources that are shown on the Stage site and the master branch contains the resources for Production. The _slate repository only has one branch, master. dpSlate uses a combination of Markdown, HTML, CSS, and YAML source files to generate HTML pages into the _content repository.

Managing Content

In order to effectively and efficiently create and manage your documentation and pages, you will need knowledge in the following areas:

• Markdown (for dpSlate)
• HTML (for content and dpSlate)
• CSS
• Git repositories (such as GitHub, Bitbucket)

In addition to this knowledge, you will also need a text editor installed on your computer to create and edit the files locally. Any text editor that supports Markdown would suffice. A few examples include:

• Atom
• Notepad++
• Sublime Text
• Visual Studio Code

Markdown

dpSlate uses a version of Markdown, specifically called dpSlate Flavored Markdown or dpFM. This is a version of standard Markdown that has been extended to encompass the needs of technical documentation through the use of YML directives. For more on dpFM, view our dpFM Cheat Sheet.

If you are unfamiliar with standard Markdown, below are some helpful resources to help you get started.

• Markdown
• Markdown Guide
• Markdown Tutorial

Our dpSlate Flavored Markdown (dpFM) allows most HTML tags to be used along with Markdown. This allows for more control over components that aren't otherwise offered in Markdown. The general rule with HTML is that you can use HTML inline with Markdown but you cannot use Markdown inside of an HTML tag.

HTML

Most of the updates that you see on the pages will be completed via the _content repository using HTML. Knowledge of HTML is critical to being able to create and edit content. Some HTML resources include:

• W3Schools.com (Recommended)
• Codecademy
• HTML.com
• Learn-HTML
• Mozilla (MDN)

Git and Bitbucket

The files for dpSlate and content pages are stored in a Git repository on Bitbucket. You will be invited to join a Bitbucket repository as part of the initial site standup.

To get started, you will need to use git commands to clone your dpSlate or content Git repository to locally. Once you accomplish that, you will be able to begin editing with your text editor of choice. To learn more about Git and how it works, the following resources are helpful:

• Git
• Bitbucket Cloud
• Atlassian Tutorials

If you are not comfortable with using command line, you can also download a Git GUI such as SourceTree or any other Git clients to help facilitate the necessary operations.

Getting Set Up

Clone a Git repository

You can use command line using the terminal, a version control UI like SourceTree, or any other client you'd like to clone your Git repository.

Get your clone command

1. Log into Bitbucket
2. Navigate to your repository. It will have your company's name, followed by _slate or _content.
3. Once your repository, click Clone from the top menu

4. You will be provided with the git command to clone your repository. It will look something like this:

   git clone https://<USERNAME>@bitbucket.org/dp_content/<CLIENT>_slate.git

   OR

   git clone https://<USERNAME>@bitbucket.org/dp_content/<CLIENT>_content.git

5. Copy your clone command

Clone your repository (via the terminal)

1. From a terminal window or Git client, change the local directory of where you would like to clone your repository.

   $ cd [path_to_directory]
   

2. Paste or type in the clone command that you copied from Bitbucket into your command line. For example:

   $ git clone https://@bitbucket.org/dp_content/_content.git
   

3. If the clone was successful, a new subdirectory will appear on your local drive with the same name as the repository that you cloned. The files located within this subdirectory is where you will create and edit your documentation.

Creating and Editing Files

Once you have cloned your repository to your local drive, you can create or edit the files located in that directory by using any text editor. 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

1. Conduct a git pull to pull in any changes from the remote repository that have occurred since your last pull
2. Navigate to the location of your repository on your local drive

3. To Create: Create a folder or file under the /site/ directory using your file manager, text editor, or Git client.

   To Edit: Open the file that you would like to edit using your file manager, text editor, or Git client.

4. Once you have made an update, save your file locally and then commit and push your local changes to the remote stage 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 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 or stage]
   // This will push the local commit to specified remote repository
   

Restricting Content

You can restrict entire pages and menu items via Channel Manager or via content security tags.

Download Channel Manager User Guide

You can also restrict content within a page by adding security tags around the content. See Security Tags for more information.

dpSlate Documentation

View our dpSlate User Guide to learn more about using dpSlate.

dpSlate User Guide