📚 feat: Add documentation site using Vitepress (main)

- Added new docs site using Vitepress framework
- Configured docs build process in Dockerfile, Makefile and goreleaser.yaml
- Added docs route in HTTP server to serve static documentation
- Added docs link to web UI header
- Included example markdown files and Vitepress configuration
- Added docs/.gitignore for documentation build artifacts
- Updated proxy configuration in web/vite.config.ts for docs and swagger

.goreleaser.yaml

@@ -17,7 +17,7 @@ before:
     - go generate ./...
     - go-bindata -prefix "database/migrations/" -pkg migrations -o database/bindata.go database/migrations/
     - sqlc generate
-    - swag init -g internal/port/httpserver/router.go
+    - swag init -g internal/port/httpserver/router.go -o docs/swagger
 
 builds:
   - env:
@@ -33,6 +33,9 @@ builds:
         - cmd: sh -c 'cd web && bun install && bun run build'
           env:
             - NODE_ENV=production
+        - cmd: sh -c 'cd docs && bun install && bun run docs:build'
+          env:
+            - NODE_ENV=production
 
 archives:
   - format: tar.gz

Dockerfile

@@ -1,6 +1,7 @@
 # Use the official Bun image
 # See all versions at https://hub.docker.com/r/oven/bun/tags
-FROM oven/bun:1 AS base
+# Build UI
+FROM oven/bun:1 AS ui-base
 WORKDIR /usr/src/app
 
 # Install dependencies into temp directory
@@ -18,6 +19,26 @@ COPY web .
 ENV NODE_ENV=production
 RUN bun test && bun run build
 
+# Buld docs using Vitepress
+FROM oven/bun:1 AS docs-base
+WORKDIR /usr/src/app
+
+# Install dependencies into temp directory
+# This will cache them and speed up future builds
+COPY docs/package.json docs/bun.lockb /temp/
+RUN cd /temp && bun install --frozen-lockfile && \
+    mkdir -p /usr/src/app/node_modules && \
+    cp -r /temp/node_modules /usr/src/app/ && \
+    rm -rf /temp
+
+# Then copy all (non-ignored) project files into the image
+COPY docs .
+
+# Run tests and build
+ENV NODE_ENV=production
+RUN bun run docs:build
+
+
 # Build Go binary
 FROM golang:1.23-alpine AS build
 WORKDIR /go/src/app
@@ -31,11 +52,12 @@ RUN go mod download
 ENV CGO_ENABLED=0 GOOS=linux
 
 COPY . .
-COPY --from=base /usr/src/app/dist web/dist
+COPY --from=ui-base /usr/src/app/dist web/dist
+COPY --from=docs-base /usr/src/app/.vitepress/dist docs/.vitepress/dist
 RUN go generate ./... && \
     go-bindata -prefix "database/migrations/" -pkg migrations -o database/bindata.go database/migrations/ && \
     sqlc generate && \
-    swag init -g internal/port/httpserver/router.go && \
+    swag init -g internal/port/httpserver/router.go -o docs/swagger && \
     go build -ldflags="-s -w" -o /go/bin/app main.go
 
 # Final stage

Makefile

@@ -32,12 +32,16 @@ generate-spec:
 	# @mkdir -p web/src/sdk && rm -rf web/src/sdk
 	# @openapi-generator generate --skip-validate-spec -i docs/swagger/swagger.yaml -g typescript-fetch -o web/src/sdk
 
-build: build-ui build-go
+build: build-ui build-docs build-go
 
 build-go: generate
 	@echo "Building go..."
 	@go build -o bin/app main.go
 
+build-docs: 
+	@echo "Building docs..."
+	@cd docs && bun run docs:build
+
 build-ui:
 	@echo "Building UI..."
 	@cd web && bun run build

docs/.gitignore

@@ -0,0 +1,18 @@
+/coverage
+/src/client/shared.ts
+/src/node/shared.ts
+*.log
+*.tgz
+.DS_Store
+.idea
+.temp
+.vite_opt_cache
+.vscode
+dist
+cache
+temp
+examples-temp
+node_modules
+pnpm-global
+TODOs.md
+*.timestamp-*.mjs

docs/.vitepress/config.mts

@@ -0,0 +1,29 @@
+import { defineConfig } from 'vitepress'
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  title: "Recally",
+  description: "Recally Documents",
+  base: "/docs/",
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Examples', link: '/markdown-examples' }
+    ],
+
+    sidebar: [
+      {
+        text: 'Examples',
+        items: [
+          { text: 'Markdown Examples', link: '/markdown-examples' },
+          { text: 'Runtime API Examples', link: '/api-examples' }
+        ]
+      }
+    ],
+
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/vuejs/vitepress' }
+    ]
+  }
+})

docs/api-examples.md

@@ -0,0 +1,49 @@
+---
+outline: deep
+---
+
+# Runtime API Examples
+
+This page demonstrates usage of some of the runtime APIs provided by VitePress.
+
+The main `useData()` API can be used to access site, theme, and page data for the current page. It works in both `.md` and `.vue` files:
+
+```md
+<script setup>
+import { useData } from 'vitepress'
+
+const { theme, page, frontmatter } = useData()
+</script>
+
+## Results
+
+### Theme Data
+<pre>{{ theme }}</pre>
+
+### Page Data
+<pre>{{ page }}</pre>
+
+### Page Frontmatter
+<pre>{{ frontmatter }}</pre>
+```
+
+<script setup>
+import { useData } from 'vitepress'
+
+const { site, theme, page, frontmatter } = useData()
+</script>
+
+## Results
+
+### Theme Data
+<pre>{{ theme }}</pre>
+
+### Page Data
+<pre>{{ page }}</pre>
+
+### Page Frontmatter
+<pre>{{ frontmatter }}</pre>
+
+## More
+
+Check out the documentation for the [full list of runtime APIs](https://vitepress.dev/reference/runtime-api#usedata).

docs/docs.go

@@ -0,0 +1,30 @@
+package docs
+
+import (
+	"embed"
+	"fmt"
+	"net/http"
+	"os"
+	"recally/internal/pkg/config"
+
+	"github.com/labstack/echo/v4"
+)
+
+const distDir = ".vitepress/dist"
+
+//go:embed all:.vitepress/dist
+var StaticFiles embed.FS
+
+var StaticHttpFS http.FileSystem
+
+func init() {
+	// dynamic file system
+	if config.Settings.Debug {
+		StaticHttpFS = http.FS(os.DirFS(fmt.Sprintf("docs/%s", distDir)))
+		return
+	}
+
+	// static file system
+	PublicDirFS := echo.MustSubFS(StaticFiles, distDir)
+	StaticHttpFS = http.FS(PublicDirFS)
+}

docs/index.md

@@ -0,0 +1,25 @@
+---
+# https://vitepress.dev/reference/default-theme-home-page
+layout: home
+
+hero:
+  name: "Recally "
+  text: "Retrieve, Read, Remember"
+  tagline: "Effortlessly capture knowledge, instantly recall insights"
+  actions:
+    - theme: brand
+      text: Markdown Examples
+      link: /markdown-examples
+    - theme: alt
+      text: API Examples
+      link: /api-examples
+
+features:
+  - title: Feature A
+    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
+  - title: Feature B
+    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
+  - title: Feature C
+    details: Lorem ipsum dolor sit amet, consectetur adipiscing elit
+---
+

docs/markdown-examples.md

@@ -0,0 +1,85 @@
+# Markdown Extension Examples
+
+This page demonstrates some of the built-in markdown extensions provided by VitePress.
+
+## Syntax Highlighting
+
+VitePress provides Syntax Highlighting powered by [Shiki](https://github.com/shikijs/shiki), with additional features like line-highlighting:
+
+**Input**
+
+````md
+```js{4}
+export default {
+  data () {
+    return {
+      msg: 'Highlighted!'
+    }
+  }
+}
+```
+````
+
+**Output**
+
+```js{4}
+export default {
+  data () {
+    return {
+      msg: 'Highlighted!'
+    }
+  }
+}
+```
+
+## Custom Containers
+
+**Input**
+
+```md
+::: info
+This is an info box.
+:::
+
+::: tip
+This is a tip.
+:::
+
+::: warning
+This is a warning.
+:::
+
+::: danger
+This is a dangerous warning.
+:::
+
+::: details
+This is a details block.
+:::
+```
+
+**Output**
+
+::: info
+This is an info box.
+:::
+
+::: tip
+This is a tip.
+:::
+
+::: warning
+This is a warning.
+:::
+
+::: danger
+This is a dangerous warning.
+:::
+
+::: details
+This is a details block.
+:::
+
+## More
+
+Check out the documentation for the [full list of markdown extensions](https://vitepress.dev/guide/markdown).

docs/package.json

@@ -0,0 +1,11 @@
+{
+  "dependencies": {},
+  "devDependencies": {
+    "vitepress": "^1.6.0"
+  },
+  "scripts": {
+    "docs:dev": "vitepress dev",
+    "docs:build": "vitepress build",
+    "docs:preview": "vitepress preview"
+  }
+}

internal/port/httpserver/router.go

@@ -2,6 +2,7 @@ package httpserver
 
 import (
 	"net/http"
+	"recally/docs"
 	"recally/web"
 
 	_ "recally/docs/swagger"
@@ -48,6 +49,12 @@ func (s *Service) registerRouters() {
 	// Swagger
 	e.GET("/swagger/*", echoSwagger.WrapHandler)
 
+	// Docs
+	e.GET("/docs/*", func(c echo.Context) error {
+		c.Response().Header().Set("Cache-Control", "public, max-age=86400") // Cache for 1 day
+		return echo.WrapHandler(http.StripPrefix("/docs", http.FileServer(docs.StaticHttpFS)))(c)
+	})
+
 	// Web UI
 	s.registerWebUIRouters(e)
 }

web/src/components/landing/header.tsx

@@ -24,13 +24,21 @@ export default function Header() {
 					>
 						Pricing
 					</Link>
+					<a
+						href="/docs/"
+						target="_blank"
+						className="text-sm font-medium hover:underline underline-offset-4"
+						rel="noreferrer"
+					>
+						Docs
+					</a>
 					<a
 						href="https://github.com/recally-io/recally"
 						target="_blank"
 						rel="noopener noreferrer"
 						className="flex gap-2 items-center text-sm font-medium hover:underline underline-offset-4"
 					>
-						<SiGithub className="w-4 h-4" /> Github
+						<SiGithub className="w-4 h-4" />
 					</a>
 				</nav>
 				<div className="flex items-center space-x-4">