diff --git a/.editorconfig b/.editorconfig index 72611bed18..38d0a2a141 100644 --- a/.editorconfig +++ b/.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] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8001324e7e..e79788a9f7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,7 +29,7 @@ A typical contributor workflow looks like this: 1. Create a new feature branch. We use a format like `[your-initials]/[short-name]`: `bd/refactor-buttons`. 1. Run the development server via `gulp` (no arguments). - - Navigate to http://localhost:9000/packages/docs/dist/ when the server starts. + - Navigate to http://localhost:9000/packages/docs-site/dist/ when the server starts. - See [Build tasks](https://github.com/palantir/blueprint/wiki/Build-tasks) on the wiki for more details on the inner workings of the Gulp build. - If you are contributing to the `table` or `landing` packages then run `npm start` in those diff --git a/Gulpfile.js b/Gulpfile.js index a7114a1576..98a7bb4d4d 100644 --- a/Gulpfile.js +++ b/Gulpfile.js @@ -71,11 +71,18 @@ const projects = [ }, { id: "docs", cwd: "packages/docs/", + dependencies: ["core"], + sass: "compile", + typescript: true, + }, { + id: "docs-site", + cwd: "packages/docs-site/", dependencies: [ // You must add your package to this dependency list if you have any // examples in the docs. "core", "datetime", + "docs", "table", ], sass: "bundle", @@ -87,6 +94,7 @@ const projects = [ // (they all import @blueprint/* but don't actually have themselves in their node_modules) "@blueprintjs/core", "@blueprintjs/datetime", + "@blueprintjs/docs", "@blueprintjs/table", "dom4", "moment", diff --git a/README.md b/README.md index b0c7265ce3..e2b3a006dc 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ __Prerequisite__: Node.js v6 or v7 1. `npm install` to install build dependencies 1. `npm run bootstrap` to install and link each package using [Lerna](https://lernajs.io/) 1. `npm run gulp` to compile and start the server and watcher -1. Open your browser to [localhost:9000/packages/docs/dist/](http://localhost:9000/packages/docs/dist/) +1. Open your browser to [localhost:9000/packages/docs-site/dist/](http://localhost:9000/packages/docs-site/dist/) ## Contributing diff --git a/circle.yml b/circle.yml index 9a57b6cccc..43381e1aef 100644 --- a/circle.yml +++ b/circle.yml @@ -4,6 +4,7 @@ general: - packages/core/dist - packages/datetime/dist - packages/docs/dist + - packages/docs-site/dist - packages/landing/dist - packages/table/dist # code coverage reports @@ -22,6 +23,7 @@ dependencies: - packages/core/node_modules - packages/datetime/node_modules - packages/docs/node_modules + - packages/docs-site/node_modules - packages/landing/node_modules - packages/table/node_modules # non-zero exit codes in `dependencies` group will fail the build early diff --git a/gulp/aliases.js b/gulp/aliases.js index 6bf2ba97b8..9cbb877baa 100644 --- a/gulp/aliases.js +++ b/gulp/aliases.js @@ -16,7 +16,7 @@ module.exports = (blueprint, gulp) => { gulp.task("compile", ["sass", "tsc", "copy"]); // generate docs data files - gulp.task("docs", ["docs-interfaces", "docs-kss", "docs-versions", "docs-releases"]); + gulp.task("docs", ["docs-json", "docs-versions", "docs-releases"]); // perform a full build of the code and then finish gulp.task("build", (done) => rs("clean", "compile", "bundle", "webpack-docs", done)); diff --git a/gulp/docs.js b/gulp/docs.js index 86d506d3d7..c3a2c12382 100644 --- a/gulp/docs.js +++ b/gulp/docs.js @@ -4,151 +4,47 @@ "use strict"; module.exports = (blueprint, gulp, plugins) => { + const dm = require("documentalist"); const glob = require("glob"); const path = require("path"); const text = require("./util/text"); - const tsdoc = require("ts-quick-docs"); const spawn = require("child_process").spawn; const semver = require("semver"); - const cwd = blueprint.findProject("docs").cwd; + const cwd = blueprint.findProject("docs-site").cwd; const config = { data: path.join(cwd, "src", "generated"), dest: path.join(cwd, "build"), - kssSources: blueprint.projectsWithBlock("sass").map((project) => path.join(project.cwd, "src")), + navPage: "_nav", }; // paths to data files used to generate documentation app const filenames = { - docs: "docs.json", - props: "props.json", + data: "docs.json", releases: "releases.json", - styleguide: path.join(cwd, "src", "styleguide.md"), versions: "versions.json", }; - const unwrapData = (section) => section.data; - - function processSection(section) { - return Object.assign({}, section, { - description: text.markdown(section.description), - highlightedMarkup: text.highlight(section.markup, "text.html.handlebars"), - modifiers: section.modifiers.map(unwrapData), - parameters: section.parameters.map(unwrapData), - sections: new Map(), - }); - } - - // find all flags: @[flag-name] [value?] - const FLAG_REGEX = /

@([\w-]+)(?:\s(.+))?<\/p>/g; - function processFlags(section) { - if (typeof section.description === "string") { - section.description = section.description.replace(FLAG_REGEX, function (m, flag, value) { - switch (flag) { - case "interface": - section.interfaceName = value; - break; - case "hide-markup": - section.hideMarkup = true; - break; - case "react-docs": - section.reactDocs = value; - break; - case "react-example": - section.reactExample = value; - break; - case "angular-example": - section.angularExample = value; - break; - default: - break; - } - // remove flag from output - return ""; - }); - } - return section; - } - - let parentsStack = []; - /** - * Convert a flat array of pages to a nested structure. Repeated references will overwrite previous instances. - * Keeps a stack of parent sections so every new section can be added to its parent. - * @param {Map} pages map of reference to section, to ensure uniqueness - * @param {Object} section - * @return {Map} of top-level pages, each of which contains its sections. - */ - function nestPages(pages, section) { - // pop the stack till we find the nearest parent - let parentPage = parentsStack.pop(); - while (parentPage != null && section.depth <= parentPage.depth) { - parentPage = parentsStack.pop(); - } - if (parentPage == null) { - // if there's no parent then we found a new root page - parentsStack = [section]; - pages.set(section.reference, section); - } else { - // otherwise add this page to its parent's sections list - parentPage.sections.set(section.reference, section); - parentsStack.push(parentPage, section); - } - return pages; - } - - // JSON properties with special processing: - var EXCLUDED = ["raw", "styleguide", "weight", "autoincrement", "referenceURI", "section"]; - var STRINGS = ["markup", "description"]; - // JSON.stringify replacer function for Kss.Styleguide - function stringifyKss(key, value) { - if (EXCLUDED.indexOf(key) >= 0) { return undefined; } - if (STRINGS.indexOf(key) >= 0 && !value) { return undefined; } - if (key === "sections") { - // unwrap Map into array, in insertion order - return Array.from(value.values()).map(entry => entry[1]); - } - return value; - } - - // run KSS against all the Sass files to extract documentation sections, then process each - // section to detect our custom @flags, then save it to a JSON file using some custom stringify - // logic to unwrap the raw KSS data. - gulp.task("docs-kss", (done) => { - var kss = require("kss"); - var options = { - // disable KSS internal markdown rendering so we can do it all ourselves! - markdown: false, - mask: /\.scss$/, - }; - - kss.traverse(config.kssSources, options, (err, styleguide) => { - if (err) { return done(err); } - - var pages = styleguide.section() - .map(unwrapData) - .map(processSection) - .map(processFlags) - .reduce(nestPages, new Map()); - // convert Map to array, in insertion order - pages = Array.from(pages.values()); - - pages.unshift({ - deprecated: false, - depth: 1, - description: text.markdown(text.fromFile(filenames.styleguide)), - experimental: false, - header: "Overview", - modifiers: [], - parameters: [], - reference: "overview", - sections: [], - }); - - text.fileStream(filenames.docs, JSON.stringify(pages, stringifyKss, 2)) - .pipe(gulp.dest(config.data)) - .on("end", done); - }); - }); + gulp.task("docs-json", () => ( + new dm.Documentalist({ + markdown: { renderer: text.renderer }, + // must mark our @Decorator APIs as reserved so we can use them in code samples + reservedTags: ["ContextMenuTarget", "HotkeysTarget"], + }) + .use(".md", new dm.MarkdownPlugin({ navPage: config.navPage })) + .use(/\.d\.ts$/, new dm.TypescriptPlugin({ + excludeNames: [/Factory$/, /^I.+State$/], + excludePaths: ["node_modules/", "core/typings"], + includeDefinitionFiles: true, + })) + .use(".scss", new dm.KssPlugin()) + .documentGlobs("packages/*/src/**/*", "packages/*/dist/index.d.ts") + .then((docs) => JSON.stringify(docs, null, 2)) + .then((content) => ( + text.fileStream(filenames.data, content) + .pipe(gulp.dest(config.data)) + )) + )); // create a JSON file containing latest released version of each project gulp.task("docs-releases", () => { @@ -162,31 +58,6 @@ module.exports = (blueprint, gulp, plugins) => { .pipe(gulp.dest(config.data)); }); - // must include external typings for React things like JSX.Element and React.HTMLProps - const TYPINGS_PATH = "packages/core/typings/tsd.d.ts"; - - gulp.task("docs-interfaces", () => { - function markdownEntry(entry) { - if (entry.documentation.length) { - entry.documentation = text.markdown(entry.documentation.trim()); - } - if (entry.properties && entry.properties.length) { - entry.properties = entry.properties.map(markdownEntry); - } - return entry; - } - - // load interfaces from .d.ts files - const props = tsdoc.fromFiles(glob.sync("packages/*/dist/index.d.ts").concat(TYPINGS_PATH), {}, { - excludeNames: [/Factory$/, /^I.+State$/], - excludePaths: ["node_modules/", "core/typings"], - includeDefinitionFiles: true, - }).map(markdownEntry); - - return text.fileStream(filenames.props, JSON.stringify(props, null, 2)) - .pipe(gulp.dest(config.data)); - }); - // create a JSON file containing published versions of the documentation gulp.task("docs-versions", (done) => { let stdout = ""; diff --git a/gulp/util/text.js b/gulp/util/text.js index 63627f3770..5ee1b5e355 100644 --- a/gulp/util/text.js +++ b/gulp/util/text.js @@ -22,12 +22,9 @@ var highlighter = new Highlights(); // highlights the given text in the given language scope. returns HTML string wrapped in 

 tag.
 // must provide full TextMate language scope: "text.html.basic"
-function highlight(textContent, scopeName) {
-    if (textContent) {
-        return highlighter.highlightSync({
-            fileContents: textContent,
-            scopeName: scopeName ? scopeName : DEFAULT_SCOPE,
-        });
+function highlight(fileContents, scopeName = DEFAULT_SCOPE) {
+    if (fileContents) {
+        return highlighter.highlightSync({ fileContents, scopeName });
     }
 }
 
@@ -64,4 +61,6 @@ module.exports = {
     // render the given text as markdown, using the custom rendering logic above.
     // code blocks are highlighted using highlight() above.
     markdown: (textContent) => marked(textContent, { renderer }),
+
+    renderer,
 };
diff --git a/gulp/watch.js b/gulp/watch.js
index ce8cfd5be4..1a5386a562 100644
--- a/gulp/watch.js
+++ b/gulp/watch.js
@@ -24,8 +24,8 @@ module.exports = (blueprint, gulp, plugins) => {
     gulp.task("watch-files", ["connect"], () => {
         blueprint.projectsWithBlock("sass").forEach((project) => {
             const tasks = [`sass-${project.id}:only`];
-            if (project.id !== "docs") {
-                tasks.push("sass-variables", "docs-kss");
+            if (project.id === "core") {
+                tasks.push("sass-variables");
             }
             gulp.watch(createSrcGlob(project, "*.scss"), tasks);
         });
@@ -34,11 +34,10 @@ module.exports = (blueprint, gulp, plugins) => {
             gulp.watch(createSrcGlob(project, "*.ts{,x}"), [`tsc-${project.id}:only`]);
         });
 
-        const docsCwd = blueprint.findProject("docs").cwd;
-        gulp.watch(`${docsCwd}/src/styleguide.md`, ["docs-kss"]);
+        gulp.watch("packages/*/!(node_modules)/**/*.md", ["docs-json"]);
 
-        // recompile docs CSS when non-docs dist/*.css files change
-        gulp.watch("packages/!(docs)/dist/*.css", ["sass-docs:only"]);
+        // recompile docs CSS when non-docs-site dist/*.css files change
+        gulp.watch("packages/!(docs-site)/dist/*.css", ["sass-docs-site:only"]);
     });
 
     gulp.task("watch", ["watch-files", "webpack-docs-watch"]);
diff --git a/gulp/webpack.js b/gulp/webpack.js
index df4672448c..6a3dd07bb9 100644
--- a/gulp/webpack.js
+++ b/gulp/webpack.js
@@ -7,7 +7,7 @@ module.exports = (blueprint, gulp) => {
     const webpack = require("webpack");
     const webpackConfig = require("./util/webpack-config");
 
-    const docsProject = blueprint.findProject("docs");
+    const docsProject = blueprint.findProject("docs-site");
     const configuration = webpackConfig.generateWebpackTypescriptConfig(docsProject);
 
     gulp.task("webpack-docs", ["docs"], (callback) => {
diff --git a/mdify.js b/mdify.js
new file mode 100644
index 0000000000..a65cec3094
--- /dev/null
+++ b/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");
+    });
diff --git a/package.json b/package.json
index 9bb783c9ec..951246990a 100644
--- a/package.json
+++ b/package.json
@@ -34,6 +34,7 @@
     "better-handlebars": "github:wmeldon/better-handlebars",
     "chai": "3.5.0",
     "del": "2.2.2",
+    "documentalist": "0.0.6",
     "enzyme": "2.6.0",
     "gulp": "3.9.1",
     "gulp-concat": "2.6.0",
@@ -69,7 +70,6 @@
     "karma-sinon": "1.0.5",
     "karma-sourcemap-loader": "0.3.7",
     "karma-webpack": "1.8.0",
-    "kss": "2.4.0",
     "language-less": "github:atom/language-less",
     "language-typescript": "github:giladgray/language-typescript#10.1.15",
     "lerna": "2.0.0-beta.30",
diff --git a/packages/core/examples/alertExample.tsx b/packages/core/examples/alertExample.tsx
index c4e981a7fa..25d66e1d4f 100644
--- a/packages/core/examples/alertExample.tsx
+++ b/packages/core/examples/alertExample.tsx
@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Alert, Button, Intent, IToaster, Toaster } from "@blueprintjs/core";
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 export interface IAlertExampleState {
     isOpen?: boolean;
diff --git a/packages/core/examples/buttonsExample.tsx b/packages/core/examples/buttonsExample.tsx
index 7ffb9d7593..0ecd8fce28 100644
--- a/packages/core/examples/buttonsExample.tsx
+++ b/packages/core/examples/buttonsExample.tsx
@@ -9,7 +9,7 @@ import * as classNames from "classnames";
 import * as React from "react";
 
 import { AnchorButton, Button, Classes, Intent, Switch } from "@blueprintjs/core";
-import BaseExample, { handleBooleanChange, handleNumberChange } from "./common/baseExample";
+import { BaseExample, handleBooleanChange, handleNumberChange } from "@blueprintjs/docs";
 import { IntentSelect } from "./common/intentSelect";
 
 export interface IButtonsExampleState {
diff --git a/packages/core/examples/collapseExample.tsx b/packages/core/examples/collapseExample.tsx
index e514ebc000..2d8b6bf3d7 100644
--- a/packages/core/examples/collapseExample.tsx
+++ b/packages/core/examples/collapseExample.tsx
@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Button, Collapse } from "@blueprintjs/core";
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 export class CollapseExample extends BaseExample<{ isOpen: boolean }> {
     public state = {
diff --git a/packages/core/examples/collapsibleListExample.tsx b/packages/core/examples/collapsibleListExample.tsx
index 742758e0b6..001855b392 100644
--- a/packages/core/examples/collapsibleListExample.tsx
+++ b/packages/core/examples/collapsibleListExample.tsx
@@ -17,7 +17,7 @@ import {
     RadioGroup,
     Slider,
 } from "@blueprintjs/core";
-import BaseExample, { handleNumberChange } from "./common/baseExample";
+import { BaseExample, handleNumberChange } from "@blueprintjs/docs";
 
 export interface ICollapsibleListExampleState {
     collapseFrom?: CollapseFrom;
diff --git a/packages/core/examples/contextMenuExample.tsx b/packages/core/examples/contextMenuExample.tsx
index 7c8d83bbe7..ba163b64e6 100644
--- a/packages/core/examples/contextMenuExample.tsx
+++ b/packages/core/examples/contextMenuExample.tsx
@@ -12,7 +12,7 @@ import * as PureRender from "pure-render-decorator";
 import * as React from "react";
 
 import { ContextMenu, ContextMenuTarget, Menu, MenuDivider, MenuItem } from "@blueprintjs/core";
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 /**
  * This component uses the imperative ContextMenu API.
@@ -52,15 +52,7 @@ class GraphNode extends React.Component<{}, { isContextMenuOpen: boolean }> {
  */
 @ContextMenuTarget
 export class ContextMenuExample extends BaseExample<{}> {
-    public renderExample() {
-        return (
-            

-                

-                    
-                

-            

-        );
-    }
+    public className = "docs-context-menu-example";
 
     public renderContextMenu(e: React.MouseEvent) {
         return 
@@ -80,7 +72,11 @@ export class ContextMenuExample extends BaseExample<{}> {
         ;
     }
 
+    public renderExample() {
+        return ;
+    }
+
     protected renderOptions() {
-        return 
Right-click on node or background.
;
+        return Right-click on node or background.;
     }
 }
diff --git a/packages/core/examples/controlsExample.tsx b/packages/core/examples/controlsExample.tsx
index 2b51e8d2ca..e55426006b 100644
--- a/packages/core/examples/controlsExample.tsx
+++ b/packages/core/examples/controlsExample.tsx
@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Checkbox, Classes, Radio, RadioGroup, Switch } from "@blueprintjs/core";
-import BaseExample, { handleStringChange } from "./common/baseExample";
+import { BaseExample, handleStringChange } from "@blueprintjs/docs";
 
 export interface IControlsExampleState {
     radioValue?: string;
diff --git a/packages/core/examples/dropdownMenuExample.tsx b/packages/core/examples/dropdownMenuExample.tsx
index 8a27282518..da0f1418a7 100644
--- a/packages/core/examples/dropdownMenuExample.tsx
+++ b/packages/core/examples/dropdownMenuExample.tsx
@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Menu, MenuDivider, MenuItem, Popover, Position } from "@blueprintjs/core";
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 export class DropdownMenuExample extends BaseExample<{}> {
     protected renderExample() {
diff --git a/packages/core/examples/editableTextExample.tsx b/packages/core/examples/editableTextExample.tsx
index f550483e8e..a8fe7064f2 100644
--- a/packages/core/examples/editableTextExample.tsx
+++ b/packages/core/examples/editableTextExample.tsx
@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Classes, EditableText, Intent, Switch } from "@blueprintjs/core";
-import BaseExample, { handleBooleanChange, handleNumberChange, handleStringChange } from "./common/baseExample";
+import { BaseExample, handleBooleanChange, handleNumberChange, handleStringChange } from "@blueprintjs/docs";
 import { IntentSelect } from "./common/intentSelect";
 
 export interface IEditableTextExampleState {
diff --git a/packages/core/examples/focusExample.tsx b/packages/core/examples/focusExample.tsx
index e3d153d30c..74c8d69363 100644
--- a/packages/core/examples/focusExample.tsx
+++ b/packages/core/examples/focusExample.tsx
@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Button, FocusStyleManager, InputGroup, Switch } from "@blueprintjs/core";
-import BaseExample, { handleBooleanChange } from "./common/baseExample";
+import { BaseExample, handleBooleanChange } from "@blueprintjs/docs";
 
 export interface IFocusExampleState {
     isFocusActive?: boolean;
diff --git a/packages/core/examples/hotkeyPiano.tsx b/packages/core/examples/hotkeyPiano.tsx
index e13052abdc..1a486edfb8 100644
--- a/packages/core/examples/hotkeyPiano.tsx
+++ b/packages/core/examples/hotkeyPiano.tsx
@@ -11,7 +11,7 @@ import * as classNames from "classnames";
 import * as React from "react";
 
 import { Hotkey, Hotkeys, HotkeysTarget } from "@blueprintjs/core";
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 class Oscillator {
     public oscillator: OscillatorNode;
diff --git a/packages/core/examples/hotkeyTester.tsx b/packages/core/examples/hotkeyTester.tsx
index 6a19abb2b2..b948e5ef20 100644
--- a/packages/core/examples/hotkeyTester.tsx
+++ b/packages/core/examples/hotkeyTester.tsx
@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { getKeyComboString, KeyCombo } from "@blueprintjs/core";
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 export interface IHotkeyTesterState {
     combo: string;
diff --git a/packages/core/examples/inputGroupExample.tsx b/packages/core/examples/inputGroupExample.tsx
index 41ef2f08bf..0a474c4590 100644
--- a/packages/core/examples/inputGroupExample.tsx
+++ b/packages/core/examples/inputGroupExample.tsx
@@ -22,7 +22,7 @@ import {
     Tag,
     Tooltip,
 } from "@blueprintjs/core";
-import BaseExample, { handleBooleanChange, handleStringChange } from "./common/baseExample";
+import { BaseExample, handleBooleanChange, handleStringChange } from "@blueprintjs/docs";
 
 export interface IInputGroupExampleState {
     disabled?: boolean;
@@ -81,8 +81,8 @@ export class InputGroupExample extends BaseExample {
         );
 
         return (
-            

-                

+            

+                

                      {
                         type={showPassword ? "text" : "password"}
                     />
                 

-                

+                

                      {
     protected renderExample() {
diff --git a/packages/core/examples/nonIdealStateExample.tsx b/packages/core/examples/nonIdealStateExample.tsx
index 4e642423cd..1dcfb4447a 100644
--- a/packages/core/examples/nonIdealStateExample.tsx
+++ b/packages/core/examples/nonIdealStateExample.tsx
@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { InputGroup, NonIdealState } from "@blueprintjs/core";
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 export class NonIdealStateExample extends BaseExample<{}> {
     protected renderExample() {
diff --git a/packages/core/examples/numericInputBasicExample.tsx b/packages/core/examples/numericInputBasicExample.tsx
index 6ecea72764..90f64558b3 100644
--- a/packages/core/examples/numericInputBasicExample.tsx
+++ b/packages/core/examples/numericInputBasicExample.tsx
@@ -13,8 +13,8 @@ import {
     Position,
     Switch,
 } from "@blueprintjs/core";
+import { BaseExample, handleBooleanChange, handleNumberChange } from "@blueprintjs/docs";
 
-import BaseExample, { handleBooleanChange, handleNumberChange } from "./common/baseExample";
 import { IntentSelect } from "./common/intentSelect";
 
 export interface INumericInputBasicExampleState {
diff --git a/packages/core/examples/numericInputExtendedExample.tsx b/packages/core/examples/numericInputExtendedExample.tsx
index 3724fc169c..93840d2fca 100644
--- a/packages/core/examples/numericInputExtendedExample.tsx
+++ b/packages/core/examples/numericInputExtendedExample.tsx
@@ -9,8 +9,7 @@ import {
     Keys,
     NumericInput,
 } from "@blueprintjs/core";
-
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 export interface INumericInputExtendedExampleState {
     value?: string;
diff --git a/packages/core/examples/overlayExample.tsx b/packages/core/examples/overlayExample.tsx
index fd8af6f54a..f43c1e3134 100644
--- a/packages/core/examples/overlayExample.tsx
+++ b/packages/core/examples/overlayExample.tsx
@@ -17,7 +17,7 @@ import {
     Overlay,
     Switch,
 } from "@blueprintjs/core";
-import BaseExample, { handleBooleanChange } from "./common/baseExample";
+import { BaseExample, handleBooleanChange } from "@blueprintjs/docs";
 
 const OVERLAY_EXAMPLE_CLASS = "docs-overlay-example-transition";
 
diff --git a/packages/core/examples/popoverExample.tsx b/packages/core/examples/popoverExample.tsx
index b6389b0a25..0ef02505ed 100644
--- a/packages/core/examples/popoverExample.tsx
+++ b/packages/core/examples/popoverExample.tsx
@@ -21,7 +21,7 @@ import {
     Slider,
     Switch,
 } from "@blueprintjs/core";
-import BaseExample, { handleBooleanChange, handleNumberChange } from "./common/baseExample";
+import { BaseExample, handleBooleanChange, handleNumberChange } from "@blueprintjs/docs";
 
 const INTERACTION_KINDS = [
     { label: "Click", value: PopoverInteractionKind.CLICK.toString() },
diff --git a/packages/core/examples/progressExample.tsx b/packages/core/examples/progressExample.tsx
index fe0749f4ba..dd732a3fbd 100644
--- a/packages/core/examples/progressExample.tsx
+++ b/packages/core/examples/progressExample.tsx
@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Intent, ProgressBar, Slider, Switch } from "@blueprintjs/core";
-import BaseExample, { handleBooleanChange, handleNumberChange } from "./common/baseExample";
+import { BaseExample, handleBooleanChange, handleNumberChange } from "@blueprintjs/docs";
 import { IntentSelect } from "./common/intentSelect";
 
 export interface IProgressExampleState {
diff --git a/packages/core/examples/rangeSliderExample.tsx b/packages/core/examples/rangeSliderExample.tsx
index 962785b8b5..a04fe052cc 100644
--- a/packages/core/examples/rangeSliderExample.tsx
+++ b/packages/core/examples/rangeSliderExample.tsx
@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { NumberRange, RangeSlider } from "@blueprintjs/core";
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 export interface IRangeSliderExampleState {
     range?: NumberRange;
diff --git a/packages/core/examples/sliderExample.tsx b/packages/core/examples/sliderExample.tsx
index 4e4baa8356..ef9a75a3ed 100644
--- a/packages/core/examples/sliderExample.tsx
+++ b/packages/core/examples/sliderExample.tsx
@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Slider } from "@blueprintjs/core";
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 export interface ISliderExampleState {
     value1?: number;
diff --git a/packages/core/examples/spinnerExample.tsx b/packages/core/examples/spinnerExample.tsx
index 214fe7f113..204ae90baa 100644
--- a/packages/core/examples/spinnerExample.tsx
+++ b/packages/core/examples/spinnerExample.tsx
@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Classes, Spinner } from "@blueprintjs/core";
-import { handleStringChange } from "./common/baseExample";
+import { handleStringChange } from "@blueprintjs/docs";
 import { ProgressExample } from "./progressExample";
 
 const SIZES = [
diff --git a/packages/core/examples/tabs2Example.tsx b/packages/core/examples/tabs2Example.tsx
index 5c0d424320..048e14e7c1 100644
--- a/packages/core/examples/tabs2Example.tsx
+++ b/packages/core/examples/tabs2Example.tsx
@@ -9,7 +9,7 @@ import * as classNames from "classnames";
 import * as React from "react";
 
 import { Classes, Switch, Tab2, Tabs2 } from "@blueprintjs/core";
-import BaseExample, { handleBooleanChange } from "./common/baseExample";
+import { BaseExample, handleBooleanChange } from "@blueprintjs/docs";
 
 export interface ITabs2ExampleState {
     activeTabId?: string;
diff --git a/packages/core/examples/tabsExample.tsx b/packages/core/examples/tabsExample.tsx
index 1f02e6fedc..cbf7ac21a7 100644
--- a/packages/core/examples/tabsExample.tsx
+++ b/packages/core/examples/tabsExample.tsx
@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Switch, Tab, TabList, TabPanel, Tabs } from "@blueprintjs/core";
-import BaseExample, { handleBooleanChange } from "./common/baseExample";
+import { BaseExample, handleBooleanChange } from "@blueprintjs/docs";
 
 export class TabsExample extends BaseExample<{ isVertical?: boolean }> {
     public state = {
diff --git a/packages/core/examples/tagExample.tsx b/packages/core/examples/tagExample.tsx
index b50f7b4bd3..fb0dd853ed 100644
--- a/packages/core/examples/tagExample.tsx
+++ b/packages/core/examples/tagExample.tsx
@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Classes, Intent, Tag } from "@blueprintjs/core";
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 export class TagExample extends BaseExample<{ showTag?: boolean }> {
     public state = {
diff --git a/packages/core/examples/textExample.tsx b/packages/core/examples/textExample.tsx
index 199ebfa01b..ae17a229c2 100644
--- a/packages/core/examples/textExample.tsx
+++ b/packages/core/examples/textExample.tsx
@@ -8,10 +8,9 @@
 import * as classNames from "classnames";
 import * as React from "react";
 
+import { BaseExample, handleStringChange } from "@blueprintjs/docs";
 import * as Classes from "../src/common/classes";
 import { Text } from "../src/components/text/text";
-import BaseExample from "./common/baseExample";
-import { handleStringChange } from "./common/baseExample";
 
 export interface ITextExampleState {
     textContent: string;
diff --git a/packages/core/examples/toastExample.tsx b/packages/core/examples/toastExample.tsx
index d93182fce4..e322835fcc 100644
--- a/packages/core/examples/toastExample.tsx
+++ b/packages/core/examples/toastExample.tsx
@@ -19,7 +19,7 @@ import {
     Switch,
     Toaster,
 } from "@blueprintjs/core";
-import BaseExample, { handleBooleanChange, handleNumberChange } from "./common/baseExample";
+import { BaseExample, handleBooleanChange, handleNumberChange } from "@blueprintjs/docs";
 
 type IToastDemo = IToastProps & { button: string };
 
diff --git a/packages/core/examples/tooltipExample.tsx b/packages/core/examples/tooltipExample.tsx
index 3c669ece59..938036dc76 100644
--- a/packages/core/examples/tooltipExample.tsx
+++ b/packages/core/examples/tooltipExample.tsx
@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Intent, Popover, Position, Switch, Tooltip } from "@blueprintjs/core";
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 export class TooltipExample extends BaseExample<{ isOpen: boolean }> {
     public state = {
diff --git a/packages/core/examples/treeExample.tsx b/packages/core/examples/treeExample.tsx
index 50fdc6d5d5..15b39a73d7 100644
--- a/packages/core/examples/treeExample.tsx
+++ b/packages/core/examples/treeExample.tsx
@@ -8,7 +8,7 @@
 import * as React from "react";
 
 import { Classes, ITreeNode, Tooltip, Tree } from "@blueprintjs/core";
-import BaseExample from "./common/baseExample";
+import { BaseExample } from "@blueprintjs/docs";
 
 export interface ITreeExampleState {
     nodes: ITreeNode[];
diff --git a/packages/core/examples/tsconfig.json b/packages/core/examples/tsconfig.json
index 7b2cf963de..9c7a233d58 100644
--- a/packages/core/examples/tsconfig.json
+++ b/packages/core/examples/tsconfig.json
@@ -17,7 +17,8 @@
         "stripInternal": true,
         "target": "es5",
         "paths": {
-            "@blueprintjs/core": ["../dist/index"]
+            "@blueprintjs/core": ["../dist/index"],
+            "@blueprintjs/docs": ["../../docs/dist/index"]
         }
     }
 }
diff --git a/packages/core/src/_accessibility.scss b/packages/core/src/_accessibility.scss
index e4bc9ea9b7..a7a5199b11 100644
--- a/packages/core/src/_accessibility.scss
+++ b/packages/core/src/_accessibility.scss
@@ -3,57 +3,6 @@
 // of the license at https://github.com/palantir/blueprint/blob/master/LICENSE
 // and https://github.com/palantir/blueprint/blob/master/PATENTS
 
-/*
-Accessibility
-
-Blueprint strives to provide accessible components out of the box. Many of the JS components
-will apply accessible HTML attributes to support different modes of usage.
-
-Styleguide a11y
-*/
-
-/*
-Focus management
-
-Focus states (that glowy blue outline around the active element) are essential for keyboard
-navigation to indicate which element is currently active. They are less important, and
-occasionally outright intrusive, when using a mouse because you can click wherever you want at
-any time.
-
-Blueprint includes a utility that manages the appearance of focus styles. When enabled, focus styles
-will be hidden while the user interacts using the mouse and will appear when the
-tab key is pressed to begin keyboard navigation. Try this out for yourself
-below.
-
-**You must explictly enable this feature in your app (and you probably want to):**
-
-```ts
-import { FocusStyleManager } from "@blueprintjs/core";
-
-FocusStyleManager.onlyShowFocusOnTabs();
-```
-
-Note that the focus style for text inputs (a slightly thicker colored border) is not removed by this
-utility because it is always useful to know where you're typing.
-
-@react-example FocusExample
-
-Styleguide a11y.focus
-*/
-
-/*
-JavaScript API
-
-This behavior is controlled by a singleton instance called `FocusStyleManager` that lives in the
-__@blueprintjs/core__ package. It supports the following public methods:
-
-- `FocusStyleManager.isActive(): boolean`: Returns whether the `FocusStyleManager` is currently running.
-- `FocusStyleManager.onlyShowFocusOnTabs(): void`: Enable behavior which hides focus styles during mouse interaction.
-- `FocusStyleManager.alwaysShowFocus(): void`: Stop this behavior (focus styles are always visible).
-
-Styleguide a11y.focus.js
-*/
-
 :focus {
   @include focus-outline();
 }
@@ -68,15 +17,3 @@ Styleguide a11y.focus.js
     outline: none !important;
   }
 }
-
-/*
-Color contrast
-
-Colors have been designed to be accessible to as many people as possible, even those who are
-visually impaired or experiencing any kind of colorblindness. Our colors have not only been chosen
-to go well together but to also adhere to [WCAG 2.0](https://www.w3.org/TR/WCAG20/) standards.
-
-Weight: 1
-
-Styleguide a11y.contrast
-*/
diff --git a/packages/core/src/_dark-theme.scss b/packages/core/src/_dark-theme.scss
deleted file mode 100644
index 6eef18db73..0000000000
--- a/packages/core/src/_dark-theme.scss
+++ /dev/null
@@ -1,35 +0,0 @@
-// Copyright 2015 Palantir Technologies, Inc. All rights reserved.
-// Licensed under the BSD-3 License as modified (the “License”); you may obtain a copy
-// of the license at https://github.com/palantir/blueprint/blob/master/LICENSE
-// and https://github.com/palantir/blueprint/blob/master/PATENTS
-
-/*
-Dark theme
-
-Blueprint provides two UI color themes: light and dark. The light theme is active by default. The
-dark theme can be applied by adding the class `pt-dark` to a container element to theme all nested
-elements.
-
-Once applied, the dark theme will cascade to nested `.pt-*` elements inside a `.pt-dark` container.
-There is no way to nest light-themed elements inside a dark container.
-
-Most elements only support the dark theme when nested inside a `.pt-dark` container because it does
-not make sense to mark individual elements as dark. The dark container is therefore responsible for
-setting a dark background color.
-
-The following elements and components support the `.pt-dark` class directly (i.e, `.pt-app.pt-dark`)
-and can be used as a container for nested dark children:
-
-- `.pt-app`
-- `.pt-card`
-- Overlays: `Dialog`, `Popover`, `Tooltip`, `Toast`
-  - `Popover` and `Tooltip` will automatically detect when their trigger is inside a `.pt-dark`
-    container and add the same class to themselves.
-
-Rather than illustrating dark components inline, this documentation site provides a site-wide switch
-in the top right corner of the page to enable the dark theme. Try it out as you read the docs.
-
-Weight: 10
-
-Styleguide components.usage.dark
-*/
diff --git a/packages/core/src/_icons.scss b/packages/core/src/_icons.scss
index d3e488aa7b..9cad17602c 100644
--- a/packages/core/src/_icons.scss
+++ b/packages/core/src/_icons.scss
@@ -5,43 +5,6 @@
 
 @import "common/icons";
 
-/*
-Icons
-
-Weight: 3
-
-Styleguide icons
-*/
-
-/*
-UI icons
-
-Blueprint UI icons are implemented via an icon font. They can be used anywhere text is
-used. It's easy to change their color or apply effects like text shadows via standard CSS
-properties.
-
-To use Blueprint UI icons, you need to apply two classes to a `` element:
-- a __sizing class__, either `pt-icon-standard` (16px) or `pt-icon-large` (20px)
-- an icon __identifier class__, such as `pt-icon-projects`
-
-```html
-
-```
-
-

-  
Non-standard sizes

-  Generally, icons should only be used at either 16px or 20px. However if a non-standard size is
-  necessary, set a `font-size` that is whole multiple of 16 or 20 with the relevant size class.
-  You can instead use the class `pt-icon` to make the icon inherit its size from surrounding text.
-

-
-@react-docs Icons
-
-Weight: -1
-
-Styleguide icons.ui
-*/
-
 #{$icon-classes} {
   display: inline-block;
 }
diff --git a/packages/core/src/_resources.scss b/packages/core/src/_resources.scss
deleted file mode 100644
index 33de11e7ca..0000000000
--- a/packages/core/src/_resources.scss
+++ /dev/null
@@ -1,27 +0,0 @@
-// Copyright 2017 Palantir Technologies, Inc. All rights reserved.
-// Licensed under the BSD-3 License as modified (the “License”); you may obtain a copy
-// of the license at https://github.com/palantir/blueprint/blob/master/LICENSE
-// and https://github.com/palantir/blueprint/blob/master/PATENTS
-
-/*
-Resources
-
-Weight: 10
-
-Styleguide resources
-*/
-
-/*
-Sketch assets
-
-
-  Blueprint Kit.sketch
-  Last updated January 25, 2017
-
-
-  Blueprint Colors.sketchpalette
-  Last updated March 22, 2016
-
-
-Styleguide resources.sketch
-*/
diff --git a/packages/core/src/_typography.scss b/packages/core/src/_typography.scss
index 3241ed4191..93426dd883 100644
--- a/packages/core/src/_typography.scss
+++ b/packages/core/src/_typography.scss
@@ -9,14 +9,6 @@
 @import "common/mixins";
 @import "common/icons";
 
-/*
-Typography
-
-Weight: 2
-
-Styleguide typography
-*/
-
 hr {
   margin: ($pt-grid-size * 2) 0;
   border: none;
@@ -32,24 +24,6 @@ hr {
   background: $pt-text-selection-color;
 }
 
-/*
-Usage
-
-Keep in mind these general web typography guidelines when building your applications.
-
-- The default text color in all components is compliant with the recommended
-  [WCAG 2.0](https://www.w3.org/TR/WCAG20/) minimum contrast ratio.
-- If you choose to go with a custom text color, make sure the background behind it provides
-  proper contrast.
-- Try not to explicitly write pixel values for your font-size or line-height CSS rules.
-  Instead, reference the classes and variables we provide in Blueprint (`.pt-ui-text`,
-  `$pt-font-size-large`, etc.).
-
-Weight: 2
-
-Styleguide typography.usage
-*/
-
 body {
   @include base-typography();
   color: $pt-text-color;
@@ -62,17 +36,12 @@ small {
 /*
 Fonts
 
-Blueprint does not include any fonts of its own; it will use the default sans-serif operating system
-font. We provide a class to use the default monospace font instead.
-
 Markup:
 
Blueprint components react overlay date picker.

 
 .pt-monospace-text - Use a monospace font (ideal for code)
 
-Weight: 1
-
-Styleguide typography.fonts
+Styleguide fonts
 */
 
 .pt-monospace-text {
@@ -90,9 +59,7 @@ Markup:
 
H5 heading

 
H6 heading

 
-Weight: 3
-
-Styleguide typography.headings
+Styleguide headings
 */
 
 $headers: (
@@ -117,20 +84,13 @@ $headers: (
 /*
 UI text
 
-The base font size for Blueprint web applications is 14px. This should be the default type size
-for most short strings of text which are not headings or titles. If you wish to reset some
-element's font size and line height to the default base styles, use the `.pt-ui-text` class.
-For longer running text, see [running text styles](#typography.running-text).
-
 Markup:
 
Blueprint components react overlay date picker.

 
 .pt-ui-text - Default UI text. This is applied to the document body as part of core styles.
 .pt-ui-text-large - Larger UI text.
 
-Weight: 4
-
-Styleguide typography.ui-text
+Styleguide pt-ui-text
 */
 
 .pt-ui-text {
@@ -145,35 +105,21 @@ Styleguide typography.ui-text
 /*
 Running text
 
-Large blocks of _running text_ should use `.pt-running-text` styles.
-
-Note that `
` elements by default don't add any styles; they just inherit the base typography.
-This is a conservative design; `
` elements are so ubiquitous that they're more often used for UI
-text than long form text. It's up to the user to decide which blocks of text in an application
-should get running text styles.
-
 Markup:
-

-  Default paragraphs have base typography styles.
-

-

-  Running text is larger and more spaced out.
-  

-  Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut
-  labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris
-  nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit
-  esse cillum dolore eu fugiat nulla pariatur.
-  

-  Excepteur sint occaecat cupidatat non proident.
-

-

-  Includes support for strong, emphasized, and underlined text.
-  Also links!
+

+  
Longform text, such as rendered Markdown documents, benefit from additional spacing and slightly
+large font size. Apply .pt-running-text to the parent element to adjust spacing for the following
+elements:

+  
    
+    
  • <p> tags have increased line-height and font size.
    • 
+    
  • <h*> tag margins are adjusted to provide clear separation between sections in a document.
    • 
+    
  • <ul> and <ol> tags receive [`.pt-list`](#typography.lists) styles for legibility.
    • 
+  

+  
New section

+  
And another paragraph.

 

 
-Weight: 5
-
-Styleguide typography.running-text
+Styleguide pt-running-text
 */
 
 .pt-running-text {
@@ -204,8 +150,6 @@ Links are underlined only when hovered.
 
 Putting an icon inside a link will cause it to inherit the link's text color.
 
-Weight: 8
-
 Styleguide typography.links
 */
 
@@ -241,9 +185,6 @@ a {
 /*
 Preformatted text
 
-Use `
` for code blocks, and `` for inline code. Note that `
` blocks will
-retain _all_ whitespace so you'll have to format the content accordingly.
-
 Markup:
 $ npm install
 
@@ -264,9 +205,7 @@ Markup:
     });
 }

 
-Weight: 6
-
-Styleguide typography.preformatted
+Styleguide preformatted
 */
 
 pre,
@@ -326,8 +265,6 @@ pre {
 /*
 Block quotes
 
-Block quotes are treated as running text.
-
 Markup:
 

   

@@ -344,9 +281,7 @@ Markup:
   

 

 
-Weight: 7
-
-Styleguide typography.blockquotes
+Styleguide blockquote
 */
 
 blockquote {
@@ -367,11 +302,6 @@ blockquote {
 /*
 Lists
 
-Blueprint provides a small amount of global styling and a few modifier classes for list elements.
-
-`
    ` and `
      ` elements in blocks with the `.pt-running-text` modifier class will
-automatically assume the `.pt-list` styles to promote readability.
-
 Markup:
 
        
   
      • Item the first
        • 
@@ -387,9 +317,7 @@ Markup:
 .pt-list - Add a little spacing between items for readability.
 .pt-list-unstyled - Remove all list styling (including indicators) so you can add your own.
 
-Weight: 8
-
-Styleguide typography.lists
+Styleguide lists
 */
 
 ol,
@@ -429,9 +357,6 @@ ul {
 /*
 Text utilities
 
-Blueprint provides a small handful of class-based text utilities which can applied to any element
-that contains text.
-
 Markup:
 
        
   Blueprint components react overlay date picker. Breadcrumbs dialog progress non-ideal state.
@@ -441,9 +366,7 @@ Markup:
 .pt-text-overflow-ellipsis - Truncates a single line of text with an ellipsis if it overflows its
   container.
 
-Weight: 9
-
-Styleguide typography.utilities
+Styleguide utilities
 */
 
 .pt-text-muted {
@@ -458,19 +381,9 @@ Styleguide typography.utilities
   @include overflow-ellipsis();
 }
 
-/*
-Internationalization
-
-Weight: 10
-
-Styleguide typography.intl
-*/
-
 /*
 Right-to-left text
 
-Use the utility class `.pt-rtl`.
-
 Markup:
 
        Arabic:
        
 
        
@@ -483,26 +396,13 @@ Markup:
   מתן החלל מאמרשיחהצפה ב. הספרות אנציקלופדיה אם זכר, על שימושי שימושיים תאולוגיה עזה
 
        
 
-Styleguide typography.intl.rtl
+Styleguide pt-rtl
 */
 
 .pt-rtl {
   text-align: right;
 }
 
-/*
-Dark theme
-
-
-Use the `.pt-dark` class to apply dark text colors *and* to cascade the dark theme to descendants.
-This only applies colors to text; you'll have to set a background color yourself. Blueprint's
-dark background color is aliased as `$pt-dark-app-background-color`.
-
-Weight: 10
-
-Styleguide typography.dark
-*/
-
 .pt-dark {
   color: $pt-dark-text-color;
 
diff --git a/packages/core/src/blueprint.scss b/packages/core/src/blueprint.scss
index 60324bbd5e..fe784aa252 100644
--- a/packages/core/src/blueprint.scss
+++ b/packages/core/src/blueprint.scss
@@ -19,5 +19,3 @@ $output-bourbon-deprecation-warnings: false;
 @import "accessibility";
 
 @import "components/index";
-
-@import "dark-theme";
diff --git a/packages/core/src/common/_colors.scss b/packages/core/src/common/_colors.scss
index d4f06fe9b8..92913ee846 100644
--- a/packages/core/src/common/_colors.scss
+++ b/packages/core/src/common/_colors.scss
@@ -3,29 +3,7 @@
 // of the license at https://github.com/palantir/blueprint/blob/master/LICENSE
 // and https://github.com/palantir/blueprint/blob/master/PATENTS
 
-/*
-Colors
-
-Hex values for these colors can be accessed in JavaScript. The global version of the module exposes
-the `Blueprint.Colors` object. In CommonJS, you may `import { Colors } from "@blueprintjs/core"`.
-
-Styleguide colors
-*/
-
-/*
-Gray scale
-
-Black, white and everything in between. The gray scale should be used for
-the main UI frame: containers, headers, sections, boxes, etc.
-If you need to call attention to a particular element (buttons, icons, tooltips, etc.),
-use one of the [core colors](#colors.core).
-
-@react-docs GrayscalePalette
-
-Weight: -1
-
-Styleguide colors.grays
-*/
+// Gray scale
 
 $black: #10161a !default;
 
@@ -49,29 +27,7 @@ $light-gray5: #f5f8fa !default;
 
 $white: #ffffff !default;
 
-/*
-Core colors
-
-Core colors are reserved for user interface design. Use these to help call
-attention to specific UI elements, such as buttons, callouts, icons, etc.
-Each core color is mapped to what we call a __visual intent__. We use intents
-to convey the status of UI elements:
-
-- _Blue_ (intent: primary) elevates elements from the typical gray scale UI frame.
-- _Green_ (intent: success) indicates successful operations.
-- _Orange_ (intent: warning) indicates warnings and intermediate states.
-- _Red_ (intent: danger) indicates errors and potentially destructive operations.
-
-Core colors are also designed to:
-
-- go well together and be used alongside each other in any application.
-- adhere to [WCAG 2.0](https://www.w3.org/TR/WCAG20/) standards, and therefore are
-  highly accessible to visually impaired and color blind users.
-
-@react-docs CoreColorsPalette
-
-Styleguide colors.core
-*/
+// Core colors
 
 $blue1: #0e5a8a !default;
 $blue2: #106ba3 !default;
@@ -97,19 +53,7 @@ $red3: #db3737 !default;
 $red4: #f55656 !default;
 $red5: #ff7373 !default;
 
-/*
-Extended colors
-
-Extended colors should typically be reserved for data visualizations: any time
-you need to represent data of some sort, you can use these.
-These colors are less strict on [WCAG 2.0](https://www.w3.org/TR/WCAG20/)
-accessibility standards and should therefore not be used for typical user
-interface design — take a look at [core colors](#colors.core) instead.
-
-@react-docs ExtendedColorsPalette
-
-Styleguide colors.extended
-*/
+// Extended colors
 
 $vermilion1: #9e2b0e !default;
 $vermilion2: #b83211 !default;
@@ -172,51 +116,3 @@ $sepia4: #b07b46 !default;
 $sepia5: #c99765 !default;
 
 @import "color-aliases";
-
-/*
-Color schemes
-
-Use the following color scheme generators to produce color schemes for your data visualizations.
-First, choose the kind of scheme based on the type of your data, then customize the number of values
-using the forms below. Finally, copy the colors array into your application and make it live!
-
-The following schemes have been carefully crafted to be visually striking and easily understandable
-while remaining accessible to visually impaired and color blind users.
-
-Styleguide colors.schemes
-*/
-
-/*
-Sequential color schemes
-
-Sequential color schemes imply order and are best suited for representing data that
-ranges from low-to-high values either on an ordinal or on a numerical scale.
-
-Weight: -1
-
-@react-docs SequentialSchemePalette
-
-Styleguide colors.schemes.sequential
-*/
-
-/*
-Diverging color schemes
-
-Diverging color schemes put equal emphasis on mid-range values and extremes
-at both ends of the data range.
-
-@react-docs DivergingSchemePalette
-
-Styleguide colors.schemes.diverging
-*/
-
-/*
-Qualitative color schemes
-
-Qualitative color schemes use a series of unrelated colors to create a
-scheme that does not imply order, merely difference in kind.
-
-@react-docs QualitativeSchemePalette
-
-Styleguide colors.schemes.qualitative
-*/
diff --git a/packages/core/src/common/_variables.scss b/packages/core/src/common/_variables.scss
index e52d02282e..e4506978d5 100644
--- a/packages/core/src/common/_variables.scss
+++ b/packages/core/src/common/_variables.scss
@@ -10,42 +10,6 @@
 // (so other variables can use it to define themselves)
 $pt-grid-size: 10px !default;
 
-/*
-Variables
-
-Available for use with Sass and Less.
-
-```css.scss
-@import "path/to/@blueprintjs/core/dist/variables";
-```
-
-The Sass `$` convention is used in this documentation for consistency with the original source code.
-Every variable mentioned below is also available in `variables.less` with an `@` prefix instead of `$`.
-
-Weight: 4
-
-Styleguide variables
-*/
-
-/*
-Font variables
-
-Typically, correct typography styles should be achieved by using the proper HTML tag (`
        ` for
-text, `` for headings, `` for code, etc.). The following variables are provided for the
-rare cases where custom styling is necessary and should be used sparingly:
-
-- `$pt-font-family`
-- `$pt-font-family-monospace`
-- `$pt-font-size`
-- `$pt-font-size-small`
-- `$pt-font-size-large`
-- `$pt-line-height`
-
-See the [Fonts section](#typography.fonts) for more information and usage guidelines.
-
-Styleguide variables.fonts
-*/
-
 // see https://bitsofco.de/the-new-system-font-stack/
 $pt-font-family: -apple-system,
                  "BlinkMacSystemFont",
@@ -68,28 +32,7 @@ $pt-font-size-small: $pt-grid-size * 1.2 !default;
 // a little bit extra to ensure the height comes out to just over 18px (and browser rounds to 18px)
 $pt-line-height: ($pt-grid-size * 1.8) / $pt-font-size + 0.0001 !default;
 
-/*
-Icon variables
-
-Most icons should be displayed using the `span.pt-icon-*` classes or via modifier classes on
-components like `.pt-button`. In rare cases, you may need direct access to the content
-string that generates each icon in the icon font. Blueprint provides these variables with
-straightforward names (see the [Icons section](#icons) for the full list of identifiers):
-
-- `$pt-icon-style`
-- `$pt-icon-align-left`
-- `$pt-icon-align-center`
-- ...
-
-Variables are also provided for the two icon font families and their pixel sizes:
-
-- `@icons16-family`
-- `@icons20-family`
-- `$pt-icon-size-standard`
-- `$pt-icon-size-large`
-
-Styleguide variables.icons
-*/
+// Icon variables
 
 $icons16-family: "Icons16" !default;
 $icons20-family: "Icons20" !default;
@@ -97,24 +40,7 @@ $icons20-family: "Icons20" !default;
 $pt-icon-size-standard: 16px !default;
 $pt-icon-size-large: 20px !default;
 
-/*
-Grids & dimensions
-
-Sizes of common components. Most sizing variables are based on `$pt-grid-size`, which has
-a value of `10px`. Custom components should adhere to the relevant `height` variable.
-
-- `$pt-grid-size`
-- `$pt-border-radius`
-- `$pt-button-height`
-- `$pt-button-height-large`
-- `$pt-input-height`
-- `$pt-input-height-large`
-- `$pt-navbar-height`
-
-Weight: 1
-
-Styleguide variables.dimensions
-*/
+// Grids & dimensions
 
 $pt-border-radius: floor($pt-grid-size / 3) !default;
 
@@ -129,40 +55,6 @@ $pt-input-height-large: $pt-grid-size * 4 !default;
 // Others
 $pt-navbar-height: $pt-grid-size * 5 !default;
 
-/*
-Grid system
-
-Blueprint doesn't provide a grid system. In general, you should try to use the `$pt-grid-size`
-variable to generate layout & sizing style rules in your CSS codebase.
-
-In lieu of a full grid system, you should try to use the __CSS flexible box layout model__ (a.k.a.
-"flexbox"). It's quite powerful on its own and allows you to build robust, responsive layouts
-without writing much CSS. Here are some resources for learning flexbox:
-   - [MDN guide](https://developer.mozilla.org/en-US/docs/Web/Guide/CSS/Flexible_boxes)
-   - [CSS Tricks guide](https://css-tricks.com/snippets/css/a-guide-to-flexbox/)
-
-Styleguide variables.dimensions.grid
-*/
-
-/*
-Layering
-
-Blueprint provides variables for three z-index layers. This should be enough for most use cases,
-especially if you make correct use of [stacking context][MDN]. [Overlay](#components.overlay)
-components such as dialogs and popovers use these z-index values to configure their stacking
-contexts.
-
-- `$pt-z-index-base`
-- `$pt-z-index-content`
-- `$pt-z-index-overlay`
-
-[MDN]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Positioning/Understanding_z_index/The_stacking_context
-
-Weight: 1
-
-Styleguide variables.layering
-*/
-
 // Z-indices
 $pt-z-index-base: 0 !default;
 $pt-z-index-content: $pt-z-index-base + 10 !default;
@@ -206,21 +98,7 @@ $pt-transition-ease: cubic-bezier(0.4, 1, 0.75, 0.9) !default;
 $pt-transition-ease-bounce: cubic-bezier(0.54, 1.12, 0.38, 1.11) !default;
 $pt-transition-duration: 100ms !default;
 
-/*
-Light theme styles
-
-Use these when you need to build custom UI components that look similar to Blueprint's
-light theme components.
-
-- `$pt-dialog-box-shadow`
-- `$pt-input-box-shadow`
-- `$pt-popover-box-shadow`
-- `$pt-tooltip-box-shadow`
-
-Weight: 2
-
-Styleguide variables.light
-*/
+// Light theme styles
 
 $pt-input-box-shadow: inset border-shadow(0.15),
                       inset 0 1px 1px rgba($black, $pt-drop-shadow-opacity) !default;
@@ -229,21 +107,7 @@ $pt-dialog-box-shadow: $pt-elevation-shadow-4 !default;
 $pt-popover-box-shadow: $pt-elevation-shadow-3 !default;
 $pt-tooltip-box-shadow: $pt-popover-box-shadow !default;
 
-/*
-Dark theme styles
-
-Use these when you need to build custom UI components that look similar to Blueprint's
-dark theme components.
-
-- `$pt-dark-dialog-box-shadow`
-- `$pt-dark-input-box-shadow`
-- `$pt-dark-popover-box-shadow`
-- `$pt-dark-tooltip-box-shadow`
-
-Weight: 3
-
-Styleguide variables.dark
-*/
+// Dark theme styles
 
 $pt-dark-input-box-shadow: inset border-shadow(0.3),
                            inset 0 1px 1px rgba($black, $pt-dark-drop-shadow-opacity) !default;
diff --git a/packages/core/src/components/_index.scss b/packages/core/src/components/_index.scss
index 650c3b3db2..994565cac0 100644
--- a/packages/core/src/components/_index.scss
+++ b/packages/core/src/components/_index.scss
@@ -3,211 +3,6 @@
 // of the license at https://github.com/palantir/blueprint/blob/master/LICENSE
 // and https://github.com/palantir/blueprint/blob/master/PATENTS
 
-/*
-Components
-
-Blueprint's JavaScript components are stable and their APIs adhere to
-[semantic versioning](http://semver.org/).
-They are distributed in the __@blueprintjs/core__ package and can be consumed as CommonJS modules
-[via NPM](https://www.npmjs.com/package/@blueprintjs/core).
-
-Weight: 6
-
-Styleguide components
-*/
-
-/*
-Usage
-
-Weight: -1
-
-Styleguide components.usage
-*/
-
-/*
-NPM installation
-
-1. Install the core package with an NPM client like `npm` or `yarn`, pulling in all relevant
-dependencies:
-
-  ```sh
-  npm install --save @blueprintjs/core
-  ```
-
-1. If you see `UNMET PEER DEPENDENCY` errors, you should manually install React:
-
-  ```sh
-  npm install --save react react-dom react-addons-css-transition-group
-  ```
-
-1. After installation, you'll be able to import the React components in your application:
-
-  ```
-  // extract specific components
-  import { Intent, Spinner, DatePickerFactory } from "@blueprintjs/core";
-  // or just take everything!
-  import * as Blueprint from "@blueprintjs/core";
-
-  // using JSX:
-  const mySpinner = ;
-
-  // using the namespace import:
-  const anotherSpinner = ;
-
-  // use factories for React.createElement shorthand if you're not using JSX.
-  // every component provides a corresponding Factory.
-  const myDatePicker = DatePickerFactory();
-  ```
-
-1. Don't forget to include the main CSS file from each Blueprint package! Additionally, the
-`resources/` directory contains supporting media such as fonts and images.
-
-  ```html
-  
-  
-  
-    
-      ...
-      
-      
-      
-      ...
-            
         
 
-    ...
-  
-  ```
-
-  ```css.scss
-  // or, using node-style package resolution in a CSS file:
-  // (dependencies' stylesheets should be resolved automatically)
-  @import "~@blueprintjs/core";
-  ```
-
-Weight: -1
-
-Styleguide components.usage.npm
-*/
-
-/*
-CDN consumption
-
-Blueprint supports the venerable [unpkg CDN](https://unpkg.com). Each package provides a UMD
-`dist/[name].bundle.js` file containing the bundled source code. The UMD wrapper exposes each
-library on the `Blueprint` global variable: `Blueprint.Core`, `Blueprint.Datetime`, etc.
-
-These bundles _do not include_ external dependencies; your application will need to ensure that
-`normalize.css`, `React`, `classnames`, and `Tether` are available at runtime.
-
-```html
-
-
-  
-    
-    
-    Blueprint Starter Kit
-    
-    
-          
         
 
-  
-    
-    
-    
-    
-    
-
-    
        
-    
-  
-
-```
-
-Styleguide components.usage.cdn
-*/
-
-
-/*
-DOM4
-
-Blueprint relies on a handful of DOM Level 4 API methods: `el.query`, `el.queryAll`, and
-`el.closest()`. `@blueprintjs/core` depends on a [polyfill library called `dom4`][dom4] to ensure
-these methods are available. This module is conditionally loaded if Blueprint is used in a browser
-environment.
-
-[dom4]: https://webreflection.github.io/dom4/
-
-Styleguide components.usage.dom4
-*/
-
-/*
-TypeScript
-
-Blueprint is written in TypeScript and therefore its own `.d.ts` type definitions are distributed in
-the NPM package and should be resolved automatically by the compiler. However, you'll need to
-install typings for Blueprint's dependencies before you can consume it:
-
-```sh
-# required for all @blueprintjs packages:
-npm install --save @types/pure-render-decorator @types/react @types/react-dom @types/react-addons-css-transition-group
-
-# @blueprintjs/datetime requires:
-npm install --save @types/moment
-
-# @blueprintjs/table requires:
-npm install --save @types/es6-shim
-```
-
-
        
-  For more information, see the TypeScript Handbook for
-  [guidance on consuming declaration files][handbook].
-
        
-
-[handbook]: https://www.typescriptlang.org/docs/handbook/declaration-files/consumption.html
-
-Styleguide components.usage.typescript
-*/
-
-/*
-Vanilla JS APIs
-
-JS components are built using React, but that does not limit their usage to just React applications.
-You can render any component in any JavaScript application with `ReactDOM.render`. Think of it like
-using a jQuery plugin.
-
-```
-const myContainerElement = document.querySelector(".my-container");
-
-// with JSX
-ReactDOM.render(
-    ,
-    myContainerElement
-);
-
-// with vanilla JS, use the factory
-ReactDOM.render(
-    SpinnerFactory({
-        className: "pt-intent-primary pt-small"
-    }),
-    myContainerElement
-);
-```
-
-To remove the component from the DOM and clean up, unmount it:
-
-```
-ReactDOM.unmountComponentAtNode(myContainerElement);
-```
-
-Check out the [React API docs](https://facebook.github.io/react/docs/react-api.html) for more details.
-
-Styleguide components.usage.vanilla
-*/
-
 @import "alert/alert";
 @import "breadcrumbs/breadcrumbs";
 @import "button/button";
@@ -215,7 +10,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";
@@ -225,7 +19,6 @@ Styleguide components.usage.vanilla
 @import "navbar/navbar";
 @import "non-ideal-state/non-ideal-state";
 @import "overlay/overlay";
-@import "text/text";
 @import "popover/popover";
 @import "portal/portal";
 @import "progress/progress-bar";
diff --git a/packages/core/src/components/alert/_alert.scss b/packages/core/src/components/alert/_alert.scss
index 299bb75bd2..63a8b9d7bf 100644
--- a/packages/core/src/components/alert/_alert.scss
+++ b/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 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.
-
-@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;
diff --git a/packages/core/src/components/alert/alert.md b/packages/core/src/components/alert/alert.md
new file mode 100644
index 0000000000..8795b3d3fd
--- /dev/null
+++ b/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](#core/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](#blueprint.usage).
+
+@interface IAlertProps
diff --git a/packages/core/src/components/breadcrumbs/_breadcrumbs.scss b/packages/core/src/components/breadcrumbs/_breadcrumbs.scss
index 588a55768d..2039664ff1 100644
--- a/packages/core/src/components/breadcrumbs/_breadcrumbs.scss
+++ b/packages/core/src/components/breadcrumbs/_breadcrumbs.scss
@@ -10,29 +10,6 @@
 /*
 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 `` 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:
 
          
   
          • 
@@ -42,23 +19,7 @@ Markup:
   
        • File
          • 
 
        
 
-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
+Styleguide pt-breadcrumbs
 */
 
 // shaving off 1px for perfect centering (... icon is 5px high)
diff --git a/packages/core/src/components/breadcrumbs/breadcrumbs.md b/packages/core/src/components/breadcrumbs/breadcrumbs.md
new file mode 100644
index 0000000000..f7fee97bec
--- /dev/null
+++ b/packages/core/src/components/breadcrumbs/breadcrumbs.md
@@ -0,0 +1,32 @@
+@# 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 `` 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](#core/components/tooltip) or
+[popover](#core/components/popover)) to a breadcrumb, wrap it around the contents of the `li`.
+
+@css pt-breadcrumbs
+
+@## JavaScript API
+
+The `Breadcrumb` component is available in the __@blueprintjs/core__ package.
+Make sure to review the [general usage docs for JS components](#blueprint.usage).
+
+The component renders an `a.pt-breadcrumb`. You are responsible for constructing
+the `ul.pt-breadcrumbs` list. [`CollapsibleList`](#core/components/collapsiblelist)
+works nicely with this component because its props are a subset of `IMenuItemProps`.
+
+@interface IBreadcrumbProps
diff --git a/packages/core/src/components/button/_button-group.scss b/packages/core/src/components/button/_button-group.scss
index 29a4bfde49..8d011c638f 100644
--- a/packages/core/src/components/button/_button-group.scss
+++ b/packages/core/src/components/button/_button-group.scss
@@ -11,19 +11,6 @@
 /*
 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:
 
        
   Queries
@@ -54,7 +41,7 @@ Markup:
 .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
+Styleguide pt-button-group
 */
 
 .pt-button-group {
@@ -166,16 +153,7 @@ 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.
+  Responsive
 
   Markup:
   
        
@@ -192,7 +170,7 @@ Styleguide components.button-group.css
     
   
        
 
-  Styleguide components.button-group.css.fill
+  Styleguide pt-button-group.pt-fill
   */
 
   &.pt-fill {
@@ -207,21 +185,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:
-  
        
+  
        
     
     
     
     
   
        
-  
        
+  
        
     
     
     
@@ -233,7 +204,7 @@ Styleguide components.button-group.css
     
   
        
 
-  Styleguide components.button-group.css.vertical
+  Styleguide pt-button-group.pt-vertical
   */
 
   &.pt-vertical {
diff --git a/packages/core/src/components/button/_button.scss b/packages/core/src/components/button/_button.scss
index 32a4750853..ad444964be 100644
--- a/packages/core/src/components/button/_button.scss
+++ b/packages/core/src/components/button/_button.scss
@@ -8,26 +8,7 @@
 @import "./common";
 
 /*
-Buttons
-
-Buttons trigger actions when clicked.
-
-Styleguide components.button
-*/
-
-/*
-CSS API
-
-Use the `pt-button` class to access button styles. You should implement buttons using the
-`
   
   
   
 
-  Weight: -1
-
-  Styleguide components.button.css.icon
+  Styleguide pt-button.pt-icon
   */
-
   &[class*="pt-icon-"]::before {
     @include pt-icon();
     margin-right: $button-icon-spacing;
@@ -116,13 +90,7 @@ Styleguide components.button.css
   }
 
   /*
-  Advanced icon layout
-
-  You can use a `pt-icon-*` class on a button to add a single icon before the button
-  text, but for more advanced icon layouts, use `` tags inside the button.
-  Add multiple icons to the same button, or move icons after the text.
-
-  To adjust margins on right-aligned icons, add the class `pt-align-right` to the icon.
+  Advanced icon usage
 
   Markup:
   
 
-  Styleguide components.button.css.advanced
+  Styleguide pt-button.pt-icon-advanced
   */
 
   #{$icon-classes} {
@@ -197,12 +165,6 @@ Styleguide components.button.css
   /*
   Minimal buttons
 
-  For a subtler button that appears to fade into the UI, add the `.pt-minimal` modifier
-  to any `.pt-button`. `pt-minimal` is compatible with all other button modifiers,
-  except for `.pt-fill` (due to lack of visual affordances).
-
-  Note that minimal buttons are _not supported_ in button groups at this time.
-
   Markup:
   Anchor
   
@@ -213,7 +175,7 @@ Styleguide components.button.css
   .pt-intent-warning - Warning intent
   .pt-intent-danger - Danger intent
 
-  Styleguide components.button.css.minimal
+  Styleguide pt-button.pt-minimal
   */
 
   &.pt-minimal {
@@ -264,58 +226,3 @@ a.pt-button {
     color: $button-color-disabled;
   }
 }
-
-/*
-JavaScript API
-
-The `Button` and `AnchorButton` components are available in the __@blueprintjs/core__ package.
-Make sure to review the [general usage docs for JS components](#components.usage).
-
-Button components render buttons with Blueprint classes and attributes.
-See the [Buttons CSS docs](#components.button.css) for styling options.
-
-You can provide your own props to these components as if they were regular JSX HTML elements. If you
-provide a `className` prop, the class names you provide will be added alongside of the default
-Blueprint class name. If you specify other attributes that the component provides, such as a `role`
-for an ``, you'll overide the default value.
-
-
        
-  
        Interactions with disabled buttons
        
-  Use `AnchorButton` if you need mouse interaction events (such as hovering) on a disabled button.
-  This is because `Button` and `AnchorButton` handle the `disabled` prop differently: `Button` uses
-  the native `disabled` attribute on the `
        
-
-@react-example ButtonsExample
-
-Styleguide components.button.js
-*/
-
-/*
-Anchor button
-
-```
-
-// renders:
-Click
-```
-
-Styleguide: components.button.js.anchor-button
-*/
-
-/*
-Button
-
-```
-
-```
-
-@interface IButtonProps
-
-Styleguide: components.button.js.button
-*/
diff --git a/packages/core/src/components/button/button-group.md b/packages/core/src/components/button/button-group.md
new file mode 100644
index 0000000000..9394a5ed79
--- /dev/null
+++ b/packages/core/src/components/button/button-group.md
@@ -0,0 +1,36 @@
+@# Button groups
+
+Button groups arrange multiple buttons in a horizontal or vertical 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.
+
+@css pt-button-group
+
+@### 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.
+
+@css pt-button-group.pt-fill
+
+@### 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.
+
+@css pt-button-group.pt-vertical
diff --git a/packages/core/src/components/button/button.md b/packages/core/src/components/button/button.md
new file mode 100644
index 0000000000..d6634f79d3
--- /dev/null
+++ b/packages/core/src/components/button/button.md
@@ -0,0 +1,88 @@
+@# Buttons
+
+Buttons trigger actions when clicked.
+
+@## CSS API
+
+Use the `pt-button` class to access button styles. You should implement buttons using the
+`
        
+
+@reactExample ButtonsExample
+
+@### Anchor button
+
+```jsx
+
+// renders:
+Click
+```
+
+@### Button
+
+```jsx
+
+```
+
+@interface IButtonProps
diff --git a/packages/core/src/components/callout/_callout.scss b/packages/core/src/components/callout/_callout.scss
index c406587bed..5dd29af3c2 100644
--- a/packages/core/src/components/callout/_callout.scss
+++ b/packages/core/src/components/callout/_callout.scss
@@ -7,22 +7,7 @@
 @import "../../common/variables";
 
 /*
-Callouts
-
-Callouts visually highlight important content for the user.
-
-Styleguide components.callout
-*/
-
-/*
-CSS API
-
-Callouts use the same visual intent modifier classes as buttons. If you need a
-heading, use the `
        ` element.
-
-
        
-  Note that the `
        ` heading is entirely optional.
-
        
+Callout
 
 Markup:
 
        
@@ -36,7 +21,7 @@ Markup:
 .pt-intent-danger  - Danger intent
 .pt-icon-info-sign - With an icon
 
-Styleguide components.callout.css
+Styleguide pt-callout
 */
 
 .pt-callout {
diff --git a/packages/core/src/components/callout/callout.md b/packages/core/src/components/callout/callout.md
new file mode 100644
index 0000000000..3475b7f0e1
--- /dev/null
+++ b/packages/core/src/components/callout/callout.md
@@ -0,0 +1,14 @@
+@# Callouts
+
+Callouts visually highlight important content for the user.
+
+@## CSS API
+
+Callouts use the same visual intent modifier classes as buttons. If you need a
+heading, use the `
        ` element.
+
+
        
+    Note that the `
        ` heading is entirely optional.
+
        
+
+@css pt-callout
diff --git a/packages/core/src/components/card/_card.scss b/packages/core/src/components/card/_card.scss
index 7b8cfa05f5..cac389f8c6 100644
--- a/packages/core/src/components/card/_card.scss
+++ b/packages/core/src/components/card/_card.scss
@@ -8,20 +8,6 @@
 /*
 Cards
 
-A card is a bounded unit of UI content with a solid background color.
-
-Styleguide components.card
-*/
-
-/*
-CSS API
-
-Start with `.pt-card` and add an elevation modifier class to apply a drop shadow that simulates
-height in the UI.
-
-You can also use the `.pt-elevation-*` classes by themselves to apply shadows to any arbitrary
-element.
-
 Markup:
 
        
   Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus nec dapibus et mauris,
@@ -34,7 +20,7 @@ Markup:
 .pt-elevation-3 - Third. For containers overlaying content temporarily.
 .pt-elevation-4 - Fourth. The strongest shadow, usually for overlay containers on top of backdrops.
 
-Styleguide components.card.css
+Styleguide pt-card
 */
 
 $card-padding: $pt-grid-size * 2 !default;
@@ -86,12 +72,6 @@ $dark-elevation-shadows: (
 /*
 Interactive cards
 
-Add the `.pt-interactive` modifier class to make a `.pt-card` respond to user interactions. When you
-hover over cards with this class applied, the mouse changes to a pointer and the elevation shadow on
-the card increases by two levels.
-
-Users expect an interactive card to be a single clickable unit.
-
 Markup:
 
        
   
        
@@ -108,7 +88,7 @@ Markup:
   
        
 
        
 
-Styleguide components.card.css.interactive
+Styleguide pt-card.pt-interactive
 */
 
 .pt-card.pt-interactive {
diff --git a/packages/core/src/components/card/card.md b/packages/core/src/components/card/card.md
new file mode 100644
index 0000000000..1286d29b33
--- /dev/null
+++ b/packages/core/src/components/card/card.md
@@ -0,0 +1,23 @@
+@# Cards
+
+A card is a bounded unit of UI content with a solid background color.
+
+@## CSS API
+
+Start with `.pt-card` and add an elevation modifier class to apply a drop shadow that simulates
+height in the UI.
+
+You can also use the `.pt-elevation-*` classes by themselves to apply shadows to any arbitrary
+element.
+
+@css pt-card
+
+@### Interactive cards
+
+Add the `.pt-interactive` modifier class to make a `.pt-card` respond to user interactions. When you
+hover over cards with this class applied, the mouse changes to a pointer and the elevation shadow on
+the card increases by two levels.
+
+Users expect an interactive card to be a single clickable unit.
+
+@css pt-card.pt-interactive
diff --git a/packages/core/src/components/collapse/_collapse.scss b/packages/core/src/components/collapse/_collapse.scss
index 0f2c135c04..f036b3f443 100644
--- a/packages/core/src/components/collapse/_collapse.scss
+++ b/packages/core/src/components/collapse/_collapse.scss
@@ -5,66 +5,6 @@
 
 @import "../../common/variables";
 
-/*
-Collapse
-
-The `Collapse` element shows and hides content with a built-in slide in/out animation.
-You might use this to create a panel of settings for your application, with sub-sections
-that can be expanded and collapsed.
-
-@react-example CollapseExample
-
-Styleguide components.collapse
-*/
-
-/*
-JavaScript API
-
-The `Collapse` component is available in the __@blueprintjs/core__ package.
-Make sure to review the [general usage docs for JS components](#components.usage).
-
-Any content should be a child of the `Collapse` element. Content must be in the document
-flow (e.g. `position: absolute;` wouldn't work, as the parent element would inherit a height of 0).
-
-Toggling the `isOpen` prop triggers the open and close animations.
-Once the component is in the closed state, the children are no longer rendered.
-
-```
-export interface ICollapseExampleState {
-    isOpen?: boolean;
-};
-
-export class CollapseExample extends React.Component<{}, ICollapseExampleState> {
-    public state = {
-        isOpen: false,
-    };
-
-    public render() {
-        return (
-            
        
-                
-                
-                    
        -                        Dummy text.
-                    
        
-                        
-            
        
-        );
-    }
-
-    private handleClick = () => {
-        this.setState({isOpen: !this.state.isOpen});
-    }
-}
-```
-
-@interface ICollapseProps
-
-Styleguide components.collapse.js
-*/
-
 $collapse-transition: ($pt-transition-duration * 2) $pt-transition-ease !default;
 
 .pt-collapse {
diff --git a/packages/core/src/components/collapse/collapse.md b/packages/core/src/components/collapse/collapse.md
new file mode 100644
index 0000000000..77b3679dd8
--- /dev/null
+++ b/packages/core/src/components/collapse/collapse.md
@@ -0,0 +1,51 @@
+@# Collapse
+
+The `Collapse` element shows and hides content with a built-in slide in/out animation.
+You might use this to create a panel of settings for your application, with sub-sections
+that can be expanded and collapsed.
+
+@reactExample CollapseExample
+
+@## JavaScript API
+
+The `Collapse` component is available in the __@blueprintjs/core__ package.
+Make sure to review the [general usage docs for JS components](#blueprint.usage).
+
+Any content should be a child of the `Collapse` element. Content must be in the document
+flow (e.g. `position: absolute;` wouldn't work, as the parent element would inherit a height of 0).
+
+Toggling the `isOpen` prop triggers the open and close animations.
+Once the component is in the closed state, the children are no longer rendered.
+
+```tsx
+export interface ICollapseExampleState {
+    isOpen?: boolean;
+};
+
+export class CollapseExample extends React.Component<{}, ICollapseExampleState> {
+    public state = {
+        isOpen: false,
+    };
+
+    public render() {
+        return (
+            
        
+                
+                
+                    
        +                        Dummy text.
+                    
        
+                        
+            
        
+        );
+    }
+
+    private handleClick = () => {
+        this.setState({ isOpen: !this.state.isOpen });
+    }
+}
+```
+
+@interface ICollapseProps
diff --git a/packages/core/src/components/collapsible-list/_collapsible-list.scss b/packages/core/src/components/collapsible-list/collapsible-list.md
similarity index 59%
rename from packages/core/src/components/collapsible-list/_collapsible-list.scss
rename to packages/core/src/components/collapsible-list/collapsible-list.md
index 0bd0eea7d3..8b76bcf6fd 100644
--- a/packages/core/src/components/collapsible-list/_collapsible-list.scss
+++ b/packages/core/src/components/collapsible-list/collapsible-list.md
@@ -1,40 +1,24 @@
-// Copyright 2015 Palantir Technologies, Inc. All rights reserved.
-// Licensed under the BSD-3 License as modified (the “License”); you may obtain a copy
-// of the license at https://github.com/palantir/blueprint/blob/master/LICENSE
-// and https://github.com/palantir/blueprint/blob/master/PATENTS
-
-/*
-Collapsible list
+@# Collapsible list
 
 The `CollapsibleList` React component accepts a list of menu items and a count of visible items. It
 shows precisely that many items and collapses the rest into a dropdown menu. The required
 `renderVisibleItem` callback prop allows for customizing the appearance of visible items, using the
 props from the `MenuItem` children.
 
-@react-example CollapsibleListExample
-
-Styleguide components.collapsiblelist
-*/
+@reactExample CollapsibleListExample
 
-/*
-JavaScript API
+@## JavaScript API
 
 The `CollapsibleList` component is available in the __@blueprintjs/core__ package.
-Make sure to review the [general usage docs for JS components](#components.usage).
+Make sure to review the [general usage docs for JS components](#blueprint.usage).
 
 Children of the `CollapsibleList` component _must_ be `MenuItem`s so they can be easily rendered
 in the dropdown. Define a `renderVisibleItem` callback to customize the appearance of visible
-items using their [`IMenuItemProps`](#components.menu.js.menu-item).
+items using their [`IMenuItemProps`](#core/components/menu.menu-item).
 
 @interface ICollapsibleListProps
 
-Weight: -10
-
-Styleguide components.collapsiblelist.js
-*/
-
-/*
-Separators
+@## Separators
 
 Often a list of items calls for separators between each item.
 Adding separators to a `CollapsibleList` is easily achieved via CSS using `::after` pseudo-elements.
@@ -43,16 +27,13 @@ Adding separators to a `CollapsibleList` is easily achieved via CSS using `::aft
 // pass `visibleItemClassName="my-list-item"` to component, then...
 
 .my-list-item::after {
-  display: inline-block;
-  content: "";
-  // custom separator styles...
+    display: inline-block;
+    content: "";
+    // custom separator styles...
 }
 
 // remove separator after the last item
 .my-list-item:last-child::after {
-  display: none;
+    display: none;
 }
 ```
-
-Styleguide components.collapsiblelist.separator
-*/
diff --git a/packages/core/src/components/components.md b/packages/core/src/components/components.md
new file mode 100644
index 0000000000..0ed89ce463
--- /dev/null
+++ b/packages/core/src/components/components.md
@@ -0,0 +1,33 @@
+@# Components
+
+
+
+@page alert
+@page breadcrumbs
+@page button
+@page button-group
+@page callout
+@page card
+@page collapse
+@page collapsible-list
+@page context-menu
+@page dialog
+@page editable-text
+@page forms
+@page hotkeys
+@page menu
+@page navbar
+@page non-ideal-state
+@page overlay
+@page popover
+@page portal
+@page progress
+@page sliders
+@page table
+@page tabs
+@page tabs2
+@page tag
+@page text
+@page toast
+@page tooltip
+@page tree
diff --git a/packages/core/src/components/context-menu/_context-menu.scss b/packages/core/src/components/context-menu/_context-menu.scss
index 1c6ae0e4bb..14da431223 100644
--- a/packages/core/src/components/context-menu/_context-menu.scss
+++ b/packages/core/src/components/context-menu/_context-menu.scss
@@ -3,124 +3,6 @@
 // of the license at https://github.com/palantir/blueprint/blob/master/LICENSE
 // and https://github.com/palantir/blueprint/blob/master/PATENTS
 
-/*
-Context menus
-
-Context menus present the user with a custom list of actions upon right-click.
-
-You can create context menus in either of the following ways:
-
-- by adding the `@ContextMenuTarget` [decorator](#components.context-menu.decorator) to a React
-  component that implements `renderContextMenu(): JSX.Element`.
-- via the [imperative](#components.context-menu.js) `ContextMenu.show` and `ContextMenu.hide` API
-  methods, ideal for non-React-based applications.
-
-@react-example ContextMenuExample
-
-Styleguide components.context-menu
-*/
-
-/*
-JavaScript API: decorator
-
-The `ContextMenuTarget` decorator is available in the __@blueprintjs/core__ package.
-Make sure to review the [general usage docs for JS components](#components.usage).
-
-The `@ContextMenuTarget` [class decorator][ts-decorator] can be applied to any `React.Component`
-class that meets the following requirements:
-
-- It defines an instance method called `renderContextMenu()` that returns a single `JSX.Element`
-  (most likely a [`Menu`](#components.menu)).
-- Its root element supports the `"contextmenu"` event and the `onContextMenu` prop.
-
-  This is always true if the decorated class uses an intrinsic element, such as `
        `, as its
-  root. If it uses a custom element as its root, you must ensure that the prop is implemented
-  correctly for that element.
-
-When the user triggers the `"contextmenu"` event on the decorated class, `renderContextMenu()` is
-called. If `renderContextMenu()` returns an element, the browser's native [context menu][wiki-cm] is
-blocked and the returned element is displayed instead in a `Popover` at the cursor's location.
-
-If the instance has a `onContextMenuClose` method, the decorator will call this function when
-the context menu is closed.
-
-```
-import { ContextMenuTarget, Menu, MenuItem } from "@blueprintjs/core";
-
-@ContextMenuTarget
-class RightClickMe extends React.Component<{}, {}> {
-    public render() {
-      // root element must support `onContextMenu`
-      return 
        {...}
        ;
-    }
-
-    public renderContextMenu() {
-        // return a single element, or nothing to use default browser behavior
-        return (
-            
-                
-                
-            
-        );
-    }
-
-    public onContextMenuClose() {
-        // Optional method called once the context menu is closed.
-    }
-}
-```
-
-[ts-decorator]: https://github.com/Microsoft/TypeScript-Handbook/blob/master/pages/Decorators.md
-[wiki-cm]: https://en.wikipedia.org/wiki/Context_menu
-
-Styleguide components.context-menu.decorator
-*/
-
-/*
-JavaScript API: imperative
-
-The `ContextMenu` component is available in the __@blueprintjs/core__ package.
-Make sure to review the [general usage docs for JS components](#components.usage).
-
-The imperative API provides a single static `ContextMenu` object, enforcing the principle that only
-one context menu can be open at a time.
-
-- `ContextMenu.show(menu: JSX.Element, offset: IOffset, onClose?: () => void): void` –
-  Show the given element at the given offset from the top-left corner of the viewport.
-  Showing a menu closes the previously shown one automatically.
-
-  The menu appears below-right of this point, but will flip to below-left instead if there is not
-  enough room onscreen. The optional callback is invoked when this menu closes.
-
-- `ContextMenu.hide(): void` – Hide the context menu, if it is open.
-- `ContextMenu.isOpen(): boolean` – Whether a context menu is currently visible.
-
-This API is ideal for non-React-based apps or for programmatically triggered menus.
-
-```
-import { ContextMenu, MenuFactory, MenuItemFactory } from "@blueprintjs/core";
-
-const rightClickMe = document.query("#right-click-me") as HTMLElement;
-rightClickMe.oncontextmenu = (e: MouseEvent) => {
-    // prevent the browser's native context menu
-    e.preventDefault();
-    // render a Menu without JSX...
-    const menu = MenuFactory({
-        children: [
-            MenuItemFactory({ onClick: handleSave, text: "Save" }),
-            MenuItemFactory({ onClick: handleDelete, text: "Delete" }),
-        ]
-    });
-    // mouse position is available on event
-    ContextMenu.show(menu, { left: e.clientX, top: e.clientY }, () => {
-        // menu was closed; callback optional
-    });
-};
-```
-
-Styleguide components.context-menu.js
-*/
-
 .pt-context-menu .pt-popover-target {
   display: block;
 }
diff --git a/packages/core/src/components/context-menu/context-menu.md b/packages/core/src/components/context-menu/context-menu.md
new file mode 100644
index 0000000000..8615d567e1
--- /dev/null
+++ b/packages/core/src/components/context-menu/context-menu.md
@@ -0,0 +1,107 @@
+@# Context menus
+
+Context menus present the user with a custom list of actions upon right-click.
+
+You can create context menus in either of the following ways:
+
+- by adding the `@ContextMenuTarget` [decorator](#core/components/context-menu.javascript-api--decorator)
+  to a React component that implements `renderContextMenu(): JSX.Element`.
+- via the [imperative](#core/components/context-menu.javascript-api--imperative) `ContextMenu.show`
+  and `ContextMenu.hide` API methods, ideal for non-React-based applications.
+
+@reactExample ContextMenuExample
+
+@## JavaScript API: decorator
+
+The `ContextMenuTarget` decorator is available in the __@blueprintjs/core__ package.
+Make sure to review the [general usage docs for JS components](#blueprint.usage).
+
+The `@ContextMenuTarget` [class decorator][ts-decorator] can be applied to any `React.Component`
+class that meets the following requirements:
+
+- It defines an instance method called `renderContextMenu()` that returns a single `JSX.Element`
+(most likely a [`Menu`](#core/components/menu)).
+- Its root element supports the `"contextmenu"` event and the `onContextMenu` prop.
+
+This is always true if the decorated class uses an intrinsic element, such as `
        `, as its
+root. If it uses a custom element as its root, you must ensure that the prop is implemented
+correctly for that element.
+
+When the user triggers the `"contextmenu"` event on the decorated class, `renderContextMenu()` is
+called. If `renderContextMenu()` returns an element, the browser's native [context menu][wiki-cm] is
+blocked and the returned element is displayed instead in a `Popover` at the cursor's location.
+
+If the instance has a `onContextMenuClose` method, the decorator will call this function when
+the context menu is closed.
+
+```tsx
+import { ContextMenuTarget, Menu, MenuItem } from "@blueprintjs/core";
+
+@ContextMenuTarget
+class RightClickMe extends React.Component<{}, {}> {
+    public render() {
+        // root element must support `onContextMenu`
+        return 
        {...}
        ;
+    }
+
+    public renderContextMenu() {
+        // return a single element, or nothing to use default browser behavior
+        return (
+            
+                
+                
+            
+        );
+    }
+
+    public onContextMenuClose() {
+        // Optional method called once the context menu is closed.
+    }
+}
+```
+
+[ts-decorator]: https://github.com/Microsoft/TypeScript-Handbook/blob/master/pages/Decorators.md
+[wiki-cm]: https://en.wikipedia.org/wiki/Context_menu
+
+@## JavaScript API: imperative
+
+The `ContextMenu` component is available in the __@blueprintjs/core__ package.
+Make sure to review the [general usage docs for JS components](#blueprint.usage).
+
+The imperative API provides a single static `ContextMenu` object, enforcing the principle that only
+one context menu can be open at a time.
+
+- `ContextMenu.show(menu: JSX.Element, offset: IOffset, onClose?: () => void): void` –
+Show the given element at the given offset from the top-left corner of the viewport.
+Showing a menu closes the previously shown one automatically.
+
+The menu appears below-right of this point, but will flip to below-left instead if there is not
+enough room onscreen. The optional callback is invoked when this menu closes.
+
+- `ContextMenu.hide(): void` – Hide the context menu, if it is open.
+- `ContextMenu.isOpen(): boolean` – Whether a context menu is currently visible.
+
+This API is ideal for non-React-based apps or for programmatically triggered menus.
+
+```tsx
+import { ContextMenu, MenuFactory, MenuItemFactory } from "@blueprintjs/core";
+
+const rightClickMe = document.query("#right-click-me") as HTMLElement;
+rightClickMe.oncontextmenu = (e: MouseEvent) => {
+    // prevent the browser's native context menu
+    e.preventDefault();
+
+    // render a Menu without JSX...
+    const menu = MenuFactory({
+        children: [
+            MenuItemFactory({ onClick: handleSave, text: "Save" }),
+            MenuItemFactory({ onClick: handleDelete, text: "Delete" }),
+        ]
+    });
+
+    // mouse position is available on event
+    ContextMenu.show(menu, { left: e.clientX, top: e.clientY }, () => {
+        // menu was closed; callback optional
+    });
+};
+```
diff --git a/packages/core/src/components/dialog/_dialog.scss b/packages/core/src/components/dialog/_dialog.scss
index fc5307a174..5a6e9bd19e 100644
--- a/packages/core/src/components/dialog/_dialog.scss
+++ b/packages/core/src/components/dialog/_dialog.scss
@@ -10,82 +10,28 @@
 @import "../../common/variables";
 
 /*
-Dialogs
+Dialog
 
-Dialogs present content overlaid over other parts of the UI.
-
-
        
-  
        Terminology note
        
-  The term "modal" is sometimes used to mean "dialog," but this is a misnomer.
-  _Modal_ is an adjective that describes parts of a UI.
-  An element is considered modal if it
-  [blocks interaction with the rest of the application](https://en.wikipedia.org/wiki/Modal_window).
-  We use the term "dialog" to avoid confusion with the adjective.
+Markup:
+
        
+  
        
+    
+    
        Dialog header
        
+    
+  
        
+  
        
+    This dialog hasn't been wired up with any open or close interactions.
+    It's just an example of markup and styles.
+  
        
+  
        
+    
        
+      
+      
+    
        
+  
        
 
        
 
-Styleguide components.dialog
-*/
-
-/*
-JavaScript API
-
-The `Dialog` component is available in the __@blueprintjs/core__ package.
-Make sure to review the [general usage docs for JS components](#components.usage).
-
-There are two ways to render dialogs:
-
-- in-place in the DOM tree. This is the default behavior.
-- injected into a newly created element attached to `document.body`.
-  Set `inline={false}` to enable this.
-
-`Dialog` is implemented as a stateless React component. The children you provide to this component
-are rendered as contents inside the `.pt-dialog` element.
-
-```
-interface IDialogExampleState {
-    isOpen: boolean;
-}
-
-class DialogExample extends React.Component<{}, IDialogExampleState> {
-    public state = { isOpen: false };
-
-    public render() {
-        return (
-            
        
-                
        
-                    
        
-                
-            
        
-        );
-    }
-
-    private toggleDialog = () => this.setState({ isOpen: !this.state.isOpen });
-}
-```
-
-@interface IDialogProps
-
-@react-example DialogExample
-
-Styleguide components.dialog.js
+Styleguide pt-dialog
 */
 
 $dialog-border-radius: $pt-border-radius * 2 !default;
@@ -204,34 +150,3 @@ $dialog-padding: $pt-grid-size * 2 !default;
     margin-left: $pt-grid-size;
   }
 }
-
-/*
-CSS API
-
-You can create dialogs manually using the HTML markup and `pt-dialog-*` classes below.
-However, you should use the dialog [JavaScript APIs](#components.dialog.js) whenever possible,
-as they automatically generate some of this markup.
-
-More examples of dialog content are shown below.
-
-Markup:
-
        
-  
        
-    
-    
        Dialog header
        
-    
-  
        
-  
        
-    This dialog hasn't been wired up with any open or close interactions.
-    It's just an example of markup and styles.
-  
        
-  
        
-    
        
-      
-      
-    
        
-  
        
-
        
-
-Styleguide components.dialog.css
-*/
diff --git a/packages/core/src/components/dialog/dialog.md b/packages/core/src/components/dialog/dialog.md
new file mode 100644
index 0000000000..9f293a5e41
--- /dev/null
+++ b/packages/core/src/components/dialog/dialog.md
@@ -0,0 +1,80 @@
+@# Dialogs
+
+Dialogs present content overlaid over other parts of the UI.
+
+
        
+    
        Terminology note
        
+    The term "modal" is sometimes used to mean "dialog," but this is a misnomer.
+    _Modal_ is an adjective that describes parts of a UI.
+    An element is considered modal if it
+    [blocks interaction with the rest of the application](https://en.wikipedia.org/wiki/Modal_window).
+    We use the term "dialog" to avoid confusion with the adjective.
+
        
+
+@## JavaScript API
+
+The `Dialog` component is available in the __@blueprintjs/core__ package.
+Make sure to review the [general usage docs for JS components](#blueprint.usage).
+
+There are two ways to render dialogs:
+
+- in-place in the DOM tree. This is the default behavior.
+- injected into a newly created element attached to `document.body`.
+Set `inline={false}` to enable this.
+
+`Dialog` is implemented as a stateless React component. The children you provide to this component
+are rendered as contents inside the `.pt-dialog` element.
+
+```tsx
+interface IDialogExampleState {
+    isOpen: boolean;
+}
+
+class DialogExample extends React.Component<{}, IDialogExampleState> {
+    public state = { isOpen: false };
+
+    public render() {
+        return (
+            
        
+                
        
+                    
        
+                
+            
        
+        );
+    }
+
+    private toggleDialog = () => this.setState({ isOpen: !this.state.isOpen });
+}
+```
+
+@interface IDialogProps
+
+@reactExample DialogExample
+
+@## CSS API
+
+You can create dialogs manually using the HTML markup and `pt-dialog-*` classes below.
+However, you should use the dialog [JavaScript APIs](#core/components/dialog.javascript-api) whenever possible,
+as they automatically generate some of this markup.
+
+More examples of dialog content are shown below.
+
+@css pt-dialog
diff --git a/packages/core/src/components/editable-text/_editable-text.scss b/packages/core/src/components/editable-text/_editable-text.scss
index 669a8c5a1c..4acfdde448 100644
--- a/packages/core/src/components/editable-text/_editable-text.scss
+++ b/packages/core/src/components/editable-text/_editable-text.scss
@@ -7,82 +7,6 @@
 @import "../../common/variables";
 @import "../forms/common";
 
-/*
-Editable text
-
-`EditableText` looks like normal UI text, but transforms into a text input field when the user
-focuses it.
-
-The text input inherits all font styling from its ancestors, making the transition between reading
-and editing text seamless.
-
-You might use this component for inline renaming, or for an [editable multiline
-description](#components.editable.multiline). You should not use `EditableText` when a static
-always-editable `` or `
@@ -101,9 +82,7 @@ Markup:
 .pt-intent-danger  - Danger intent
 .pt-fill  - Take up full width of parent element
 
-Weight: 3
-
-Styleguide components.forms.textarea
+Styleguide pt-textarea
 */
 
 // stylelint-disable selector-no-qualifying-type
diff --git a/packages/core/src/components/forms/_label.scss b/packages/core/src/components/forms/_label.scss
index 9770f7af28..dba146a0ac 100644
--- a/packages/core/src/components/forms/_label.scss
+++ b/packages/core/src/components/forms/_label.scss
@@ -8,30 +8,6 @@
 /*
 Labels
 
-Labels enhance the usability of your forms.
-
-
        
-  
        Simple labels vs. form groups
        
-  
        Blueprint provides two ways of connecting label text to control fields, depending on the complexity of the control.
        
-  
        Simple labels are a basic way to connect a label with a single control.
        
-  
        Form groups support more complex control layouts but require more markup to maintain consistent visuals.
        
-
        
-
-Weight: 1
-
-Styleguide components.forms.labels
-*/
-
-/*
-Simple labels
-
-Simple labels are useful for basic forms for a single ``.
-
-- Add extra information to the label with `span.pt-text-muted`.
-
-- Putting the `` element _inside_ a `