I have no idea how to force push to staging, so here I am opening a PR like a noob 😅

404.html

@@ -1,5 +1,6 @@
 ---
 layout: default
+permalink: /404.html
 ---
 
 <style type="text/css" media="screen">
@@ -22,3 +23,12 @@ <h1>404</h1>
   <p><strong>Page not found :(</strong></p>
   <p>The requested page could not be found.</p>
 </div>
+
+<script>
+  !function(){
+  window.analytics.track('Docs 404', {
+    docs_page_404_context: document.referrer
+  }
+  )
+}
+</script>

Makefile

@@ -34,7 +34,9 @@ catalog:
 .PHONY: env
 env:
 	gem install bundler && \
-	bundle install
+	bundle install && \
+	cp -i .env.example .env | true && \
+	echo "Environment configured"
 
 .PHONY: seed
 seed:
@@ -52,7 +54,7 @@ deps:
 .PHONY: dev
 dev:
 	make clean && \
-	bundle exec jekyll serve --incremental -H 0.0.0.0
+	bundle exec jekyll serve --incremental -H 0.0.0.0 -V
 
 
 # Docker-based commands...
@@ -86,11 +88,11 @@ docker-nav:
 	  --volume="$(PWD):/srv/jekyll" \
 	  jekyll/jekyll \
 		bundle exec rake nav:update
-		
+
 .PHONY: docker-catalog
 docker-catalog:
 	docker run -it \
 	  --volume="$(PWD):/srv/jekyll" \
 	  jekyll/jekyll \
 		bundle install && \
-		bundle exec rake catalog:update
+		bundle exec rake catalog:update

README.md

@@ -14,27 +14,75 @@ Use the local build process to preview local changes. If you're doing a release,
 
 ## Makefile commands
 
-- docs: locally builds the docs and serves the static content via a Docker container running nginx
-- build: Builds the site docs. Used by CI to publish the docs to staging and production
-- nav: Rebuilds the entire nav datafile based on the current doc structure. This is destructive and should not be used unless absolutely necessary.
-- catalog: Pulls in the latest catalog data from the Platform API and saves it in the respective data files. Requires an API key saved in .env
-- env: for when you're first getting set up: installs bundler, and installs the deps for the repo.
-- seed: copies all example data files out of the `_templates` directory and puts them in the `_data` directory.
-- clean: runs `jekyll clean` locally
-- deps: re-runs `bundle install` locally.
-- dev: runs `jekyll serve` locally with incremental builds. Useful when updating CSS, JS, or content and you don't want to rebuild everytime.
+- `docs`: locally builds the docs and serves the static content via a Docker container running nginx
+- `build`: Builds the site docs. Used by CI to publish the docs to staging and production
+- `nav`: Rebuilds the entire nav datafile based on the current doc structure. This is destructive and should not be used unless absolutely necessary.
+- `catalog`: Pulls in the latest catalog data from the Platform API and saves it in the respective data files. Requires an API key saved in .env
+- `env`: for when you're first getting set up: installs bundler, and installs the deps for the repo.
+- `seed`: copies all example data files out of the `_templates` directory and puts them in the `_data` directory. Useful if you don't have a way to setup an API key.
+- `clean`: runs `jekyll clean` locally
+- `deps`: re-runs `bundle install` locally.
+- `dev`: runs `jekyll serve` locally with incremental builds. Useful when updating CSS, JS, or content and you don't want to rebuild everytime.
 
 - docker-clean: runs a `jekyll clean` on a docker host.
 - docker-deps: runs `bundle install` on a docker host.
 - docker-dev: runs `make dev` on a docker host.
 - docker-nav: runs `make nav` on a docker host.
 - docker-catalog: runs `make catalog` on a docker host.
 
+# Layouts
+`default.html` is the container through which all the individual other layouts (currently one, `page.html`) are built to have the right title, seo, etc.
 
 # Platform Config API + Catalog
 
 ### Data Source
-The Segment Config API is currently providing the data for the Source and Destination catalog pages. This happens at build time and the results are stored in the respective `_data/catalog` yml files. 
+The Segment Config API is currently providing the data for the Source and Destination catalog pages. This happens at build time and the results are stored in the respective `_data/catalog` yml files.
+
+For local development, you can always run `make seed` to use the example files if you don't want to mess with interacting with the Platform API.
+
+### API Key
+The Platform API needs an API key to pull in the _latest_ catalog data and currently looks for one in the environment variable `PLATFORM_API_TOKEN`. This value is stored in a special file named `.env` that the appropriate scripts reference. You can what this file looks like by looking at `.env.example`
+
+If you want to interact with the Platform API, locally, first make sure you have run `make env`. This will create the appropriate `.env` file for you to work with
+
+**NOTE: Never check-in `.env` or remove it from `.gitignore`.**
+
+Once your local environment is configured, you then have two options to pull Platform API data: You can use the token in [`chamber`](https://github.com/segmentio/chamber) or you can create your own token. The one in chamber is also used by CircleCI when the docs are built + deployed.
+
+#### Chamber
+
+If you installed and have access to `chamber`, run the following command:
+
+```bash
+$ aws-okta exec prod-privileged -- chamber read segment-docs platform_api_key
+```
+
+or for staging...
+
+```bash
+$ aws-okta exec stage-privileged -- chamber read segment-docs platform_api_key
+```
+
+You should get something like this as the output of the command.
+```bash
+Key			Value												Version		LastModified	User
+platform_api_key	[REDACTED FOR DOCS]		2		08-05 10:24:55	arn:aws:sts::752180062774:assumed-role/production-write/bryan.mikaelian@segment.com
+```
+
+Edit the `.env` file (generated from `make env`) and replace the environment variable with the token above. `make catalog` should then work and you should see some output like this:
+
+```bash
+$ make catalog
+"Saving catalogs from Platform API..."
+"Finished Destinations."
+"Finished Sources."
+"Done."
+```
+
+#### Bring your own token
+
+You create your own token via the Access Management Page. Feel free to use [`segment-engineering`](https://app.segment.com/segment-engineering/settings/access-management) or [`segment_prod`](https://app.segment.com/segment_prod/settings/access-management). Once you have the token, set the value in the `.env` file.
+
 
 ### Catalog Data + Doc Links
 By default, the links on the catalog page and respective sidenavs will attempt to automagically set hyperlinks, for actual doc file, at the path `connections/:type/:slug`. However, given the transitory state of Docs V2, these links might 404 since the respective doc might be in a different directory.
@@ -45,7 +93,7 @@ These two catalogs are hardcoded in the `_data` directory since the Config API d
 # Sidenav
 The sidenav is managed by the files in `_data/sidenav/`. Depending on what section we are in determines the file used. We currently support up to 2 levels deep on a sidenav.
 
-# Breacrumb
+# Breadcrumb
 The current breadcrumb is currently determined based on the `page.path` and the current page's `title` front-matter attribute.
 
 # Searching
@@ -56,20 +104,18 @@ Swiftype is set up as a script in `_layouts/default.html`
 # Syntax highlighting
 
 We're using Rouge, set in the `_config.yml`. It's now default for Jekyll 3 and later, so 🎉.
-
-A list of the cues rouge accepts can be found [here](https://github.com/rouge-ruby/rouge/wiki/list-of-supported-languages-and-lexers).
+A list of the cues Rouge accepts can be found [here](https://github.com/rouge-ruby/rouge/wiki/list-of-supported-languages-and-lexers).
 
 
 # Frontmatter
 
-- `redirect_from`: defaults to none. Takes an array of URLs from the frontmatter in a file, and generates a "stub" page at each URL. Each stub file redirects to the original file.
-
 - `beta`: default false. When true, show an "in beta" warning in the page layout (see the warning in `_includes/content/beta.md`)
-
-- hidden: omits the file from the `sitemap.xml` and adds a `<meta name="robots" content="noindex" />` to the top of the generated HTML file. TODO: it should probably also omit the item from the navbar generator script 🤔
-
+- `description`: takes a string. Adds the text here to the meta "description" tag used for SEO purposes
 - `feedback`: defaults to true. When false, hide the feedback footer. Good for legal and landing pages,
-
-- `seo-priority`: values from `1.0` to `0.1`, default: `0.5 `. Sets the `Priority` tag in the sitemap
-
+- `hidden`: omits the file from the `sitemap.xml` and adds a `<meta name="robots" content="noindex" />` to the top of the generated HTML file. TODO: it should probably also omit the item from the navbar generator script 🤔
+- `hide_toc`: hides the right-nav TOC that's generated from H2s
+- `integration_type`: This is set on two paths in the `_config.yml` to add a noun (Source or Destination) to the end of the title, and the end of the title tag in the html layout.
+- `landing`: defaults to false. Use this to drop the noun set by `integration_type` from the title and heading.
+- `redirect_from`: defaults to none. Takes an array of URLs from the frontmatter in a file, and generates a "stub" page at each URL. Each stub file redirects to the original file.
 - `seo-changefreq`: default: `weekly `. Use the values [in the sitemap spec](https://www.sitemaps.org/protocol.html#xmlTagDefinitions). - sets the `changefreq` tag in the sitemap.xml generator, which tells search crawlers how often to check back.
+- `seo-priority`: values from `1.0` to `0.1`, default: `0.5 `. Sets the `Priority` tag in the sitemap

_config.yml

@@ -7,13 +7,21 @@ url: "http://0.0.0.0:4000" # the base hostname & protocol for your site, e.g. ht
 markdown: kramdown
 highlighter: rouge
 defaults:
-  -
-    scope:
+  - scope:
       path: ""
     values:
       layout: "page"
       hidden: false
       beta: false
+  - scope:
+      path: "connections/destinations"
+    values:
+      integration_type: destination
+  - scope:
+      path: "connections/sources/catalog"
+    values:
+      integration_type: source
+
 
 plugins:
   - jekyll-sitemap

_data/landing.yml

@@ -1,31 +1,31 @@
 - name: Guides
   icon: icon-guides.svg
-  description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut in ipsum aliquam purus"
+  description: "Start here! Best practices, Setup steps, and other useful information."
 
 - name: Academy
   icon: icon-academy.svg
-  description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut in ipsum aliquam purus"
+  description: "Learn more about the 'whys' and 'hows' of analytics. A great read if you're just getting started."
+
+- name: App
+  icon: icon-app.svg
+  description: "Learn your way around the Segment web application - hook up data sources to tools and warehouses, set up filtering, and more."
 
 - name: Connections
   icon: icon-connections.svg
-  description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut in ipsum aliquam purus"
+  description: "Collect data once, and integrate tools for analytics, growth, marketing and more."
 
 - name: Protocols
   icon: icon-protocols.svg
-  description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut in ipsum aliquam purus"
+  description: "Prevent data quality issues before they start with a tracking schema and data quality enforcement."
 
 - name: Personas
   icon: icon-personas.svg
-  description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut in ipsum aliquam purus"
+  description: "Improve your interactions by building audiences to personalize experiences."
 
 - name: Privacy
   icon: icon-privacy.svg
-  description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut in ipsum aliquam purus"
-
-- name: App
-  icon: icon-app.svg
-  description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut in ipsum aliquam purus"
+  description: "Respect your customers’ privacy with tools for data discovery and policy enforcement."
 
 - name: Partners
   icon: icon-partners.svg
-  description: "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut in ipsum aliquam purus"
+  description: "Join the Segment Platform and enable thousands of companies to activate their first party data."

_includes/content/connection-modes.md

@@ -1,44 +1,52 @@
-The first step is to make sure {{ destination.title }} supports the source type and connection mode you've chosen to implement. You can learn more about what dictates [the connection modes we support here](https://segment.com/docs/destinations/#connection-modes).
-
-
+<!-- in the file we're pulling from the API, "name" corresponds with the path to the yml blob for a specific destination.-->
+{% assign name = page.path | replace: "connections", "catalog" | remove: "/index.md" %}
+{% assign destination_from_api = site.data.catalog.destinations.destinations | where: "name", name | first %}
 <!--
 components -> how do we send data
 platforms -> what data do we recognize-->
 
-{% for components in destination %}
-  {% if destination.components.type == "ios" or destination.components.type == "android" %}
-    {% assign has-mobile = true %}
-    {% assign device-mobile = true %}
+{% for item in destination_from_api.components %}
+  {% if item.type == "IOS" or item.type == "ANDROID" %}
+    {% assign has_mobile = true %}
+    {% assign device_mobile = true %}
+  {% endif %}
+  {% if item.type == "WEB" %}
+    {% assign has_browser = true %}
+    {% assign device_web = true %}
   {% endif %}
-  {% if destination.components.type == "browser" %}
-    {% assign has-browser = true %}
-    {% assign device-web = true %}
+  {% if item.type == "SERVER" %}
+    {% assign has_server = true %}
   {% endif %}
-  {% if destination.components.type == "server" %}
-    {% assign has-server = true %}
-    {% assign device-server = true %}
+  {% if item.type == "CLOUD" %}
+    {% assign has_server = true %}
   {% endif %}
 {% endfor %}
 
-<!-- `cloud-web` is complicated -->
-{% if has-browser == true and browserUnbundlingSupported == true && browserUnbundlingPublic == true %}
-  {% assign cloud-web = true %}
-{% elsif has-server == true and has-browser == false and destination.platforms.browser == true %}
-  {% assign cloud-web = true %}
+{% if destination_from_api.direct == true or destination_from_api.platforms.server == true %}
+  {% assign has_server = true %}
+{% endif %}
+
+<!-- `cloud_web` is complicated -->
+{% if has_browser == true and destination_from_api.browserUnbundlingSupported == true && destination_from_api.browserUnbundlingPublic == true %}
+  {% assign cloud_web = true %}
+{% elsif has_server == true and has_browser == false and destination_from_api.platforms.browser == true %}
+  {% assign cloud_web = true %}
 {% else %}
-  {% assign cloud-web = false %}
+  {% assign cloud_web = false %}
 {% endif %}
 
-<!-- cloud-mobile only checks for server? -->
-{% if has-server == true %}
-{% assign cloud-mobile = true %}
+<!-- cloud_mobile only checks for server? -->
+{% if has_server == true %}
+{% assign cloud_mobile = true %}
 {% endif %}
 
-<!-- cloud-server is also complicated -->
-{% if has-server == true and destaintion.platforms.server == true %}
-{% assign cloud-mobile = true %}
+<!-- cloud_server is also complicated -->
+{% if has_server == true and destination_from_api.platforms.server == true %}
+{% assign cloud_server = true %}
 {% endif %}
 
+The first step is to make sure {{ destination_from_api.display_name }} supports the source type and connection mode you've chosen to implement. You can learn more about what dictates [the connection modes we support here](https://segment.com/docs/destinations/#connection-modes).
+
 <table>
   <tr>
     <th></th>
@@ -48,14 +56,14 @@ platforms -> what data do we recognize-->
   </tr>
   <tr>
     <td>📱 Device-based</td>
-    <td>{% if device-web == true %} ✅ {% endif %}</td>
-    <td>{% if device-mobile == true %} ✅ {% endif %}</td>
-    <td>{% if device-server == true %} ✅ {% endif %}</td>
+    <td>{% if device_web == true %} ✅ {% endif %}</td>
+    <td>{% if device_mobile == true %} ✅ {% endif %}</td>
+    <td>{% if device_server == true %} ✅ {% endif %}</td>
   </tr>
   <tr>
     <td>☁️  Cloud-based</td>
-    <td>{% if cloud-web == true %} ✅ {% endif %}</td>
-    <td>{% if cloud-mobile == true %} ✅ {% endif %}</td>
-    <td>{% if cloud-server == true %} ✅ {% endif %}</td>
+    <td>{% if cloud_web == true %} ✅ {% endif %}</td>
+    <td>{% if cloud_mobile == true %} ✅ {% endif %}</td>
+    <td>{% if cloud_server == true %} ✅ {% endif %}</td>
   </tr>
-</table>
+</table>