feat(docs): added documentation website (#72)

.github/workflows/ci-docs.yaml

@@ -0,0 +1,30 @@
+name: CI - Docs
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  ci-docs:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: packages/docs
+
+    steps:
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4
+      - run: corepack enable
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          corepack: true
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm i
+        working-directory: ./
+
+      - name: Build the lib
+        run: pnpm build

.gitignore

@@ -27,4 +27,5 @@ logs
 !.env.example
 
 .wrangler
-coverage
+coverage
+cache

packages/app-client/.env.example

@@ -1 +1,2 @@
-VITE_BASE_API_URL=http://localhost:8787
+VITE_BASE_API_URL=http://localhost:8787
+VITE_FALLBACK_DOCUMENTATION_URL=http://localhost:3001

packages/app-client/.gitignore

@@ -26,3 +26,5 @@ gitignore
 # System Files
 .DS_Store
 Thumbs.db
+
+cache

packages/app-client/public/robots.txt

@@ -1,4 +1,5 @@
 User-agent: *
 Disallow: /
 Allow: /$
-Allow: /og-image.png
+Allow: /og-image.png
+Allow: /docs/

packages/app-client/src/modules/config/config.ts

@@ -1,3 +1,4 @@
 export const config = {
   baseApiUrl: import.meta.env.VITE_BASE_API_URL ?? window.location.origin,
+  documentationBaseUrl: import.meta.env.VITE_DOCUMENTATION_BASE_URL ?? 'https://docs.enclosed.cc',
 };

packages/app-client/src/modules/docs/docs.models.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, test } from 'vitest';
+import { buildDocUrl, joinUrlParts } from './docs.models';
+
+describe('docs models', () => {
+  describe('buildDocUrl', () => {
+    test('it creates a url to the documentation', () => {
+      expect(
+        buildDocUrl({
+          path: '/test',
+
+          baseUrl: 'https://docs.enclosed.cc',
+        }),
+      ).to.eql('https://docs.enclosed.cc/test');
+    });
+
+    test('it uses the default base url', () => {
+      expect(buildDocUrl({ path: '/test' })).to.eql('https://docs.enclosed.cc/test');
+    });
+
+    test('it handles clashing slashes', () => {
+      expect(
+        buildDocUrl({
+          path: '/test',
+          baseUrl: 'https://docs.enclosed.cc/',
+        }),
+      ).to.eql('https://docs.enclosed.cc/test');
+    });
+  });
+
+  describe('joinUrlParts', () => {
+    test('it merges url parts and trim slashes', () => {
+      expect(joinUrlParts('/part1/', '/part2/', 'part3', 'part4/')).to.eql('part1/part2/part3/part4');
+      expect(joinUrlParts('/part1/part2/', 'part3', 'part4/')).to.eql('part1/part2/part3/part4');
+      expect(joinUrlParts('')).to.eql('');
+    });
+
+    test('multiple slashes inside a part are preserved', () => {
+      expect(joinUrlParts('/part1//part2/', '/part3/')).to.eql('part1//part2/part3');
+    });
+  });
+});

packages/app-client/src/modules/docs/docs.models.ts

@@ -0,0 +1,19 @@
+import { config } from '../config/config';
+
+export { buildDocUrl, joinUrlParts };
+
+function joinUrlParts(...parts: string[]): string {
+  return parts.map(part => part.replace(/(^\/|\/$)/g, '')).join('/');
+}
+
+function buildDocUrl({
+  path,
+  baseUrl = config.documentationBaseUrl,
+}: {
+  path: string;
+  baseUrl?: string;
+}): string {
+  const url = joinUrlParts(baseUrl, path);
+
+  return url;
+}

packages/app-client/src/modules/ui/layouts/app.layout.tsx

@@ -1,10 +1,11 @@
 import { A, useNavigate } from '@solidjs/router';
 import type { Component, ParentComponent } from 'solid-js';
 import { DropdownMenu } from '@kobalte/core/dropdown-menu';
-import { DropdownMenuContent, DropdownMenuItem, DropdownMenuTrigger } from '../components/dropdown-menu';
+import { DropdownMenuContent, DropdownMenuItem, DropdownMenuSeparator, DropdownMenuTrigger } from '../components/dropdown-menu';
 import { Button } from '@/modules/ui/components/button';
 import { useThemeStore } from '@/modules/theme/theme.store';
 import { useNoteContext } from '@/modules/notes/notes.context';
+import { buildDocUrl } from '@/modules/docs/docs.models';
 
 export const Navbar: Component = () => {
   const themeStore = useThemeStore();
@@ -43,21 +44,48 @@ export const Navbar: Component = () => {
             <DropdownMenuTrigger as={Button} class="text-lg px-0 size-9" variant="ghost" aria-label="Change theme">
               <div classList={{ 'i-tabler-moon': themeStore.getColorMode() === 'dark', 'i-tabler-sun': themeStore.getColorMode() === 'light' }}></div>
             </DropdownMenuTrigger>
-            <DropdownMenuContent>
-              <DropdownMenuItem onClick={() => themeStore.setColorMode({ mode: 'light' })} class="flex items-center gap-2">
+            <DropdownMenuContent class="w-42">
+              <DropdownMenuItem onClick={() => themeStore.setColorMode({ mode: 'light' })} class="flex items-center gap-2 cursor-pointer">
                 <div class="i-tabler-sun text-lg"></div>
                 Light mode
               </DropdownMenuItem>
-              <DropdownMenuItem onClick={() => themeStore.setColorMode({ mode: 'dark' })} class="flex items-center gap-2">
+              <DropdownMenuItem onClick={() => themeStore.setColorMode({ mode: 'dark' })} class="flex items-center gap-2 cursor-pointer">
                 <div class="i-tabler-moon text-lg"></div>
                 Dark mode
               </DropdownMenuItem>
-              <DropdownMenuItem onClick={() => themeStore.setColorMode({ mode: 'system' })} class="flex items-center gap-2">
+              <DropdownMenuItem onClick={() => themeStore.setColorMode({ mode: 'system' })} class="flex items-center gap-2 cursor-pointer">
                 <div class="i-tabler-device-laptop text-lg"></div>
                 System
               </DropdownMenuItem>
             </DropdownMenuContent>
           </DropdownMenu>
+
+          <DropdownMenu>
+            <DropdownMenuTrigger as={Button} class="text-lg px-0 size-9" variant="ghost" aria-label="Change theme">
+              <div class="i-tabler-dots-vertical"></div>
+            </DropdownMenuTrigger>
+
+            <DropdownMenuContent class="w-46">
+              <DropdownMenuItem as="a" class="flex items-center gap-2 cursor-pointer" target="_blank" href={buildDocUrl({ path: '/' })}>
+                <div class="i-tabler-file-text text-lg"></div>
+                Documentation
+              </DropdownMenuItem>
+
+              <DropdownMenuItem as="a" class="flex items-center gap-2 cursor-pointer" target="_blank" href={buildDocUrl({ path: '/integrations/cli' })}>
+                <div class="i-tabler-terminal text-lg"></div>
+                Enclosed CLI
+              </DropdownMenuItem>
+
+              <DropdownMenuSeparator />
+
+              <DropdownMenuItem as="a" class="flex items-center gap-2 cursor-pointer" target="_blank" href="https://buymeacoffee.com/cthmsst" rel="noopener noreferrer">
+                <div class="i-tabler-pig-money text-lg"></div>
+                Support Enclosed
+              </DropdownMenuItem>
+
+            </DropdownMenuContent>
+
+          </DropdownMenu>
         </div>
       </div>
     </div>

packages/docs/.vitepress/config.ts

@@ -0,0 +1,135 @@
+import { defineConfig } from 'vitepress';
+import { getPlausibleScripts } from './plausible';
+
+const basePath = process.env.DOCS_BASE_PATH; // undefined for root /
+
+const createAbsoluteUrl = (path: string) => 'https://enclosed.cc/' +  path.replace(/(^\/$)/g, '');
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: 'Enclosed',
+  description: 'Send private and secure notes',
+  base: basePath,
+  lang: 'en-US',
+  lastUpdated: true,
+  srcDir: './src',
+  outDir: './dist',
+
+  markdown: {
+    theme: {
+      dark: 'github-dark',
+      light: 'github-light',
+    },
+  },
+
+  head: [
+    ['meta', { name: 'author', content: 'Corentin Thomasset' }],
+    ['meta', { name: 'keywords', content: 'Enclosed, notes, secure, private, encrypted, self-hosted' }],
+    ['link', { rel: 'icon', href: '/favicon.ico' }],
+    ['link', { rel: 'apple-touch-icon', href: '/apple-touch-icon.png' }],
+    ['link', {rel: 'icon', type: 'image/png', sizes: '32x32', href: '/favicon-32x32.png'}],
+    ['link', {rel: 'icon', type: 'image/png', sizes: '16x16', href: '/favicon-16x16.png'}],
+
+    ['meta', {name: 'theme-color', content: '#ffffff'}],
+
+
+
+    ['meta', {name: 'og:title', content: 'Enclosed documentation'}],
+    ['meta', {name: 'og:description', content: 'Send private and secure notes'}],
+    ['meta', {name: 'og:image', content: createAbsoluteUrl('og-image.png')}],
+    ['meta', {name: 'og:url', content: 'https://enclosed.cc'}],
+    ['meta', {name: 'og:type', content: 'website'}],
+    ['meta', {name: 'og:site_name', content: 'Enclosed'}],
+    ['meta', {name: 'og:locale', content: 'en_US'}],
+
+    ['meta', {name: 'twitter:card', content: 'summary'}],
+    ['meta', {name: 'twitter:site', content: '@cthmsst'}],
+    ['meta', {name: 'twitter:creator', content: '@cthmsst'}],
+    ['meta', {name: 'twitter:title', content: 'Enclosed documentation'}],
+    ['meta', {name: 'twitter:description', content: 'Send private and secure notes'}],
+    ['meta', {name: 'twitter:image', content: createAbsoluteUrl('og-image.png')}],
+
+    ...getPlausibleScripts(),
+  ],
+
+  themeConfig: {
+
+    logo: {
+      light: '/logo-light.svg',
+      dark: '/logo-dark.svg',
+      alt: 'Logo',
+    },
+
+    siteTitle: 'Enclosed - DOCS',
+
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Enclosed App', link: 'https://enclosed.cc' },
+    ],
+
+    sidebar: [
+      {
+        text: 'Enclosed',
+        items: [
+          { text: 'Introduction', link: '/' },
+          { text: 'How it works?', link: '/how-it-works' },
+        ],
+      },
+      {
+        text: 'Self hosting',
+        items: [
+          { text: 'Using Docker', link: '/self-hosting/docker' },
+          { text: 'Using Docker Compose', link: '/self-hosting/docker-compose' },
+          { text: 'Configuration', link: '/self-hosting/configuration' },
+        ],
+      },
+      {
+        text: 'Integrations',
+        items: [
+          { text: 'CLI', link: '/integrations/cli' },
+          { text: 'NPM package', link: '/integrations/npm-package' },
+        ]
+      },
+    ],
+
+
+    footer: {
+      copyright: 'Copyright © 2024-present Corentin Thomasset',
+    },
+
+    editLink: {
+      pattern: 'https://github.com/CorentinTh/enclosed/edit/main/packages/docs/src/:path',
+      text: 'Edit this page on GitHub',
+    },
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/CorentinTh/enclosed', ariaLabel: 'GitHub' },
+      { icon: 'twitter', link: 'https://twitter.com/cthmsst', ariaLabel: 'Twitter' },
+    ],
+
+    search: {
+      provider: 'local',
+
+      options: {
+        detailedView: true,
+
+        miniSearch: {
+          /**
+           * @type {Pick<import('minisearch').Options, 'extractField' | 'tokenize' | 'processTerm'>}
+           */
+          options: {
+          },
+          /**
+           * @type {import('minisearch').SearchOptions}
+           */
+          searchOptions: {
+            fuzzy: 0.3,
+            prefix: true,
+            boost: { title: 4, text: 2, titles: 1 },
+          },
+        },
+      },
+    },
+  },
+});
+

packages/docs/.vitepress/plausible.ts

@@ -0,0 +1,17 @@
+import { HeadConfig } from "vitepress";
+
+const isPlausibleEnabled = process.env.VITE_IS_PLAUSIBLE_ENABLED === 'true';
+const plausibleDomain = String(process.env.VITE_PLAUSIBLE_DOMAIN);
+const plausibleScriptSrc = String(process.env.VITE_PLAUSIBLE_SCRIPT_SRC);
+
+export { getPlausibleScripts };
+
+function getPlausibleScripts(): HeadConfig[] {
+    if (!isPlausibleEnabled || !plausibleDomain) {
+        return [];
+    }
+
+    return [
+        ['script', { async: '', defer: '', 'data-domain': plausibleDomain, src: plausibleScriptSrc }],
+    ];
+}

packages/docs/.vitepress/theme/custom.css

@@ -0,0 +1,19 @@
+:root {
+    --vp-c-brand-1: #000000;
+    --vp-c-brand-2: #000000;
+}
+
+.dark {
+    --vp-c-brand-1: #ffffff;
+    --vp-c-brand-2: #ffffff;
+
+    --vp-c-text-1: rgba(255, 255, 245, 0.92);
+    --vp-c-text-2: rgba(235, 235, 245, 0.6);
+    --vp-c-text-3: rgba(235, 235, 245, 0.38);
+}
+
+
+.VPSocialLink span{
+    height: 18px !important;
+    width: 18px !important;
+}

packages/docs/.vitepress/theme/index.js

@@ -0,0 +1,4 @@
+import DefaultTheme from 'vitepress/theme'
+import './custom.css'
+
+export default DefaultTheme