docs: create and deploy docs website (analogjs#22)

Closes analogjs#3

.github/workflows/ci.yml

@@ -6,6 +6,11 @@ on:
       - main
   pull_request: {}
 
+env:
+  DOCS_APP_ARTIFACT_NAME: docs-app
+  DOCS_APP_PATH: dist/apps/docs-app/
+  NODE_OPTIONS: --max-old-space-size=6144
+
 jobs:
   checks:
     runs-on: ubuntu-latest
@@ -21,3 +26,55 @@ jobs:
         run: yarn build
       - name: Test
         run: yarn test
+      - name: Upload docs website
+        # Runs on merge to the `main` branch
+        if: github.event_name == 'push' && github.ref_name == 'main'
+        uses: actions/upload-artifact@v3
+        with:
+          if-no-files-found: error
+          name: ${{ env.DOCS_APP_ARTIFACT_NAME }}
+          path: ${{ env.DOCS_APP_PATH }}
+          retention-days: 1
+
+  deploy-docs:
+    name: '[Merge] Deploy docs website'
+    needs: checks
+    # Runs on merge to the `main` branch
+    if: github.event_name == 'push' && github.ref_name == 'main'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    # Authorize deployment to GitHub Pages
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    concurrency:
+      # Group concurrency on workflow, then:
+      # - Is merge run? Group on branch name (`refs/heads/main`)
+      # - Is pull request? Group on pull request branch name, for example `feat/add-awesome-feature`
+      group: >-
+        ${{ github.workflow }}-deploy-docs-${{
+          github.event_name == 'push'
+            && github.ref
+            || github.head_ref
+        }}
+      # Run merge workflows in sequence to prevent parallel deployments and releases
+      # Cancel stale pull request runs in progress for the same branch
+      cancel-in-progress: ${{ github.event_name != 'push' }}
+    steps:
+      - name: Download docs website
+        uses: actions/download-artifact@v3
+        with:
+          name: ${{ env.DOCS_APP_ARTIFACT_NAME }}
+          path: ${{ env.DOCS_APP_PATH }}
+      - name: Set up GitHub Pages
+        uses: actions/configure-pages@v1
+      - name: Upload GitHub Pages-compatible tarball
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: ${{ env.DOCS_APP_PATH }}
+      - name: Deploy docs website tarball
+        id: deploy
+        uses: actions/deploy-pages@v1

.gitignore

@@ -40,4 +40,8 @@ Thumbs.db
 
 .angular
 analog-project
-stats.html
+stats.html
+
+# Generated Docusaurus files
+.docusaurus/
+.cache-loader/

.node-version

@@ -1 +1 @@
-14.20.0
+16.16.0

.prettierignore

@@ -2,3 +2,5 @@
 
 /dist
 /coverage
+.prettierignore
+.docusaurus/

CONTRIBUTING.md

@@ -1,24 +1,118 @@
-# Developing
+# Contributing
 
-## Setup
+Analog is an MIT-licensed open source project with its ongoing development made by contributors.
+
+## Contributing to the framework
+
+### Folder structure
+
+Source code for the Analog framework exists under the `packages/` folder. To contribute features or bug fixes to the framework, locate the relevant code in one of the `packages` sub-folder. In addition to the `create-analog` sub-folder, there is a sub-folder for each of the `npm` packages in the `@analogjs/*` scope:
+
+- `packages/create-analog` → `create-analog`
+- `packages/vite-plugin-angular` → `@analogjs/vite-plugin-angular`
+
+### Setup
+
+Analog uses [Yarn Classic](https://classic.yarnpkg.com/) to manage its dependencies.
+
+Before opening a pull request, run the following command from the root folder to make sure your development dependencies are up-to-date:
 
 ```shell
 yarn
 ```
 
-## Running Example App
+### Running locally
+
+To serve the example application locally, run the following command from the root folder:
 
 ```shell
 yarn dev
 ```
 
-## Build all packages
+### Build
+
+Analog uses [Nx](https://nx.dev) for builds. To build all projects locally, run the following command from the root folder:
 
 ```shell
 yarn build
 ```
 
-## Submitting Pull Requests
+### Testing
+
+Analog uses [Jest](https://jestjs.io) for tests. To test all projects locally, run the following command from the root folder:
+
+```shell
+yarn test
+```
+
+## Contributing to the docs and analogjs.org website
+
+### Folder struture
+
+Source code for the Analog docs and the analogjs.org website exists under the `apps/docs-app` project folder. To contribute documentation or website content, locate the relevant source code in one of the sub-folders:
+
+- `blog` - Blog (unused).
+- `docs` - Documentation pages with React MDX support.
+- `src/components` - React components.
+- `src/css` - Global styles.
+- `src/pages` - React page components.
+- `static` - Images and other static assets.
+
+### Setup
+
+Analog uses [Yarn Classic](https://classic.yarnpkg.com/) to manage its dependencies.
+
+Before opening a pull request, run the following command from the root folder to make sure your development dependencies are up-to-date:
+
+```shell
+yarn
+```
+
+### Running locally
+
+Analog uses [Docusaurus](https://docusaurus.io/) to develop the docs and analogjs.org website. Run the following command from the `apps/docs-app` folder to serve the website:
+
+```shell
+yarn nx serve
+```
+
+or alternatively run this command from the root folder:
+
+```shell
+yarn nx serve docs-app
+```
+
+Once the development server is up and running, you can preview the docs and website by visiting [http://localhost:3000](http://localhost:3000).
+
+### Build
+
+Analog uses [Nx](https://nx.dev) to build the docs and analogjs.org website. To build the website locally, run the following command from the `apps/docs-app` folder:
+
+```shell
+yarn nx build
+```
+
+or alternatively run this command from the root folder:
+
+```shell
+yarn nx build docs-app
+```
+
+### Running static website locally
+
+To run the the generated static website locally, run the following command from the `apps/docs-app` folder:
+
+```shell
+yarn nx serve-static
+```
+
+or alternatively run this command from the root folder:
+
+```shell
+yarn nx serve-static docs-app
+```
+
+## Submitting pull requests
 
 **Please follow these basic steps to simplify pull request reviews. If you don't you'll probably just be asked to anyway.**
 
@@ -48,13 +142,13 @@ Questions and requests for support should not be opened as issues and should be
 
 - Start a new [Q&A Discussion](https://github.com/analogjs/analog/discussions/new?category=q-a) on GitHub.
 
-## <a name="commit"></a> Commit Message Guidelines
+## <a name="commit"></a> Commit message guidelines
 
 We have very precise rules over how our git commit messages can be formatted. This leads to **more
 readable messages** that are easy to follow when looking through the **project history**. But also,
 we use the git commit messages to **generate the changelog**.
 
-### Commit Message Format
+### Commit message format
 
 Each commit message consists of a **header**, a **body** and a **footer**. The header has a special
 format that includes a **type**, a **scope** and a **subject**:

angular.json

@@ -5,6 +5,7 @@
     "analog-app": "apps/analog-app",
     "analog-app-e2e": "apps/analog-app-e2e",
     "create-analog": "packages/create-analog",
+    "docs-app": "apps/docs-app",
     "vite-plugin-angular": "packages/vite-plugin-angular"
   }
 }

apps/docs-app/README.md

@@ -0,0 +1,5 @@
+# analogjs.org website and docs
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+See [`CONTRIBUTING.md`](../../CONTRIBUTING.md) for instructions on contributing to this project.

apps/docs-app/babel.config.js

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

apps/docs-app/docs/contributing.md

@@ -0,0 +1,13 @@
+---
+sidebar_position: 4
+title: Contributing
+---
+
+import Contributing, { toc as ContributingToc } from '../../../CONTRIBUTING.md';
+
+<Contributing />
+
+<!-- Workaround for generating table of contents -->
+<!-- See https://github.com/facebook/docusaurus/issues/3915#issuecomment-896193142 -->
+
+export const toc = [...ContributingToc];

apps/docs-app/docs/contributors.mdx

@@ -0,0 +1,21 @@
+---
+sidebar_position: 3
+---
+
+import GithubLogo from '@site/static/img/logos/github-logo.svg';
+import GithubSponsorsLogo from '@site/static/img/logos/github-sponsors-logo.svg';
+import styles from './contributors.module.css';
+
+# Contributors
+
+## Analog core team
+
+### Brandon Roberts
+
+![Brandon Roberts](https://github.com/brandonroberts.png)
+
+Brandon is an NgRx core team member, Angular GDE, sports ranter, and gif slinger.
+
+[<GithubLogo className={styles.githubLogo} width="110" height="110" /><br />@brandonroberts on GitHub](https://github.com/brandonroberts)
+
+[<GithubSponsorsLogo width="120" height="120" /><br />Sponsor Brandon on GitHub Sponsors](https://github.com/sponsors/brandonroberts)

apps/docs-app/docs/contributors.module.css

@@ -0,0 +1,3 @@
+[data-theme='light'] .githubLogo > * {
+  fill: #000000;
+}

apps/docs-app/docs/installation.md

@@ -0,0 +1,84 @@
+---
+sidebar_position: 2
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Installation
+
+## Installing with `create-analog`
+
+You can scaffold an Analog project with the following `create-analog` command:
+
+<Tabs groupId="package-manager">
+  <TabItem value="npm">
+
+```shell
+npm create analog@latest
+```
+
+  </TabItem>
+
+  <TabItem label="Yarn" value="yarn">
+
+```shell
+yarn create analog
+```
+
+  </TabItem>
+
+  <TabItem value="pnpm">
+
+```shell
+pnpm create analog
+```
+
+  </TabItem>
+</Tabs>
+
+### Optional `create-analog` flags
+
+| Flag         | Description                                                                        | Value type | Default value |
+| ------------ | ---------------------------------------------------------------------------------- | ---------- | ------------- |
+| &lt;name&gt; | Name of the project. Specify `.` to scaffold the project in the current directory. | string     |               |
+| `--template` | Template preset.                                                                   | string     |               |
+
+### Template presets
+
+| Preset        | Description                     |
+| ------------- | ------------------------------- |
+| `angular-v14` | Angular version 14 application. |
+
+### Example
+
+To scaffold an Angular version 14 application in the `my-angular-app` directory, run:
+
+<Tabs groupId="package-manager">
+  <TabItem value="npm">
+
+```shell
+# npm >=7.0
+npm create analog@latest my-angular-app -- --template angular-v14
+# npm 6.x
+npm create analog@latest my-angular-app --template angular-v14
+```
+
+  </TabItem>
+
+  <TabItem label="Yarn" value="yarn">
+
+```shell
+yarn create analog my-angular-app --template angular-v14
+```
+
+  </TabItem>
+
+  <TabItem value="pnpm">
+
+```shell
+pnpm create analog my-angular-app --template angular-v14
+```
+
+  </TabItem>
+</Tabs>

apps/docs-app/docs/introduction.md

@@ -0,0 +1,24 @@
+---
+id: introduction
+sidebar_position: 1
+slug: /
+---
+
+# Introduction
+
+Analog is a fullstack meta-framework for building applications and websites with [Angular](https://angular.io).
+
+## Goals
+
+- Vite-based
+  - Supports Vite/Vitest
+- Low config
+- File-based routing
+  - Support for API/server routes
+- Hybrid SSR/SSG support
+- Integrated CLI (future)
+
+## Packages
+
+- `@analogjs/vite-plugin-angular` - A Vite plugin for building, serving, and testing Angular applications.
+- `create-analog` - An initializer for scaffolding an Analog project.