Tweak docs

jaredpalmer · Nov 4, 2019 · f1a2643 · f1a2643
1 parent 6225b8e
commit f1a2643
Show file tree

Hide file tree

Showing 10 changed files with 1,058 additions and 812 deletions.
diff --git a/src/index.ts b/src/index.ts
@@ -288,7 +288,10 @@ prog
         scripts: {
           start: 'tsdx watch',
           build: 'tsdx build',
-          test: template === 'react' ? 'tsdx test --env=jsdom --passWithNoTests' : 'tsdx test',
+          test:
+            template === 'react'
+              ? 'tsdx test --env=jsdom --passWithNoTests'
+              : 'tsdx test',
           lint: 'tsdx lint',
         },
         peerDependencies: template === 'react' ? { react: '>=16' } : {},

diff --git a/website/docs/api.md b/website/docs/api.md
@@ -1,6 +1,6 @@
 ---
 id: api
-title: API
+title: API Reference
 ---
 
 ### `tsdx watch`
@@ -19,14 +19,16 @@ Options
   --format              Specify module format(s)  (default cjs,esm)
   --tsconfig            Specify your custom tsconfig path (default <root-folder>/tsconfig.json)
   --verbose             Keep outdated console output in watch mode instead of clearing the screen
+  --noClean             Don't clean the dist folder
   -h, --help            Displays this message
 
 Examples
   $ tsdx watch --entry src/foo.tsx
   $ tsdx watch --target node
   $ tsdx watch --name Foo
   $ tsdx watch --format cjs,esm,umd
-  $ tsdx build --tsconfig ./tsconfig.foo.json
+  $ tsdx watch --tsconfig ./tsconfig.foo.json
+  $ tsdx watch --noClean
 ```
 
 ### `tsdx build`
@@ -73,11 +75,13 @@ Options
   --fix               Fixes fixable errors and warnings
   --ignore-pattern    Ignore a pattern
   --write-file        Write the config file locally
+  --report-file       Write JSON report to file locally
   -h, --help          Displays this message
 
 Examples
   $ tsdx lint src
   $ tsdx lint src --fix
   $ tsdx lint src test --ignore-pattern test/foo.ts
   $ tsdx lint src --write-file
+  $ tsdx lint src --report-file report.json
 ```
diff --git a/website/docs/starthere.md → website/docs/get-started.md b/website/docs/starthere.md → website/docs/get-started.md
@@ -1,8 +1,26 @@
 ---
-id: starthere
+id: get-started
 title: Getting Started
 ---
 
+## Overview
+
+Despite all the recent hype, setting up a new TypeScript (x React) library can be tough. Between [Rollup](https://github.com/rollup/rollup), [Jest](https://github.com/facebook/jest), `tsconfig`, [Yarn resolutions](https://yarnpkg.com/en/docs/selective-version-resolutions), ESLint, and getting VSCode to play nicely....there is just a whole lot of stuff to do (and things to screw up). TSDX is a zero-config CLI that helps you develop, test, and publish modern TypeScript packages with ease--so you can focus on your awesome new library and not waste another afternoon on the configuration.
+
+## Features
+
+TSDX comes with the "battery-pack included" and is part of a complete TypeScript breakfast:
+
+- Bundles your code with [Rollup](https://github.com/rollup/rollup) and outputs multiple module formats (CJS & ESM by default, and also UMD if you want) plus development and production builds
+- Comes with treeshaking, ready-to-rock lodash optimizations, and minification/compression
+- Live reload / watch-mode
+- Works with React
+- Human readable error messages (and in VSCode-friendly format)
+- Bundle size snapshots
+- Opt-in to extract `invariant` error codes
+- Jest test runner setup with sensible defaults via `tsdx test`
+- Zero-config, single dependency
+
 ## Quick Start
 
 ```

diff --git a/website/docs/features.md → website/docs/philosophy.md b/website/docs/features.md → website/docs/philosophy.md
@@ -1,22 +1,8 @@
 ---
-id: features
-title: Features
+id: philosophy
+title: Philosophy
 ---
 
-## Features
-
-TSDX comes with the "battery-pack included" and is part of a complete TypeScript breakfast:
-
-- Bundles your code with [Rollup](https://github.com/rollup/rollup) and outputs multiple module formats (CJS & ESM by default, and also UMD if you want) plus development and production builds
-- Comes with treeshaking, ready-to-rock lodash optimizations, and minification/compression
-- Live reload / watch-mode
-- Works with React
-- Human readable error messages (and in VSCode-friendly format)
-- Bundle size snapshots
-- Opt-in to extract `invariant` error codes
-- Jest test runner setup with sensible defaults via `tsdx test`
-- Zero-config, single dependency
-
 ## Inspiration
 
 TSDX is ripped out of [Formik's](https://github.com/jaredpalmer/formik) build tooling. TSDX is very similar to [@developit/microbundle](https://github.com/developit/microbundle), but that is because Formik's Rollup configuration and Microbundle's internals have converged around similar plugins over the last year or so.

diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
@@ -21,8 +21,10 @@ module.exports = {
         src: 'img/logo.svg',
       },
       links: [
-        { to: 'docs/starthere', label: 'Docs', position: 'right' },
-        { to: 'blog', label: 'Blog', position: 'right' },
+        { to: 'docs/get-started', label: 'Docs', position: 'right' },
+        { to: 'help', label: 'Help', position: 'right' },
+        { to: 'users', label: 'Users', position: 'right' },
+        // { to: 'blog', label: 'Blog', position: 'right' },
         {
           href: 'https://github.com/palmerhq/tsdx',
           label: 'GitHub',
@@ -31,14 +33,14 @@ module.exports = {
       ],
     },
     footer: {
-      style: 'dark',
+      style: 'light',
       links: [
         {
           title: 'Docs',
           items: [
             {
               label: 'Docs',
-              to: 'docs/starthere',
+              to: 'docs/get-started',
             },
           ],
         },

diff --git a/website/package.json b/website/package.json
@@ -10,11 +10,11 @@
     "deploy": "docusaurus deploy"
   },
   "dependencies": {
-    "@docusaurus/core": "^2.0.0-alpha.24",
-    "@docusaurus/preset-classic": "^2.0.0-alpha.24",
+    "@docusaurus/core": "^2.0.0-alpha.32",
+    "@docusaurus/preset-classic": "^2.0.0-alpha.32",
     "classnames": "^2.2.6",
-    "react": "^16.8.4",
-    "react-dom": "^16.8.4"
+    "react": "^16.11.0",
+    "react-dom": "^16.11.0"
   },
   "browserslist": {
     "production": [

diff --git a/website/sidebars.js b/website/sidebars.js
@@ -7,7 +7,13 @@
 
 module.exports = {
   docs: {
-    Guide: ['features', 'starthere', 'optimizations', 'customization', 'api'],
+    Guide: [
+      'get-started',
+      'optimizations',
+      'customization',
+      'philosophy',
+      'api',
+    ],
     Contributing: ['docusaurus', 'contributing'],
   },
 };
diff --git a/website/src/pages/help.js b/website/src/pages/help.js
@@ -0,0 +1,101 @@
+/**
+ * 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.
+ */
+
+import React from 'react';
+import Layout from '@theme/Layout';
+
+import Link from '@docusaurus/Link';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+function Help() {
+  return (
+    <Layout permalink="/help" description="Docusaurus 2 Help page">
+      <div className="container margin-vert--xl">
+        <div className="text--center margin-bottom--xl">
+          <h1>Need Help?</h1>
+          <p>
+            If you need help with TSDX, you can try one of the mechanisms below.
+          </p>
+        </div>
+        <div className="row">
+          <div className="col">
+            <h2>Browse the docs</h2>
+            <p>
+              Learn more about Docusaurus using the{' '}
+              <Link to={useBaseUrl('docs/get-started')}>
+                official documentation.
+              </Link>
+            </p>
+          </div>
+          <div className="col">
+            <h2>Twitter</h2>
+            <p>
+              You can follow and contact the maintainers on Twitter{' '}
+              <a
+                target="_blank"
+                rel="noreferrer noopener"
+                href="https://twitter.com/jaredpalmer"
+              >
+                @jaredpalmer
+              </a>{' '}
+              and{' '}
+              <a
+                target="_blank"
+                rel="noreferrer noopener"
+                href="https://twitter.com/swyx"
+              >
+                @swyx
+              </a>
+              .
+            </p>
+          </div>
+          <div className="col">
+            <h2>GitHub</h2>
+            <p>
+              At our{' '}
+              <a
+                target="_blank"
+                rel="noreferrer noopener"
+                href="https://github.com/jaredpalmer/tsdx"
+              >
+                GitHub repo
+              </a>{' '}
+              Browse and submit{' '}
+              <a
+                target="_blank"
+                rel="noreferrer noopener"
+                href="https://github.com/jaredpalmer/tsdx/issues"
+              >
+                issues
+              </a>{' '}
+              or{' '}
+              <a
+                target="_blank"
+                rel="noreferrer noopener"
+                href="https://github.com/jaredpalmer/tsdx/pulls"
+              >
+                pull requests
+              </a>{' '}
+              for bugs you find or any new features you may want implemented. Be
+              sure to also check out our{' '}
+              <a
+                target="_blank"
+                rel="noreferrer noopener"
+                href="https://github.com/jaredpalmer/tsdx/blob/master/CONTRIBUTING.md"
+              >
+                contributing guide
+              </a>
+              .
+            </p>
+          </div>
+        </div>
+      </div>
+    </Layout>
+  );
+}
+
+export default Help;
diff --git a/website/src/pages/index.js b/website/src/pages/index.js
@@ -10,7 +10,7 @@ import classnames from 'classnames';
 import Layout from '@theme/Layout';
 import Link from '@docusaurus/Link';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-import withBaseUrl from '@docusaurus/withBaseUrl';
+import useBaseUrl from '@docusaurus/useBaseUrl';
 import styles from './styles.module.css';
 
 const features = [
@@ -32,7 +32,7 @@ const features = [
     description: (
       <>
         TSDX is a zero-config CLI that helps you develop, test, and publish
-        modern TypeScript packages with ease--so you can focus on your awesome
+        modern TypeScript packages use ease--so you can focus on your awesome
         new library and not waste another afternoon on the configuration.
       </>
     ),
@@ -43,24 +43,24 @@ const features = [
     description: (
       <ul>
         <li>
-          Bundles your code with{' '}
+          Bundles your code use{' '}
           <a href="https://github.com/rollup/rollup">Rollup</a> and outputs
           multiple module formats (CJS &amp; ESM by default, and also UMD if you
           want) plus development and production builds
         </li>
         <li>
-          Comes with treeshaking, ready-to-rock lodash optimizations, and
+          Comes use treeshaking, ready-to-rock lodash optimizations, and
           minification/compression
         </li>
         <li>Live reload / watch-mode</li>
-        <li>Works with React</li>
+        <li>Works use React</li>
         <li>Human readable error messages (and in VSCode-friendly format)</li>
         <li>Bundle size snapshots</li>
         <li>
           Opt-in to extract <code>invariant</code> error codes
         </li>
         <li>
-          Jest test runner setup with sensible defaults via{' '}
+          Jest test runner setup use sensible defaults via{' '}
           <code>tsdx test</code>
         </li>
         <li>Zero-config, single dependency</li>
@@ -72,6 +72,7 @@ const features = [
 function Home() {
   const context = useDocusaurusContext();
   const { siteConfig = {} } = context;
+  const baseUrl = useBaseUrl('/');
   return (
     <Layout
       title={`Hello from ${siteConfig.title}`}
@@ -112,7 +113,7 @@ function Home() {
                 styles.getStarted
               )}
               style={{ marginRight: '1rem' }}
-              to={withBaseUrl('docs/starthere')}
+              to={useBaseUrl('docs/get-started')}
             >
               Get Started
             </Link>
@@ -153,7 +154,7 @@ cd mylib && yarn start`}
                       <div className="text--center">
                         <img
                           className={styles.featureImage}
-                          src={withBaseUrl(imageUrl)}
+                          src={baseUrl + imageUrl}
                           alt={title}
                         />
                       </div>