# docs

> Use when working on the documentation website, Docusaurus config, docs content, theme customization, or versioning. Covers the website/ directory.

- Author: Robin Joseph
- Repository: shishobooks/shisho
- Version: 20260207222040
- Stars: 2
- Forks: 0
- Last Updated: 2026-02-08
- Source: https://github.com/shishobooks/shisho
- Web: https://mule.run/skillshub/@@shishobooks/shisho~docs:20260207222040

---

---
name: docs
description: Use when working on the documentation website, Docusaurus config, docs content, theme customization, or versioning. Covers the website/ directory.
---

# Documentation Site

## Overview

Shisho's docs site is a Docusaurus 3 app in `website/` deployed to GitHub Pages. Dark-mode only, violet theme, versioned per release.

## Quick Reference

| Item | Value |
|------|-------|
| Framework | Docusaurus 3.9.2 |
| Location | `website/` |
| Dev server | `make docs` |
| Build | `cd website && yarn build` |
| Deploy URL | `https://shishobooks.github.io/shisho/` |
| Deploy trigger | Push to `master` touching `website/**` |
| Workflow | `.github/workflows/docs.yml` |
| Icons | `lucide-react` (swizzled theme icons) |
| Fonts | Geist Variable, Noto Sans, Noto Sans JP |

## Directory Structure

```
website/
├── docs/                    # Current "Unreleased" version content
│   ├── getting-started.md
│   ├── directory-structure.md
│   ├── configuration.md
│   ├── supported-formats.md
│   ├── plugins.md
│   └── advanced/
│       ├── _category_.json  # Label, position, collapsed state
│       └── primary-file.md
├── versioned_docs/          # Snapshots per release (auto-generated)
├── versioned_sidebars/      # Sidebar snapshots per release
├── versions.json            # Released version list
├── docusaurus.config.ts     # Main config
├── sidebars.ts              # Autogenerated sidebar
├── src/
│   ├── pages/index.tsx      # Homepage
│   ├── components/          # ShishoLogo.tsx
│   ├── css/custom.css       # Theme overrides (OKLCH violet palette)
│   └── theme/               # Swizzled Docusaurus components
│       ├── Icon/            # lucide-react replacements for all default icons
│       ├── Admonition/Icon/ # Custom admonition icons (Note, Warning, etc.)
│       ├── Navbar/Logo/     # Custom logo with 司書 superscript
│       └── NavbarItem/      # Custom dropdown behavior
├── static/img/              # favicon.ico, logo-mark.svg, social card
├── package.json
└── tsconfig.json
```

## Versioning

Docs are versioned alongside app releases. The `scripts/release.sh` script handles this automatically:

1. On `make release tag=X.X.X`, the script runs `yarn docs:version X.X.X` inside `website/`
2. This snapshots `docs/` → `versioned_docs/version-X.X.X/` and sidebars → `versioned_sidebars/`
3. `versions.json` is updated with the new version
4. All versioned files are committed with the release

**URL structure:**
- Latest released version: `/docs/getting-started` (default)
- Unreleased (current): `/docs/unreleased/getting-started`
- Specific version: `/docs/X.X.X/getting-started`

The `docusaurus.config.ts` reads `versions.json` to determine the latest version. Current docs are labeled "Unreleased" with a banner.

## Adding a New Doc Page

1. Create `website/docs/your-page.md` with frontmatter:
   ```md
   ---
   sidebar_position: 6
   ---

   # Page Title

   Content here.
   ```
2. Sidebar is autogenerated from `docs/` — ordering controlled by `sidebar_position`
3. Run `make docs` to preview

### Sidebar Ordering

Pages are ordered by `sidebar_position` in frontmatter. Core/essential pages go first, niche or advanced topics go last. When adding a new page, check the existing positions and place it appropriately — don't insert early in the list unless the page is something most users need to see. New pages for optional or secondary features should go at the end.

## Monorepo Integration Points

The docs site is integrated into the main project's tooling:

| Tool | Integration |
|------|------------|
| `make setup` | Runs `cd website && yarn` to install deps |
| `make docs` | Starts Docusaurus dev server |
| `make release` | Versions docs via `yarn docs:version` |
| `yarn lint:types` | Runs `yarn --cwd website typecheck` |
| ESLint | `website/src/**/*.{ts,tsx}` included in React config |
| Prettier | `website/build/` and `website/.docusaurus/` ignored |
| CI | `.github/workflows/ci.yml` installs website deps for type checking |

## Deployment

GitHub Actions workflow (`.github/workflows/docs.yml`):
- **Triggers**: Push to `master` when `website/**` changes, or manual `workflow_dispatch`
- **Concurrency**: `docs-pages` group, cancels in-progress deploys
- **Build**: Node.js 24, `yarn install --frozen-lockfile`, `yarn build`
- **Deploy**: GitHub Pages via `actions/deploy-pages@v4`

The `baseUrl` is auto-detected: uses `DOCS_BASE_URL` env var if set, `/${projectName}/` in GitHub Actions, or `/` locally.

## Theme Customization

- **Dark mode only** — `colorMode.disableSwitch: true`
- **Colors**: Violet palette using OKLCH in `custom.css` (`--shisho-violet-300`)
- **Icons**: All default Docusaurus icons swizzled to use `lucide-react` components (in `src/theme/Icon/`)
- **Admonition icons**: Custom icons for Note, Warning, Info, Danger, Tip (in `src/theme/Admonition/Icon/`)
- **Navbar logo**: Custom component with shelf icon + "Shisho" + "司書" superscript

## .gitignore Gotcha

The macOS `Icon\r\r` ignore pattern in `.gitignore` conflicts with the swizzled `Icon/` directories. The root `.gitignore` has explicit exceptions:
```
!website/src/theme/Icon/
!website/src/theme/Icon/**
!website/src/theme/Admonition/Icon/
!website/src/theme/Admonition/Icon/**
```

If new icon directories are added under `src/theme/`, add corresponding exceptions.

## Common Mistakes

- **Editing versioned_docs directly** — These are snapshots. Edit `docs/` for unreleased content; versioned docs are regenerated on release.
- **Forgetting `sidebar_position`** — Pages without it appear in alphabetical order. Always set explicit positions.
- **Running `yarn` instead of `make setup`** — In a new worktree, `make setup` handles both root and website deps.
- **Missing `.gitignore` exception for new Icon dirs** — New swizzled `Icon/` subdirectories won't be tracked without an exception.