Update docs

This commit is contained in:
Alan Grainger
2026-10-08 08:57:34 +13:00
parent aacbc1d79c
commit dbab0d3394
6 changed files with 117 additions and 28 deletions
+6
View File
@@ -8,6 +8,9 @@ on:
paths: paths:
- 'docs/**' - 'docs/**'
- '.github/workflows/docs.yaml' - '.github/workflows/docs.yaml'
schedule:
# Weekly rebuild, so the navbar's star count stays current
- cron: '0 3 * * 1'
permissions: permissions:
contents: read contents: read
@@ -42,9 +45,12 @@ jobs:
working-directory: docs working-directory: docs
# Dead internal links fail the build, which fails the workflow and leaves the live site untouched. # Dead internal links fail the build, which fails the workflow and leaves the live site untouched.
# The token lifts the GitHub API rate limit for the star-count fetch in .vitepress/config.ts.
- name: Build site - name: Build site
run: npm run build run: npm run build
working-directory: docs working-directory: docs
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Configure Pages - name: Configure Pages
uses: actions/configure-pages@v5 uses: actions/configure-pages@v5
+33 -2
View File
@@ -1,8 +1,38 @@
import { defineConfig } from 'vitepress' import { defineConfigWithTheme, type DefaultTheme } from 'vitepress'
const REPO_URL = 'https://github.com/alangrainger/immich-public-proxy' const REPO_URL = 'https://github.com/alangrainger/immich-public-proxy'
export default defineConfig({ /** The default theme's config plus the star count the navbar pill shows. */
export interface ThemeConfig extends DefaultTheme.Config {
/** GitHub stars at build time; the pill is omitted when undefined. */
stars?: number
}
/**
* The repo's star count, fetched once per build so visitors' browsers never
* call GitHub themselves. Undefined when the API can't be reached (a local
* build with no network, or the anonymous rate limit), which hides the pill.
* The docs workflow passes GITHUB_TOKEN for a higher limit and rebuilds
* weekly so the number stays current.
*/
async function fetchStars (): Promise<number | undefined> {
const headers: Record<string, string> = { Accept: 'application/vnd.github+json' }
if (process.env.GITHUB_TOKEN) headers.Authorization = 'Bearer ' + process.env.GITHUB_TOKEN
try {
const res = await fetch('https://api.github.com/repos/alangrainger/immich-public-proxy', {
headers,
signal: AbortSignal.timeout(5000)
})
const body = res.ok ? await res.json() : undefined
if (typeof body?.stargazers_count === 'number') return body.stargazers_count
console.warn('Star count unavailable (GitHub API status ' + res.status + '); the navbar pill is omitted.')
} catch (e) {
console.warn('Star count unavailable (' + (e instanceof Error ? e.message : String(e)) + '); the navbar pill is omitted.')
}
return undefined
}
export default async () => defineConfigWithTheme<ThemeConfig>({
title: 'Immich Public Proxy', title: 'Immich Public Proxy',
description: 'Share your Immich photos and albums publicly without exposing your Immich instance to the internet.', description: 'Share your Immich photos and albums publicly without exposing your Immich instance to the internet.',
lang: 'en-NZ', lang: 'en-NZ',
@@ -15,6 +45,7 @@ export default defineConfig({
], ],
themeConfig: { themeConfig: {
logo: '/ipp.svg', logo: '/ipp.svg',
stars: await fetchStars(),
search: { search: {
provider: 'local' provider: 'local'
}, },
+29
View File
@@ -1,3 +1,32 @@
/* Star-count pill in the navbar, after the GitHub icon. Shown at every width:
below 1280px the default theme hides the GitHub icon in its "..." menu, so
the pill is the only visible link to the repo there. */
.ipp-stars {
display: inline-flex;
align-items: center;
gap: 4px;
margin-left: 12px;
padding: 0 10px;
height: 28px;
border: 1px solid var(--vp-c-divider);
border-radius: 14px;
font-size: 13px;
font-weight: 500;
line-height: 1;
color: var(--vp-c-text-2);
transition: color 0.25s, border-color 0.25s;
}
.ipp-stars:hover {
color: var(--vp-c-text-1);
border-color: var(--vp-c-text-3);
}
.ipp-stars svg {
width: 16px;
height: 16px;
}
/* Landing-page hero tweaks for the screenshot-as-hero-image. /* Landing-page hero tweaks for the screenshot-as-hero-image.
VitePress's default hero floats a square logo up-and-left; for a wide VitePress's default hero floats a square logo up-and-left; for a wide
screenshot we want it centred and vertically aligned with the hero text. */ screenshot we want it centred and vertically aligned with the hero text. */
+38 -20
View File
@@ -1,11 +1,48 @@
import DefaultTheme from 'vitepress/theme' import DefaultTheme from 'vitepress/theme'
import { useData } from 'vitepress'
import { h } from 'vue' import { h } from 'vue'
import type { ThemeConfig } from '../config'
import './custom.css' import './custom.css'
const DEMO_URL = 'https://demo.ipp.nz/s/demo-gallery' const DEMO_URL = 'https://demo.ipp.nz/s/demo-gallery'
const REPO_URL = 'https://github.com/alangrainger/immich-public-proxy'
// Material Design "star"
const STAR_PATH = 'M12 17.27 18.18 21l-1.64-7.03L22 9.24l-7.19-.61L12 2 9.19 8.63 2 9.24l5.46 4.73L5.82 21z'
/** 1234 as "1.2k", under a thousand as is. */
function formatStars (count: number): string {
return count >= 1000 ? (count / 1000).toFixed(1).replace(/\.0$/, '') + 'k' : String(count)
}
/**
* The GitHub star count as a navbar pill, after the GitHub icon. The count
* comes from the build (`themeConfig.stars`, see config.ts); nothing is
* rendered when the build had none.
*/
const StarCount = {
setup () {
const { theme } = useData<ThemeConfig>()
return () => {
const stars = theme.value.stars
if (stars === undefined) return null
return h('a', {
class: 'ipp-stars',
href: REPO_URL,
target: '_blank',
rel: 'noreferrer',
title: 'Star on GitHub',
'aria-label': stars + ' GitHub stars'
}, [
h('svg', { viewBox: '0 0 24 24', 'aria-hidden': 'true' }, [h('path', { fill: 'currentColor', d: STAR_PATH })]),
formatStars(stars)
])
}
}
}
/** /**
* Extend the default theme to: * Extend the default theme to:
* - show the GitHub star count in the navbar (`nav-bar-content-after`);
* - use the live-demo screenshot as the hero image (`home-hero-image`), * - use the live-demo screenshot as the hero image (`home-hero-image`),
* absolutely centred within the hero image container so it lines up * absolutely centred within the hero image container so it lines up
* vertically with the hero text; * vertically with the hero text;
@@ -15,26 +52,7 @@ export default {
extends: DefaultTheme, extends: DefaultTheme,
Layout () { Layout () {
return h(DefaultTheme.Layout, null, { return h(DefaultTheme.Layout, null, {
'home-hero-actions-after': () => h( 'nav-bar-content-after': () => h(StarCount),
'div',
{ style: 'display: flex; gap: 8px; margin-top: 24px; flex-wrap: wrap;' },
[
h('a', { href: 'https://github.com/alangrainger/immich-public-proxy', target: '_blank', rel: 'noreferrer' }, [
h('img', {
src: 'https://badgen.net/github/stars/alangrainger/immich-public-proxy?scale=1.1',
alt: 'GitHub stars',
style: 'vertical-align: middle;'
})
]),
h('a', { href: 'https://hub.docker.com/r/alangrainger/immich-public-proxy', target: '_blank', rel: 'noreferrer' }, [
h('img', {
src: 'https://badgen.net/docker/pulls/alangrainger/immich-public-proxy?icon=docker&label=docker%20pulls&color=green&scale=1.1',
alt: 'Docker pulls',
style: 'vertical-align: middle;'
})
])
]
),
'home-hero-image': () => h( 'home-hero-image': () => h(
'a', 'a',
{ {
+4
View File
@@ -21,6 +21,10 @@ npm run dev # live preview
npm run build # fails on dead internal links; run it before pushing npm run build # fails on dead internal links; run it before pushing
``` ```
The navbar's star count is fetched from the GitHub API when the site builds (`fetchStars` in `.vitepress/config.ts`)
and rendered by the theme, so visitors' browsers never call GitHub. A local build with no network prints a warning
and omits the pill; nothing is wrong. The deploy workflow also rebuilds weekly so the number stays current.
The sidebar is hand-maintained in `.vitepress/config.ts`, so a new page is invisible until it is added there. The sidebar is hand-maintained in `.vitepress/config.ts`, so a new page is invisible until it is added there.
Static files (images, favicon) live in `public/` and are referenced by absolute path, e.g. `/share-link.webp`. Static files (images, favicon) live in `public/` and are referenced by absolute path, e.g. `/share-link.webp`.
`public/CNAME` holds the custom domain; it is copied to the root of the build and must stay there. `public/CNAME` holds the custom domain; it is copied to the root of the build and must stay there.
+7 -6
View File
@@ -18,14 +18,15 @@ hero:
link: /config/ link: /config/
features: features:
- title: Locked down by design - icon: 🔒
title: Locked down by design
details: IPP sits in front of Immich and only serves what you have explicitly shared. It needs no API key and knows nothing about your instance, keeping the attack surface tiny. details: IPP sits in front of Immich and only serves what you have explicitly shared. It needs no API key and knows nothing about your instance, keeping the attack surface tiny.
- title: Photos, videos and albums - icon: 📤
details: Share single images, videos, and whole albums - with optional password protection, styled to match Immich's own light and dark themes. title: Let visitors upload photos (optional)
- title: Let visitors upload photos details: You can optionally enable uploads, so guests can add their own photos and videos to a share. This doesn't need an Immich API key.
details: Guests can add their own photos and videos to a share, straight into your Immich album. Optional, and still with no API key.
link: /visitor-uploads link: /visitor-uploads
- title: Managed entirely in Immich - icon: ⚙️
title: Managed entirely in Immich
details: All sharing stays managed within Immich itself. Set IPP up once and you never need to touch it again. details: All sharing stays managed within Immich itself. Set IPP up once and you never need to touch it again.
--- ---