docs(guides): add a getting-started guide, from account to first push #183

Sammanfogat

supernaut sammanfogade 2 incheckningar från docs/getting-started-guide in i main

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

supernaut kommenterad

2026-08-02 21:23:38 +00:00

Ägare

/docs carried three guides — Renovate, Actions and Accounts — and none of them answered what to do
first. Someone finishing sign-up landed on an empty account with no documented path to a working
repository.

Adds getting-started in both locales, first on /docs at order: 0: connect a machine over SSH,
create a first repository, then clone, commit and push, and hand off to the Actions and Renovate
guides.

Three decisions worth stating

It opens with what a participant account cannot do. Hosting your own repository is not included
in the free account, so a guide that goes straight to "create your first repository" is wrong for
the account type most readers arrive with. The guide says so in its second section and links to the
account types rather than discovering the limit for the reader at the moment it bites.

Git over SSH only, no HTTPS path. With internal sign-in disabled there is no password to give,
so the HTTPS route would have to teach an access-token flow — the weaker of the two, documented
alongside the stronger one. SSH is the single answer here.

Links to settings pages use their URLs, not translated menu labels. Gitborg Auth and the Bitborg
app are translated independently of this site, so a guide quoting a menu label goes stale silently.
A URL cannot.

It links to accounts rather than restating it — account creation and signing in are documented
once.

The content gate needed fixing first

Writing the first guide with shell samples surfaced two ways check-content-style.mjs contradicted
the style guide it enforces:

Fenced blocks were scanned as prose. git commit in a bash sample tripped
sv-term/anglicism, even though the guide exempts code identifiers "kept verbatim". The
documented remedy could not be applied either — an ignore directive is an HTML comment, and inside
a fence it renders as part of the sample the reader copies.
The ignore directive was inert in every .md file in the repository. Prettier formats an HTML
comment as its own block and leaves a blank line after it, so by the time pre-commit had run, the
directive no longer sat on lines[index - 1] and the suppression silently stopped applying. It
now binds to the nearest preceding non-blank line.

The second one is the more interesting failure: the escape hatch the guide tells authors to use had
never worked in Markdown, and failed by doing nothing rather than by erroring.

Both behaviours are now written into docs/content-style.md, which the guide itself declares the
source of truth for the checker.

Verified, not assumed

The SSH port and the auth story were read from the infrastructure, not assumed.
git_ssh_port: 22 (ansible/group_vars/all/vars.yml), so no port suffix belongs in the clone
URL; and app.ini.j2 states that internal sign-in is off while Basic auth stays on "so
git-over-HTTPS and API access with tokens keep working" — which is what rules the password out.
The participant-account limit was read from the shipped accounts guide, not inferred from
pricing copy.
pnpm lang-check clean over 76 files — including after Prettier reformats, which is the state
that actually reaches CI and the state the old directive failed in.
pnpm build passes and sitemap-0.xml contains docs/getting-started, so the new guide is
routed and indexed in both locales.
pnpm test 296 passing, up from 293: three new cases pin the gate's logic — fenced code skipped,
prose after a closed fence still checked, and a directive separated from its target by a blank
line still honoured.
pnpm lint clean, pnpm check 0 errors and 0 warnings, pnpm format:check clean.
Pre-push ran build, test and the end-to-end suite against the committed tree: all green.

Ordering is deterministic rather than observed: /docs sorts on order ascending
(src/pages/docs/index.astro:22) and the existing guides hold 1, 2 and 3, so order: 0 leads
without renumbering them.

Closes #181. Part of gitborg/gitborg-docs#28.

`/docs` carried three guides — Renovate, Actions and Accounts — and none of them answered what to do first. Someone finishing sign-up landed on an empty account with no documented path to a working repository. Adds `getting-started` in both locales, first on `/docs` at `order: 0`: connect a machine over SSH, create a first repository, then clone, commit and push, and hand off to the Actions and Renovate guides. ### Three decisions worth stating **It opens with what a participant account cannot do.** Hosting your own repository is not included in the free account, so a guide that goes straight to "create your first repository" is wrong for the account type most readers arrive with. The guide says so in its second section and links to the account types rather than discovering the limit for the reader at the moment it bites. **Git over SSH only, no HTTPS path.** With internal sign-in disabled there is no password to give, so the HTTPS route would have to teach an access-token flow — the weaker of the two, documented alongside the stronger one. SSH is the single answer here. **Links to settings pages use their URLs, not translated menu labels.** Gitborg Auth and the Bitborg app are translated independently of this site, so a guide quoting a menu label goes stale silently. A URL cannot. It links to `accounts` rather than restating it — account creation and signing in are documented once. ### The content gate needed fixing first Writing the first guide with shell samples surfaced two ways `check-content-style.mjs` contradicted the style guide it enforces: - **Fenced blocks were scanned as prose.** `git commit` in a `bash` sample tripped `sv-term/anglicism`, even though the guide exempts code identifiers "kept verbatim". The documented remedy could not be applied either — an ignore directive is an HTML comment, and inside a fence it renders as part of the sample the reader copies. - **The ignore directive was inert in every `.md` file in the repository.** Prettier formats an HTML comment as its own block and leaves a blank line after it, so by the time pre-commit had run, the directive no longer sat on `lines[index - 1]` and the suppression silently stopped applying. It now binds to the nearest preceding non-blank line. The second one is the more interesting failure: the escape hatch the guide tells authors to use had never worked in Markdown, and failed by doing nothing rather than by erroring. Both behaviours are now written into `docs/content-style.md`, which the guide itself declares the source of truth for the checker. ### Verified, not assumed - **The SSH port and the auth story were read from the infrastructure, not assumed.** `git_ssh_port: 22` (`ansible/group_vars/all/vars.yml`), so no port suffix belongs in the clone URL; and `app.ini.j2` states that internal sign-in is off while Basic auth stays on "so git-over-HTTPS and API access with tokens keep working" — which is what rules the password out. - **The participant-account limit was read from the shipped `accounts` guide**, not inferred from pricing copy. - `pnpm lang-check` clean over 76 files — including after Prettier reformats, which is the state that actually reaches CI and the state the old directive failed in. - `pnpm build` passes and `sitemap-0.xml` contains `docs/getting-started`, so the new guide is routed and indexed in both locales. - `pnpm test` 296 passing, up from 293: three new cases pin the gate's logic — fenced code skipped, prose after a closed fence still checked, and a directive separated from its target by a blank line still honoured. - `pnpm lint` clean, `pnpm check` 0 errors and 0 warnings, `pnpm format:check` clean. - Pre-push ran `build`, `test` and the end-to-end suite against the committed tree: all green. Ordering is deterministic rather than observed: `/docs` sorts on `order` ascending (`src/pages/docs/index.astro:22`) and the existing guides hold 1, 2 and 3, so `order: 0` leads without renumbering them. Closes #181. Part of gitborg/gitborg-docs#28.

supernaut lade till 2 incheckningar

2026-08-02 21:23:38 +00:00

fix(lang-check): skip fenced code, and honour a directive Prettier has moved 0b1121d2d8

Writing the first guide with shell samples surfaced two ways the gate contradicts the style
guide it enforces.

Fenced blocks were scanned as prose, so a `git commit` line in a bash sample tripped
sv-term/anglicism. The documented remedy could not be applied either: an HTML comment inside a
fence renders as part of the sample the reader is meant to copy.

The directive was also inert in every .md file. Prettier formats an HTML comment as its own
block and leaves a blank line after it, so by commit time the directive no longer sat on
lines[index - 1] and the suppression silently stopped applying. It now binds to the nearest
preceding non-blank line, which is what an author writing it directly above its target means.

Both are documented in the style guide, which is the source of truth for the checker.

docs(guides): add a getting-started guide, from account to first push

ci / ci (pull_request) Successful in 1m17s

Detaljer

9bc4512b5f

Closes #181.

/docs had three guides and none of them answered what to do first. Someone finishing sign-up
landed on an empty account with no documented path to a working repository.

Covers connecting a machine over SSH, creating a first repository, and the clone-commit-push
loop, then hands off to the Actions and Renovate guides. It opens by saying what a participant
account cannot do — hosting your own repository needs a paid or trial account — because a
getting-started guide that assumes the reader can create a repository is wrong for the account
type most readers will have.

Git over SSH only. There is no HTTPS path here by choice: with internal sign-in disabled there
is no password to give, and documenting a token flow would teach the weaker of the two.

Links to settings pages use their URLs rather than translated menu labels, so the guide cannot
drift from the interface's own translations.

supernaut sammanfogade incheckning f177281a84 till main

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

supernaut tog bort grenen docs/getting-started-guide

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

supernaut refererade denna ändringsförfrågan från en incheckning

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

docs(guides): add a getting-started guide, from account to first push (#183)

supernaut refererade denna ändringsförfrågan från en incheckning

2026-08-03 09:41:50 +00:00

docs(guides): add a getting-started guide, from account to first push (#183)

Logga in för att delta i denna konversation.

Inga granskare