Skip to content

Commit 8082dd9

Browse files
amondnetamondnet
committed
docs: fix card-group nesting and add CLI page
The home page's ::card-group had the same colon count as the nested ::card blocks, which broke MDC nesting and caused the cards to render as raw text. Bump the outer component to :::card-group so the parser can tell where each card ends. Also add /cli, a full landing page for @pleaseai/code-style covering usage, subcommands, supported tools, the managed AGENTS.md block, flags, localisation, and CI usage. A fourth card on the home page links to it alongside the existing package cards.
1 parent 8281f25 commit 8082dd9

2 files changed

Lines changed: 183 additions & 6 deletions

File tree

‎docs/content/4.cli.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
title: CLI
3+
description: One-command setup for PleaseAI code style — installs packages and writes config files.
4+
navigation:
5+
icon: i-lucide-terminal
6+
---
7+
8+
# CLI
9+
10+
`@pleaseai/code-style` is a zero-config CLI that wires PleaseAI's shared code style into any project. It installs the ESLint / Prettier / EditorConfig packages and manages an `AGENTS.md` rules block so AI coding assistants know how to write code that passes lint on the first try.
11+
12+
Inspired by [ultracite](https://github.com/haydenbleasel/ultracite) and NaverPay's [`@naverpay/code-style-cli`](https://github.com/NaverPayDev/code-style).
13+
14+
## Quick Start
15+
16+
Run from the root of any project that has a `package.json`:
17+
18+
:::code-group
19+
```bash [bun]
20+
bunx @pleaseai/code-style
21+
```
22+
23+
```bash [pnpm]
24+
pnpm dlx @pleaseai/code-style
25+
```
26+
27+
```bash [npm]
28+
npx @pleaseai/code-style
29+
```
30+
:::
31+
32+
The CLI will:
33+
34+
1. Detect your package manager from the lockfile (bun → pnpm → yarn → npm, falling back to bun)
35+
2. Show a checkbox UI listing the available tools; already-installed ones are labelled `(installed)`
36+
3. Install the packages you select as dev dependencies
37+
4. Write or update the matching config files
38+
39+
## Commands
40+
41+
### `init`
42+
43+
Interactive setup — the default when no subcommand is given.
44+
45+
```bash
46+
pleaseai-code-style init
47+
pleaseai-code-style init --yes # non-interactive, accept defaults
48+
```
49+
50+
### `update`
51+
52+
Refresh **only** the `AGENTS.md` rules block without touching packages or other config files. Use this after bumping `@pleaseai/code-style` to pull in the latest rules.
53+
54+
```bash
55+
pleaseai-code-style update
56+
```
57+
58+
### `doctor`
59+
60+
Report the current project configuration status — which packages are installed, which config files exist.
61+
62+
```bash
63+
pleaseai-code-style doctor
64+
```
65+
66+
## Supported Tools
67+
68+
| Tool | npm package(s) | Config file |
69+
| --- | --- | --- |
70+
| eslint-config | `@pleaseai/eslint-config`, `eslint` | `eslint.config.mjs` |
71+
| prettier-config | `@pleaseai/prettier-config`, `prettier` | `package.json#prettier` |
72+
| editorconfig | `@pleaseai/editorconfig` | `.editorconfig` |
73+
| agents-md | — | `AGENTS.md` (marker-managed block) |
74+
75+
## The `AGENTS.md` Rules Block
76+
77+
The CLI writes a marker-delimited block into `AGENTS.md` so you can mix your own content around it without losing edits on the next run:
78+
79+
```md [AGENTS.md]
80+
My project notes live here.
81+
82+
<!-- pleaseai-code-style:start -->
83+
# PleaseAI Code Style
84+
85+
These rules are managed by `@pleaseai/code-style`. Run
86+
`pleaseai-code-style update` to refresh this block.
87+
88+
- Formatter: `@pleaseai/eslint-config` (wraps `@antfu/eslint-config`)
89+
- No semicolons, single quotes, 2-space indent, trailing commas, LF line endings
90+
- ESM only — never emit `require`/`module.exports`
91+
- ...
92+
<!-- pleaseai-code-style:end -->
93+
94+
My own content stays here untouched.
95+
```
96+
97+
The CLI **only** owns the content between the two marker comments — everything else in `AGENTS.md` is preserved verbatim. Running `update` twice in a row is a no-op; the block never duplicates.
98+
99+
The full canonical rules list is shipped as `node_modules/@pleaseai/code-style/rules.md` for AI assistants that prefer to read the long version.
100+
101+
## Options
102+
103+
| Flag | Description |
104+
| --- | --- |
105+
| `--yes`, `-y` | Accept defaults and overwrite existing files without prompting |
106+
| `--lang <ko\|en>` | Force the CLI locale (defaults to `$LC_ALL` / `$LANG`) |
107+
| `--help`, `-h` | Print help |
108+
| `--version`, `-v` | Print the CLI version |
109+
110+
## Localisation
111+
112+
The CLI auto-detects your locale from `LC_ALL`, `LANG`, or `LC_MESSAGES` and currently ships Korean and English messages. Override with `--lang ko` or `--lang en`:
113+
114+
```bash
115+
pleaseai-code-style --lang ko init
116+
```
117+
118+
## CI Usage
119+
120+
Combine `--yes` with a locale override for a fully non-interactive invocation suitable for CI or project templates:
121+
122+
```bash
123+
pleaseai-code-style --yes --lang en init
124+
```
125+
126+
This accepts defaults for every tool, overwrites any existing config files, and uses English output.
127+
128+
## Binaries
129+
130+
The package exposes two bin entries — use whichever you prefer:
131+
132+
- `pleaseai-code-style`
133+
- `please-style` (short alias)
134+
135+
Both point to the same executable.

‎docs/content/index.md‎

Lines changed: 48 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,26 +6,68 @@ navigation: false
66

77
# PleaseAI Code Style
88

9-
Shared ESLint, Prettier, and EditorConfig configurations for consistent code style across PleaseAI projects.
9+
Shared ESLint, Prettier, and EditorConfig configurations for consistent code style across PleaseAI projects — plus a CLI that wires them all up in one command.
1010

1111
## Packages
1212

13-
::card-group
14-
::card{title="ESLint Config" icon="i-lucide-shield-check" to="/eslint-config"}
13+
:::card-group
14+
::card
15+
---
16+
title: ESLint Config
17+
icon: i-lucide-shield-check
18+
to: /eslint-config
19+
---
1520
Opinionated ESLint flat config built on top of `@antfu/eslint-config`.
1621
::
1722

18-
::card{title="Prettier Config" icon="i-lucide-paintbrush" to="/prettier-config"}
23+
::card
24+
---
25+
title: Prettier Config
26+
icon: i-lucide-paintbrush
27+
to: /prettier-config
28+
---
1929
Shared Prettier configuration for consistent formatting.
2030
::
2131

22-
::card{title="EditorConfig" icon="i-lucide-file-cog" to="/editorconfig"}
32+
::card
33+
---
34+
title: EditorConfig
35+
icon: i-lucide-file-cog
36+
to: /editorconfig
37+
---
2338
Shared `.editorconfig` for consistent editor settings.
2439
::
25-
::
40+
41+
::card
42+
---
43+
title: CLI
44+
icon: i-lucide-terminal
45+
to: /cli
46+
---
47+
One-command setup for eslint, prettier, editorconfig, and the `AGENTS.md` rules block.
48+
::
49+
:::
2650

2751
## Quick Start
2852

53+
The fastest path is the CLI — it installs the packages and writes the config files for you:
54+
55+
:::code-group
56+
```bash [bun]
57+
bunx @pleaseai/code-style
58+
```
59+
60+
```bash [pnpm]
61+
pnpm dlx @pleaseai/code-style
62+
```
63+
64+
```bash [npm]
65+
npx @pleaseai/code-style
66+
```
67+
:::
68+
69+
Prefer to wire things up by hand? Install the ESLint config directly:
70+
2971
:::code-group
3072
```bash [bun]
3173
bun add -D @pleaseai/eslint-config eslint

0 commit comments

Comments
 (0)