Skip to content

Commit dd52dd5

Browse files
sjquantsjquant
authored
Add documentation website (#16)
* feat: add documentation website * fix: refine docs site branding and contrast * fix: tune terminal spacing and color tokens * chore: keep docs logo generated from brand assets * feat: refine docs and terminal code block styling * fix: restore mobile navbar sidebar styles * feat: sharpen homepage messaging and seo * fix: align docs logo with brand icon * fix: harden docs code block copy button * fix: add mobile spacing below hero terminal * fix: refine hero spacing and docs code blocks * feat: align docs palette with brand colors * fix: simplify docs code block styling * fix: tighten docs code block padding * fix: soften brand tokens across docs * fix: neutralize homepage palette * fix: cool down hero background * fix: mute terminal and footer tones * fix: left align homepage signal list * fix: add space above proof cards * fix: restore terminal color depth * fix: warm the terminal palette * fix: use dark hero background in dark mode
1 parent b65e644 commit dd52dd5

25 files changed

Lines changed: 14208 additions & 1 deletion

‎.github/workflows/docs.yml‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
name: Docs
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- '.github/workflows/docs.yml'
7+
- 'package.json'
8+
- 'website/**'
9+
push:
10+
branches:
11+
- main
12+
paths:
13+
- '.github/workflows/docs.yml'
14+
- 'package.json'
15+
- 'website/**'
16+
workflow_dispatch:
17+
18+
permissions:
19+
contents: read
20+
pages: write
21+
id-token: write
22+
23+
concurrency:
24+
group: docs-pages
25+
cancel-in-progress: true
26+
27+
jobs:
28+
build:
29+
runs-on: ubuntu-latest
30+
31+
steps:
32+
- name: Checkout repository
33+
uses: actions/checkout@v4
34+
with:
35+
fetch-depth: 0
36+
37+
- name: Set up pnpm
38+
uses: pnpm/action-setup@v4
39+
40+
- name: Set up Node.js
41+
uses: actions/setup-node@v4
42+
with:
43+
node-version: 20
44+
cache: pnpm
45+
cache-dependency-path: website/pnpm-lock.yaml
46+
47+
- name: Install website dependencies
48+
run: pnpm install --frozen-lockfile
49+
working-directory: website
50+
51+
- name: Build docs site
52+
run: pnpm build
53+
working-directory: website
54+
55+
- name: Upload Pages artifact
56+
uses: actions/upload-pages-artifact@v3
57+
with:
58+
path: website/build
59+
60+
deploy:
61+
if: github.event_name != 'pull_request'
62+
needs: build
63+
runs-on: ubuntu-latest
64+
environment:
65+
name: github-pages
66+
url: ${{ steps.deployment.outputs.page_url }}
67+
68+
steps:
69+
- name: Deploy to GitHub Pages
70+
id: deployment
71+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,4 +13,7 @@ Cargo.lock
1313
# MSVC Windows builds of rustc generate these, which store debugging information
1414
*.pdb
1515

16-
dist/
16+
dist/
17+
website/.docusaurus/
18+
website/build/
19+
website/node_modules/

‎README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,12 @@ Shell (Mac, Linux):
1212
curl -fsSL https://raw.githubusercontent.com/sjquant/flopha/main/scripts/install.sh | sh
1313
```
1414

15+
## Docs
16+
17+
- Website source: `website/`
18+
- Local preview: `pnpm docs:start`
19+
- Production build: `pnpm docs:build`
20+
1521
## Features
1622

1723
- Semantic versioning CLI for Git tags and release branches

‎package.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"name": "flopha",
3+
"private": true,
4+
"packageManager": "pnpm@10.6.3",
5+
"scripts": {
6+
"docs:build": "pnpm --dir website build",
7+
"docs:start": "pnpm --dir website start",
8+
"docs:serve": "pnpm --dir website serve",
9+
"docs:typecheck": "pnpm --dir website typecheck"
10+
}
11+
}

‎scripts/sync-brand.mjs‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
import {mkdir, readFile, writeFile} from 'node:fs/promises';
2+
import path from 'node:path';
3+
import {fileURLToPath} from 'node:url';
4+
5+
const currentDir = path.dirname(fileURLToPath(import.meta.url));
6+
const repoRoot = path.resolve(currentDir, '..');
7+
const sourcePath = path.join(repoRoot, 'assets', 'brand', 'flopha-icon.svg');
8+
const targetPath = path.join(repoRoot, 'website', 'static', 'img', 'flopha-icon.svg');
9+
10+
await mkdir(path.dirname(targetPath), {recursive: true});
11+
const source = await readFile(sourcePath, 'utf8');
12+
await writeFile(targetPath, source);

‎website/.gitignore‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
/.docusaurus
2+
/build
3+
/node_modules
4+
/static/img/flopha-icon.svg

‎website/README.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# flopha docs
2+
3+
This site is built with [Docusaurus](https://docusaurus.io/) and is intended for GitHub Pages deployment.
4+
5+
## Local development
6+
7+
```bash
8+
pnpm install
9+
pnpm start
10+
```
11+
12+
## Production build
13+
14+
```bash
15+
pnpm build
16+
pnpm serve
17+
```

‎website/docs/command-reference.mdx‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
id: command-reference
3+
title: Command Reference
4+
---
5+
6+
# Command Reference
7+
8+
## `flopha last-version`
9+
10+
Print the latest matching version.
11+
12+
```bash
13+
flopha last-version [--pattern <pattern>] [--source <tag|branch>] [--checkout]
14+
```
15+
16+
Options:
17+
18+
- `--pattern`, `-p`: Match a custom version format.
19+
- `--source`, `-s`: Read versions from tags or branches. Default is `tag`.
20+
- `--checkout`: Check out the resolved version after printing it.
21+
22+
## `flopha next-version`
23+
24+
Calculate the next version.
25+
26+
```bash
27+
flopha next-version \
28+
[--increment <major|minor|patch>] \
29+
[--auto] \
30+
[--rule <level:regex>] \
31+
[--pre <channel>] \
32+
[--pattern <pattern>] \
33+
[--source <tag|branch>] \
34+
[--create]
35+
```
36+
37+
Options:
38+
39+
- `--increment`, `-i`: Explicit bump level. Default is `patch`.
40+
- `--auto`: Detect the bump from commit messages since the last version.
41+
- `--rule`: Replace the built-in auto-detection rules. Requires `--auto`.
42+
- `--pre`: Create a pre-release tag like `-alpha.1` or `-rc.1`.
43+
- `--pattern`, `-p`: Match and generate a custom version format.
44+
- `--source`, `-s`: Read versions from tags or branches. Default is `tag`.
45+
- `--create`: Create the new tag or branch after printing it.
46+
47+
## `flopha log`
48+
49+
Show matching versions newest first.
50+
51+
```bash
52+
flopha log [--pattern <pattern>] [--source <tag|branch>] [--limit <number>]
53+
```
54+
55+
Options:
56+
57+
- `--pattern`, `-p`: Match a custom version format.
58+
- `--source`, `-s`: Read versions from tags or branches. Default is `tag`.
59+
- `--limit`, `-n`: Limit the number of rows.
60+
61+
## Global behavior
62+
63+
- `--verbose`, `-v` enables debug logging.
64+
- The CLI fetches from the `origin` remote before resolving versions.
65+
- The default version pattern is `v{major}.{minor}.{patch}`.

‎website/docs/installation.mdx‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
id: installation
3+
title: Installation
4+
---
5+
6+
# Installation
7+
8+
## Install the binary
9+
10+
For macOS and Linux:
11+
12+
```bash
13+
curl -fsSL https://raw.githubusercontent.com/sjquant/flopha/main/scripts/install.sh | sh
14+
```
15+
16+
The installer places the binary under `~/.flopha/bin` unless `FLOPHA_INSTALL` is already set.
17+
18+
## Add it to your shell
19+
20+
If `flopha` is not already on your `PATH`, add this to your shell profile:
21+
22+
```bash
23+
export FLOPHA_INSTALL="$HOME/.flopha"
24+
export PATH="$FLOPHA_INSTALL/bin:$PATH"
25+
```
26+
27+
## Verify the install
28+
29+
```bash
30+
flopha last-version
31+
```
32+
33+
Run the command inside a Git repository that has an `origin` remote and tags or branches that match your chosen pattern.
34+
35+
## Build locally
36+
37+
If you prefer building from source:
38+
39+
```bash
40+
cargo build --release
41+
./target/release/flopha last-version
42+
```

‎website/docs/intro.mdx‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
id: intro
3+
title: Overview
4+
slug: /
5+
---
6+
7+
# Release versioning for Git tags and branches
8+
9+
`flopha` is a small Git-focused CLI for repositories that encode releases as semantic versions. It looks at matching tags or branches, resolves the latest version, calculates the next one, and can create the result directly in Git.
10+
11+
It is useful when your repository needs more than a one-off `git tag`:
12+
13+
- You release with a custom prefix like `desktop@1.4.2` or `release/1.4.2`.
14+
- You want to drive version bumps from conventional commits.
15+
- You need branch-based version streams instead of tag-only releases.
16+
- You want pre-release channels such as `alpha`, `beta`, or `rc`.
17+
18+
## What it does well
19+
20+
- Resolve the latest matching version with `flopha last-version`.
21+
- Calculate the next semantic version with `flopha next-version`.
22+
- Infer the bump from commit history with `flopha next-version --auto`.
23+
- Create tags or branches once the version is resolved.
24+
- Show version history with commit counts using `flopha log`.
25+
26+
## Default behavior
27+
28+
By default, `flopha` looks for tags matching `v{major}.{minor}.{patch}` and fetches from `origin` before operating. You can override both the version pattern and the version source when your repository uses a different release scheme.
29+
30+
## Next
31+
32+
- Go to [Installation](/docs/installation) to install the binary.
33+
- Go to [Quick Start](/docs/quick-start) for the common day-to-day commands.
34+
- Go to [Version Patterns](/docs/version-patterns) for custom formats.

0 commit comments

Comments
 (0)