Skip to content

Instantly share code, notes, and snippets.

@greglindahl

greglindahl/devportal-training.md

Last active November 22, 2016 19:52
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save greglindahl/50e22e845e086b7d19d347ad0f0a9fa2 to your computer and use it in GitHub Desktop.
Save greglindahl/50e22e845e086b7d19d347ad0f0a9fa2 to your computer and use it in GitHub Desktop.
Download ZIP
Devportal Lunch and Learn Objectives and Exercises
Raw
devportal-training.md

Devportal Introduction

Purpose

Gain a basic understanding of the devportal. What powers it and how it works.

Objectives

  • learn how to clone the devportal repo, install, and run locally
  • understand the basic site structure (where does everything live?)
  • create a sample page
  • conventions
  • understand the branching and PR process

Jekyll

What is it and where does Mr. Hyde fit in to all of this?

Jekyll is a simple, blog-aware, static site generator. It takes a template directory containing raw text files in various formats, runs it through a converter (like Markdown) and our Liquid renderer, and spits out a complete, ready-to-publish static website suitable for serving with your favorite web server. Jekyll also happens to be the engine behind GitHub Pages, which means you can use Jekyll to host your project’s page, blog, or website from GitHub’s servers for free.

Installation

Installing Jekyll is easy and straight-forward, but there are a few requirements you’ll need to make sure your system has before you start.

  • Ruby (including development headers, v1.9.3 or above for Jekyll 2 and v2 or above for Jekyll 3)
  • RubyGems
  • Linux, Unix, or macOS
  • NodeJS, or another JavaScript runtime (Jekyll 2 and earlier, for CoffeeScript support).
  • Python 2.7 (for Jekyll 2 and earlier)

https://jekyllrb.com/docs/installation/

$ git clone git@github.com:cloud-elements/devportal.git
$ cd devportal
$ sudo gem install jekyll redcarpet jekyll-sitemap

What the heck are redcarpet and jekyll-sitemap?

Redcarpet is a Ruby library for Markdown processing that smells like butterflies and popcorn. Cheatsheet

Jekyll Sitemap is a Jekyll plugin to silently generate a sitemaps.org compliant sitemap for your Jekyll site

Usage

Let's create a branch called training.
Build devportal with the following command:

$ jekyll serve

Now browse to http://127.0.0.1:4000/ and code away!

Site Structure

All documentation pages live in the docs directory.

Element Docs will be placed in their respective directory, e.g. Salesforce. The Element Docs are structured in the following way:

|-- root
  |-- docs
    |-- elements
      |-- element directory (e.g. Salesforce)
        |-- element specific docs (e.g. endpoint setup, create instance)

Platform docs like Hub level documentation, Events Framework, and OAuth Proxy are located at the docs -- platform level:

|-- root
  |-- docs
    |-- platform
      |-- event-management
        |-- event-management specific docs (e.g. how to guides, videos)

Product docs like Element Builder, Mapper, Groud2Cloud, Formulas are located at the docs -- products level:

|-- root
  |-- docs
    |-- products
      |-- element-builder
        |-- element-builder specific docs (e.g. how to guides, videos)

Quick Start docs like authentication and FAQs are located at the docs -- getstarted level:

|-- root
  |-- docs
    |-- getstarted
      |-- authentication

CSS, JS, and IMGs live in the assets directory. The Swagger docs live in the api-docs directory.

Video on Site Structure

Creating Your First Page

Jekyll requires information at the top of each page called Front Matter

The front matter is where Jekyll starts to get really cool. Any file that contains a YAML front matter block will be processed by Jekyll as a special file. The front matter must be the first thing in the file and must take the form of valid YAML set between triple-dashed lines. Here is a basic example:

---
layout: eff this
title: Blogging Like a Hacker
---

Between these triple-dashed lines, you can set predefined variables (see below for a reference) or even create custom ones of your own. These variables will then be available to you to access using Liquid tags both further down in the file and also in any layouts or includes that the page or post in question relies on.

Let's try it out!

  1. create a new file at the root called yourmom.md

  2. Put the following YAML at the top of the doc:

---
heading: Your Mom
seo: Your Mom | Cloud Elements API Docs
title: Bacon Ipsum
description: Bacon ipsum dolor amet fatback chuck hamburger, burgdoggen jowl pork belly corned beef. Chicken picanha meatball beef ribs cow kevin.
layout: docs
---

  1. Use the # and create your title Bacon Ipsum: # Bacon Ipsum

  2. Head to https://baconipsum.com/ to generate some bacon ipsum.

  3. Paste the bacon ipsum into your yourmom.md and Save

  4. Navigate to http://127.0.0.1:4000/yourmom.html

Congrats on creating your first page!!

Conventions

Layouts

In the previous section, the YAML in our test page contained the layout: docs variable. The layout variable let's Jekyll know which HTML layout to render in the browser.

All layouts live in the _layouts directory.

Includes

If you have small page fragments that you wish to include in multiple places on your site, you can use the include tag.

{% include footer.html %}

Jekyll expects all include files to be placed in an _includes directory at the root of your source directory. This will embed the contents of <source>/_includes/footer.html into the calling file.

Need some padding on your page?

There is a padding fragment you can put right in your markdown:

Pancetta short loin porchetta, venison short ribs drumstick tenderloin prosciutto strip steak sausage pastrami. Corned beef picanha venison ham bresaola. Ribeye turducken spare ribs chuck tri-tip, porchetta beef ribs corned beef pork chop capicola. Landjaeger pig tri-tip, bacon beef tenderloin prosciutto. Rump sirloin pork loin pork chop salami jerky. Shoulder drumstick ribeye, alcatra pancetta ham jerky shankle turducken picanha sirloin ball tip brisket pastrami salami. Short loin sirloin jerky, pancetta rump tri-tip porchetta strip steak ribeye.

{% include padding-all.html %}

Strip steak brisket rump porchetta, doner shank bacon turkey boudin. Filet mignon hamburger beef ribs pig, biltong pork chop tenderloin pork loin flank cow brisket doner leberkas turkey. Filet mignon turducken biltong flank, landjaeger rump sausage short ribs pork belly prosciutto shank ham. Ham hock cupim tongue, turducken pork loin tri-tip pork chop frankfurter spare ribs drumstick. Tenderloin frankfurter t-bone, bresaola shankle short ribs sausage. Shank kevin pork belly ground round, jerky leberkas turkey hamburger strip steak biltong.

Plugins

Jekyll has a plugin system with hooks that allow you to create custom generated content specific to your site. You can run custom code for your site without having to modify the Jekyll source itself.

YAML Specific to the Devportal

The YAML used to create element pages is different from platform pages. This is due to the way the API docs are rendered inside of the devportal.

An elementId is needed to render the element swagger docs. A resource key is needed to render the element swagger docs.

Let's take a look at some examples:

Salesforce YAML:

---
heading: Salesforce CRM
seo: API Docs | Salesforce CRM | Cloud Elements API Docs
title: API Docs
description: Salesforce CRM API Documentation.
layout: apidocs
breadcrumbs: /docs/elements.html
elementId: 23
parent: Back to Element Guides
order: 90
---

/instances

---
heading: Instance APIs
seo: Instance API Docs | Cloud Elements API Docs
title: Platform Documentation
description: Instance API Documentation.
layout: apidocs
apis: API Docs
platform: instances
breadcrumbs: /docs/platform/platform-docs.html
parent: Back to Platform Docs
order: 90
---

/hubs/crm

---
heading: CRM APIs
seo: CRM API Docs | Cloud Elements API Docs
title: Platform Documentation
description: CRM Hub API Documentation.
layout: apidocs
apis: API Docs
platform: crm
breadcrumbs: /docs/hubs/hub-docs.html
parent: Back to Hub Docs
order: 90
---

More on Pages

Order Variable

The order variable will determine where the page will display in the right hand side menu of the Element Docs

Menu

Code Blocks

The devportal does support rendering text as code.

Simply wrap the block in three grave accent () Optionally add the type of code you wish to display like JSON`

Let's take a look at an example:

Code block

Pro Tip: Don't forget to add a carriage return before and after your code block or it might not render correctly.

Contributing

The master branch is continuously deployed to production.

Please, feel free to make any contributions you feel will make Cloud Elements Documentation better.

Submit all pull requests to the master branch

Branching Model

GitHub Flow branching workflow model.

Pull Requests

jekyll serve is a required status check for all GitHub PRs, so be sure to run jekyll serve locally before creating a PR to ensure all code passes

Merging to master

  • expert writing the content
  • run jekyll serve to ensure your code runs locally (check your docs: http://127.0.0.1:4000/) prior to making a PR)
  • get the content checked by 1 other person that is an expert or close
  • get 1 other person to check your spelling, grammar, and mechanics
  • if you are confident in your changes, please feel free merge into master
  • delete the branch once it has been merged

Checking my changes locally Merging to Master

Summary

  • learned how to clone the devportal repo, install, and run locally
  • reviewed the basic site structure
  • created a sample page
  • reviewed some conventions
  • reviewed the branching and PR process

We just scratched the surface. Read more on the Jekyll site if you are curious about features and functionality.

Next Steps:

  • Doc-a-thon
  • Experiment on a local branch: training
  • Ask Questions
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment