0 Fork 0

mirror of https://github.com/paperclipai/paperclip-docs.git synced 2026-11-07 06:16:07 -10:00

Files

T

DottaandPaperclip 91bbe2cdbd [codex] Add static SEO docs routes (#32 )

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - The public docs site is how operators and contributors discover
reference material and guides.
> - The docs pages were routed through hash URLs, which makes individual
pages harder for crawlers and link previews to treat as first-class
documents.
> - The release build needs to emit static HTML pages for each docs
route while preserving the client-side docs experience.
> - This pull request adds static docs route generation and verification
around canonical, crawlable route output.
> - The benefit is that docs pages can be indexed and shared as normal
path-based URLs without losing local navigation behavior.

## Linked Issues or Issue Description

No public GitHub issue exists for this docs-site improvement.

Problem:
- Docs pages were reachable primarily through hash routes such as
`/#/reference/skills`.
- Crawlers and social previews benefit from static route-specific HTML
at normal paths such as `/reference/skills`.
- The release build should publish those pages predictably and verify
that they include canonical metadata, page titles, and visible article
content.

## What Changed

- Added static route generation to the docs release build so each nav
route gets an `index.html` output with route-specific title, canonical
URL, article content, and sitemap entry.
- Updated the browser app bootstrap to support path-based docs routes
and retain compatibility with hash links.
- Added `docs:test:static-routes` coverage for generated static route
output.
- Documented Cloudflare Pages preview and production deployment details.

## Verification

- `npm run docs:test:static-routes`
- `npm run docs:build`

## Risks

Low to medium risk. This changes release output shape for the docs site,
so the main risk is a Pages deployment configuration mismatch. The build
keeps existing client-side rendering behavior and includes a
static-route verification script to catch missing canonical pages before
publishing.

## Model Used

OpenAI GPT-5 Codex coding agent, tool-using software engineering mode.
Exact service context window was not exposed in this runtime.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <[email protected]>

2026-06-23 07:51:31 -05:00

2.7 KiB

Raw Blame History

Paperclip Docs

Source for the Paperclip documentation site — user guides, API and CLI reference, adapter docs, and deployment notes.

Read the docs: https://docs.paperclip.ing/

What's inside

Guides — Getting started, core concepts, and day-to-day usage.
API reference — Control-plane endpoints and payload schemas.
CLI reference — paperclip command surface.
Adapters — Plugin authoring and the integrations catalogue.
Deploy — Self-hosting, upgrades, and operational guidance.

The site is a single static shell that renders the Markdown files in docs/ directly — no framework, no build step required to read the raw pages.

Build and deployment

Build a release bundle locally with:

npm run docs:build

Cloudflare Pages is connected directly to paperclipai/paperclip-docs through GitHub. There is no normal Wrangler publish step for this repo:

Pushes to main deploy production at https://docs.paperclip.ing/.
Pushes to other branches create Cloudflare Pages preview/canary deployments.
Canary URLs are created by Cloudflare for each deployment, for example https://92b9a99c.paperclip-docs-74t.pages.dev. Use the URL shown in the Cloudflare Pages deployment row or GitHub deployment/check for the pushed branch and commit.

Contributing

Spotted a typo, a broken link, or something that could be clearer? There are two easy paths, both linked from the footer of every docs page:

Suggest an edit — opens the underlying Markdown file in GitHub's web editor. Make the change and submit a PR without leaving the browser.
Report an issue — opens a prefilled Docs feedback issue with the page URL already attached.

For larger changes, fork the repo and open a PR against main. Screenshots live under docs/user-guides/screenshots/{light,dark}/ and should be provided in both themes when replacing UI captures.

Community

License

The Paperclip software is open source — see the main paperclip repository for its license.

The documentation in this repository is licensed under Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International (CC BY-NC-ND 4.0). You may read and share it for non-commercial purposes with attribution. Commercial use of any kind requires prior written permission from the copyright holders. See LICENSE for the full text.

2.7 KiB Raw Blame History