docs: update docs to latest markdown (#107)

docs/callouts.md

@@ -12,14 +12,15 @@ metadata:
     3: 173
     4: "#edf3ec"
 ---
+
 [block:api-header]
 {
   "title": "Syntax"
 }
 [/block]
 Callouts are very nearly equivalent to standard Markdown block quotes in their syntax, other than some specific requirements on their content: To be considered a “callout”, a block quote must start with an initial emoji. This is used to determine the callout's theme. Here's an example of how you might write a warning callout.
 
-    > 👍 [Success](#edge-cases)
+    > 👍 Success
     > 
     > Vitae reprehenderit at aliquid error voluptates eum dignissimos.
 
@@ -33,6 +34,19 @@ Default themes are specified using one of the following emojis. (If you don't li
 | 👍 | `.callout_okay` | ✅ |
 | 🚧 | `.callout_warn` | ⚠️ |
 | ❗️ | `.callout_error` | 🛑 |
+
+<hr>
+<details><summary><em>Tips & Tricks </em></summary><br>
+
+If you have a block quote that starts with an initial emoji which *should not* be rendered as a ReadMe callout, just bold the emoji. It's a bit of a hack for sure, but it's easy enough, and hey: it works! So this:
+
+    > **👋** Lorem ipsum dolor sit amet consectetur adipisicing elit.
+
+Renders to a plain ol' block quote:
+
+> **👋** Lorem ipsum dolor sit amet consectetur adipisicing elit.
+
+</details><hr>
 [block:api-header]
 {
   "title": "Examples"
@@ -62,22 +76,6 @@ If a callout starts with an emoji that's not dedicated to one of the themes (abo
 > 🥇 Themeless
 >
 > Lorem ipsum dolor sit amet consectetur adipisicing elit.
-
-<!--
-> ✅ Default themes using the alternate emoji!
--->
-
-<details><summary><em>Tips & Tricks </em></summary><hr>
-
-If you have a block quote that starts with an initial emoji which *should not* be rendered as a ReadMe callout, just bold the emoji. It's a bit of a hack for sure, but it's easy enough, and hey: it works! So this:
-
-    > **👋** Lorem ipsum dolor sit amet consectetur adipisicing elit.
-
-Renders to a plain ol' block quote:
-
-> **👋** Lorem ipsum dolor sit amet consectetur adipisicing elit.
-
-</details><hr>
 [block:api-header]
 {
   "title": "Custom CSS"
@@ -106,21 +104,21 @@ Callouts come in [various themes](#section--examples-). These can be customized
 
 Each callout will also have a `theme` attribute that's set to it's emoji prefix. Combined with a basic attribute selector, we should be able to create entirely new styles per-emoji, in addition to the built in themes above!
 
-```markdown Markdown Syntax
-> 🎅 Old Saint Nick
->
-> 'Twas the night before Christmas, when all through the house not a creature was stirring, not even a mouse. The stockings were hung by the chimney with care, in hopes that St. Nicholas soon would be there. The children were nestled all snug in their beds, while visions of sugar plums danced in their heads.
-```
 ```css Custom CSS
 .markdown-body .callout[theme="🎅"] {
   --background: #c54245;
   --border: #ffffff6b;
   --text: #f5fffa;
 }
 ```
+```markdown Markdown Syntax
+> 🎅 Old Saint Nick
+>
+> 'Twas the night before Christmas, when all through the house not a creature was stirring, not even a mouse. The stockings were hung by the chimney with care, in hopes that St. Nicholas soon would be there. The children were nestled all snug in their beds, while visions of sugar plums danced in their heads.
+```
 ```html Generated HTML
+<!-- condensed for clarity! -->
 <blockquote class="callout callout_default" theme="🎅">
-  <!-- essentially -->
   <h3>🎅 Old Saint Nick</h3>
   <p>'Twas the night before Christmas, when all through the house not a creature was stirring, not even a mouse. The stockings were hung by the chimney with care, in hopes that St. Nicholas soon would be there. The children were nestled all snug in their beds, while visions of sugar plums danced in their heads.</p>
 </blockquote>
@@ -134,61 +132,63 @@ And voilà...
 
 ### Custom Icons
 
-What if we wanted to use a custom icon instead of the emoji? With just a touch of Custom CSS, we should be able to display the callout's 📷 emoji using the icon glyph we found on FontAwesome's site!
-[block:code]
-{
-  "codes": [
-    {
-      "code": ".callout[theme=📷] {\n  --emoji: unset;\n  --icon: \"\\f083\";\n  --icon-color: #c50a50;\n}",
-      "language": "css",
-      "name": "Custom Icons CSS"
-    }
-  ]
-}
-[/block]
-<details><summary>This works like a charm! (Click to compare the custom icon against the default.)</summary><br>
+Emojis are already a pretty good starting point as far as default icon options go! There are a *lot* of 'em, and they're supported across nearly all platforms. But what if we're going for a different look, or need to match our docs to a branding kit? Icons are a big part of setting the "tone" for your site.
 
-Here's what it looks like by default:
+With a touch of Custom CSS, we should be able to get a callout using the 📷 emoji to display an icon font glyph!
 
+```css Custom CSS
+.callout[theme=📷] {
+  --emoji: unset;
+  --icon: "\f083"; /* copied front FontAwesome */
+  --icon-color: #c50a50;
+}
+```
+``` Markdown Syntax
 > 📷 Cool pix!
+>
 > Vitae reprehenderit at aliquid error voluptates eum dignissimos.
+```
+
+This works like a charm:
 
-And here it is with our custom CSS:
-</details>
+<div id="my-theme">
 
 > 📸 Cool pix!
 > Vitae reprehenderit at aliquid error voluptates eum dignissimos.
+[block:html]
+{
+  "html": "<style>\n  #my-theme .callout[theme=📸] {\n    --emoji: unset;\n    --icon: \"\";\n  }\n  #my-theme .callout[theme=📷],\n  #my-theme .callout[theme=📸] {\n    --icon-color: #c50a50;\n    --border: var(--icon-color);\n    --title: var(--icon-color);\n  }\n  summary {\n    outline: none;\n    user-select: none;\n  }\n</style>"
+}
+[/block]
+</div>
+
+<hr><details><summary><em>Setting the Custom Icon Font</em></summary><br>
 
 The custom icon font defaults to `FontAwesome`, but you can use any font family available on the page by setting the `--icon-font` variable!
 
 ```css
 .callout[theme=📷] {
-  /* etc. */
-  --icon-font-family: 
+  --icon-font-family: FontAwesome; /* copied from https://fontawesome.com/v4.7.0/icon/camera-retro */
 }
 ```
-[block:html]
-{
-  "html": "<style>\n  .callout[theme=📸] {\n    --emoji: unset;\n    --icon: \"\";\n  }\n  .callout[theme=📷],\n  .callout[theme=📸] {\n    --icon-color: #c50a50;\n    --border: var(--icon-color);\n    --title: var(--icon-color);\n  }\n  details, summary {\n    outline: none;\n  }\n</style>"
-}
-[/block]
 
+</details><hr>
 [block:api-header]
 {
   "title": "Edge Cases"
 }
 [/block]
 Callouts don't need to have any body text:
 
-> 🥈  No body text.
+> 🥇  No body text.
 
 You can also skip the title, if you're so inclined!
 
-> 🥉  
+> 🥈  
 > 
 > Lorem ipsum dolor sit amet consectetur adipisicing elit. Error eos animi obcaecati quod repudiandae aliquid nemo veritatis ex, quos delectus minus sit omnis vel dolores libero, recusandae ea dignissimos iure?
 [block:html]
 {
   "html": "<style>\n.markdown-body .callout[theme=\"🎅\"] {\n  --background: #c50a4f;\n  --border: #ffffff6b;\n  --text: #f5fffa;\n}\n</style>"
 }
-[/block]
+[/block]

docs/custom-css.md

@@ -35,21 +35,6 @@ The new Markdown engine uses CSS variables to enable simple theming for all mode
   --markdown-font: Papyrus, serif;
   --markdown-text: #333;
   --markdown-title: hotpink;
-  --markdown-lineHeight: 2;
+  --markdown-line-height: 2;
 }
 ```
-
-## Styling Components
-
-### Callouts
-
-Our callouts have been refactored to be based on the default block quote element and styling. It comes with various themes, which can be customized using the following selectors. [**More**](doc:callouts)...
-
-### Tables
-
-Tables have been simplified to mirror a more standard implementation, which should make them easier to style. [**More**](doc:tables)...
-[block:html]
-{
-  "html": "<style>\n.callout.callout_default[theme=🐷] {\n  --background: #fdf2fa;\n  --title: #ed32ba;\n  --border: var(--title);\n}\n</style>"
-}
-[/block]

docs/embeds.md

@@ -3,6 +3,7 @@ title: "Embeds"
 slug: "embeds"
 hidden: false
 ---
+
 [block:api-header]
 {
   "title": "Syntax"
@@ -16,7 +17,27 @@ Embedded content is written as a simple Markdown link, with a title of "@embed",
   "title": "Examples"
 }
 [/block]
-### Magic Block
+
+[block:embed]
+{
+  "html": false,
+  "url": "https://github.com/readmeio/api-explorer/pull/671",
+  "title": "RDMD CSS theming and style adjustments. by rafegoldberg · Pull Request #671 · readmeio/api-explorer",
+  "favicon": "https://github.com/favicon.ico",
+  "image": "https://avatars2.githubusercontent.com/u/6878153?s=400&v=4"
+}
+[/block]
+
+[block:embed]
+{
+  "html": false,
+  "url": "https://www.nytimes.com/2020/05/03/us/politics/george-w-bush-coronavirus-unity.html",
+  "title": "George W. Bush Calls for End to Pandemic Partisanship",
+  "favicon": "https://www.nytimes.com/vi-assets/static-assets/favicon-4bf96cb6a1093748bf5b3c429accb9b4.ico",
+  "image": "https://static01.nyt.com/images/2020/05/02/world/02dc-virus-bush-2/merlin_171999921_e857a690-fb9b-462d-a20c-28c8161107c9-facebookJumbo.jpg"
+}
+[/block]
+<details><summary><b>Magic Block</b> (Embedly)</summary><br>
 [block:embed]
 {
   "html": "<iframe class=\"embedly-embed\" src=\"//cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.youtube.com%2Fembed%2FJ3-uKv1DShQ%3Ffeature%3Doembed&display_name=YouTube&url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DJ3-uKv1DShQ&image=https%3A%2F%2Fi.ytimg.com%2Fvi%2FJ3-uKv1DShQ%2Fhqdefault.jpg&key=f2aa6fc3595946d0afc3d76cbbd25dc3&type=text%2Fhtml&schema=youtube\" width=\"640\" height=\"480\" scrolling=\"no\" title=\"YouTube embed\" frameborder=\"0\" allow=\"autoplay; fullscreen\" allowfullscreen=\"true\"></iframe>",
@@ -26,10 +47,28 @@ Embedded content is written as a simple Markdown link, with a title of "@embed",
   "image": "https://i.ytimg.com/vi/J3-uKv1DShQ/hqdefault.jpg"
 }
 [/block]
-### Markdown Block
+</details>
+<details><summary><b>Magic Block</b> (iFrame)</summary><br>
+[block:embed]
+{
+  "html": "<iframe class=\"embedly-embed\" src=\"//cdn.embedly.com/widgets/media.html?src=https%3A%2F%2Fwww.google.com%2Fmaps%2Fembed%2Fv1%2Fplace%3Fcenter%3D37.829698%252C-122.258166%26key%3DAIzaSyD9HrlRuI1Ani0-MTZ7pvzxwxi4pgW0BCY%26zoom%3D16%26q%3DMama%27s%2BRoyal%2BCafe&display_name=Google+Maps&url=https%3A%2F%2Fwww.google.com%2Fmaps%2Fplace%2FMama%27s%2BRoyal%2BCafe%2F%4037.829698%2C-122.258166%2C16z%2Fdata%3D%214m13%211m7%213m6%211s0x80857dfb145a04ff%3A0x96b17d967421636f%212s4126%2BOpal%2BSt%2C%2BOakland%2C%2BCA%2B94609%213b1%218m2%213d37.8296978%214d-122.2581661%213m4%211s0x0%3A0x722326b6c2ac7642%218m2%213d37.8277961%214d-122.2563006%3Fhl%3Den&image=http%3A%2F%2Fmaps-api-ssl.google.com%2Fmaps%2Fapi%2Fstaticmap%3Fcenter%3D37.829698%2C-122.258166%26zoom%3D15%26size%3D250x250%26sensor%3Dfalse&key=f2aa6fc3595946d0afc3d76cbbd25dc3&type=text%2Fhtml&schema=google\" width=\"600\" height=\"450\" scrolling=\"no\" title=\"Google Maps embed\" frameborder=\"0\" allow=\"autoplay; fullscreen\" allowfullscreen=\"true\"></iframe>",
+  "url": "https://www.google.com/maps/place/Mama's+Royal+Cafe/@37.829698,-122.258166,16z/data=!4m13!1m7!3m6!1s0x80857dfb145a04ff:0x96b17d967421636f!2s4126+Opal+St,+Oakland,+CA+94609!3b1!8m2!3d37.8296978!4d-122.2581661!3m4!1s0x0:0x722326b6c2ac7642!8m2!3d37.8277961!4d-122.2563006?hl=en",
+  "title": "Mama's Royal Cafe",
+  "favicon": "https://www.google.com/images/branding/product/ico/maps15_bnuw3a_32dp.ico",
+  "image": "http://maps-api-ssl.google.com/maps/api/staticmap?center=37.829698,-122.258166&zoom=15&size=250x250&sensor=false"
+}
+[/block]
+</details>
+<details><summary><b>Markdown Block</b></summary><br>
 
 [Embed Title](https://youtu.be/8bh238ekw3 "@embed")
 
-## Known Issues
+</details>
 
-At the moment, embed links written in the new ReadMe-flavored markdown syntax will simply display the link. (Magic block embeds will continue to work, though!) We're aware of the shortcoming, and plan to refactor this component as we move forward.
+## Known Issues
+At the moment, embed links written in the new ReadMe-flavored markdown syntax will simply display the link. (Magic block embeds will continue to work, though!) We're aware of the shortcoming, and plan to refactor this component as we move forward.
+[block:html]
+{
+  "html": "<style>\n  summary {\n    outline: none;\n    user-select: none;\n  }\n</style>"
+}
+[/block]

docs/getting-started.md

@@ -13,10 +13,10 @@ metadata:
     3: 315
     4: "#2caaf8"
 ---
-[<img src=https://github.com/readmeio/api-explorer/workflows/CI/badge.svg align=right />](https://www.npmjs.com/package/@readme/markdown) A remark-based Markdown engine for parsing and rendering ReadMe docs. (In fact, you're looking at it right now, since we've used it to render every doc in this project!)
+[<img src=https://github.com/readmeio/markdown/workflows/CI/badge.svg align=right style="margin-top: 3px; margin-bottom: 3px;" />](https://www.npmjs.com/package/@readme/markdown) A remark-based Markdown engine for parsing and rendering ReadMe docs. (In fact, you're looking at it right now, since we've used it to render every doc in this project!)
 
 ```bash
-npm i -S @readme/markdown
+npm install --save @readme/markdown
 ```
 
 > 🧙‍ **Backwards Compatible**
@@ -52,24 +52,24 @@ This gives you various methods and utilities:
 
 | Export        | Description                                    | Arguments        |
 |:------------- |:---------------------------------------------- | ----------------:|
-| *`react`*     |_default;_ returns a VDOM React tree           | `text`, `options`|
+| *`react`*     |_default;_ returns a VDOM React tree            | `text`, `options`|
 | *`html`*      | transform markdown in to HTML                  | `text`, `options`|
 | *`ast`*       | transform markdown to an mdast object          | `text`, `options`|
-| *`md`*        | transform mdast in to ReadMe-flavored markdown | `ast`, `options`|
+| *`md`*        | transform mdast in to ReadMe-flavored markdown | `ast`, `options` |
 
 ### Utilities
 
-The `rdmd.utils` export gives you access to various tools and configuration settings:
+The `utils` export gives you access to various tools and configuration settings:
 
 - **`options`**
   _a hash of default settings accepted by the rdmd engine._
   - `markdownOptions`—configuration object passed to `remark`
   - `correctnewlines`—flag to toggle newline transformation.
   - `normalize`—auto-normalize magic blocks before processing.
 - **`<GlossaryContext/>`** and **`<VariablesContext/>`**
-  React provider and consumer wrappers for [ReadMe data replacement.](doc:features#section-data-replacement).
+  React provider and consumer wrappers for [user data injection](doc:features#section-data-injection).
 [block:html]
 {
-  "html": "<style>\n  .markdown-body .callout.callout_default[theme=🧙‍]{\n    --background: #fffae7;\n  --border: #e6b8086e;\n  --title: #e0b400;\n  }\n</style>"
+  "html": "<style>\n  .markdown-body .callout.callout_default[theme=🧙‍]{\n    --background: #fffae7;\n    --border: #e6b8086e;\n    --title: #e0b400;\n  }\n</style>"
 }
-[/block]
+[/block]

docs/images.md

@@ -3,19 +3,29 @@ title: "Images"
 slug: "images"
 hidden: false
 ---
-[block:callout]
-{
-  "type": "warning",
-  "title": "Known Issue",
-  "body": "The ReadMe-flavored markdown engine does not currently support lightbox functionality (click-to-zoom). **[But we're working on it!](https://github.com/readmeio/api-explorer/issues/621)**"
-}
-[/block]
 ## Syntax
 
-    ![Alt text](https://cdn.path.to/some/image.jpg "Image Title")
+    ![Alt text](https://cdn.path.to/some/image.jpg "This is some image...")
 [block:api-header]
 {
   "title": "Examples"
 }
 [/block]
-![Bro eats pizza and makes an OK gesture.](https://files.readme.io/6f52e22-man-eating-pizza-and-making-an-ok-gesture.jpg "Pizza Face")
+
+[block:image]
+{
+  "images": [
+    {
+      "image": [
+        "https://files.readme.io/b8674d6-pizzabro.jpg",
+        "pizzabro.jpg",
+        1024,
+        682,
+        "#d1c8c5"
+      ],
+      "caption": "Click to zoom."
+    }
+  ]
+}
+[/block]
+<!-- ![Bro eats pizza and makes an OK gesture.](https://files.readme.io/6f52e22-man-eating-pizza-and-making-an-ok-gesture.jpg "Pizza Face") -->