Jacky's Photography Docs

Docs Site

The documentation site is a Vite, React, and MDX static app in packages/docs. It is published at docs.photo.jackyw.cn and documents this customized Jacky's Photography repository, not upstream Afilmory in general. Keep examples aligned with the current workspace, deployment workflow, private photo checkout, and builder.config.ts.

Public URLs

Content Structure

Documentation pages live in packages/docs/contents/:

  • index.mdx is the task-oriented entry point for readers.
  • architecture/index.mdx is the authority for workspace ownership, package boundaries, and generated data flow.
  • accessibility/index.mdx documents keyboard navigation, dialog focus, sharing fallbacks, and manifest-visibility boundaries.
  • photo-metadata/index.mdx documents manual descriptions, tag curation, manifest merge behavior, and photo SEO output.
  • storage/index.mdx documents supported builder storage providers and the current local/R2 setup.
  • performance/index.mdx records image loading, manifest, and chunk-splitting decisions.
  • deployment/*.mdx contains platform-specific deployment notes.
  • docs-site.mdx explains how to maintain this documentation site.

Route generation follows the file system:

  • contents/index.mdx becomes /.
  • contents/storage/index.mdx becomes /storage.
  • contents/accessibility/index.mdx becomes /accessibility.
  • contents/photo-metadata/index.mdx becomes /photo-metadata.
  • contents/deployment/github-pages.mdx becomes /deployment/github-pages.

The route generator writes src/routes.ts and src/routes.json; treat both as generated files.

Route keys omit trailing slashes internally. Public links, canonical URLs, social metadata and sitemap entries use directory URLs such as /architecture/, matching the generated architecture/index.html file. Reuse the path helpers in src/site.ts when adding navigation.

Sidebar and content navigation use real links. Ordinary same-origin document clicks update the content and history without reloading; Back and Forward restore the corresponding route and metadata. Modified clicks and external links retain browser behavior. src/page-meta.ts supplies the metadata for both static output and client navigation.

Commands

From the repository root:

pnpm docs:dev
pnpm docs:build
pnpm docs:preview
pnpm create:doc

From packages/docs/ directly:

pnpm dev
pnpm build
pnpm preview
pnpm create:doc

pnpm docs:build runs TypeScript and Vite client builds, regenerates routes and table-of-contents data, renders the static pages, and finalizes output through packages/docs/scripts/build.ts.

Writing Pages

Every page must include frontmatter:

---
title: Page Title
description: Short page description.
createdAt: 2026-08-30T13:22:42+08:00
lastModified: 2026-08-30T13:22:42+08:00
---

Update lastModified whenever a content page changes. The repository hook runs pnpm update:lastmodified for staged Markdown and MDX files, and you can also run it manually with file paths when needed.

Use pnpm create:doc for new pages when you want scaffolded frontmatter and route placement prompts.

Style Notes

  • Keep docs operational and specific to this repository.
  • Use Node.js 24, pnpm 10.19.0, React 19, Vite, and the current workspace package names in examples.
  • Describe the current manifest relationship accurately: builder writes apps/web/src/data/photos-manifest.json; packages/data/src/photos-manifest.json is a symlink to it.
  • Document apps/web/dist/ as the web build output and Jackyhq/Photography-Web as the mirrored deployment repository.
  • Keep photo metadata docs aligned with content/photo-descriptions.json, scripts/sync-photo-descriptions.ts, and plugins/builder/photo-descriptions.ts.
  • Do not describe photos/ as sample media. It is a private checkout containing copyrighted personal photos.
  • Avoid committing local generated output, .DS_Store, or tool conversation history.
  • When changing packages/docs/contents/deployment/*, verify the commands against .github/workflows/deploy.yml and root package.json.

Verification

Before publishing documentation changes, run:

pnpm docs:build

For content-only edits, this catches route generation, MDX syntax, table-of-contents extraction, and static rendering issues.

For routing, metadata or generation changes, also run:

pnpm exec vitest run packages/docs

Then check a direct nested URL, sidebar navigation followed by Back and Forward, the address bar and canonical URL, opening a link in another tab, and an unknown route. Documentation builds and tests do not need the private photo checkout.

Hosting and HTTP Status

Publish the complete packages/docs/dist/ output at the documentation domain. The build creates every document's directory index.html, a top-level 404.html, robots.txt, and sitemap.xml. Only published document routes appear in the sitemap. The 404 page contains the actual not-found content, uses noindex, follow, and has no canonical or structured data pointing to the homepage.

The source repository's deployment workflow validates the docs build but mirrors only the gallery's apps/web/dist/ to Jackyhq/Photography-Web. Configure the documentation host separately to run pnpm docs:build from the repository root and publish packages/docs/dist/. Repository output changes do not themselves update that external project's settings.

The host must serve generated files before applying fallbacks, redirect directory URLs consistently to their trailing-slash form, and return the contents of 404.html with HTTP status 404 for unknown paths. Do not rewrite every missing URL to the homepage with status 200. A client-rendered 404 cannot change an HTTP status already sent by the host.

On Cloudflare Pages, a top-level 404.html disables the default SPA fallback, and directory index pages use trailing-slash URLs. See Serving Pages for those host defaults. Existing Workers, Functions, custom rewrites or redirects may override static serving and must be checked on the deployment itself.

After deployment, verify that /architecture/, /sitemap.xml, and /robots.txt return their respective files with status 200, /architecture redirects consistently to /architecture/, and an arbitrary missing path returns the generated 404 content with status 404. This final check validates the external hosting configuration; it cannot be inferred from a local build.

Created At
Last Modified