Skip to content

Commit 7e09669

Browse files
bogdanmatasarubogdanmatasaru
authored
Merge pull request #1 from bogdanmatasaru/english-reference-rewrite
Rebuild as a premium English Claude Code guide (docs site + assets + bootstrap)
2 parents 43444d9 + acf52ff commit 7e09669

76 files changed

Lines changed: 8708 additions & 695 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/skills/project-onboard/SKILL.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
name: project-onboard
3+
description: Set up a project for smooth work with Claude Code — generate/update CLAUDE.md, propose an allowlist of permissions so it stops asking on repetitive commands, and suggest relevant MCP servers. Use when you first open a new repo with Claude Code.
4+
---
5+
6+
# project-onboard
7+
8+
Goal: after `setup.sh` has prepared the *environment* (Ghostty + Claude Code
9+
installed), this skill prepares the *current project* so work is smooth from the
10+
first message.
11+
12+
Run the steps in order. Be concise with the user; show what you did, don't explain
13+
the theory.
14+
15+
## 1. Understand the repo
16+
17+
- Detect the stack: look for `package.json`, `pyproject.toml`, `go.mod`,
18+
`Cargo.toml`, `Makefile`, `*.csproj`, etc.
19+
- Identify the build / test / lint / run commands (from scripts, Makefile, CI).
20+
- Note obvious conventions (formatter, folder structure, test framework).
21+
22+
## 2. CLAUDE.md
23+
24+
- If `CLAUDE.md` does **not** exist: run the equivalent of `/init` — generate a
25+
short one with: the key commands (build/test/lint/run), a brief structure
26+
overview, code conventions, and non-obvious things to know. Keep it tight (not
27+
an essay).
28+
- If it **exists**: read it, propose additions only for what's missing and useful.
29+
- Ask for confirmation before writing/committing.
30+
31+
## 3. Permissions (fewer prompts)
32+
33+
- From the commands found in step 1, propose an allowlist in `.claude/settings.json`
34+
for the safe & repetitive ones (e.g. `Bash(npm run test:*)`, `Bash(npm run build)`,
35+
`Bash(git status)`, `Bash(git diff:*)`).
36+
- Do NOT add destructive commands (deploy, push --force, rm). Read/test/build only.
37+
- Write to `.claude/settings.json` (project), not the global settings.
38+
39+
## 4. Relevant MCP servers (optional)
40+
41+
- If the project uses GitHub and `gh` is authenticated, suggest the GitHub MCP.
42+
- If it's a web/UI project, mention a browser MCP for visual verification.
43+
- Only suggest + show the command; don't install without an OK.
44+
45+
## 5. Final summary
46+
Show a short list:
47+
- what was created/changed (CLAUDE.md, settings.json),
48+
- the detected test/build commands,
49+
- the recommended next step (e.g. "run /code-review after your first changes").
50+
51+
Rules: confirm before writing to versioned files; don't touch the user's global
52+
settings; don't invent commands — verify they exist in the repo.

‎.github/ISSUE_TEMPLATE/bug_report.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
name: Bug report
3+
about: Something in the repo doesn't work (setup.sh, the docs site, a broken link)
4+
title: "[bug] "
5+
labels: bug
6+
---
7+
8+
**What's broken:**
9+
10+
**Steps to reproduce:**
11+
12+
**Expected vs actual:**
13+
14+
**Environment** (OS, shell, `claude --version`, Node version if relevant):
15+
16+
**Logs / screenshots:**

‎.github/ISSUE_TEMPLATE/content-correction.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
name: Content correction
3+
about: Something in the guide is inaccurate or out of date
4+
title: "[correction] "
5+
labels: correction
6+
---
7+
8+
**Where** (page / file path, e.g. `docs/reference/hooks.md`):
9+
10+
**What's wrong:**
11+
12+
**What it should say** (with a source if you have one — ideally a link to
13+
<https://code.claude.com/docs>):
14+
15+
**Claude Code version you're on** (`claude --version`):

‎.github/ISSUE_TEMPLATE/new-resource.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
---
2+
name: New resource / asset
3+
about: Suggest a CLAUDE.md template, slash command, hook, skill, or workflow
4+
title: "[resource] "
5+
labels: enhancement
6+
---
7+
8+
**Type** (CLAUDE.md template / command / hook / skill / settings / workflow):
9+
10+
**What it does and who it helps:**
11+
12+
**The asset** (paste it, or link a gist — keep it copy-paste-ready):
13+
14+
**Have you used it in a real project?** (yes/no — helps us vet it)

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
<!-- Keep PRs focused: one topic per PR makes review fast. -->
2+
3+
## What & why
4+
5+
<!-- One or two lines: what this changes and why it helps. -->
6+
7+
## Type
8+
9+
- [ ] Content correction (fixes something inaccurate/out of date)
10+
- [ ] New content / recipe
11+
- [ ] New asset (CLAUDE.md / command / hook / skill / settings)
12+
- [ ] Fix (link, typo, build)
13+
- [ ] Other:
14+
15+
## Checklist
16+
17+
- [ ] Facts about Claude Code are cited (link to <https://code.claude.com/docs>)
18+
- [ ] Version caveats noted where relevant (e.g. "v2.1.x+")
19+
- [ ] Code blocks are copy-paste-ready
20+
- [ ] `npm run docs:build` passes locally (if I changed docs) — optional
21+
- [ ] One topic per PR

‎.github/workflows/ci.yml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
name: CI
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches: [main]
7+
8+
jobs:
9+
lint-and-build:
10+
runs-on: ubuntu-latest
11+
steps:
12+
- uses: actions/checkout@v4
13+
- uses: actions/setup-node@v4
14+
with:
15+
node-version: 20
16+
cache: npm
17+
- run: npm ci
18+
19+
- name: Lint Markdown
20+
run: npm run lint:md
21+
22+
- name: Build docs (validates internal links + Mermaid)
23+
run: npm run docs:build
24+
25+
shellcheck:
26+
runs-on: ubuntu-latest
27+
steps:
28+
- uses: actions/checkout@v4
29+
- name: ShellCheck setup.sh & tests
30+
run: |
31+
sudo apt-get update && sudo apt-get install -y shellcheck
32+
shellcheck -S warning setup.sh test/run-tests.sh
33+
- name: Run setup.sh test suite
34+
run: ./test/run-tests.sh

‎.github/workflows/deploy-docs.yml‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
name: Deploy docs to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
# Allow one concurrent deployment
14+
concurrency:
15+
group: pages
16+
cancel-in-progress: false
17+
18+
jobs:
19+
build:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- uses: actions/checkout@v4
23+
with:
24+
fetch-depth: 0 # for lastUpdated timestamps
25+
- uses: actions/setup-node@v4
26+
with:
27+
node-version: 20
28+
cache: npm
29+
- run: npm ci
30+
- run: npm run docs:build
31+
- uses: actions/configure-pages@v5
32+
- uses: actions/upload-pages-artifact@v3
33+
with:
34+
path: docs/.vitepress/dist
35+
36+
deploy:
37+
needs: build
38+
runs-on: ubuntu-latest
39+
environment:
40+
name: github-pages
41+
url: ${{ steps.deployment.outputs.page_url }}
42+
steps:
43+
- id: deployment
44+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Node / VitePress
2+
node_modules/
3+
docs/.vitepress/dist/
4+
docs/.vitepress/cache/
5+
*.log
6+
7+
# OS / editor
8+
.DS_Store
9+
Thumbs.db
10+
*.swp
11+
.idea/
12+
.vscode/
13+
14+
# setup.sh backups
15+
*.bak.*

‎.markdownlint-cli2.jsonc‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
{
2+
// Lenient config: we care about real issues, not cosmetic line lengths.
3+
"config": {
4+
"default": true,
5+
"MD013": false, // line length
6+
"MD033": false, // inline HTML (we use <kbd>, <picture>, etc.)
7+
"MD041": false, // first line in file should be a top-level heading (frontmatter)
8+
"MD025": { "front_matter_title": "" }, // frontmatter title + one H1 is intentional
9+
"MD028": false, // blank lines inside GitHub-style alert blockquotes are fine
10+
"MD024": { "siblings_only": true }, // duplicate headings allowed across sections
11+
"MD036": false, // emphasis used as heading
12+
"MD026": false, // trailing punctuation in heading
13+
"MD007": { "indent": 2 },
14+
"MD029": false, // ordered list prefix
15+
"MD046": false, // code block style
16+
"MD034": false, // bare URLs are fine in "Source:" lines
17+
"MD040": false // prompt examples are plain text, not code
18+
},
19+
"globs": ["docs/**/*.md", "*.md", "assets/**/*.md"],
20+
"ignores": ["node_modules", "docs/.vitepress/dist", "**/CHANGELOG.md"]
21+
}

‎CHANGELOG.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Changelog
2+
3+
All notable changes to this guide are documented here. The format is based on
4+
[Keep a Changelog](https://keepachangelog.com/), and the project content tracks
5+
Claude Code releases.
6+
7+
## [Unreleased]
8+
9+
### Added
10+
- Full English rewrite as a Markdown-native, beginner→expert reference.
11+
- Diátaxis structure: `getting-started/` (tutorials), `guides/` (how-to),
12+
`reference/` (one file per feature), `explanation/` (mental models),
13+
`environment/` (terminal + bootstrap).
14+
- Copy-paste **asset library**: `CLAUDE.md` templates, slash commands, hooks,
15+
settings examples, and shareable skills.
16+
- **Learning path** with a diagnostic that routes you to the right starting point.
17+
- **Cheatsheet** — a single-page, Cmd-F-friendly reference.
18+
- **VitePress** documentation site generated from the same Markdown, with Mermaid
19+
diagrams and full-text search.
20+
- One-command `setup.sh` bootstrap (Ghostty + Claude Code) with a 32-assertion test
21+
suite, plus cost / rate-limit monitoring guidance.
22+
- Trust scaffolding: LICENSE, CONTRIBUTING, Code of Conduct, issue/PR templates, CI.
23+
24+
### Changed
25+
- Translated the entire guide and the `setup.sh` bootstrap to professional English.
26+
27+
### Removed
28+
- The legacy Romanian `claude-code-ghid.html` / `.pdf` (content extracted into the
29+
new English docs).
30+
31+
[Unreleased]: https://github.com/bogdanmatasaru/claude-code-guide

0 commit comments

Comments
 (0)