Merge pull request #15 from tiktok/octogonz/docusaurus

Initial Docusaurus setup

.github/workflows/ci.yml

@@ -20,7 +20,7 @@ jobs:
       fail-fast: false
       matrix:
         node:
-          - '16'
+          - '18'
         platform:
           - ubuntu-latest
 

.github/workflows/publish.yaml

@@ -10,7 +10,7 @@ jobs:
           token: ${{ secrets.BOT_ACCESS_TOKEN }}
       - uses: actions/setup-node@v3
         with:
-          node-version: 16
+          node-version: 18
       - name: git config email
         run: git config --local user.email tiktokbot@users.noreply.github.com
       - name: git config name

.gitignore

@@ -85,4 +85,8 @@ lib-shim
 dist
 dist-storybook
 *.scss.ts
-*.sass.ts
+*.sass.ts
+
+# Docusaurus build outputs
+build
+.docusaurus

README.md

@@ -34,13 +34,23 @@ For details, consult the [Sparo documentation](./apps/sparo/README.md).
 
 <!-- GENERATED PROJECT SUMMARY START -->
 
-## Packages
+## Published Packages
+
+<!-- the table below was generated using the ./repo-scripts/repo-toolbox script -->
+
+| Folder | Version | Changelog | Package |
+| ------ | ------- | --------- | ------- |
+| [/apps/sparo](./apps/sparo/) | [![npm version](https://badge.fury.io/js/sparo.svg)](https://badge.fury.io/js/sparo) | [changelog](./apps/sparo/CHANGELOG.md) | [sparo](https://www.npmjs.com/package/sparo) |
+| [/apps/sparo-lib](./apps/sparo-lib/) | [![npm version](https://badge.fury.io/js/sparo-lib.svg)](https://badge.fury.io/js/sparo-lib) | | [sparo-lib](https://www.npmjs.com/package/sparo-lib) |
+
+
+## Unpublished Local Projects
 
 <!-- the table below was generated using the ./repo-scripts/repo-toolbox script -->
 
 | Folder | Description |
 | ------ | -----------|
-| [/apps/sparo](./apps/sparo/) | Improve Git performance in your large scale frontend monorepo by integrating sparse checkout with Rush and PNPM |
+| [/apps/website](./apps/website/) | The Sparo documentation website |
 <!-- GENERATED PROJECT SUMMARY END -->
 
 ## Contributing

apps/website/README.md

@@ -0,0 +1,48 @@
+# Website
+
+This is the [Docusaurus](https://docusaurus.io/) project for the Sparo website.
+
+## Development
+
+1. Install the monorepo dependencies using [RushJS](https://rushjs.io/):
+
+   ```shell
+   rush install
+   rush build
+   ```
+
+2. Launch the local development server:
+
+   ```shell
+   cd apps/website
+   rushx start
+   ```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+## Deployment
+
+1. If you will manually copy the files to a server, you can build the **apps/sparo/build** folder like this:
+
+   ```shell
+   cd apps/website
+   rushx build
+   ```
+
+2. To automatically deploy to GitHub Pages (as an administrator):
+
+   ```shell
+   # If you are using HTTPS authentication for GitHub:
+   cd apps/website
+   GIT_USER=<Your GitHub username> rushx deploy
+   ```
+
+   ```
+   # If you are using SSH authentication for GitHub:
+   USE_SSH=true rushx deploy
+   ```
+
+## See also
+
+- [Deployment](https://docusaurus.io/docs/deployment) from the Docusaurus help
+

apps/website/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')]
+};

apps/website/docs/index.md

@@ -4,18 +4,21 @@ hide_title: true
 custom_edit_url: null
 ---
 
-![Sparo](../static/images/sparo-380.png)
+<div style={{ display: 'flex', justifyContent: 'center', alignItems: 'center' }}>
+  <img src="images/site/sparo-logo.svg" alt="Sparo" title="Sparo" style={{ width: '380px', paddingTop: '30px' }} />
+</div>
 
+## Clone faster!
+
+Sparo optimizes performance of Git operations for your large frontend monorepo.
 
 <!-- Text below this line should stay in sync with the project and repo README.md -->
 <!-- ---------------------------------------------------------------------------- -->
 
-**Sparo** optimizes performance of Git operations for your large frontend monorepo.
-
 ## Key features
 
 - **Familiar interface:** The `sparo` command-line interface (CLI) wrapper offers **better defaults** and **performance suggestions** without altering the familiar `git` syntax. (The native `git` CLI is also supported.)
-- **A proven solution:** Git provides [quite a lot of ingredients](./pages/guide/git_features.md) for optimizing very large repos; Sparo is your recipe for combining these features intelligently.
+- **A proven solution:** Git provides [quite a lot of ingredients](./pages/reference/git_optimization.md) for optimizing very large repos; Sparo is your recipe for combining these features intelligently.
 - **Simplified sparse checkout:** Work with sparse checkout [profiles](./pages/guide/sparo_profiles.md) instead of confusing "cones" and globs
 - **Frontend integration:** Sparo leverages [Rush](https://rushjs.io/) and [PNPM](https://pnpm.io/) workspace configurations, including the ability to automatically checkout project dependencies
 - **Dual workflows:** The `sparo-ci` tool implements a specialized checkout model optimized for continuous integration (CI) pipelines
@@ -77,7 +80,3 @@ Try out Sparo in 5 easy steps:
    sparo commit -m "Example command"
    ```
 
-<br>
-<br>
-
-👉 [Getting started](./pages/guide/getting_started.md)

apps/website/docs/pages/commands/overview.md

@@ -1,14 +1,14 @@
 ---
-title: Command line overview
+title: Overview
 ---
 
-The `git` command-line tool supports various subcommands such as `git clone`, `git checkout`, and so forth.  The `sparo` command-line is intended to be a complete replacement for `git`.  
+The `git` command-line tool supports various subcommands such as `git clone`, `git checkout`, and so forth.  The `sparo` command-line is intended to be a complete replacement for `git`.
 
 Sparo has four kinds of subcommands:
 
 1. **Mirrored subcommands** such as `sparo branch` and `sparo revert` directly invoke the corresponding `git` version of that subcommand.  The motivation for using mirrored subcommands is to enable Sparo to provide advice about parameters that may cause performance issues.  Additionally, you can optionally configure Sparo to collect anonymized usage metrics to help you measure the experience in your repository.  (Collected data is sent to your own service. It is not accessible by any other party.)
 
-2. **Enhanced subcommands** follow the same basic design as their `git` counterparts, but with adaptations for sparse checkout profiles and more efficient defaults.  There are four enhanced commands: 
+2. **Enhanced subcommands** follow the same basic design as their `git` counterparts, but with adaptations for sparse checkout profiles and more efficient defaults.  There are four enhanced commands:
    - `sparo clone`
    - `sparo checkout`
    - `sparo fetch`

apps/website/docs/pages/guide/getting_started.md

@@ -25,9 +25,9 @@ sparo clone https://github.com/my-company/my-monorepo.git
 
 - Only the default branch (usually `main`) is fetched.
 
-- Git blobless [partial clone](../reference/git_features.md) is enabled to postpone downloading file contents.
+- Git blobless [partial clone](../reference/git_optimization.md) is enabled to postpone downloading file contents.
 
-- Git [sparse checkout](../reference/git_features.md) is used to clone only the ["skeleton" folders](../reference/skeleton_folders.md), which includes all workspace **package.json** files, but excludes the source code subfolders.
+- Git [sparse checkout](../reference/git_optimization.md) is used to clone only the ["skeleton" folders](../reference/skeleton_folders.md), which includes all workspace **package.json** files, but excludes the source code subfolders.
 
 - Sparse checkout is configured for the more efficient "cone mode".
 
@@ -35,7 +35,7 @@ sparo clone https://github.com/my-company/my-monorepo.git
 
 ### Step 3: Create a sparse profile
 
-Define a [Sparo profile](./pages/configs/profile_json.md) describing the subset of repository folders for Git sparse checkout.  Here is a basic example:
+Define a [Sparo profile](../configs/profile_json.md) describing the subset of repository folders for Git sparse checkout.  Here is a basic example:
 
 **common/sparo-profiles/my-team.json**
 ```json
@@ -75,7 +75,7 @@ sparo checkout --profile my-team
 
 ### Step 5: Use the mirrored subcommands
 
-For everyday work, consider choosing [mirrored subcommands](./pages/commands/overview.md) such as `sparo revert` instead of `git revert`. The Sparo wrapper provides (1) better defaults, (2) suggestions for better performance, and (3) optional anonymized performance metrics.
+For everyday work, consider choosing [mirrored subcommands](../commands/overview.md) such as `sparo revert` instead of `git revert`. The Sparo wrapper provides (1) better defaults, (2) suggestions for better performance, and (3) optional anonymized performance metrics.
 
 Examples:
 

apps/website/docs/pages/guide/sparo_profiles.md

@@ -0,0 +1,4 @@
+---
+title: Sparo profiles
+---
+

apps/website/docs/pages/support/news.md

@@ -2,5 +2,4 @@
 title: What's new
 ---
 
-<!-- TODO: replace with CDN URL -->
-To find out what's changed in the latest release, please consult the [CHANGELOG.md](../../../../sparo/CHANGELOG.md) notes.
+To find out what's changed in the latest release, please consult the [CHANGELOG.md](https://github.com/tiktok/sparo/blob/main/apps/sparo/CHANGELOG.md) notes.

apps/website/docusaurus.config.js

@@ -0,0 +1,116 @@
+// @ts-check
+// `@type` JSDoc annotations allow editor autocompletion and type checking
+// (when paired with `@ts-check`).
+// There are various equivalent ways to declare your Docusaurus config.
+// See: https://docusaurus.io/docs/api/docusaurus-config
+
+import { themes as prismThemes } from 'prism-react-renderer';
+
+/** @type {import('@docusaurus/types').Config} */
+const config = {
+  title: 'Sparo',
+  tagline: 'Faster Git for large frontend monorepos',
+  favicon: 'images/site/sparo-favicon.ico',
+
+  // Set the production url of your site here
+  url: 'https://tiktok.github.io',
+  // Set the /<baseUrl>/ pathname under which your site is served
+  // For GitHub pages deployment, it is often '/<projectName>/'
+  baseUrl: '/sparo/',
+
+  // GitHub pages deployment config.
+  // If you aren't using GitHub pages, you don't need these.
+  organizationName: 'tiktok', // Usually your GitHub org/user name.
+  projectName: 'sparo', // Usually your repo name.
+
+  onBrokenLinks: 'throw',
+  onBrokenMarkdownLinks: 'throw',
+
+  // Even if you don't use internationalization, you can use this field to set
+  // useful metadata like html lang. For example, if your site is Chinese, you
+  // may want to replace "en" with "zh-Hans".
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en']
+  },
+
+  presets: [
+    [
+      'classic',
+      /** @type {import('@docusaurus/preset-classic').Options} */
+      ({
+        docs: {
+          routeBasePath: '/',
+          sidebarPath: './sidebars.js',
+          breadcrumbs: false,
+          // Please change this to your repo.
+          // Remove this to remove the "edit this page" links.
+          editUrl: 'https://github.com/tiktok/sparo/tree/main/apps/website/'
+        },
+        /*
+        blog: {
+          showReadingTime: true,
+          // Please change this to your repo.
+          // Remove this to remove the "edit this page" links.
+          editUrl:
+            'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/'
+        },
+        */
+        theme: {
+          customCss: './src/css/custom.css'
+        }
+      })
+    ]
+  ],
+
+  themeConfig:
+    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
+    ({
+      // Replace with your project's social card
+      image: 'images/site/sparo-ograph.png',
+      navbar: {
+        title: '',
+        logo: {
+          alt: 'Sparo',
+          src: 'images/site/sparo-title.svg'
+        },
+        items: [
+          {
+            type: 'localeDropdown',
+            position: 'left'
+          },
+          {
+            to: 'pages/guide/getting_started',
+            position: 'right',
+            label: 'Docs'
+          },
+          {
+            href: 'https://github.com/tiktok/sparo',
+            label: 'GitHub',
+            position: 'right'
+          },
+          {
+            to: 'pages/support/news',
+            position: 'right',
+            label: 'News'
+          },
+          {
+            to: 'pages/support/help',
+            position: 'right',
+            label: 'Help'
+          }
+        ]
+      },
+      footer: {
+        style: 'dark',
+        links: [],
+        copyright: `Copyright © ${new Date().getFullYear()} TikTok Pte. Ltd.`
+      },
+      prism: {
+        theme: prismThemes.github,
+        darkTheme: prismThemes.dracula
+      }
+    })
+};
+
+export default config;

apps/website/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "website",
+  "version": "0.0.0",
+  "private": true,
+  "description": "The Sparo documentation website",
+  "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": "3.1.1",
+    "@docusaurus/preset-classic": "3.1.1",
+    "@mdx-js/react": "^3.0.0",
+    "clsx": "^2.0.0",
+    "prism-react-renderer": "^2.3.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  },
+  "devDependencies": {
+    "@docusaurus/module-type-aliases": "3.1.1",
+    "@docusaurus/types": "3.1.1"
+  },
+  "browserslist": {
+    "production": [
+      ">0.5%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 3 chrome version",
+      "last 3 firefox version",
+      "last 5 safari version"
+    ]
+  },
+  "engines": {
+    "node": ">=18.0"
+  }
+}

apps/website/sidebars.js

@@ -0,0 +1,70 @@
+/**
+ * Creating a sidebar enables you to:
+ - create an ordered group of docs
+ - render a sidebar for each doc of that group
+ - provide next/previous navigation
+
+ The sidebars can be generated from the filesystem, or explicitly defined here.
+
+ Create as many sidebars as you want.
+ */
+
+// @ts-check
+
+/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
+const sidebars = {
+  // By default, Docusaurus generates a sidebar from the docs folder structure
+  //tutorialSidebar: [{ type: 'autogenerated', dirName: '.' }]
+
+  // But you can create a sidebar manually
+  /*
+  tutorialSidebar: [
+    'intro',
+    'hello',
+    {
+      type: 'category',
+      label: 'Tutorial',
+      items: ['tutorial-basics/create-a-document'],
+    },
+  ],
+   */
+
+  docsSidebar: [
+    {
+      type: 'category',
+      label: 'Introduction',
+      collapsible: false,
+      items: ['index', 'pages/guide/getting_started', 'pages/guide/sparo_profiles']
+    },
+    {
+      type: 'category',
+      label: 'Reference',
+      collapsible: false,
+      items: [
+        'pages/reference/git_optimization',
+        'pages/reference/skeleton_folders',
+        'pages/reference/security'
+      ]
+    },
+    {
+      type: 'category',
+      label: 'Config files',
+      collapsible: false,
+      items: ['pages/configs/profile_json']
+    },
+    {
+      type: 'category',
+      label: 'Commands',
+      collapsible: false,
+      items: ['pages/commands/overview']
+    },
+    {
+      type: 'category',
+      label: 'Support',
+      collapsible: false,
+      items: ['pages/support/help', 'pages/support/news', 'pages/support/contributing']
+    }
+  ]
+};
+
+export default sidebars;

apps/website/src/css/custom.css

@@ -0,0 +1,30 @@
+/**
+ * Any CSS included here will be global. The classic template
+ * bundles Infima by default. Infima is a CSS framework designed to
+ * work well for content-centric websites.
+ */
+
+/* You can override the default Infima variables here. */
+:root {
+  --ifm-color-primary: #2e8555;
+  --ifm-color-primary-dark: #29784c;
+  --ifm-color-primary-darker: #277148;
+  --ifm-color-primary-darkest: #205d3b;
+  --ifm-color-primary-light: #33925d;
+  --ifm-color-primary-lighter: #359962;
+  --ifm-color-primary-lightest: #3cad6e;
+  --ifm-code-font-size: 95%;
+  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
+}
+
+/* For readability concerns, you should choose a lighter palette in dark mode. */
+[data-theme='dark'] {
+  --ifm-color-primary: #25c2a0;
+  --ifm-color-primary-dark: #21af90;
+  --ifm-color-primary-darker: #1fa588;
+  --ifm-color-primary-darkest: #1a8870;
+  --ifm-color-primary-light: #29d5b0;
+  --ifm-color-primary-lighter: #32d8b4;
+  --ifm-color-primary-lightest: #4fddbf;
+  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
+}

rush.json

@@ -42,7 +42,7 @@
    * LTS schedule: https://nodejs.org/en/about/releases/
    * LTS versions: https://nodejs.org/en/download/releases/
    */
-  "nodeSupportedVersionRange": ">=16.13.0 <17.0.0 || >=18.15.0 <19.0.0",
+  "nodeSupportedVersionRange": ">=18.15.0 <19.0.0 || >=20.9.0 <21.0.0",
 
   /**
    * If the version check above fails, Rush will display a message showing the current
@@ -445,6 +445,10 @@
       "projectFolder": "apps/sparo-lib",
       "versionPolicyName": "sparo",
       "shouldPublish": true
+    },
+    {
+      "packageName": "website",
+      "projectFolder": "apps/website"
     }
   ]
 }