Skip to content

Stitch Connect Documentation

Jump to bottom
Erin Cochran edited this page Mar 21, 2018 · 1 revision

TODO: Intro

Collections

Connect docs are stored in two collections:

  • _connect-content - This collection contains the “live” pages that will display on the deployed site:

  • _connect-files - This collection contains the individual files that create the content that displays on each of the live pages.

    • /api - This folder contains all the content for the API.

      • /documentation - The individual files that make up the API content. Ex: Authentication, Core Objects, etc.
      • /objects - The files that render content for each of the API’s objects. Ex: Accounts, Properties, Source Form Properties, etc.

    • /js - This folder contains all the content for the JS client.

      • /documentation - The individual files that make up the JS content. Ex: Installation, Versioning, Functions, etc.
      • /functions - The files that render content for each of the JS client’s functions. Ex: addSource, authorizeSource.

    • /overview - This folder contains all the content for the Overview/landing page.

Layouts & Content Rendering

Every page for Connect uses the same layout: /_layouts/connect.html.

The Sidenav

The API and JS references both have sidebars specific to their pages.

In _includes/layout/connect-sidebar.html, the {% case page.sidebar %} code checks the sidebar property in each page’s Frontmatter and assigns a variable based on that value. The data the sidebar uses to render the sidenav is pulled from a data file. For example:

{% assign navigation = site.data.sidebars.connect.api %}

In this case, the navigation is assigned to the values in _data/sidebars/connect.hml > api. The logic in the connect-sidebar.html include will loop through this list and display the content accordingly:

[PLACEHOLDER FOR IMAGE]

URLs & Variables

The URLs in the data file contain variables that allow the variables to be shortened. Just under the {% case %} logic in connect-sidebar.html are these two lines:

{% assign api = site.data.connect.api %}
        = _data/connect/api.yml
{% assign js = site.data.connect.js-client %}
        = _data/connect/js-client.yml

For example: Without the variable assignment of api, {{ api.introduction }} would have to be written as {{ site.data.connect.api.introduction }}. This can be used on any page that contains this sidenav.

Note: Any link that will navigate the user off of the current page must contain site.baseurl and the correct page permalink.

If, for example, a link on the JS page points to something on the API page, the variable must look like this:

{{ api.section | prepend: site.baseurl | append: api.authentication | flatify }}

/* Renders to */

/docs/stitch-connect/api/#authentication

Content Rendering

Like the sidenav, the connect.html layout checks the page’s sidebar value to identify the correct content to render:

{% case page.sidebar %}
    {% when 'overview' %}
        {% assign docs = site.connect-files | where:"content-type","overview" | sort:"order" %}

    {% when 'api' %}
        {% assign docs = site.connect-files | where:"content-type","api-doc" | sort:"order" %}

    {% when 'js' %}
        {% assign docs = site.connect-files | where:"content-type","js-doc" | sort:"order" %}
{% endcase %}

This code translates to: "Look in the _connect-files collection for files where page.content-type = this-type and display them according to the formatting below."

Doc Sections

There are two ways a top-level doc (content-type: api-doc, js-doc, overview) can contain content:

  1. In sections, inside the file itself. For example: In _connect-files/api/documentation/api-form-properties.md, there are several sections in the page's Frontmatter:

    sections:
  - content: |
      Stitch connects to a large, diverse universe of applications and data warehouses, each of which is configured differently.
      ...

  - title: "Destination Form Properties"
    anchor: "destination-form-properties"
    content: |
      Destination form properties should be sent in the `connection` argument when using the [Create]({{ api.core-objects.destinations.create.anchor }}) or [Update a Destination]({{ api.core-objects.destinations.update.anchor }}) endpoints.

      {% include connect/api-endpoint-rollup.html type="form-property" subtype="destination" %}

    Which is then rendered according to the code following {% if doc.sections %}.

  2. In includes. In this case, the content may not live in the top-level doc itself - it likely lives inside the include file. For example:

    ---
title: Core Objects
content-type: "api-doc"
order: 6

include: connect/api-object.html
---

    In this case, the content for the Core Objects section is in the _includes/connect/api-object.html file and will be rendered using this code in _layout/connect.html:

    {% if doc.include %}
     {% include {{doc.include}} %}
{% endif %}

Object Files

Note: "Object" in this context refers to an API object, endpoint, data structure, JS function, etc.

Common Content Snippets

TODO: Describe how to use data files (api, general, js.yml) to re-use content in object files.

Clone this wiki locally