diff --git a/packages/docusaurus-plugin-content-pages/src/__tests__/__fixtures__/website/pages/hello/world.js b/packages/docusaurus-plugin-content-pages/src/__tests__/__fixtures__/website/src/pages/hello/world.js
similarity index 100%
rename from packages/docusaurus-plugin-content-pages/src/__tests__/__fixtures__/website/pages/hello/world.js
rename to packages/docusaurus-plugin-content-pages/src/__tests__/__fixtures__/website/src/pages/hello/world.js
diff --git a/packages/docusaurus-plugin-content-pages/src/__tests__/__fixtures__/website/pages/index.js b/packages/docusaurus-plugin-content-pages/src/__tests__/__fixtures__/website/src/pages/index.js
similarity index 100%
rename from packages/docusaurus-plugin-content-pages/src/__tests__/__fixtures__/website/pages/index.js
rename to packages/docusaurus-plugin-content-pages/src/__tests__/__fixtures__/website/src/pages/index.js
diff --git a/packages/docusaurus-plugin-content-pages/src/index.js b/packages/docusaurus-plugin-content-pages/src/index.js
index 8ed0d8363c..38d1b789ec 100644
--- a/packages/docusaurus-plugin-content-pages/src/index.js
+++ b/packages/docusaurus-plugin-content-pages/src/index.js
@@ -11,7 +11,7 @@ const fs = require('fs');
 const {encodePath, fileToPath, docuHash} = require('@docusaurus/utils');
 
 const DEFAULT_OPTIONS = {
-  path: 'pages', // Path to data on filesystem, relative to site dir.
+  path: 'src/pages', // Path to data on filesystem, relative to site dir.
   routeBasePath: '', // URL Route.
   include: ['**/*.{js,jsx}'], // Extensions to include.
 };
diff --git a/packages/docusaurus/CHANGELOG.md b/packages/docusaurus/CHANGELOG.md
index 6b46c75471..16384e630f 100644
--- a/packages/docusaurus/CHANGELOG.md
+++ b/packages/docusaurus/CHANGELOG.md
@@ -3,6 +3,7 @@
 ## Unreleased
 
 - Added Google analytics and Google gtag plugins.
+- Moved source components to `/src`. Please create a `website/src` directory and move your `/pages` and `/theme` code into it. This is to make it easier to integrate your website with external build/static analysis tooling (you can now just pass in `src/**/*.js` as the path to process).
 
 ## 2.0.0-alpha.19
 
diff --git a/packages/docusaurus/src/commands/deploy.ts b/packages/docusaurus/src/commands/deploy.ts
index 61780706b5..b5863e8c6d 100644
--- a/packages/docusaurus/src/commands/deploy.ts
+++ b/packages/docusaurus/src/commands/deploy.ts
@@ -8,7 +8,11 @@
 import fs from 'fs-extra';
 import path from 'path';
 import shell from 'shelljs';
-import {CONFIG_FILE_NAME} from '../constants';
+import {
+  BUILD_DIR_NAME,
+  CONFIG_FILE_NAME,
+  GENERATED_FILES_DIR_NAME,
+} from '../constants';
 import {loadConfig} from '../server/config';
 import {build} from './build';
 
@@ -131,9 +135,9 @@ export async function deploy(siteDir: string): Promise<void> {
 
       shell.cd('../..');
 
-      const fromPath = path.join('build');
+      const fromPath = path.join(BUILD_DIR_NAME);
       const toPath = path.join(
-        '.docusaurus',
+        GENERATED_FILES_DIR_NAME,
         `${projectName}-${deploymentBranch}`,
       );
 
diff --git a/packages/docusaurus/src/commands/swizzle.ts b/packages/docusaurus/src/commands/swizzle.ts
index 38d12425ff..bbb87df6bc 100644
--- a/packages/docusaurus/src/commands/swizzle.ts
+++ b/packages/docusaurus/src/commands/swizzle.ts
@@ -10,6 +10,8 @@ import fs from 'fs-extra';
 import importFresh from 'import-fresh';
 import path from 'path';
 
+import {THEME_PATH} from '../constants';
+
 export async function swizzle(
   siteDir: string,
   themeName: string,
@@ -20,7 +22,7 @@ export async function swizzle(
   let fromPath = pluginInstance.getThemePath();
 
   if (fromPath) {
-    let toPath = path.resolve(siteDir, 'theme');
+    let toPath = path.resolve(siteDir, THEME_PATH);
     if (componentName) {
       fromPath = path.join(fromPath, componentName);
       toPath = path.join(toPath, componentName);
diff --git a/packages/docusaurus/src/constants.ts b/packages/docusaurus/src/constants.ts
index a3242a83b5..abd43666f4 100644
--- a/packages/docusaurus/src/constants.ts
+++ b/packages/docusaurus/src/constants.ts
@@ -5,6 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-export const GENERATED_FILES_DIR_NAME = '.docusaurus';
-export const STATIC_DIR_NAME = 'static';
+export const BUILD_DIR_NAME = 'build';
 export const CONFIG_FILE_NAME = 'docusaurus.config.js';
+export const GENERATED_FILES_DIR_NAME = '.docusaurus';
+export const SRC_DIR_NAME = 'src';
+export const STATIC_DIR_NAME = 'static';
+export const THEME_PATH = `${SRC_DIR_NAME}/theme`;
diff --git a/packages/docusaurus/src/server/__tests__/__fixtures__/custom-site/docusaurus.config.js b/packages/docusaurus/src/server/__tests__/__fixtures__/custom-site/docusaurus.config.js
index 8aa30a0b1b..07f979ed05 100644
--- a/packages/docusaurus/src/server/__tests__/__fixtures__/custom-site/docusaurus.config.js
+++ b/packages/docusaurus/src/server/__tests__/__fixtures__/custom-site/docusaurus.config.js
@@ -18,7 +18,7 @@ module.exports = {
       '@docusaurus/plugin-content-docs',
       {
         path: '../docs',
-        sidebarPath: require.resolve('./sidebars.json'),
+        sidebarPath: require.resolve('./sidebars.js'),
       },
     ],
     '@docusaurus/plugin-content-pages',
diff --git a/packages/docusaurus/src/server/__tests__/__fixtures__/custom-site/sidebars.js b/packages/docusaurus/src/server/__tests__/__fixtures__/custom-site/sidebars.js
new file mode 100644
index 0000000000..afb5e4eca9
--- /dev/null
+++ b/packages/docusaurus/src/server/__tests__/__fixtures__/custom-site/sidebars.js
@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2017-present, Facebook, Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+module.exports = {
+  docs: {
+    Test: ['foo/bar', 'foo/baz'],
+    Guides: ['hello'],
+  },
+};
diff --git a/packages/docusaurus/src/server/__tests__/__fixtures__/custom-site/sidebars.json b/packages/docusaurus/src/server/__tests__/__fixtures__/custom-site/sidebars.json
deleted file mode 100644
index 24d61b49c7..0000000000
--- a/packages/docusaurus/src/server/__tests__/__fixtures__/custom-site/sidebars.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
-  "docs": {
-    "Test": [
-      "foo/bar",
-      "foo/baz"
-    ],
-    "Guides": [
-      "hello"
-    ]
-  }
-}
diff --git a/packages/docusaurus/src/server/__tests__/__fixtures__/simple-site/docusaurus.config.js b/packages/docusaurus/src/server/__tests__/__fixtures__/simple-site/docusaurus.config.js
index b8c5697691..0ead074a11 100644
--- a/packages/docusaurus/src/server/__tests__/__fixtures__/simple-site/docusaurus.config.js
+++ b/packages/docusaurus/src/server/__tests__/__fixtures__/simple-site/docusaurus.config.js
@@ -18,7 +18,7 @@ module.exports = {
       '@docusaurus/plugin-content-docs',
       {
         path: '../docs',
-        sidebarPath: require.resolve('./sidebars.json'),
+        sidebarPath: require.resolve('./sidebars.js'),
       },
     ],
     '@docusaurus/plugin-content-pages',
diff --git a/packages/docusaurus/src/server/__tests__/__fixtures__/simple-site/sidebars.js b/packages/docusaurus/src/server/__tests__/__fixtures__/simple-site/sidebars.js
new file mode 100644
index 0000000000..afb5e4eca9
--- /dev/null
+++ b/packages/docusaurus/src/server/__tests__/__fixtures__/simple-site/sidebars.js
@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2017-present, Facebook, Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+module.exports = {
+  docs: {
+    Test: ['foo/bar', 'foo/baz'],
+    Guides: ['hello'],
+  },
+};
diff --git a/packages/docusaurus/src/server/__tests__/__fixtures__/simple-site/sidebars.json b/packages/docusaurus/src/server/__tests__/__fixtures__/simple-site/sidebars.json
deleted file mode 100644
index 24d61b49c7..0000000000
--- a/packages/docusaurus/src/server/__tests__/__fixtures__/simple-site/sidebars.json
+++ /dev/null
@@ -1,11 +0,0 @@
-{
-  "docs": {
-    "Test": [
-      "foo/bar",
-      "foo/baz"
-    ],
-    "Guides": [
-      "hello"
-    ]
-  }
-}
diff --git a/packages/docusaurus/src/server/__tests__/__fixtures__/simple-site/pages/hello/world.js b/packages/docusaurus/src/server/__tests__/__fixtures__/simple-site/src/pages/hello/world.js
similarity index 100%
rename from packages/docusaurus/src/server/__tests__/__fixtures__/simple-site/pages/hello/world.js
rename to packages/docusaurus/src/server/__tests__/__fixtures__/simple-site/src/pages/hello/world.js
diff --git a/packages/docusaurus/src/server/__tests__/__fixtures__/simple-site/pages/index.js b/packages/docusaurus/src/server/__tests__/__fixtures__/simple-site/src/pages/index.js
similarity index 100%
rename from packages/docusaurus/src/server/__tests__/__fixtures__/simple-site/pages/index.js
rename to packages/docusaurus/src/server/__tests__/__fixtures__/simple-site/src/pages/index.js
diff --git a/packages/docusaurus/src/server/index.ts b/packages/docusaurus/src/server/index.ts
index 15f3152020..ef0ff85b4b 100644
--- a/packages/docusaurus/src/server/index.ts
+++ b/packages/docusaurus/src/server/index.ts
@@ -8,7 +8,12 @@
 import {generate} from '@docusaurus/utils';
 import _ from 'lodash';
 import path from 'path';
-import {CONFIG_FILE_NAME, GENERATED_FILES_DIR_NAME} from '../constants';
+import {
+  BUILD_DIR_NAME,
+  CONFIG_FILE_NAME,
+  GENERATED_FILES_DIR_NAME,
+  THEME_PATH,
+} from '../constants';
 import {loadClientModules} from './client-modules';
 import {loadConfig} from './config';
 import {loadPlugins} from './plugins';
@@ -39,7 +44,7 @@ export async function load(
     `export default ${JSON.stringify(siteConfig, null, 2)};`,
   );
 
-  const outDir = path.resolve(siteDir, 'build');
+  const outDir = path.resolve(siteDir, BUILD_DIR_NAME);
   const {baseUrl} = siteConfig;
 
   const context: LoadContext = {
@@ -72,7 +77,7 @@ export async function load(
   const pluginThemes = _.compact(
     plugins.map(plugin => plugin.getThemePath && plugin.getThemePath()),
   );
-  const userTheme = path.resolve(siteDir, 'theme');
+  const userTheme = path.resolve(siteDir, THEME_PATH);
   const alias = loadThemeAlias([fallbackTheme, ...pluginThemes, userTheme]);
   // Make a fake plugin to resolve aliased theme components.
   plugins.push({
diff --git a/packages/docusaurus/templates/classic/docusaurus.config.js b/packages/docusaurus/templates/classic/docusaurus.config.js
index e28f6c26ca..8b7f0c4e89 100644
--- a/packages/docusaurus/templates/classic/docusaurus.config.js
+++ b/packages/docusaurus/templates/classic/docusaurus.config.js
@@ -74,7 +74,7 @@ module.exports = {
           sidebarPath: require.resolve('./sidebars.js'),
         },
         theme: {
-          customCss: require.resolve('./css/custom.css'),
+          customCss: require.resolve('./src/css/custom.css'),
         },
       },
     ],
diff --git a/packages/docusaurus/templates/classic/css/custom.css b/packages/docusaurus/templates/classic/src/css/custom.css
similarity index 100%
rename from packages/docusaurus/templates/classic/css/custom.css
rename to packages/docusaurus/templates/classic/src/css/custom.css
diff --git a/packages/docusaurus/templates/classic/pages/index.js b/packages/docusaurus/templates/classic/src/pages/index.js
similarity index 100%
rename from packages/docusaurus/templates/classic/pages/index.js
rename to packages/docusaurus/templates/classic/src/pages/index.js
diff --git a/packages/docusaurus/templates/classic/pages/styles.module.css b/packages/docusaurus/templates/classic/src/pages/styles.module.css
similarity index 100%
rename from packages/docusaurus/templates/classic/pages/styles.module.css
rename to packages/docusaurus/templates/classic/src/pages/styles.module.css
diff --git a/website/docs/writing-docs.mdx b/website/docs/writing-docs.mdx
index 81f1e9de91..c20e331ec5 100644
--- a/website/docs/writing-docs.mdx
+++ b/website/docs/writing-docs.mdx
@@ -59,7 +59,7 @@ The headers are well-spaced so that the hierarchy is clear.
 
 This will render in the browser as follows:
 
-import BrowserWindow from '../components/BrowserWindow';
+import BrowserWindow from '../src/components/BrowserWindow';
 
 <BrowserWindow url="http://localhost:3000">
 <h2>Hello from Docusaurus</h2>
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
index e06f3d746a..cf3eb14649 100644
--- a/website/docusaurus.config.js
+++ b/website/docusaurus.config.js
@@ -27,7 +27,7 @@ module.exports = {
           postsPerPage: 3,
         },
         theme: {
-          customCss: require.resolve('./css/custom.css'),
+          customCss: require.resolve('./src/css/custom.css'),
         },
       },
     ],
diff --git a/website/components/BrowserWindow/index.js b/website/src/components/BrowserWindow/index.js
similarity index 100%
rename from website/components/BrowserWindow/index.js
rename to website/src/components/BrowserWindow/index.js
diff --git a/website/components/BrowserWindow/styles.module.css b/website/src/components/BrowserWindow/styles.module.css
similarity index 100%
rename from website/components/BrowserWindow/styles.module.css
rename to website/src/components/BrowserWindow/styles.module.css
diff --git a/website/css/custom.css b/website/src/css/custom.css
similarity index 100%
rename from website/css/custom.css
rename to website/src/css/custom.css
diff --git a/website/pages/feedback/index.js b/website/src/pages/feedback/index.js
similarity index 100%
rename from website/pages/feedback/index.js
rename to website/src/pages/feedback/index.js
diff --git a/website/pages/index.js b/website/src/pages/index.js
similarity index 100%
rename from website/pages/index.js
rename to website/src/pages/index.js
diff --git a/website/pages/styles.module.css b/website/src/pages/styles.module.css
similarity index 100%
rename from website/pages/styles.module.css
rename to website/src/pages/styles.module.css
diff --git a/website/scripts/canny.js b/website/src/scripts/canny.js
similarity index 100%
rename from website/scripts/canny.js
rename to website/src/scripts/canny.js