docs: sync exported markdown to RDMD site

.github/workflows/release.yml

@@ -47,7 +47,6 @@ jobs:
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           branch: ${{ github.ref }}
-        continue-on-error: true
 
       # Merge @latest release back to @next.
       #
@@ -58,3 +57,11 @@ jobs:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           branch: next
         continue-on-error: true
+
+      # Sync docs to rdmd.readme.io
+      #
+      - name: Sync docs to rdmd.readme.io
+        if: "github.ref == 'refs/heads/master'"
+        run: npm run sync -- --key=$KEY
+        env:
+          KEY: ${{ secrets.RDME_KEY }}

example/Fixtures/Syntax/callouts.md → docs/callouts.md

@@ -1,11 +1,25 @@
+---
+title: "Callouts"
+slug: "callouts"
+hidden: false
+metadata: 
+  title: "Callouts — ReadMe-Favored Markdown"
+  description: "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, which is used to determine the callout's theme."
+  image: 
+    0: "https://files.readme.io/9134da7-rdmd.readme-stage-pr-2438.readme.ninja_docs_callouts.png"
+    1: "rdmd.readme-stage-pr-2438.readme.ninja_docs_callouts.png"
+    2: 530
+    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
+    > 👍 [Success](#edge-cases)
     > 
     > Vitae reprehenderit at aliquid error voluptates eum dignissimos.
 
@@ -19,19 +33,6 @@ 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"
@@ -61,6 +62,22 @@ 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"
@@ -89,21 +106,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>
@@ -117,63 +134,61 @@ And voilà...
 
 ### Custom Icons
 
-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.
+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>
 
-With a touch of Custom CSS, we should be able to get a callout using the 📷 emoji to display an icon font glyph!
+Here's what it looks like by default:
 
-```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:
 
-<div id="my-theme">
+And here it is with our custom CSS:
+</details>
 
 > 📸 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=📷] {
-  --icon-font-family: FontAwesome; /* copied from https://fontawesome.com/v4.7.0/icon/camera-retro */
+  /* etc. */
+  --icon-font-family: 
 }
 ```
+[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]

example/Fixtures/Syntax/code-blocks/code-block-tests.md → docs/code-block-tests.md

@@ -1,5 +1,11 @@
+---
+title: "Code Block Tests"
+slug: "code-block-tests"
+hidden: true
+---
 Basics
 ===
+
 ### Simple
 ```php
 <b><?= "Hello world!" ?></b>;

example/Fixtures/Syntax/code-blocks.md → docs/code-blocks.md

@@ -1,3 +1,9 @@
+---
+title: "Code Blocks"
+slug: "code-blocks"
+hidden: false
+---
+
 [block:api-header]
 {
   "title": "Examples"
@@ -106,4 +112,4 @@ We support syntax highlighting on a number of languages:
 | SQL | `cql`, `mssql`, `mysql`, `plsql`, `postgres`, `postgresql`, `pgsql`, `sql`, `sqlite` |
 | Swift | `swift` |
 | TypeScript | `ts`, `typescript` |
-| YAML | `yaml`, `yml` |
+| YAML | `yaml`, `yml` |

docs/custom-css.md

@@ -0,0 +1,55 @@
+---
+title: "Custom Styling"
+slug: "custom-css"
+excerpt: "Styling best-practices and CSS selector references."
+hidden: false
+---
+By and large, the new markdown processor outputs standard HTML. This means most basic CSS element selectors will continue to work seamlessly. Depending on how complex your Markdown and custom CSS are, you should only have to update a few styles here and there!
+
+> 🐷 **Need CSS Help?**
+>
+> We're always happy to help troubleshoot tricky styling issues! [Shoot us an email](mailto:[email protected]?subject=ReadMe-Flavored+Markdown+Feedback), and we'll try to make ourselves useful.
+
+## Scoping Your Styles
+
+When writing custom styles for the new processor, you should explicitly target content generated by the new Markdown engine using the **`.markdown-body`** class prefix. You can also style Markdown for a specific template by adding additional prefixes.
+
+```scss Markdown Selector Scope
+/* Guides Pages */
+#content-body .markdown-body {}
+
+/* Reference Pages */
+#api-explorer .markdown-body {}
+#api-explorer .markdown-body > .pin {} /* target pinned sidebar content */
+```
+
+> **Note**: The `.markdown-body` prefix is unique to the new engine, which is useful when refactoring custom styles. In the run up to the production release, this can be a useful “hook” for progressively enhancing your custom CSS. Just prefix your selectors with the `.markdown-body` class and appending the new ruleset to your custom CSS
+
+## CSS Variables Theming
+
+The new Markdown engine uses CSS variables to enable simple theming for all modern browsers (i.e. IE11+.) Certain custom components offer their own theme variables. The markdown engine also offers some high-level theming variables:
+
+```css
+.markdown-body {
+  --markdown-radius: 3px;
+  --markdown-font: Papyrus, serif;
+  --markdown-text: #333;
+  --markdown-title: hotpink;
+  --markdown-lineHeight: 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

@@ -0,0 +1,35 @@
+---
+title: "Embeds"
+slug: "embeds"
+hidden: false
+---
+[block:api-header]
+{
+  "title": "Syntax"
+}
+[/block]
+Embedded content is written as a simple Markdown link, with a title of "@embed", like so:
+
+    [Embed Title](https://youtu.be/8bh238ekw3 "@embed")
+[block:api-header]
+{
+  "title": "Examples"
+}
+[/block]
+### Magic Block
+[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>",
+  "url": "https://www.youtube.com/watch?v=J3-uKv1DShQ&feature=youtu.be",
+  "title": "Funny Solidier Drop Kick",
+  "favicon": "https://s.ytimg.com/yts/img/favicon-vfl8qSV2F.ico",
+  "image": "https://i.ytimg.com/vi/J3-uKv1DShQ/hqdefault.jpg"
+}
+[/block]
+### Markdown Block
+
+[Embed Title](https://youtu.be/8bh238ekw3 "@embed")
+
+## 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.

example/Fixtures/Syntax/features.md → docs/features.md

@@ -1,11 +1,12 @@
+---
+title: "And more..."
+slug: "features"
+excerpt: "Additional Markdown features of the ReadMe platform implementation."
+hidden: false
+---
 We've also built a lot of great features right in to the ReadMe app, which work on top of our markdown engine to give your developers a best-in-class documentation experience. These features aren't all baked in to the new engine itself, but they're worth mentioning nonetheless!
 
-## Sectioning Semantics
-
-- Automatic **table of contents** based on sections.
-- Generated **[heading anchor links](doc:headings#section-incremented-anchors)**.
-
-## Data Injection
+## Data Replacement
 
 #### User Variables
 
@@ -30,3 +31,12 @@ You can use GitHub-style emoji short codes (feat. Owlbert!)
     :sparkles: :owlbert-reading:
 
 This expands out to: “:sparkles: :owlbert-reading:”
+
+## Generative Semantics
+
+- Markup-based TOC generation.
+- Auto-generated [heading anchors](doc:headings#section-incremented-anchors).
+
+## Known Issues
+
+- Variable and glossary term expansions are rendered even when they've been manually escaped by the author.