Triple quote long examples docs.

docs/build/schema.md

@@ -275,7 +275,13 @@ Represents user information for a trigger, search, or create.
 #### Examples
 
 * `{ label: 'New Thing', description: 'Gets a new thing for you.' }`
-* `{ label: 'New Thing', description: 'Gets a new thing for you.', directions: 'This is how you use the thing.', hidden: false, important: true }`
+* ```
+  { label: 'New Thing',
+    description: 'Gets a new thing for you.',
+    directions: 'This is how you use the thing.',
+    hidden: false,
+    important: true }
+  ```
 
 #### Anti-Examples
 
@@ -384,15 +390,40 @@ How will Zapier create a new object?
 
 #### Examples
 
-* `{ key: 'recipe', noun: 'Recipe', display: { label: 'Create Recipe', description: 'Creates a new recipe.' }, operation: { perform: '$func$2$f$', sample: { id: 1 } } }`
-* `{ key: 'recipe', noun: 'Recipe', display: { label: 'Create Recipe', description: 'Creates a new recipe.' }, operation: { perform: '$func$2$f$', sample: { id: 1 }, shouldLock: true } }`
-* `{ key: 'recipe', noun: 'Recipe', display: { label: 'Create Recipe', description: 'Creates a new recipe.', hidden: true }, operation: { perform: '$func$2$f$' } }`
+* ```
+  { key: 'recipe',
+    noun: 'Recipe',
+    display: { label: 'Create Recipe', description: 'Creates a new recipe.' },
+    operation: { perform: '$func$2$f$', sample: { id: 1 } } }
+  ```
+* ```
+  { key: 'recipe',
+    noun: 'Recipe',
+    display: { label: 'Create Recipe', description: 'Creates a new recipe.' },
+    operation: { perform: '$func$2$f$', sample: { id: 1 }, shouldLock: true } }
+  ```
+* ```
+  { key: 'recipe',
+    noun: 'Recipe',
+    display: { label: 'Create Recipe', description: 'Creates a new recipe.', hidden: true },
+    operation: { perform: '$func$2$f$' } }
+  ```
 
 #### Anti-Examples
 
 * `'abc'`
-* `{ key: 'recipe', noun: 'Recipe', display: { label: 'Create Recipe', description: 'Creates a new recipe.' }, operation: { perform: '$func$2$f$', shouldLock: 'yes' } }`
-* `{ key: 'recipe', noun: 'Recipe', display: { label: 'Create Recipe', description: 'Creates a new recipe.' }, operation: { perform: '$func$2$f$' } }`
+* ```
+  { key: 'recipe',
+    noun: 'Recipe',
+    display: { label: 'Create Recipe', description: 'Creates a new recipe.' },
+    operation: { perform: '$func$2$f$', shouldLock: 'yes' } }
+  ```
+* ```
+  { key: 'recipe',
+    noun: 'Recipe',
+    display: { label: 'Create Recipe', description: 'Creates a new recipe.' },
+    operation: { perform: '$func$2$f$' } }
+  ```
 
 #### Properties
 
@@ -788,12 +819,21 @@ How will we find create a specific object given inputs? Will be turned into a cr
 
 #### Examples
 
-* `{ display: { label: 'Create Tag', description: 'Create a new Tag in your account.' }, operation: { perform: '$func$2$f$', sample: { id: 1 } } }`
-* `{ display: { label: 'Create Tag', description: 'Create a new Tag in your account.', hidden: true }, operation: { perform: '$func$2$f$' } }`
+* ```
+  { display: { label: 'Create Tag', description: 'Create a new Tag in your account.' },
+    operation: { perform: '$func$2$f$', sample: { id: 1 } } }
+  ```
+* ```
+  { display: { label: 'Create Tag', description: 'Create a new Tag in your account.', hidden: true },
+    operation: { perform: '$func$2$f$' } }
+  ```
 
 #### Anti-Examples
 
-* `{ display: { label: 'Create Tag', description: 'Create a new Tag in your account.' }, operation: { perform: '$func$2$f$' } }`
+* ```
+  { display: { label: 'Create Tag', description: 'Create a new Tag in your account.' },
+    operation: { perform: '$func$2$f$' } }
+  ```
 
 #### Properties
 
@@ -816,12 +856,21 @@ How will we get a single object given a unique identifier/id?
 
 #### Examples
 
-* `{ display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' }, operation: { perform: { url: '$func$0$f$' }, sample: { id: 385, name: 'proactive enable ROI' } } }`
-* `{ display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.', hidden: true }, operation: { perform: { url: '$func$0$f$' } } }`
+* ```
+  { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' },
+    operation: { perform: { url: '$func$0$f$' }, sample: { id: 385, name: 'proactive enable ROI' } } }
+  ```
+* ```
+  { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.', hidden: true },
+    operation: { perform: { url: '$func$0$f$' } } }
+  ```
 
 #### Anti-Examples
 
-* `{ display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' }, operation: { perform: { url: '$func$0$f$' } } }`
+* ```
+  { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' },
+    operation: { perform: { url: '$func$0$f$' } } }
+  ```
 
 #### Properties
 
@@ -844,12 +893,21 @@ How will we get notified of new objects? Will be turned into a trigger automatic
 
 #### Examples
 
-* `{ display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' }, operation: { type: 'hook', perform: '$func$0$f$', sample: { id: 385, name: 'proactive enable ROI' } } }`
-* `{ display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.', hidden: true }, operation: { type: 'hook', perform: '$func$0$f$' } }`
+* ```
+  { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' },
+    operation: { type: 'hook', perform: '$func$0$f$', sample: { id: 385, name: 'proactive enable ROI' } } }
+  ```
+* ```
+  { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.', hidden: true },
+    operation: { type: 'hook', perform: '$func$0$f$' } }
+  ```
 
 #### Anti-Examples
 
-* `{ display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' }, operation: { type: 'hook', perform: '$func$0$f$' } }`
+* ```
+  { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' },
+    operation: { type: 'hook', perform: '$func$0$f$' } }
+  ```
 
 #### Properties
 
@@ -872,12 +930,26 @@ How will we get a list of new objects? Will be turned into a trigger automatical
 
 #### Examples
 
-* `{ display: { label: 'New User', description: 'Trigger when a new User is created in your account.' }, operation: { perform: { url: 'http://fake-crm.getsandbox.com/users' }, sample: { id: 49, name: 'Veronica Kuhn', email: 'veronica.kuhn@company.com' } } }`
-* `{ display: { label: 'New User', description: 'Trigger when a new User is created in your account.', hidden: true }, operation: { perform: { url: 'http://fake-crm.getsandbox.com/users' } } }`
+* ```
+  { display: { label: 'New User', description: 'Trigger when a new User is created in your account.' },
+    operation: 
+     { perform: { url: 'http://fake-crm.getsandbox.com/users' },
+       sample: { id: 49, name: 'Veronica Kuhn', email: 'veronica.kuhn@company.com' } } }
+  ```
+* ```
+  { display: 
+     { label: 'New User',
+       description: 'Trigger when a new User is created in your account.',
+       hidden: true },
+    operation: { perform: { url: 'http://fake-crm.getsandbox.com/users' } } }
+  ```
 
 #### Anti-Examples
 
-* `{ display: { label: 'New User', description: 'Trigger when a new User is created in your account.' }, operation: { perform: { url: 'http://fake-crm.getsandbox.com/users' } } }`
+* ```
+  { display: { label: 'New User', description: 'Trigger when a new User is created in your account.' },
+    operation: { perform: { url: 'http://fake-crm.getsandbox.com/users' } } }
+  ```
 
 #### Properties
 
@@ -900,12 +972,23 @@ How will we find a specific object given filters or search terms? Will be turned
 
 #### Examples
 
-* `{ display: { label: 'Find a Recipe', description: 'Search for recipe by cuisine style.' }, operation: { perform: '$func$2$f$', sample: { id: 1 } } }`
-* `{ display: { label: 'Find a Recipe', description: 'Search for recipe by cuisine style.', hidden: true }, operation: { perform: '$func$2$f$' } }`
+* ```
+  { display: { label: 'Find a Recipe', description: 'Search for recipe by cuisine style.' },
+    operation: { perform: '$func$2$f$', sample: { id: 1 } } }
+  ```
+* ```
+  { display: { label: 'Find a Recipe', description: 'Search for recipe by cuisine style.', hidden: true },
+    operation: { perform: '$func$2$f$' } }
+  ```
 
 #### Anti-Examples
 
-* `{ key: 'recipe', noun: 'Recipe', display: { label: 'Find a Recipe', description: 'Search for recipe by cuisine style.' }, operation: { perform: '$func$2$f$' } }`
+* ```
+  { key: 'recipe',
+    noun: 'Recipe',
+    display: { label: 'Find a Recipe', description: 'Search for recipe by cuisine style.' },
+    operation: { perform: '$func$2$f$' } }
+  ```
 
 #### Properties
 
@@ -928,14 +1011,57 @@ Represents a resource, which will in turn power triggers, searches, or creates.
 
 #### Examples
 
-* `{ key: 'tag', noun: 'Tag', get: { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' }, operation: { perform: { url: 'http://fake-crm.getsandbox.com/tags/{{inputData.id}}' }, sample: { id: 385, name: 'proactive enable ROI' } } } }`
-* `{ key: 'tag', noun: 'Tag', sample: { id: 385, name: 'proactive enable ROI' }, get: { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' }, operation: { perform: { url: 'http://fake-crm.getsandbox.com/tags/{{inputData.id}}' } } } }`
-* `{ key: 'tag', noun: 'Tag', get: { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.', hidden: true }, operation: { perform: { url: 'http://fake-crm.getsandbox.com/tags/{{inputData.id}}' } } }, list: { display: { label: 'New Tag', description: 'Trigger when a new Tag is created in your account.' }, operation: { perform: { url: 'http://fake-crm.getsandbox.com/tags' }, sample: { id: 385, name: 'proactive enable ROI' } } } }`
+* ```
+  { key: 'tag',
+    noun: 'Tag',
+    get: 
+     { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' },
+       operation: 
+        { perform: { url: 'http://fake-crm.getsandbox.com/tags/{{inputData.id}}' },
+          sample: { id: 385, name: 'proactive enable ROI' } } } }
+  ```
+* ```
+  { key: 'tag',
+    noun: 'Tag',
+    sample: { id: 385, name: 'proactive enable ROI' },
+    get: 
+     { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' },
+       operation: { perform: { url: 'http://fake-crm.getsandbox.com/tags/{{inputData.id}}' } } } }
+  ```
+* ```
+  { key: 'tag',
+    noun: 'Tag',
+    get: 
+     { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.', hidden: true },
+       operation: { perform: { url: 'http://fake-crm.getsandbox.com/tags/{{inputData.id}}' } } },
+    list: 
+     { display: { label: 'New Tag', description: 'Trigger when a new Tag is created in your account.' },
+       operation: 
+        { perform: { url: 'http://fake-crm.getsandbox.com/tags' },
+          sample: { id: 385, name: 'proactive enable ROI' } } } }
+  ```
 
 #### Anti-Examples
 
-* `{ key: 'tag', noun: 'Tag', get: { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' }, operation: { perform: { url: 'http://fake-crm.getsandbox.com/tags/{{inputData.id}}' } } }, list: { display: { label: 'New Tag', description: 'Trigger when a new Tag is created in your account.' }, operation: { perform: { url: 'http://fake-crm.getsandbox.com/tags' }, sample: { id: 385, name: 'proactive enable ROI' } } } }`
-* `{ key: 'tag', noun: 'Tag', get: { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' }, operation: { perform: { url: 'http://fake-crm.getsandbox.com/tags/{{inputData.id}}' } } } }`
+* ```
+  { key: 'tag',
+    noun: 'Tag',
+    get: 
+     { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' },
+       operation: { perform: { url: 'http://fake-crm.getsandbox.com/tags/{{inputData.id}}' } } },
+    list: 
+     { display: { label: 'New Tag', description: 'Trigger when a new Tag is created in your account.' },
+       operation: 
+        { perform: { url: 'http://fake-crm.getsandbox.com/tags' },
+          sample: { id: 385, name: 'proactive enable ROI' } } } }
+  ```
+* ```
+  { key: 'tag',
+    noun: 'Tag',
+    get: 
+     { display: { label: 'Get Tag by ID', description: 'Grab a specific Tag by ID.' },
+       operation: { perform: { url: 'http://fake-crm.getsandbox.com/tags/{{inputData.id}}' } } } }
+  ```
 
 #### Properties
 
@@ -1040,13 +1166,28 @@ How will Zapier search for existing objects?
 
 #### Examples
 
-* `{ key: 'recipe', noun: 'Recipe', display: { label: 'Find a Recipe', description: 'Search for recipe by cuisine style.' }, operation: { perform: '$func$2$f$', sample: { id: 1 } } }`
-* `{ key: 'recipe', noun: 'Recipe', display: { label: 'Find a Recipe', description: 'Search for recipe by cuisine style.', hidden: true }, operation: { perform: '$func$2$f$' } }`
+* ```
+  { key: 'recipe',
+    noun: 'Recipe',
+    display: { label: 'Find a Recipe', description: 'Search for recipe by cuisine style.' },
+    operation: { perform: '$func$2$f$', sample: { id: 1 } } }
+  ```
+* ```
+  { key: 'recipe',
+    noun: 'Recipe',
+    display: { label: 'Find a Recipe', description: 'Search for recipe by cuisine style.', hidden: true },
+    operation: { perform: '$func$2$f$' } }
+  ```
 
 #### Anti-Examples
 
 * `'abc'`
-* `{ key: 'recipe', noun: 'Recipe', display: { label: 'Find a Recipe', description: 'Search for recipe by cuisine style.' }, operation: { perform: '$func$2$f$' } }`
+* ```
+  { key: 'recipe',
+    noun: 'Recipe',
+    display: { label: 'Find a Recipe', description: 'Search for recipe by cuisine style.' },
+    operation: { perform: '$func$2$f$' } }
+  ```
 
 #### Properties
 
@@ -1091,12 +1232,27 @@ How will Zapier get notified of new objects?
 
 #### Examples
 
-* `{ key: 'new_recipe', noun: 'Recipe', display: { label: 'New Recipe', description: 'Triggers when a new recipe is added.' }, operation: { type: 'polling', perform: '$func$0$f$', sample: { id: 1 } } }`
-* `{ key: 'new_recipe', noun: 'Recipe', display: { label: 'New Recipe', description: 'Triggers when a new recipe is added.', hidden: true }, operation: { type: 'polling', perform: '$func$0$f$' } }`
+* ```
+  { key: 'new_recipe',
+    noun: 'Recipe',
+    display: { label: 'New Recipe', description: 'Triggers when a new recipe is added.' },
+    operation: { type: 'polling', perform: '$func$0$f$', sample: { id: 1 } } }
+  ```
+* ```
+  { key: 'new_recipe',
+    noun: 'Recipe',
+    display: { label: 'New Recipe', description: 'Triggers when a new recipe is added.', hidden: true },
+    operation: { type: 'polling', perform: '$func$0$f$' } }
+  ```
 
 #### Anti-Examples
 
-* `{ key: 'new_recipe', noun: 'Recipe', display: { label: 'New Recipe', description: 'Triggers when a new recipe is added.' }, operation: { perform: '$func$0$f$' } }`
+* ```
+  { key: 'new_recipe',
+    noun: 'Recipe',
+    display: { label: 'New Recipe', description: 'Triggers when a new recipe is added.' },
+    operation: { perform: '$func$0$f$' } }
+  ```
 
 #### Properties
 

lib/utils/buildDocs.js

@@ -32,14 +32,29 @@ const collectSchemas = InitSchema => {
   return schemas;
 };
 
-const quoteOrNa = val => (val ? `\`${val.replace('`', '')}\`` : '_n/a_');
+const BREAK_LENGTH = 96;
+const prepQuote = val => val.replace('`', '');
+const quote = (val, triple, indent = '') =>
+  // either ``` with optional indentation or `
+  triple && val.length > BREAK_LENGTH
+    ? '```\n' +
+      val
+        .match(/[^\r\n]+/g)
+        .map(line => indent + line)
+        .join('\n') +
+      '\n' +
+      indent +
+      '```'
+    : `\`${prepQuote(val)}\``;
+const quoteOrNa = (val, triple = false, indent = '') =>
+  val ? quote(val, triple, indent) : '_n/a_';
 
 const formatExample = example => {
   const ex = _.isPlainObject(example) ? _.omit(example, SKIP_KEY) : example;
   return `* ${quoteOrNa(
-    // GH parses the newlines in bullets correctly, but it's a good thing to fix
-    // docs say Infinity for no line break at all
-    util.inspect(ex, { depth: null, breakLength: Infinity })
+    util.inspect(ex, { depth: null, breakLength: BREAK_LENGTH }),
+    true,
+    '  '
   )}`;
 };