# Documentation

Guides and reference for the portfolio, its features, and its development workflow.



Guides and reference for using, developing, and maintaining nicholasadamou.com.

This site brings together a professional introduction, open-source projects,
client websites, technical notes, and photography. These docs explain the visitor
experience and the implementation behind it, including the two homepage layouts,
interactive scenes, content publishing, public APIs, and deployment workflow.

## Start with what you want to do [#start-with-what-you-want-to-do]

- [Explore the site](/docs/using-the-site/overview): Find projects, client work, writing, photography, contact details, and the controls available throughout the site.
- [Run it locally](/docs/getting-started/installation): Set up the Flox environment, start the portfolio and documentation, and verify your first change.
- [Layouts and scenes](/docs/using-the-site/layouts-and-scenes): Choose a homepage layout, adjust the artwork, and use the dock and keyboard controls.
- [Write and publish content](/docs/features/mdx-content): Add notes with consistent frontmatter, heading hierarchy, syntax highlighting, and a useful table of contents.
- [Architecture](/docs/architecture/overview): Understand the server-rendered pages, interactive components, content sources, and separate docs application.
- [APIs and agents](/docs/api/public-content): Read public content from JSON, Markdown, the command line, or an MCP client.

## Two applications, one public website [#two-applications-one-public-website]

The portfolio and documentation are independent Next.js applications in the same
repository. Visitors use the same public origin: the portfolio owns the main
pages, and the docs application owns `/docs`.

```mermaid
"flowchart LR\n    Visitor[Visitor or developer] --> Site[nicholasadamou.com]\n    Site --> Portfolio[Portfolio pages]\n    Site --> Docs[Documentation at /docs]\n    Portfolio --> Content[Notes, client work and projects]\n    Docs --> Guides[Visitor and developer guides]\n    Guides --> Source[Markdown in docs/src]"
```

The shared domain keeps links and reading workflows straightforward. Independent
Vercel projects keep the applications' styles, dependencies, and releases separate.
See the [documentation architecture](/docs/architecture/documentation) for routing,
asset isolation, source provenance, and deployment details.

## Common maintenance tasks [#common-maintenance-tasks]

- [Add client work](/docs/using-the-site/client-work): Register a client, prepare screenshots and brand assets, and publish a case study.
- [Maintain the design system](/docs/using-the-site/brand): Keep the portrait, typography, spacing, action buttons, and social cards consistent.
- [Understand the homepage](/docs/features/homepage): Find the source for layout preferences, scene transitions, dock panels, and reduced-motion behavior.
- [Prepare a release](/docs/contributing/quality-and-releases): Run the shared quality gates, review the changes, and follow the tested release process.

## What to expect from these docs [#what-to-expect-from-these-docs]

Visitor guides describe what you can do without an account. Development guides
show commands and the files responsible for each feature. Architecture pages
explain how those parts connect, while API reference pages cover programmatic
access. Examples use public content and placeholders rather than credentials.

Code blocks include language-aware syntax highlighting, copy controls, and file
labels where a path helps explain the example. Diagrams explain relationships or
request flows; the Markdown export keeps their Mermaid source. Guide cards remain
ordinary links in exported Markdown, so the same content works for browsers and
assistants.

## Development environment [#development-environment]

The portfolio uses Next.js 16, React 19, TypeScript, and Tailwind CSS 4. Flox
provides the locked Node.js 24 and Bun 1.3 toolchain. The separate documentation
app uses Next.js with Fumadocs MDX and the actual set-me-up-docs interface, adapted
to the portfolio's identity and neutral palette.

## Project resources [#project-resources]

* [Live portfolio](https://nicholasadamou.com)
* [Source repository](https://github.com/nicholasadamou/nicholasadamou.com)
* [Documentation source](https://github.com/nicholasadamou/nicholasadamou.com/tree/main/docs)
* [Issue tracker](https://github.com/nicholasadamou/nicholasadamou.com/issues)

When contributing, update the relevant documentation in the same change as the
behavior it describes. The repository's `AGENTS.md` makes that part of completing
the work, and CI validates the documentation application before release.