docs: Adds a docusaurus documentation page for relic. (#132)

Author: SandPod

.github/workflows/dart-tests.yaml

@@ -116,3 +116,33 @@ jobs:
         with:
           token: ${{ secrets.CODECOV_TOKEN }}
           files: coverage/lcov.info
+
+  docs-markdown-lint:
+    name: Markdown lint for docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Run markdownlint on maintained docs
+        uses: articulate/actions-markdownlint@v1
+        with:
+            config: ./doc/site/.markdownlint.yaml
+            files: ./doc/site/**/*.md
+
+  docs-test-build:
+    name: Test build docs 
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v3
+        with:
+            node-version: 20 
+            cache: npm
+            cache-dependency-path: doc/site/package-lock.json
+      - name: Install dependencies
+        run: npm ci 
+        working-directory: ./doc/site
+      - name: Build
+        run: npm run build
+        working-directory: ./doc/site

.github/workflows/deploy-documentation.yml

@@ -0,0 +1,63 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy Relic documentation
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: 
+      - "main"
+    paths:
+      - 'docsite/**'
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Install node
+        uses: actions/setup-node@v3
+        with:
+            node-version: 20 
+            cache: npm
+            cache-dependency-path: docsite/package-lock.json
+      - name: Install dependencies
+        run: npm ci 
+        working-directory: ./docs
+      - name: Build docs
+        run: npm run build
+        working-directory: ./docs
+      - name: Upload build artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './doc/site/build'
+          
+  deploy:
+    name: Deploy documentation
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      # - name: Setup Pages
+      #   uses: actions/configure-pages@v5
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

doc/site/.gitignore

@@ -0,0 +1,21 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+settings.json

doc/site/.markdownlint.yaml

@@ -0,0 +1,4 @@
+MD001: false
+MD013: false
+MD014: false
+MD024: false

doc/site/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "useTabs": false,
+  "bracketSpacing": true
+}

doc/site/README.md

@@ -0,0 +1,84 @@
+# Relic documentation website
+
+This is the code for Relic's official documentation. You can view the updated documentation by choosing the _Next_ option in the top menu bar.
+
+### Install
+
+Make sure that you have Node.js installed on your computer.
+
+```bash
+brew install node
+```
+
+Run `npm install` from the docs directory:
+
+```bash
+cd docs
+npm install
+```
+
+### Local Development
+
+```bash
+npm 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.
+
+### Add version
+
+Make sure that the documentation is all up-to-date then run:
+
+```bash
+npm run docusaurus docs:version X.X.X
+```
+
+### Amend the latest version
+
+If you need to make changes to the latest version, you can do so by removing the latest version from `versions.json` and adding it again running the create version command with the same version number.
+
+```bash
+npm run docusaurus docs:version X.X.X
+```
+
+### Add redirects
+
+To maintain link integrity when relocating or renaming documentation pages, it's recommended to implement redirects. This is facilitated by the `@docusaurus/plugin-client-redirects` plugin. Redirects can be configured in the `docusaurus.config.js` file, within the `redirects` section of the plugin configuration.
+
+### Deploy
+
+Once a PR is merged into the `main` branch of this repository, a GitHub action is triggered that builds and deploys the documentation to Github pages. The documentation is available at `https://miniature-fortnight-wgn2qnl.pages.github.io`.
+
+### Formatting
+
+To ensure consistent formatting, we use markdownlint [(VS Code Extension)](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)
+
+Install the `markdownlint-cli` globally, by running the following command from your terminal:
+
+```bash
+$ npm install -g markdownlint-cli
+```
+
+Formatting is only enforced in `/doc/site/` directory so therefore you only need to run the markdownlint-cli in this folder with:
+
+```bash
+$ markdownlint './doc/site/**/*.md'
+```
+
+### Force deploy from branch
+
+This is useful if you want to deploy the branch you are working on to the documentation site but should in general never be used.
+
+Follow these steps to deploy a specific branch:
+
+1. Push your changes to the branch you are working on.
+2. In github, go to the settings tab for the `serverpod_cloud` repository.
+3. On the left side menu, click on `Environments`.
+4. Select `github-pages` from the list`.
+5. Add your branch to the list of branches that can deploy to github pages. (Only `main` is allowed by default).
+6. Open `.github/workflows/deploy-documentation.yml` and change the branch from `main` to the branch you want to deploy from.
+7. Push the changes to the repository.
+
+Once the changes are pushed, the documentation will be deployed to the documentation site.
+
+Once you are done, remember to remove the branch from the list of branches that can deploy to github pages and change the branch in the `deploy-documentation.yml` file back to `main`.

doc/site/babel.config.js

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

doc/site/docs/index.md

@@ -0,0 +1,7 @@
+---
+sidebar_position: -1
+---
+
+# Introduction
+
+Relic is a strictly typed HTTP server with incredible performance.

doc/site/docusaurus.config.js

@@ -0,0 +1,106 @@
+// @ts-check
+// Note: type annotations allow type checking and IDEs autocompletion
+
+import { themes } from 'prism-react-renderer';
+const lightCodeTheme = themes.github;
+const darkCodeTheme = themes.dracula;
+
+/** @type {import('@docusaurus/types').Config} */
+const config = {
+  title: 'Relic',
+  tagline: 'Strictly typed HTTP server with incredible performance.',
+  url: 'https://docs.relic.dev',
+  baseUrl: '/',
+  onBrokenLinks: 'throw',
+  onBrokenMarkdownLinks: 'warn',
+  favicon: 'img/favicon.png',
+  organizationName: 'serverpod', // Usually your GitHub org/user name.
+  projectName: 'relic', // Usually your repo name.
+  trailingSlash: false,
+  presets: [
+    [
+      'classic',
+      /** @type {import('@docusaurus/preset-classic').Options} */
+      ({
+        docs: {
+          routeBasePath: '/',
+          sidebarPath: require.resolve('./sidebars.js'),
+          // Please change this to your repo.
+          editUrl:
+            'https://github.com/serverpod/relic/tree/main/doc/site/',
+          breadcrumbs: false,
+        },
+        blog: false,
+        theme: {
+          customCss: require.resolve('./src/css/custom.css'),
+        },
+        gtag: {
+          trackingID: 'G-0EYLJMP04H',
+          anonymizeIP: true,
+        },
+      }),
+    ],
+  ],
+
+  themeConfig:
+    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
+    ({
+      colorMode: {
+        respectPrefersColorScheme: true,
+        disableSwitch: false,
+      },
+      navbar: {
+        // title: 'My Site',
+        logo: {
+          alt: 'Serverpod Logo',
+          src: 'img/logo-horizontal.svg',
+          srcDark: 'img/logo-horizontal-dark.svg',
+          href: 'https://serverpod.dev',
+        },
+        items: [
+          {
+            type: 'docsVersionDropdown',
+            position: 'left',
+          },
+          {
+            href: 'https://careers.serverpod.dev/',
+            label: 'Career',
+            position: 'right',
+          },
+          {
+            href: 'https://twitter.com/ServerpodDev',
+            label: 'Twitter',
+            position: 'right',
+          },
+          {
+            href: 'https://github.com/serverpod/serverpod',
+            label: 'GitHub',
+            position: 'right',
+          },
+          {
+            type: 'search',
+            position: 'right',
+          },
+        ],
+      },
+      footer: {
+        style: 'dark',
+        copyright: `Copyright © ${new Date().getFullYear()} Serverpod authors.`,
+      },
+      prism: {
+        theme: lightCodeTheme,
+        darkTheme: darkCodeTheme,
+        additionalLanguages: ['dart', 'bash'],
+      },
+    }),
+  plugins: [
+    [
+      '@docusaurus/plugin-client-redirects',
+      {
+        redirects: [],
+      },
+    ],
+  ],
+};
+
+module.exports = config;