create-docusaurus 0.0.1 → 0.0.2

package/src/index.ts

@@ -0,0 +1,289 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import chalk from 'chalk';
+import fs from 'fs-extra';
+import {execSync} from 'child_process';
+import prompts, {Choice} from 'prompts';
+import path from 'path';
+import shell from 'shelljs';
+import {kebabCase, sortBy} from 'lodash';
+import supportsColor from 'supports-color';
+
+const RecommendedTemplate = 'classic';
+const TypeScriptTemplateSuffix = '-typescript';
+
+function hasYarn() {
+  try {
+    execSync('yarnpkg --version', {stdio: 'ignore'});
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+function isValidGitRepoUrl(gitRepoUrl: string) {
+  return ['https://', 'git@'].some((item) => gitRepoUrl.startsWith(item));
+}
+
+async function updatePkg(pkgPath: string, obj: Record<string, unknown>) {
+  const content = await fs.readFile(pkgPath, 'utf-8');
+  const pkg = JSON.parse(content);
+  const newPkg = Object.assign(pkg, obj);
+
+  await fs.outputFile(pkgPath, JSON.stringify(newPkg, null, 2));
+}
+
+function readTemplates(templatesDir: string) {
+  const templates = fs
+    .readdirSync(templatesDir)
+    .filter(
+      (d) =>
+        !d.startsWith('.') &&
+        !d.startsWith('README') &&
+        !d.endsWith(TypeScriptTemplateSuffix) &&
+        d !== 'shared',
+    );
+
+  // Classic should be first in list!
+  return sortBy(templates, (t) => t !== RecommendedTemplate);
+}
+
+function createTemplateChoices(templates: string[]) {
+  function makeNameAndValueChoice(value: string): Choice {
+    const title =
+      value === RecommendedTemplate ? `${value} (recommended)` : value;
+    return {title, value};
+  }
+
+  return [
+    ...templates.map((template) => makeNameAndValueChoice(template)),
+    makeNameAndValueChoice('Git repository'),
+  ];
+}
+
+function getTypeScriptBaseTemplate(template: string): string | undefined {
+  if (template.endsWith(TypeScriptTemplateSuffix)) {
+    return template.replace(TypeScriptTemplateSuffix, '');
+  }
+  return undefined;
+}
+
+async function copyTemplate(
+  templatesDir: string,
+  template: string,
+  dest: string,
+) {
+  await fs.copy(path.resolve(templatesDir, 'shared'), dest);
+
+  // TypeScript variants will copy duplicate resources like CSS & config from base template
+  const tsBaseTemplate = getTypeScriptBaseTemplate(template);
+  if (tsBaseTemplate) {
+    const tsBaseTemplatePath = path.resolve(templatesDir, tsBaseTemplate);
+    await fs.copy(tsBaseTemplatePath, dest, {
+      filter: (filePath) =>
+        fs.statSync(filePath).isDirectory() ||
+        path.extname(filePath) === '.css' ||
+        path.basename(filePath) === 'docusaurus.config.js',
+    });
+  }
+
+  await fs.copy(path.resolve(templatesDir, template), dest, {
+    // Symlinks don't exist in published NPM packages anymore, so this is only to prevent errors during local testing
+    filter: (filePath) => !fs.lstatSync(filePath).isSymbolicLink(),
+  });
+}
+
+export default async function init(
+  rootDir: string,
+  siteName?: string,
+  reqTemplate?: string,
+  cliOptions: Partial<{
+    useNpm: boolean;
+    skipInstall: boolean;
+    typescript: boolean;
+  }> = {},
+): Promise<void> {
+  const useYarn = cliOptions.useNpm ? false : hasYarn();
+  const templatesDir = path.resolve(__dirname, '../templates');
+  const templates = readTemplates(templatesDir);
+  const hasTS = (templateName: string) =>
+    fs.pathExistsSync(
+      path.resolve(templatesDir, `${templateName}${TypeScriptTemplateSuffix}`),
+    );
+
+  let name = siteName;
+
+  // Prompt if siteName is not passed from CLI.
+  if (!name) {
+    const prompt = await prompts({
+      type: 'text',
+      name: 'name',
+      message: 'What should we name this site?',
+      initial: 'website',
+    });
+    name = prompt.name;
+  }
+
+  if (!name) {
+    throw new Error(chalk.red('A website name is required.'));
+  }
+
+  const dest = path.resolve(rootDir, name);
+  if (fs.existsSync(dest)) {
+    throw new Error(`Directory already exists at "${dest}"!`);
+  }
+
+  let template = reqTemplate;
+  let useTS = cliOptions.typescript;
+  // Prompt if template is not provided from CLI.
+  if (!template) {
+    const templatePrompt = await prompts({
+      type: 'select',
+      name: 'template',
+      message: 'Select a template below...',
+      choices: createTemplateChoices(templates),
+    });
+    template = templatePrompt.template;
+    if (template && !useTS && hasTS(template)) {
+      const tsPrompt = await prompts({
+        type: 'confirm',
+        name: 'useTS',
+        message:
+          'This template is available in TypeScript. Do you want to use the TS variant?',
+        initial: false,
+      });
+      useTS = tsPrompt.useTS;
+    }
+  }
+
+  // If user choose Git repository, we'll prompt for the url.
+  if (template === 'Git repository') {
+    const repoPrompt = await prompts({
+      type: 'text',
+      name: 'gitRepoUrl',
+      validate: (url?: string) => {
+        if (url && isValidGitRepoUrl(url)) {
+          return true;
+        }
+        return chalk.red(`Invalid repository URL`);
+      },
+      message:
+        'Enter a repository URL from GitHub, Bitbucket, GitLab, or any other public repo.\n(e.g: https://github.com/ownerName/repoName.git)',
+    });
+    template = repoPrompt.gitRepoUrl;
+  }
+
+  console.log(`
+${chalk.cyan('Creating new Docusaurus project...')}
+`);
+
+  if (template && isValidGitRepoUrl(template)) {
+    console.log(`Cloning Git template ${chalk.cyan(template)}...`);
+    if (
+      shell.exec(`git clone --recursive ${template} ${dest}`, {silent: true})
+        .code !== 0
+    ) {
+      throw new Error(chalk.red(`Cloning Git template ${template} failed!`));
+    }
+  } else if (template && templates.includes(template)) {
+    // Docusaurus templates.
+    if (useTS) {
+      if (!hasTS(template)) {
+        throw new Error(
+          `Template ${template} doesn't provide the Typescript variant.`,
+        );
+      }
+      template = `${template}${TypeScriptTemplateSuffix}`;
+    }
+    try {
+      await copyTemplate(templatesDir, template, dest);
+    } catch (err) {
+      console.log(
+        `Copying Docusaurus template ${chalk.cyan(template)} failed!`,
+      );
+      throw err;
+    }
+  } else {
+    throw new Error('Invalid template.');
+  }
+
+  // Update package.json info.
+  try {
+    await updatePkg(path.join(dest, 'package.json'), {
+      name: kebabCase(name),
+      version: '0.0.0',
+      private: true,
+    });
+  } catch (err) {
+    console.log(chalk.red('Failed to update package.json.'));
+    throw err;
+  }
+
+  // We need to rename the gitignore file to .gitignore
+  if (
+    !fs.pathExistsSync(path.join(dest, '.gitignore')) &&
+    fs.pathExistsSync(path.join(dest, 'gitignore'))
+  ) {
+    await fs.move(path.join(dest, 'gitignore'), path.join(dest, '.gitignore'));
+  }
+  if (fs.pathExistsSync(path.join(dest, 'gitignore'))) {
+    fs.removeSync(path.join(dest, 'gitignore'));
+  }
+
+  const pkgManager = useYarn ? 'yarn' : 'npm';
+  if (!cliOptions.skipInstall) {
+    console.log(`Installing dependencies with ${chalk.cyan(pkgManager)}...`);
+
+    try {
+      // Use force coloring the output, since the command is invoked by shelljs, which is not the interactive shell
+      shell.exec(
+        `cd "${name}" && ${useYarn ? 'yarn' : 'npm install --color always'}`,
+        {
+          env: {
+            ...process.env,
+            ...(supportsColor.stdout ? {FORCE_COLOR: '1'} : {}),
+          },
+        },
+      );
+    } catch (err) {
+      console.log(chalk.red('Installation failed.'));
+      throw err;
+    }
+  }
+  console.log();
+
+  // Display the most elegant way to cd.
+  const cdpath =
+    path.join(process.cwd(), name) === dest
+      ? name
+      : path.relative(process.cwd(), name);
+
+  console.log(`
+Successfully created "${chalk.cyan(cdpath)}".
+Inside that directory, you can run several commands:
+
+  ${chalk.cyan(`${pkgManager} start`)}
+    Starts the development server.
+
+  ${chalk.cyan(`${pkgManager} ${useYarn ? '' : 'run '}build`)}
+    Bundles your website into static files for production.
+
+  ${chalk.cyan(`${pkgManager} ${useYarn ? '' : 'run '}serve`)}
+    Serves the built website locally.
+
+  ${chalk.cyan(`${pkgManager} deploy`)}
+    Publishes the website to GitHub pages.
+
+We recommend that you begin by typing:
+
+  ${chalk.cyan('cd')} ${cdpath}
+  ${chalk.cyan(`${pkgManager} start`)}
+
+Happy building awesome websites!
+`);
+}

package/templates/README.md

@@ -0,0 +1,8 @@
+# Templates
+
+Official templates provided by Docusaurus. They are designed to be selected when using the `npx @docusaurus/init init [name] [template]` CLI command.
+
+## Guide to Test Templates for Developer
+
+1. `yarn install` in the root of the repo (one level above this directory).
+1. Go to any template's directory, example: `cd classic && yarn start`.

package/templates/bootstrap/docusaurus.config.js

@@ -0,0 +1,93 @@
+// @ts-check
+// Note: type annotations allow type checking and IDEs autocompletion
+
+/** @type {import('@docusaurus/types').Config} */
+const config = {
+  title: 'My Site',
+  tagline: 'The tagline of my site',
+  url: 'https://your-docusaurus-test-site.com',
+  baseUrl: '/',
+  onBrokenLinks: 'throw',
+  onBrokenMarkdownLinks: 'warn',
+  favicon: 'img/favicon.ico',
+  organizationName: 'facebook', // Usually your GitHub org/user name.
+  projectName: 'docusaurus', // Usually your repo name.
+  themeConfig: {
+    navbar: {
+      title: 'My Site',
+      logo: {
+        alt: 'My Site Logo',
+        src: 'img/logo.svg',
+      },
+      items: [
+        {
+          to: 'docs/intro',
+          activeBasePath: 'docs',
+          label: 'Docs',
+          position: 'left',
+        },
+        {to: 'blog', label: 'Blog', position: 'left'},
+        {
+          href: 'https://github.com/facebook/docusaurus',
+          label: 'GitHub',
+          position: 'right',
+        },
+      ],
+    },
+    footer: {
+      style: 'dark',
+      links: [
+        {
+          title: 'Community',
+          items: [
+            {
+              label: 'Stack Overflow',
+              href: 'https://stackoverflow.com/questions/tagged/docusaurus',
+            },
+            {
+              label: 'Discord',
+              href: 'https://discordapp.com/invite/docusaurus',
+            },
+            {
+              label: 'Twitter',
+              href: 'https://twitter.com/docusaurus',
+            },
+          ],
+        },
+        {
+          title: 'More',
+          items: [
+            {
+              label: 'Blog',
+              to: 'blog/',
+            },
+            {
+              label: 'GitHub',
+              href: 'https://github.com/facebook/docusaurus',
+            },
+          ],
+        },
+      ],
+      copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
+    },
+  },
+  presets: [
+    [
+      '@docusaurus/preset-bootstrap',
+      {
+        docs: {
+          sidebarPath: require.resolve('./sidebars.js'),
+          editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
+        },
+        blog: {
+          showReadingTime: true,
+          // Please change this to your repo.
+          editUrl:
+            'https://github.com/facebook/docusaurus/edit/main/website/blog/',
+        },
+      },
+    ],
+  ],
+};
+
+module.exports = config;

package/templates/bootstrap/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "docusaurus-2-bootstrap-template",
+  "version": "2.0.0-beta.6",
+  "private": true,
+  "scripts": {
+    "docusaurus": "docusaurus",
+    "start": "docusaurus start",
+    "build": "docusaurus build",
+    "swizzle": "docusaurus swizzle",
+    "deploy": "docusaurus deploy",
+    "clear": "docusaurus clear",
+    "serve": "docusaurus serve",
+    "write-translations": "docusaurus write-translations",
+    "write-heading-ids": "docusaurus write-heading-ids"
+  },
+  "dependencies": {
+    "@docusaurus/core": "2.0.0-beta.6",
+    "@docusaurus/preset-bootstrap": "2.0.0-beta.6",
+    "@mdx-js/react": "^1.6.21",
+    "@svgr/webpack": "^5.5.0",
+    "clsx": "^1.1.1",
+    "file-loader": "^6.2.0",
+    "react": "^17.0.1",
+    "react-dom": "^17.0.1",
+    "url-loader": "^4.1.1"
+  },
+  "browserslist": {
+    "production": [
+      ">0.2%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  }
+}

package/templates/bootstrap/src/pages/index.js

@@ -0,0 +1,87 @@
+import React from 'react';
+import clsx from 'clsx';
+import Layout from '@theme/Layout';
+import Link from '@docusaurus/Link';
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import styles from './styles.module.css';
+
+const features = [
+  {
+    title: 'Easy to Use',
+    imageUrl: 'img/undraw_docusaurus_mountain.svg',
+    description: (
+      <>
+        Docusaurus was designed from the ground up to be easily installed and
+        used to get your website up and running quickly.
+      </>
+    ),
+  },
+  {
+    title: 'Focus on What Matters',
+    imageUrl: 'img/undraw_docusaurus_tree.svg',
+    description: (
+      <>
+        Docusaurus lets you focus on your docs, and we&apos;ll do the chores. Go
+        ahead and move your docs into the <code>docs</code> directory.
+      </>
+    ),
+  },
+  {
+    title: 'Powered by React',
+    imageUrl: 'img/undraw_docusaurus_react.svg',
+    description: (
+      <>
+        Extend or customize your website layout by reusing React. Docusaurus can
+        be extended while reusing the same header and footer.
+      </>
+    ),
+  },
+];
+
+function Feature({imageUrl, title, description}) {
+  const imgUrl = useBaseUrl(imageUrl);
+  return (
+    <div className={clsx('col col--4', styles.feature)}>
+      {imgUrl && (
+        <div className="text--center">
+          <img className={styles.featureImage} src={imgUrl} alt={title} />
+        </div>
+      )}
+      <h3>{title}</h3>
+      <p>{description}</p>
+    </div>
+  );
+}
+
+export default function Home() {
+  const context = useDocusaurusContext();
+  const {siteConfig = {}} = context;
+
+  return (
+    <Layout
+      title={`Hello from ${siteConfig.title}`}
+      description="Description will go into a meta tag in <head />">
+      <div className={styles.hero}>
+        <header>
+          <h1>{siteConfig.title}</h1>
+          <p>{siteConfig.tagline}</p>
+          <div className={styles.buttons}>
+            <Link to={useBaseUrl('docs/')}>Get Started</Link>
+          </div>
+        </header>
+        <main>
+          {features && features.length > 0 && (
+            <section className={styles.section}>
+              <div className={styles.features}>
+                {features.map((props, idx) => (
+                  <Feature key={idx} {...props} />
+                ))}
+              </div>
+            </section>
+          )}
+        </main>
+      </div>
+    </Layout>
+  );
+}

package/templates/bootstrap/src/pages/styles.module.css

@@ -0,0 +1,49 @@
+/* stylelint-disable docusaurus/copyright-header */
+
+/**
+ * CSS files with the .module.css suffix will be treated as CSS modules
+ * and scoped locally.
+ */
+
+.heroBanner {
+  padding: 4rem 0;
+  text-align: center;
+  position: relative;
+  overflow: hidden;
+}
+
+@media screen and (max-width: 966px) {
+  .heroBanner {
+    padding: 2rem;
+  }
+}
+
+.buttons {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.hero {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  align-items: center;
+  place-content: center;
+}
+
+.section {
+  margin: 10rem;
+}
+
+.features {
+  display: flex;
+  align-items: center;
+  padding: 2rem 0;
+  width: 100%;
+}
+
+.featureImage {
+  height: 200px;
+  width: 200px;
+}

package/templates/classic/docusaurus.config.js

@@ -0,0 +1,118 @@
+// @ts-check
+// Note: type annotations allow type checking and IDEs autocompletion
+
+const lightCodeTheme = require('prism-react-renderer/themes/github');
+const darkCodeTheme = require('prism-react-renderer/themes/dracula');
+
+/** @type {import('@docusaurus/types').Config} */
+const config = {
+  title: 'My Site',
+  tagline: 'Dinosaurs are cool',
+  url: 'https://your-docusaurus-test-site.com',
+  baseUrl: '/',
+  onBrokenLinks: 'throw',
+  onBrokenMarkdownLinks: 'warn',
+  favicon: 'img/favicon.ico',
+  organizationName: 'facebook', // Usually your GitHub org/user name.
+  projectName: 'docusaurus', // Usually your repo name.
+
+  presets: [
+    [
+      '@docusaurus/preset-classic',
+      /** @type {import('@docusaurus/preset-classic').Options} */
+      ({
+        docs: {
+          sidebarPath: require.resolve('./sidebars.js'),
+          // Please change this to your repo.
+          editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
+        },
+        blog: {
+          showReadingTime: true,
+          // Please change this to your repo.
+          editUrl:
+            'https://github.com/facebook/docusaurus/edit/main/website/blog/',
+        },
+        theme: {
+          customCss: require.resolve('./src/css/custom.css'),
+        },
+      }),
+    ],
+  ],
+
+  themeConfig:
+    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
+    ({
+      navbar: {
+        title: 'My Site',
+        logo: {
+          alt: 'My Site Logo',
+          src: 'img/logo.svg',
+        },
+        items: [
+          {
+            type: 'doc',
+            docId: 'intro',
+            position: 'left',
+            label: 'Tutorial',
+          },
+          {to: '/blog', label: 'Blog', position: 'left'},
+          {
+            href: 'https://github.com/facebook/docusaurus',
+            label: 'GitHub',
+            position: 'right',
+          },
+        ],
+      },
+      footer: {
+        style: 'dark',
+        links: [
+          {
+            title: 'Docs',
+            items: [
+              {
+                label: 'Tutorial',
+                to: '/docs/intro',
+              },
+            ],
+          },
+          {
+            title: 'Community',
+            items: [
+              {
+                label: 'Stack Overflow',
+                href: 'https://stackoverflow.com/questions/tagged/docusaurus',
+              },
+              {
+                label: 'Discord',
+                href: 'https://discordapp.com/invite/docusaurus',
+              },
+              {
+                label: 'Twitter',
+                href: 'https://twitter.com/docusaurus',
+              },
+            ],
+          },
+          {
+            title: 'More',
+            items: [
+              {
+                label: 'Blog',
+                to: '/blog',
+              },
+              {
+                label: 'GitHub',
+                href: 'https://github.com/facebook/docusaurus',
+              },
+            ],
+          },
+        ],
+        copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
+      },
+      prism: {
+        theme: lightCodeTheme,
+        darkTheme: darkCodeTheme,
+      },
+    }),
+};
+
+module.exports = config;