Write template setup documentation #5

New issue

Closed

opened 2026-05-19 19:51:44 -05:00 by erik · 2 comments

erik commented

2026-05-19 19:51:44 -05:00

Owner

Goal

Document how a site owner uses slug init and the in-repo template to create, configure, run, federate, and prepare a standalone Slugkit-compatible site.

Spec: docs/web-specs/08-template-setup-documentation.md

Requirements

Add setup documentation that starts from slug init <directory> and ends with a locally running site.
Document installing site dependencies, configuring .env, running migrations, starting the dev server, opening the admin UI, creating an API key, configuring slug, and running slug doctor.
Document required vs optional environment variables.
Document required site customization: identity, theme, navigation, media storage, and ActivityPub actor/domain settings.
Explain that the template lives in the Slugkit toolkit repo for development, but slug init creates a standalone site without the CLI source.
Explain that raw template/site is not the deployable website; initialized sites are the deployable starting point.
Explain that initialized sites own their code and may customize freely while preserving the Slugkit API contract.
Document ActivityPub prerequisites: stable HTTPS domain, actor username, actor display metadata, key material, WebFinger/actor routes, and federation diagnostics.
Link to API, CLI, and web specs where useful.
Keep docs accurate against the implemented commands and template structure.

Acceptance criteria

A fresh user can follow docs from slug init to running local 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 where useful.
Documentation is verified against the implemented template commands.

Dependencies

task-d60f5efc
task-77200cff
task-ce8d5c45

## Goal Document how a site owner uses `slug init` and the in-repo template to create, configure, run, federate, and prepare a standalone Slugkit-compatible site. Spec: `docs/web-specs/08-template-setup-documentation.md` ## Requirements - Add setup documentation that starts from `slug init <directory>` and ends with a locally running site. - Document installing site dependencies, configuring `.env`, running migrations, starting the dev server, opening the admin UI, creating an API key, configuring `slug`, and running `slug doctor`. - Document required vs optional environment variables. - Document required site customization: identity, theme, navigation, media storage, and ActivityPub actor/domain settings. - Explain that the template lives in the Slugkit toolkit repo for development, but `slug init` creates a standalone site without the CLI source. - Explain that raw `template/site` is not the deployable website; initialized sites are the deployable starting point. - Explain that initialized sites own their code and may customize freely while preserving the Slugkit API contract. - Document ActivityPub prerequisites: stable HTTPS domain, actor username, actor display metadata, key material, WebFinger/actor routes, and federation diagnostics. - Link to API, CLI, and web specs where useful. - Keep docs accurate against the implemented commands and template structure. ## Acceptance criteria - [ ] A fresh user can follow docs from `slug init` to running local 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 where useful. - [ ] Documentation is verified against the implemented template commands. ## Dependencies - task-d60f5efc - task-77200cff - task-ce8d5c45

erik added the

labels

2026-05-19 19:51:44 -05:00

erik added

status:inprogress

and removed

status:active

labels

2026-06-23 21:19:04 -05:00

erik commented

2026-06-23 21:30:06 -05:00

Author

Owner

Synced from todu comment by @todu on 2026-06-24T02:29:47.107Z

PR Review Result

PR #196 reviewed: approved.

Acceptance criteria: 8/8 met.
Blocking issues: 0.
Warnings: 0.
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
Verified generated slug init README output uses standalone wording and non-workspace commands.
Forgejo Actions #273 is green: success build-lint-test for commit 4bd03a2191.

Merge gate: waiting for explicit human merge approval; not merged.

_Synced from todu comment by @todu on 2026-06-24T02:29:47.107Z_ ## PR Review Result PR #196 reviewed: **approved**. - Acceptance criteria: 8/8 met. - Blocking issues: 0. - Warnings: 0. - 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` - Verified generated `slug init` README output uses standalone wording and non-workspace commands. - Forgejo Actions #273 is green: `success build-lint-test` for commit `4bd03a2191`. Merge gate: waiting for explicit human merge approval; not merged.

erik

2026-06-23 22:42:07 -05:00

closed this issue
added
status:done
and removed
status:inprogress
labels

erik commented

2026-06-23 22:42:09 -05:00

Author

Owner

Synced from todu comment by @todu on 2026-06-24T03:39:04.408Z

Closing Summary

Task close gate result: READY.

Acceptance criteria verified against the task details, merged PR #196, local main merge commit 5223d68, CI #273 success, and PR review approval.

Fresh slug init to local site flow is documented in template/site/README.md under “Quick start from slug init”.
Required vs optional configuration is documented in the environment variables section.
API key creation, CLI configuration, slug login, and slug doctor are documented.
Customization checklist covers identity, theme/layout/assets, navigation/footer, media storage, and ActivityPub actor/domain setup.
Raw template vs initialized standalone deployable site boundary is documented and preserved in generated README replacement logic.
ActivityPub stable HTTPS domain, actor metadata, signing keys, WebFinger/actor routes, and diagnostics are documented.
Related API and CLI specs are linked.
Verification evidence: PR #196 merged to main as 5223d68; CI #273 succeeded for commit 4bd03a2191; PR review approved with 8/8 acceptance criteria met.

_Synced from todu comment by @todu on 2026-06-24T03:39:04.408Z_ ## Closing Summary Task close gate result: **READY**. Acceptance criteria verified against the task details, merged PR #196, local main merge commit `5223d68`, CI #273 success, and PR review approval. - Fresh `slug init` to local site flow is documented in `template/site/README.md` under “Quick start from `slug init`”. - Required vs optional configuration is documented in the environment variables section. - API key creation, CLI configuration, `slug login`, and `slug doctor` are documented. - Customization checklist covers identity, theme/layout/assets, navigation/footer, media storage, and ActivityPub actor/domain setup. - Raw template vs initialized standalone deployable site boundary is documented and preserved in generated README replacement logic. - ActivityPub stable HTTPS domain, actor metadata, signing keys, WebFinger/actor routes, and diagnostics are documented. - Related API and CLI specs are linked. - Verification evidence: PR #196 merged to `main` as `5223d68`; CI #273 succeeded for commit `4bd03a2191`; PR review approved with 8/8 acceptance criteria met.