Docs: a getting-started guide, from account to first push #181

Nytt ärende

Stängd

öppnade 2026-08-02 21:08:50 +00:00 av supernaut · 0 kommentarer

supernaut kommenterad

2026-08-02 21:08:50 +00:00

Ägare

/docs carries three guides — Renovate, Actions and Accounts — and none of them tells a new user
what to do first. Someone who has just completed sign-up and landed on an empty account has no path
from there to a working repository: creating one, cloning it and pushing a first commit are
documented nowhere on the site.

This is the piece that makes the documentation set usable at launch. It is the only remaining build
item of its epic that blocks anything — the migration guide in gitborg/gitborg-web#182 is worth
having but can follow.

Scope

A new guide in the guides collection, in both locales:

src/content/guides/sv/getting-started.md
src/content/guides/en/getting-started.md

Covering, in order:

Create a first repository from the web interface.
Clone it — over HTTPS and over SSH, since both are available.
Make and push a first commit.
Where to go next: link onward to the Actions guide and the Renovate guide.

Do not restate account creation or how signing in works. accounts.md already covers both, and
duplicating them creates two places that have to stay true to each other. Link to it and begin from
"you have an account".

Wiring

Frontmatter must satisfy the guides schema in src/content.config.ts: title, description,
order, and an optional topic.
order: 0. /docs sorts ascending (src/pages/docs/index.astro:22) and the existing guides hold
1, 2 and 3, so 0 places this first without renumbering them.
A new topic slug needs a label pair in src/i18n/topics.ts — an unmapped slug silently falls
back to the raw slug rather than failing. Suggested: getting-started →
{ en: "Getting started", sv: "Kom igång" }.

Definition of done

the guide appears first on both /docs and /en/docs, ahead of Renovate
pnpm build passes — invalid frontmatter fails the build, and the sitemap derives its guide slugs
from these files, so a broken entry is not only a docs problem
Swedish copy uses Forgejo's sv-SE terms (kodförråd, incheckning, ändringsförfrågan) with an
English gloss on first use
pnpm lang-check passes
sv/en parity: matching filenames, matching structure, neither locale carrying content the other
lacks
accounts.md is linked, not restated

Part of gitborg/gitborg-docs#28.

`/docs` carries three guides — Renovate, Actions and Accounts — and none of them tells a new user what to do first. Someone who has just completed sign-up and landed on an empty account has no path from there to a working repository: creating one, cloning it and pushing a first commit are documented nowhere on the site. This is the piece that makes the documentation set usable at launch. It is the only remaining build item of its epic that blocks anything — the migration guide in gitborg/gitborg-web#182 is worth having but can follow. ## Scope A new guide in the `guides` collection, in both locales: - `src/content/guides/sv/getting-started.md` - `src/content/guides/en/getting-started.md` Covering, in order: 1. Create a first repository from the web interface. 2. Clone it — over HTTPS and over SSH, since both are available. 3. Make and push a first commit. 4. Where to go next: link onward to the Actions guide and the Renovate guide. **Do not restate account creation or how signing in works.** `accounts.md` already covers both, and duplicating them creates two places that have to stay true to each other. Link to it and begin from "you have an account". ## Wiring - Frontmatter must satisfy the `guides` schema in `src/content.config.ts`: `title`, `description`, `order`, and an optional `topic`. - `order: 0`. `/docs` sorts ascending (`src/pages/docs/index.astro:22`) and the existing guides hold 1, 2 and 3, so 0 places this first without renumbering them. - A new `topic` slug needs a label pair in `src/i18n/topics.ts` — an unmapped slug silently falls back to the raw slug rather than failing. Suggested: `getting-started` → `{ en: "Getting started", sv: "Kom igång" }`. ## Definition of done - the guide appears first on both `/docs` and `/en/docs`, ahead of Renovate - `pnpm build` passes — invalid frontmatter fails the build, and the sitemap derives its guide slugs from these files, so a broken entry is not only a docs problem - Swedish copy uses Forgejo's `sv-SE` terms (kodförråd, incheckning, ändringsförfrågan) with an English gloss on first use - `pnpm lang-check` passes - sv/en parity: matching filenames, matching structure, neither locale carrying content the other lacks - `accounts.md` is linked, not restated Part of gitborg/gitborg-docs#28.

supernaut refererade till detta ärende

2026-08-02 21:09:09 +00:00

Docs: a migration guide for repositories coming from GitHub or GitLab #182

supernaut lade till etiketterna

area/web

ready-for-implementation

type

docs

2026-08-02 21:09:22 +00:00

~~supernaut refererade till detta ärende från bitborg/bitborg-docs 2026-08-02 21:11:19 +00:00~~

Public site conversion & trust surface #28

supernaut lade till detta till projektet Bitborg Web