Merge branch 'master' into putRecords-Migration

Author: markzegarelli

.env.example

@@ -1 +1,2 @@
-PLATFORM_API_TOKEN=look for me in chamber
+PLATFORM_API_TOKEN=look for me in chamber
+PAPI_TOKEN=get one from a papi-enabled workspace

.github/workflows/link-check.yml

@@ -0,0 +1,21 @@
+# This is a basic workflow to help you get started with Actions
+
+name: Link Check
+
+# Controls when the action will run. 
+on:
+  # Triggers the workflow on push or pull request events but only for the master branch
+  pull_request:
+
+# A workflow run is made up of one or more jobs that can run sequentially or in parallel
+jobs:
+  markdown-link-check:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@master
+    - uses: gaurav-nelson/github-action-markdown-link-check@v1
+      with:
+        use-quiet-mode: 'yes'
+        config-file: '.mlc-config.json'
+        use-verbose-mode: 'yes'
+        check-modified-files-only: 'yes'

.gitignore

@@ -12,3 +12,6 @@ src/assets/docs.bundle.js
 yarn-error.log
 # Make sure to update `analytics` to the full path to your Typewriter client.
 .vscode/spellright.dict
+
+# Local Netlify folder
+.netlify

.mlc-config.json

@@ -0,0 +1,12 @@
+{
+  "replacementPatterns": [
+    {
+    "pattern": "^/docs",
+    "replacement": "/github/workspace/src"
+    },
+    {
+      "pattern": "(\\S+?)\/(\\S+?)\/?$",
+      "replacement": "$1/$2.md"
+    }
+]
+}

.vale.ini

@@ -3,4 +3,5 @@ StylesPath = vale-styles
 Vocab = Docs
 
 [*.md]
-BasedOnStyles = write-good, Segment
+BasedOnStyles = write-good, segment
+TokenIgnores = ({% .* %})

.vscode/launch.json

@@ -0,0 +1,7 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": []
+}

Gemfile

@@ -18,6 +18,7 @@ group :jekyll_plugins do
   gem "premonition", "~> 2.0.0"
   gem "jekyll-include-cache"
   gem 'jekyll-algolia'
+  gem 'jekyll-dotenv'
 end
 
 # Windows does not include zoneinfo files, so bundle the tzinfo-data gem

Gemfile.lock

@@ -60,6 +60,9 @@ GEM
     jekyll-commonmark (1.3.1)
       commonmarker (~> 0.14)
       jekyll (>= 3.7, < 5.0)
+    jekyll-dotenv (0.2.0)
+      dotenv (~> 2.7)
+      jekyll (~> 4)
     jekyll-include-cache (0.2.1)
       jekyll (>= 3.7, < 5.0)
     jekyll-last-modified-at (1.3.0)
@@ -85,12 +88,14 @@ GEM
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     mercenary (0.4.0)
-    mini_portile2 (2.5.0)
+    mini_portile2 (2.5.1)
     multipart-post (2.1.1)
-    nokogiri (1.11.1)
+    nokogiri (1.11.4)
       mini_portile2 (~> 2.5.0)
       racc (~> 1.4)
-    nokogiri (1.11.1-x86_64-linux)
+    nokogiri (1.11.4-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.11.4-x86_64-linux)
       racc (~> 1.4)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
@@ -103,7 +108,7 @@ GEM
     rb-fsevent (0.10.4)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
-    rexml (3.2.4)
+    rexml (3.2.5)
     rouge (3.25.0)
     ruby-enum (0.8.0)
       i18n
@@ -124,6 +129,7 @@ GEM
 
 PLATFORMS
   ruby
+  x86_64-darwin-20
   x86_64-linux
 
 DEPENDENCIES
@@ -132,6 +138,7 @@ DEPENDENCIES
   jekyll!
   jekyll-algolia
   jekyll-commonmark
+  jekyll-dotenv
   jekyll-include-cache
   jekyll-last-modified-at
   jekyll-redirect-from

Makefile

@@ -53,6 +53,10 @@ serve: package
 catalog: vendor/bundle
 	@node scripts/catalog.js
 
+.PHONY: changelog
+changelog: vendor/bundle
+	@node scripts/changelog.js
+
 .PHONY: sidenav
 sidenav: vendor/bundle
 	@node scripts/nav.js

README.md

@@ -64,7 +64,7 @@ See the [Contributor Guide](contributors.md) for more info.
 
 If you're planning substantial changes to the docs, follow this process for great success! 🏆
 
-1. 📞 Contact the docs team* during the planning phase. This way, we can help with logistics and information architecture, and alert you to any gotchas in your content area.
+1. 📞 Contact the docs team ( @segmentio/segment-doc-team ) during the planning phase. This way, we can help with logistics and information architecture, and alert you to any gotchas in your content area.
 2. 📝 Unless previously booked, we don't need to be involved in the writing - go for it! (We're happy to consult if you get stuck or need someone to bounce ideas off.)
 3. 👀 When you've got a draft at least 70% ready for review, tag a member of the docs team, who'll do an initial review. (This can be either in Paper/Gdocs, or in a Github [Draft PR](#draft-prs) with markdown changes if you're comfortable with that.) They'll do a copy edit pass, and ask clarifying questions.
 4. ❓The doc author/owner should answer the questions asked in the review phase. Either the doc author, or the docs team member can resolve comments as they are clarified in the doc text.👍
@@ -76,8 +76,6 @@ If you're planning substantial changes to the docs, follow this process for grea
 
 Once the PR is merged, the docs site rebuilds and the changes are live!
 
-(* The docs team is just Laura right now.)
-
 
 ### The Docs Process for direct contributors
 
@@ -88,17 +86,16 @@ Once the PR is merged, the docs site rebuilds and the changes are live!
 3. Commit your changes.
 3. Push the branch to `segment-docs` and make a PR to master.
     - Include any context you can in the PR: links to ZD tickets, Jira tickets, Paper docs or wiki pages about the project. (If you include a Jira ticket number, Jira can often link directly to the PR.)
-3. [Check if you need a review](#most-frequently-asked-question-do-i-need-a-review) and tag @sanscontext (or another member of the docs team). (Github also tags the CODEOWNERS for the path you're editing.)
+3. [Check if you need a review](#most-frequently-asked-question-do-i-need-a-review) and tag a member of the docs team. (Github also tags the CODEOWNERS for the path you're editing.)
 5. If the reviewers ask for clarifications or edits:
     - make the changes
     - push the new commits to the branch
 5. Once you get an approving review and the checks pass, merge your PR.
-6. Once you've merged the branch, _delete it_!
-7. Once merged, you can track build and deploy process in [buildkite/segment-docs](https://buildkite.com/segment/segment-docs).
+7. Once merged, Netlify builds the changes to `master` and redeploys the docs site.
 
 ### Draft PRs
 
-If you're doing a substantial change and you're going to want to spend a few weeks on it, use [Github's Draft PRs feature](https://help.github.com/en/articles/about-pull-requests#draft-pull-requests), or add `WIP` to the title of your PR. This lets us know to ignore the PR until you're ready (otherwise Laura will ping you weekly about it!).
+If you're doing a substantial change and you're going to want to spend a few weeks on it, use [Github's Draft PRs feature](https://help.github.com/en/articles/about-pull-requests#draft-pull-requests), or add `DRAFT` or `WIP` to the title of your PR. This lets us know to ignore the PR until you're ready (otherwise we might ping you weekly about it!).
 
 
 ## How the docs build works
@@ -111,10 +108,10 @@ When you run `make dev` (or `make docs`) on your laptop, Jekyll runs the same pr
 
 Some of these files include Liquid script, which allows them to load reusable content ("includes"), render fancy HTML styling, and run simple code processes to build programmatic content. As long as the Jekyll process is running on your laptop, you can edit the content of a page in markdown and save it, and Jekyll will detect the change and rebuild that page so you can view it locally. However, this doesn't work if you're editing the page layouts or stylesheets, which are assumed to be static at build time.
 
-When you merge a PR to master, our build system runs the Jekyll program, and automatically publishes the rebuilt HTML files to our web server. (Which is why we *require* that the Buildkite build passes before you merge!)
+When you merge a PR to master, the Netlify build system runs the Jekyll program, and automatically publishes the rebuilt HTML files.
 
 ## Formatting and Prettifying
-Some important tips are in the [styleguide](styleguide.md). We also have a (rendering)[Formatting guide](/src/utils/formatguide.md) available so you can see how different formatting looks when rendered.
+Some important tips are in the [styleguide](styleguide.md). We also have a (rendering) [Formatting guide](/src/utils/formatguide.md) available so you can see how different formatting looks when rendered.
 
 ## Repo structure
 
@@ -147,15 +144,13 @@ A few possibilities/suggestions:
 - **Name images to describe a process flow**. For example `checkout-1-add-to-cart.png`, `checkout-2-est-shipping.png` and so on.
 
 
-### Diagram Library
-
-We have a diagram library in Sketch, which you can use to build pretty, on-brand architecture diagrams, etc. There's a [readme file in that directory](diagram-library/readme.md) with instructions on how to use it.
-
 ### Content structure
 
 There are folders for each of the top level products, and those folders might also contain topics that are related to that product area (for example the Privacy Portal section also contains GDPR/CCPA docs).
 
-For the Connections product, the section is divided into the Spec, then Sources, Destinations, and Warehouses, with general accessory topics at the folder root. (More specific accessory topics are in each sub directory.) Each also contains a `catalog` directory, which contains all the directories with information about specific integrations. The top-level of this folder (the `index.md`) is a pretty "catalog" page which gives a tile-like view by category, suitable for browsing. It pulls the logo for these tiles from the path for the integration in the metadata service.
+For the Connections product, the section is divided into the Spec, then Sources, Destinations, and Storage Destinations (formerly called "Warehouses"), with general accessory topics at the folder root. (More specific accessory topics are in each sub directory.)
+
+Each also contains a `catalog` directory, which contains all the directories with information about specific integrations. The top-level of this `catalog` folder (the `index.md`) is a pretty "catalog" page which gives a tile-like view by category, suitable for browsing. It pulls the logo for these tiles from the path for the integration in the metadata, either in `destinations.yml`, `sources.yml`, or `warehouses.yml`.
 
 
 ### Programmatic content
@@ -166,7 +161,7 @@ Programmatic content is built using information in the files in `/src/_data/cata
 
 Most of the programmatic content is built into the `_layouts` templates that each page uses. Sources, Destinations, and Warehouses use the `integration.html` template, which uses some Liquid logic, and calls an `include` depending on the integration type. Most of logic for the actual content must live in the include file itself, however logic controlling *if* the include is built can live in the `layout`.
 
-Destination pages include the `integration_foot.md` content which uses Liquid scripting and pulls from the catalog metadata.
+Destination pages include the `destination-dossier.html` and `destination_footer.md` content, which use Liquid scripting and pulls from the catalog metadata.
 
 Sources pages check if the source is a cloud-app, then include information about if the source is an object or event source, based on the `type` data from the ConfigAPI.
 
@@ -189,6 +184,7 @@ Each piece of frontmatter does something special!
 #### Content-related frontmatter
 - `beta`: default false. When true, show an "in beta" warning in the page layout (see the warning in `_includes/content/beta-note.md`)
 - `rewrite`: defaults to false. This is a legacy frontmatter flag that comes from the old `site-docs` repo, and which labels any destination that was rewritten in ~2018 to a standardized template. It disables the duplicate "connection modes" table that would otherwise show up in the boilerplate content at the end of the page.
+- `hide-dossier`: defaults to false. When true, hides the "quick info" box at the top of a destination page.
 - `hide-boilerplate`: defaults to false. When true, none of the content from `destination-footer.md` is appended to the destination page.
 - `hide-cmodes`: defaults to false. A renaming of "rewrite" for more clarity, hides the connection modes table in the boilerplate.
 - `hide-personas-partial`: defaults to false. When true, hides the section of content from `destination-footer.md` that talks about being able to receive personas data.
@@ -222,14 +218,10 @@ We have two neat icons that you can add to a bottom-level menu item to mark it w
 - `dev`: runs `jekyll serve` locally with incremental builds. Useful when updating CSS, JS, or content and you don't want to rebuild every time.
 - `docs`: same as `make dev`, but for Laura's convenience.
 - `build`: Builds the site docs. Used by CI to publish the docs to staging and production
-- `catalog`: Pulls in the latest catalog data from the Platform API and saves it in the respective data files. Requires an API key to be passed in env via PLATFORM_API_TOKEN. [Instructions here](#bring-your-own-token).
+- `catalog`: Pulls in the latest catalog data from the Platform API and saves it in the respective data files. Requires an API key to be passed in env via PLATFORM_API_TOKEN. [Instructions here](https://github.com/segmentio/segment-docs/blob/master/contributors.md#refresh-the-segment-catalog).
 - `sidenav`: Builds the side navs for 'main', 'legal', 'api', 'partners' and stores the output in `/src/_data/sidenav-auto/`. This output isn't used for the actual build.
 - `typewriter`: pulls in the current state of the Docs tracking plan for implementing Segment tracking
 - `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 set up an API key.
 - `clean`: removes all build artifacts
 - `clean-deps`: removes all downloaded `gems` and `node_modules`
 - `deps`: installs the required `gems` and `node_modules`
-
-
-- docker-build: runs `make build` on a docker host.
-- docker-dev: runs `make dev` on a docker host.