markdownify docs

.editorconfig

@@ -13,7 +13,7 @@ indent_size = 2
 indent_style = space
 
 # some files use 4 spaces for indentation
-[*.{js,jsx,ts,tsx,java,xml}]
+[*.{js,jsx,ts,tsx,java,xml,md}]
 indent_size = 4
 
 [*.java]

mdify.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+const glob = require("glob");
+const fs = require("fs");
+
+// captures: [title, body, reference]
+const BLOCK_REGEX = /\/\*\n(.+)\n\n((?:.|\n)+?)\nStyleguide:? (.+)\n\*\//g;
+
+const HEADINGS = "######";
+
+glob.sync("packages/core/src/components/*/*.scss")
+    .filter((filepath) => !/common\.scss$/.test(filepath))
+    .forEach((comp) => {
+        const scss = fs.readFileSync(comp, "utf-8").replace(/^ */gm, "");
+        const contents = [`---\nparent: ${comp.indexOf("/forms/") > 0 ? "forms" : "components"}\n---`];
+
+        /** @type {RegExpExecArray} */
+        let match;
+        // tslint:disable-next-line:no-conditional-assignment
+        while ((match = BLOCK_REGEX.exec(scss)) !== null) {
+            const [title, body, reference] = match.slice(1);
+            const depth = reference.split(".").length - 1;
+
+            contents.push(
+                `${HEADINGS.slice(0, depth)} ${title}`,
+                body.trim().replace(/@\w+(-\w+)/g, (tag, ext) => tag.replace(ext, ext[1].toUpperCase() + ext.slice(2)))
+            );
+        }
+        fs.writeFileSync(comp.replace(".scss", ".md").replace("/_", "/"), contents.join("\n\n") + "\n");
+    });

packages/core/src/components/_index.scss

@@ -172,7 +172,6 @@ Styleguide components.usage.vanilla
 @import "callout/callout";
 @import "card/card";
 @import "collapse/collapse";
-@import "collapsible-list/collapsible-list";
 @import "context-menu/context-menu";
 @import "dialog/dialog";
 @import "editable-text/editable-text";

packages/core/src/components/alert/_alert.scss

@@ -5,37 +5,6 @@
 
 @import "../../common/variables";
 
-/*
-Alerts
-
-Alerts notify users of important information and force them to acknowledge the alert content before
-continuing.
-
-Although similar to [dialogs](#components.dialog), alerts are more restrictive and should only be
-used for important notifications. The user can only exit the alert by clicking one of the
-confirmation buttons — clicking the overlay or pressing the <kbd class="pt-key">esc</kbd> key will
-not close the alert.
-
-You can only use this component in controlled mode. Use the `onClick` handlers in the primary and
-secondary action props to handle closing the `Alert`. Optionally, display an icon next to the body
-to show the type of the alert.
-
-@react-example AlertExample
-
-Styleguide components.alert
-*/
-
-/*
-JavaScript API
-
-The `Alert` component is available in the __@blueprintjs/core__ package.
-Make sure to review the [general usage docs for JS components](#components.usage).
-
-@interface IAlertProps
-
-Styleguide components.alert.js
-*/
-
 .pt-alert {
   max-width: $pt-grid-size * 40;
   padding: $pt-grid-size * 2;

packages/core/src/components/alert/alert.md

@@ -0,0 +1,21 @@
+@# Alerts
+
+Alerts notify users of important information and force them to acknowledge the alert content before
+continuing.
+
+Although similar to [dialogs](#components.dialog), alerts are more restrictive and should only be
+used for important informations. The user can only exit the alert by clicking one of the
+confirmation buttons—clicking the overlay or pressing the `esc` key will not close the alert.
+
+You can only use this component in controlled mode. Use the `onClick` handlers in the primary and
+secondary action props to handle closing the `Alert`. Optionally, display an icon next to the body
+to show the type of the alert.
+
+@reactExample AlertExample
+
+@## JavaScript API
+
+The `Alert` component is available in the __@blueprintjs/core__ package.
+Make sure to review the [general usage docs for JS components](#components.usage).
+
+@interface IAlertProps

packages/core/src/components/breadcrumbs/_breadcrumbs.scss

@@ -8,31 +8,6 @@
 @import "../../common/variables";
 
 /*
-Breadcrumbs
-
-Breadcrumbs identify the current resource in an application.
-
-Styleguide components.breadcrumbs
-*/
-
-/*
-CSS API
-
-* Begin with a `ul.pt-breadcrumbs`; each crumb should be in its own `li` as a direct descendant.
-* Breadcrumbs are typically navigation links (for example, to the parent folder in a file path), and
-  therefore should use `<a>` tags (except for the final breadcrumb).
-* Each navigation breadcrumb should use `.pt-breadcrumb`.
-* Make a breadcrumb non-interactive with the `.pt-disabled` class. You should only use this
-  state when you want to indicate that the user cannot navigate to the breadcrumb (for example, if
-  the user does not have permission to access it). Otherwise, clicking a breadcrumb should take the
-  user to that resource.
-* Mark the final breadcrumb `.pt-breadcrumb-current` for an emphasized appearance.
-* The `.pt-breadcrumbs-collapsed` button-like element can be used as the target for a dropdown menu
-  containing breadcrumbs that are collapsed due to layout constraints.
-* When adding another element (such as a [tooltip](#components.tooltip) or
-  [popover](#components.popover)) to a breadcrumb, wrap it around the contents of the `li`.
-
-
 Markup:
 <ul class="pt-breadcrumbs">
   <li><a class="pt-breadcrumbs-collapsed" href="#"></a></li>
@@ -41,24 +16,6 @@ Markup:
   <li><a class="pt-breadcrumb" href="#">Folder three</a></li>
   <li><span class="pt-breadcrumb pt-breadcrumb-current">File</span></li>
 </ul>
-
-Styleguide components.breadcrumbs.css
-*/
-
-/*
-JavaScript API
-
-The `Breadcrumb` component is available in the __@blueprintjs/core__ package.
-Make sure to review the [general usage docs for JS components](#components.usage).
-
-The component renders an `a.pt-breadcrumb`.
-You are responsible for constructing the `ul.pt-breadcrumbs` list.
-[`CollapsibleList`](#components.collapsiblelist) works nicely with this component
-because its props are a subset of `IMenuItemProps`.
-
-@interface IBreadcrumbProps
-
-Styleguide components.breadcrumbs.js
 */
 
 // shaving off 1px for perfect centering (... icon is 5px high)

packages/core/src/components/breadcrumbs/breadcrumbs.md

@@ -0,0 +1,30 @@
+@# Breadcrumbs
+
+Breadcrumbs identify the current resource in an application.
+
+@## CSS API
+
+* Begin with a `ul.pt-breadcrumbs`; each crumb should be in its own `li` as a direct descendant.
+* Breadcrumbs are typically navigation links (for example, to the parent folder in a file path), and
+therefore should use `<a>` tags (except for the final breadcrumb).
+* Each navigation breadcrumb should use `.pt-breadcrumb`.
+* Make a breadcrumb non-interactive with the `.pt-disabled` class. You should only use this
+state when you want to indicate that the user cannot navigate to the breadcrumb (for example, if
+the user does not have permission to access it). Otherwise, clicking a breadcrumb should take the
+user to that resource.
+* Mark the final breadcrumb `.pt-breadcrumb-current` for an emphasized appearance.
+* The `.pt-breadcrumbs-collapsed` button-like element can be used as the target for a dropdown menu
+containing breadcrumbs that are collapsed due to layout constraints.
+* When adding another element (such as a [tooltip](#components.tooltip) or
+[popover](#components.popover)) to a breadcrumb, wrap it around the contents of the `li`.
+
+@## JavaScript API
+
+The `Breadcrumb` component is available in the __@blueprintjs/core__ package.
+Make sure to review the [general usage docs for JS components](#components.usage).
+
+The component renders an `a.pt-breadcrumb`. You are responsible for constructing
+the `ul.pt-breadcrumbs` list. [`CollapsibleList`](#components.collapsiblelist)
+works nicely with this component because its props are a subset of `IMenuItemProps`.
+
+@interface IBreadcrumbProps

packages/core/src/components/button/_button-group.scss

@@ -9,21 +9,6 @@
 @import "./common";
 
 /*
-Button groups
-
-Button groups arrange multiple buttons in a horizontal or vertical group.
-
-Styleguide components.button-group
-*/
-
-/*
-CSS API
-
-Arrange multiple buttons in a group by wrapping them in `.pt-button-group`.
-You can apply sizing directly on the button group container element.
-
-You should implement interactive segmented controls as button groups.
-
 Markup:
 <div class="pt-button-group {{.modifier}}">
   <a class="pt-button pt-icon-database" tabindex="0" role="button">Queries</a>
@@ -53,8 +38,6 @@ Markup:
 .pt-large - Use large buttons
 .pt-minimal - Use minimal buttons. Note that these minimal buttons will not automatically
               truncate text in an ellipsis because of the divider line added in CSS.
-
-Styleguide components.button-group.css
 */
 
 .pt-button-group {
@@ -167,17 +150,6 @@ Styleguide components.button-group.css
   }
 
   /*
-  Responsive button groups
-
-  Add the class `pt-fill` to a button group to make all buttons expand equally to fill the
-  available space. Then add the class `pt-fixed` to individual buttons to revert them to their
-  original default sizes.
-
-  Alternatively, add the class `pt-fill` to an individual button (instead of to the container)
-  to expand it to fill the available space while other buttons retain their original sizes.
-
-  You can adjust the specific size of a button with the `flex-basis` CSS property.
-
   Markup:
   <div class="pt-button-group pt-large pt-fill">
     <a class="pt-button pt-intent-primary pt-fixed" tabindex="0" role="button">Start</a>
@@ -192,8 +164,6 @@ Styleguide components.button-group.css
     <button class="pt-button pt-fill">Middle</button>
     <button class="pt-button pt-icon-arrow-right"></button>
   </div>
-
-  Styleguide components.button-group.css.fill
   */
 
   &.pt-fill {
@@ -206,23 +176,14 @@ Styleguide components.button-group.css
   }
 
   /*
-  Vertical button groups
-
-  Add the class `pt-vertical` to create a vertical button group. The buttons in a vertical
-  group all have the same size as the widest button in the group.
-
-  Add the modifier class `pt-align-left` to left-align all button text and icons.
-
-  You can also combine vertical groups with the `pt-fill` and `pt-minimal` class modifiers.
-
   Markup:
-  <div class="pt-button-group pt-vertical" style="padding-right: 10px">
+  <div class="pt-button-group pt-vertical">
     <a class="pt-button pt-icon-search-template" role="button" tabindex="0"></a>
     <a class="pt-button pt-icon-zoom-in" role="button" tabindex="0"></a>
     <a class="pt-button pt-icon-zoom-out" role="button" tabindex="0"></a>
     <a class="pt-button pt-icon-zoom-to-fit" role="button" tabindex="0"></a>
   </div>
-  <div class="pt-button-group pt-vertical" style="padding-right: 10px">
+  <div class="pt-button-group pt-vertical">
     <button type="button" class="pt-button pt-active">Home</button>
     <button type="button" class="pt-button">Pages</button>
     <button type="button" class="pt-button">Blog</button>
@@ -233,8 +194,6 @@ Styleguide components.button-group.css
     <button type="button" class="pt-button pt-intent-primary pt-icon-media pt-active">Media</button>
     <button type="button" class="pt-button pt-intent-primary pt-icon-link">Sources</button>
   </div>
-
-  Styleguide components.button-group.css.vertical
   */
 
   &.pt-vertical {