erik/slugkit
1
0
Fork 0
Code Issues 6 Pull requests Projects Releases 6 Packages Wiki Activity Actions

Write template setup documentation #196

Merged
erik merged 2 commits from docs/task-0342b16b-template-setup-documentation into main 2026-06-23 22:37:21 -05:00
Conversation 1 Commits 2 Files changed 2 +163 -49
erik commented 2026-06-23 21:19:57 -05:00
Owner
Copy link

Summary

Expand the template setup documentation so a fresh site owner can go from slug init to a locally running and CLI-connected Slugkit-compatible site.

Task

Task: #task-0342b16b

Changes

  • Reworked template/site/README.md into a full setup guide covering:
    • slug init, dependency install, .env, migrations, dev server, admin login, API key setup, CLI config, and slug doctor.
    • Required vs optional environment variables.
    • Identity, theme, navigation, media, and ActivityPub customization checklist.
    • Raw template source vs initialized deployable site boundaries.
    • ActivityPub secure-origin/domain/actor/key prerequisites and diagnostics.
    • Links to API, CLI, and web specs.
  • Updated slug init README placeholder replacements so generated standalone sites keep standalone wording and avoid toolkit-only workspace instructions.

Testing

  • Unit tests updated/verified
  • Manual documentation review performed

Verification:

  • npm exec --workspace @evcraddock/slug-cli -- vitest run --config ../vitest.config.ts src/__tests__/commands.test.ts -t "init"
  • ./scripts/pre-pr.sh
  • npm run build && npm run lint && npm test

Checklist

  • ./scripts/pre-pr.sh passes
  • Documentation updated
  • No unrelated changes included
## Summary Expand the template setup documentation so a fresh site owner can go from `slug init` to a locally running and CLI-connected Slugkit-compatible site. ## Task Task: #task-0342b16b ## Changes - Reworked `template/site/README.md` into a full setup guide covering: - `slug init`, dependency install, `.env`, migrations, dev server, admin login, API key setup, CLI config, and `slug doctor`. - Required vs optional environment variables. - Identity, theme, navigation, media, and ActivityPub customization checklist. - Raw template source vs initialized deployable site boundaries. - ActivityPub secure-origin/domain/actor/key prerequisites and diagnostics. - Links to API, CLI, and web specs. - Updated `slug init` README placeholder replacements so generated standalone sites keep standalone wording and avoid toolkit-only workspace instructions. ## Testing - [x] Unit tests updated/verified - [x] Manual documentation review performed Verification: - `npm exec --workspace @evcraddock/slug-cli -- vitest run --config ../vitest.config.ts src/__tests__/commands.test.ts -t "init"` - `./scripts/pre-pr.sh` - `npm run build && npm run lint && npm test` ## Checklist - [x] `./scripts/pre-pr.sh` passes - [x] Documentation updated - [x] No unrelated changes included
docs: expand template setup guide
Some checks failed
CI / build-lint-test (pull_request) Failing after 47s
Details
0f51786cad 
Task: #task-0342b16b
chore: rerun ci after flaky follow test
All checks were successful
CI / build-lint-test (pull_request) Successful in 43s
Details
4bd03a2191 
Task: #task-0342b16b
erik commented 2026-06-23 21:29:29 -05:00
Author
Owner
Copy link

PR Review: approved

Summary: The template setup documentation is in scope and accurately reflects the implemented slug init flow, standalone site boundary, template scripts, settings/API-key UI, CLI configuration, and ActivityPub/media prerequisites. The README placeholder replacements also keep generated standalone sites from inheriting toolkit-only workspace instructions.

Acceptance criteria:

  • Fresh user can follow docs from slug init to a locally running site.
  • Docs clearly identify required vs optional configuration.
  • Docs explain how to create an API key and connect slug.
  • Docs include a customization checklist for identity, theme, navigation, media, and ActivityPub.
  • Docs explain the boundary between raw template source and initialized deployable site code.
  • Docs explain ActivityPub domain/actor setup and secure-origin requirements.
  • Docs link to API and CLI specs/references where useful.
  • Documentation is verified against implemented template commands.

Review notes:

  • Verified changed commands against template/site/package.json, .env.example, cli/src/commands.ts, and implemented settings/federation routes.
  • Verified generated README behavior with slug init so initialized sites get standalone wording and non-workspace commands.
  • Local verification passed:
    • npm exec --workspace @evcraddock/slug-cli -- vitest run --config ../vitest.config.ts src/__tests__/commands.test.ts -t "init"
    • ./scripts/pre-pr.sh
  • Forgejo Actions #273 is green: success build-lint-test for commit 4bd03a2191.

Blocking issues: none.

Warnings: none.

Final verdict: approved. Waiting for explicit human merge approval; not merging.

## PR Review: approved Summary: The template setup documentation is in scope and accurately reflects the implemented `slug init` flow, standalone site boundary, template scripts, settings/API-key UI, CLI configuration, and ActivityPub/media prerequisites. The README placeholder replacements also keep generated standalone sites from inheriting toolkit-only workspace instructions. Acceptance criteria: - [x] Fresh user can follow docs from `slug init` to a locally running site. - [x] Docs clearly identify required vs optional configuration. - [x] Docs explain how to create an API key and connect `slug`. - [x] Docs include a customization checklist for identity, theme, navigation, media, and ActivityPub. - [x] Docs explain the boundary between raw template source and initialized deployable site code. - [x] Docs explain ActivityPub domain/actor setup and secure-origin requirements. - [x] Docs link to API and CLI specs/references where useful. - [x] Documentation is verified against implemented template commands. Review notes: - Verified changed commands against `template/site/package.json`, `.env.example`, `cli/src/commands.ts`, and implemented settings/federation routes. - Verified generated README behavior with `slug init` so initialized sites get standalone wording and non-workspace commands. - Local verification passed: - `npm exec --workspace @evcraddock/slug-cli -- vitest run --config ../vitest.config.ts src/__tests__/commands.test.ts -t "init"` - `./scripts/pre-pr.sh` - Forgejo Actions #273 is green: `success build-lint-test` for commit `4bd03a2191`. Blocking issues: none. Warnings: none. Final verdict: approved. Waiting for explicit human merge approval; not merging.
erik merged commit 5223d68d5b into main 2026-06-23 22:37:21 -05:00
erik deleted branch docs/task-0342b16b-template-setup-documentation 2026-06-23 22:37:22 -05:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels   
activitypub

   
admin

   
api

   
articles

   
auth

   
bug

   
cleanup

   
cli

   
comments

   
compatibility

   
config

   
contacts

   
database

   
deployment

   
design

   
dev-env

   
docs

   
documentation

   
email

   
enhancement

   
feature

   
federation

   
feed

   
homepage

   
implementation

   
integration

   
media

   
openapi

   
priority:high

   
priority:low

   
priority:medium

   
proof

   
public-routes

   
public-ui

   
release

   
safety

   
social

   
sources

   
status:active

   
status:canceled

   
status:done

   
status:inprogress

   
status:waiting

   
syndication

   
tailwind

   
template

   
test

   
web
No labels
activitypub
admin
api
articles
auth
bug
cleanup
cli
comments
compatibility
config
contacts
database
deployment
design
dev-env
docs
documentation
email
enhancement
feature
federation
feed
homepage
implementation
integration
media
openapi
priority:high
priority:low
priority:medium
proof
public-routes
public-ui
release
safety
social
sources
status:active
status:canceled
status:done
status:inprogress
status:waiting
syndication
tailwind
template
test
web
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
erik/slugkit!196
No description provided.