Merge pull request #97 from braboj/fix/headings-readability

Improve heading structure and readability

Author: braboj

assets/archive/git-object-model-v2.png

@@ -4,14 +4,21 @@ section: "appendix"
 order: 8
 ---
 
-## Overview
+## 1. Overview
 
 This appendix contains reference material that supports the tutorial
 chapters — merge strategies, Git clients, external resources, and
 notes. For step-by-step recipes, see the [Playbook](../playbook/).
 For command help, run `git help <command>`.
 
-## Merge Strategies
+In this chapter you will learn:
+
+- Merge strategies — when Git uses each strategy and how to force one
+- SSH key setup — generate keys, configure the agent, and connect to GitHub
+- Git clients — popular graphical tools for each platform
+- References — books, troubleshooting guides, visualizations, and workflow models
+
+## 2. Merge Strategies
 
 Git selects a merge strategy automatically. You can force one with
 `git merge -s <strategy>`.
@@ -29,7 +36,7 @@ Git selects a merge strategy automatically. You can force one with
 > The option resolves individual conflicts by preferring the current
 > branch but still includes non-conflicting changes.
 
-## SSH Key Setup
+## 3. SSH Key Setup
 
 SSH lets you authenticate with remotes without entering a password
 each time. This is the recommended method for frequent use.
@@ -76,7 +83,7 @@ Hi username! You've successfully authenticated...
 $ git remote set-url origin git@github.com:user/repo.git
 ```
 
-## Git Clients
+## 4. Git Clients
 
 | Client | Platform | Notes |
 |--------|----------|-------|
@@ -86,7 +93,7 @@ $ git remote set-url origin git@github.com:user/repo.git
 | [TortoiseGit](https://tortoisegit.org/) | Windows | Shell integration |
 | [Git Extensions](https://gitextensions.github.io/) | Windows | Lightweight, open source |
 
-## References
+## 5. References
 
 ### Books and tutorials
 
@@ -111,7 +118,7 @@ $ git remote set-url origin git@github.com:user/repo.git
 - [Trunk-Based Development](https://www.toptal.com/software/trunk-based-development-git-flow) — comparison with Git Flow
 - [OneFlow](https://www.endoflineblog.com/oneflow-a-git-branching-model-and-workflow) — simplified alternative to Git Flow
 
-## Notes
+## 6. Notes
 
 1. Git cannot commit empty folders. Add a placeholder file (e.g.
    `.gitkeep`) if you need an empty directory tracked.

assets/drawio/git-object-model.drawio

@@ -4,15 +4,24 @@ section: "branching-and-merging"
 order: 3
 ---
 
-## Overview
+## 1. Overview
 
 This chapter covers the daily workflow of parallel development in Git —
 creating branches, combining work through merging and rebasing,
 resolving conflicts, and temporarily shelving changes with the stash.
 These are the operations you will use most often when working with others
 or managing multiple features at once.
 
-## Branching
+In this chapter you will learn:
+
+- How to create, rename, and delete branches
+- Merge strategies: fast-forward, 3-way, no-fast-forward, and squash
+- How rebasing produces a linear history
+- How to cherry-pick individual commits between branches
+- How to resolve merge and rebase conflicts
+- How to stash and restore work in progress
+
+## 2. Branching
 
 As covered in [Building Blocks](../building-blocks/), a branch is a
 pointer to a specific commit. Creating a branch is a "cheap" operation —
@@ -98,7 +107,7 @@ To rename a different branch:
 git branch -m <oldName> <newName>
 ```
 
-## Merging
+## 3. Merging
 
 Merging is a process of combining changes from different branches. Usually
 this is required when people are working in parallel on the same source code.
@@ -165,7 +174,7 @@ afterward.
 Squash merges are useful when a feature branch contains many small or
 messy commits and you want a clean, single-commit result on `main`.
 
-## Rebasing
+## 4. Rebasing
 
 Rebasing is an **alternative to merging**. Instead of creating a merge
 commit, it replays your branch's commits on top of another branch,
@@ -195,7 +204,7 @@ The table below summarizes when to use each approach:
 | Safe on shared branches? | Yes | No — rewrites commit hashes |
 | When to use | Combining finished work | Cleaning up local history before merging |
 
-## Cherry-picking
+## 5. Cherry-picking
 
 Cherry-picking copies a single commit from one branch onto another. Unlike
 merging, it does not bring over the full branch history — only the changes
@@ -223,7 +232,7 @@ Common use cases:
 > later merged, Git usually handles this cleanly, but it can produce
 > confusing history. Prefer merging when possible.
 
-## Conflicts
+## 6. Conflicts
 
 A merge conflict occurs when Git cannot automatically combine changes from
 two branches. This happens when both branches modify the same lines in the
@@ -404,7 +413,7 @@ git commit -m "Merge main into feature, combine greeting changes"
 
 The conflict is resolved and the repository history records the merge.
 
-## Stashing
+## 7. Stashing
 
 The stash allows changes to be saved without committing broken or untested
 code before switching to another branch.

assets/images/git-object-model.png

@@ -4,14 +4,22 @@ section: "building-blocks"
 order: 2
 ---
 
-## Overview
+## 1. Overview
 
 This chapter covers the internal building blocks of Git — how repositories
 are structured, how Git stores data as objects, and how references connect
 everything together. Understanding these internals will help you make sense
 of what Git commands actually do under the hood.
 
-## Repository
+In this chapter you will learn:
+
+- The difference between bare and non-bare repositories
+- How Git's object model stores files, directories, commits, and tags
+- How the index (staging area) prepares changes for commits
+- How references and HEAD connect names to commits
+- How to navigate and rewrite history with reset
+
+## 2. Repository
 
 A repository is a database that stores the complete history of a project
 as a series of snapshots (commits). Every commit records exactly what
@@ -83,7 +91,7 @@ The `.git` folder contains the same structure as a bare repository.
 The difference is that a non-bare repository also has a working tree
 next to it — the place where you do your actual work.
 
-## Object Model
+## 3. Object Model
 
 Every time you commit, Git takes a **snapshot** — a complete picture of
 every tracked file in your project at that moment. A snapshot is not a
@@ -318,7 +326,7 @@ Add project documentation
 | `-s` | Object size in bytes | `231` |
 | `-p` | Object content (pretty-print) | Depends on the type — see examples above |
 
-## Index (Staging Area)
+## 4. Index (Staging Area)
 
 The index is the area between your working tree and the repository. It
 holds a list of changes that are ready to be included in the next
@@ -388,7 +396,7 @@ and execute (1).
 So `100644` means "regular file, readable and writable by the owner"
 and `100755` means "executable file, runnable by anyone."
 
-## References
+## 5. References
 
 Every object in Git is identified by a 40-character hash, but humans
 don't think in hashes — we think in names like `main`, `feature/login`,
@@ -478,7 +486,7 @@ $ cat .git/refs/remotes/origin/main
 If this hash matches your local `refs/heads/main`, the branches are in
 sync. If they differ, one side has commits the other doesn't.
 
-## History Navigation
+## 6. History Navigation
 
 Navigating history in Git means moving two things: **HEAD** (your
 current position) and **branch tips** (where each branch points).

astro-site/src/content/docs/appendix.md

@@ -4,14 +4,25 @@ section: "expert-topics"
 order: 6
 ---
 
-## Overview
+## 1. Overview
 
 This chapter covers power-user topics — configuration layers, revision
 selectors, pathspec and refspec syntax, interactive rebase, bisect,
 hooks, and garbage collection. These concepts are not needed for daily
 Git use but become essential as projects and teams grow.
 
-## Configuration
+In this chapter you will learn:
+
+- How Git's layered configuration system works and how to customize it
+- How to use revision selectors (tilde, caret, ranges) to navigate commit history
+- How pathspec patterns filter files in Git commands
+- How refspec syntax maps local and remote references
+- How to rewrite commit history with interactive rebase
+- How to find the commit that introduced a bug using bisect
+- How to automate tasks with Git hooks
+- How garbage collection and the reflog protect and clean up orphaned commits
+
+## 2. Configuration
 
 ![Configuration Model](../assets/images/git-configuration-model.png)
 
@@ -69,7 +80,7 @@ $ git config --list --show-scope          # all settings with scope level
 When the same parameter is set at multiple levels, the most specific
 wins: local overrides global, global overrides system.
 
-## Revision Selectors
+## 3. Revision Selectors
 
 Revision selectors let you reference specific commits without knowing
 their hashes. They are used with `git log`, `git diff`, `git show`,
@@ -137,7 +148,7 @@ $ git show "HEAD@{yesterday}"      # where HEAD was yesterday
 $ git show "main@{2.weeks.ago}"    # where main was 2 weeks ago
 ```
 
-## Pathspec
+## 4. Pathspec
 
 A pathspec is a pattern that matches files or directories. Most Git
 commands that work with files accept pathspecs.
@@ -175,7 +186,7 @@ Signatures control the matching behavior. Syntax: `:(signature)pattern`
 
 Signatures can be combined: `':(top,icase)*.mp?'`
 
-## Refspec
+## 5. Refspec
 
 When you run `git fetch` or `git push`, Git needs to know which
 references on one side map to which references on the other. A refspec
@@ -216,7 +227,7 @@ $ git push origin :refs/heads/feature         # delete remote branch (empty src)
 $ git fetch origin main:refs/remotes/origin/main  # fetch one branch explicitly
 ```
 
-## Interactive Rebase
+## 6. Interactive Rebase
 
 Interactive rebase lets you edit, reorder, squash, or drop commits
 before sharing them. It rewrites history — use it only on local
@@ -261,7 +272,7 @@ Result: one commit with a combined message replacing all three.
 > **Warning:** Interactive rebase rewrites commit hashes. Never rebase
 > commits that have already been pushed to a shared branch.
 
-## Git Bisect
+## 7. Git Bisect
 
 `git bisect` performs a binary search through commit history to find
 the commit that introduced a bug. Instead of checking every commit,
@@ -299,7 +310,7 @@ $ git bisect run ./test.sh
 Git runs the script at each midpoint automatically and reports the
 first bad commit when done.
 
-## Hooks
+## 8. Hooks
 
 Hooks are scripts that Git runs automatically before or after specific
 events. They live in `.git/hooks/` and are not tracked by Git (each
@@ -352,7 +363,7 @@ $ git push --no-verify             # skip pre-push hook
 
 Use sparingly — hooks exist for a reason.
 
-## Garbage Collection
+## 9. Garbage Collection
 
 When you reset, rebase, or delete a branch, the commits that were on it
 don't disappear immediately. They become **orphaned** — they still exist

astro-site/src/content/docs/branching-and-merging.md

@@ -6,6 +6,8 @@ order: 9
 
 ## Glossary
 
+A reference of key Git terms used throughout this tutorial, with links to the chapter where each concept is covered.
+
 | Term | Definition | Chapter |
 |------|-----------|---------|
 | Annotated tag | A tag object with author, date, and message — stored in `.git/objects/` | [2](../building-blocks/) |

astro-site/src/content/docs/building-blocks.md

@@ -4,7 +4,7 @@ section: "introduction"
 order: 1
 ---
 
-## Overview
+## 1. Overview
 
 Git is a version control system. It keeps a complete history of every change
 you make to your files, so you can go back to any earlier version at any time.
@@ -18,7 +18,15 @@ Why use version control?
 - Multiple people can work on the same project without overwriting each other
 - You can experiment on a separate branch and merge it back when it works
 
-## Features
+In this chapter you will learn:
+
+- What Git is and why version control matters
+- How to install Git on your platform
+- Where to host your repositories
+- How Git moves changes through workspace, index, and repository
+- The most common commands in daily operations
+
+## 2. Features
 
 Git is **open source** and free to use. Unlike older systems such as
 Subversion (SVN) where all history lives on a central server, Git is
@@ -31,34 +39,26 @@ share with others when you are ready.
 - **Branching** — work on separate ideas at the same time without interfering with each other
 - **Fast** — most operations happen on your own machine, with no waiting for a server
 
-## Installation
-
-Download Git from the official website: https://git-scm.com/downloads
-
-After installation, open a terminal and verify with:
-
-```text
-$ git --version
-```
+## 3. Installation
 
 ### Windows
 
-1. Download the installer from the link above
+1. Download the installer from https://git-scm.com/downloads
 2. Run the installer with the default options
-3. Open PowerShell and verify
+3. Open PowerShell and run `git --version`
 
 ### macOS
 
 **Option A — Xcode Command Line Tools (no extra software needed):**
 
-1. Open Terminal and type `git --version`
+1. Open Terminal and run `git --version`
 2. If Git is not installed, macOS will prompt you to install the Command Line Tools — follow the dialog
 
 **Option B — Homebrew:**
 
-```text
-$ brew install git
-```
+1. Install [Homebrew](https://brew.sh/) if you do not have it
+2. Run `brew install git`
+3. Run `git --version`
 
 ### Linux
 
@@ -73,7 +73,9 @@ $ brew install git
 | FreeBSD         | `pkg install git`                    |
 | Nix/NixOS       | `nix-env -i git`                     |
 
-## Hosting
+After installing, run `git --version` to verify.
+
+## 4. Hosting
 
 A Git hosting service stores your repositories online so you can access them
 from anywhere and collaborate with others. You do not need your own server —
@@ -93,7 +95,7 @@ The table below compares the free tiers of each provider.
 
 ![Git Hosting Comparison](../assets/images/git-hosting.png)
 
-## How Git Works
+## 5. How Git Works
 
 Git moves your changes through three locations before they are shared
 with others. The diagram below shows these locations and the commands
@@ -124,7 +126,7 @@ both as equals — there is no single authoritative copy. (The word "master"
 here means primary, not the branch name `master` — Git uses `main` as the
 default branch name.)
 
-### How a commit works
+### How a Commit Works
 
 When you run `git commit`, Git takes a snapshot of everything in the index
 and stores it permanently in the repository. Each snapshot is called a
@@ -147,7 +149,7 @@ In the diagram above, `D` is the latest commit. It points back to `C`,
 which points to `B`, and so on. Git follows these links to reconstruct the
 full history.
 
-## Command Overview
+## 6. Command Overview
 
 ![Command Overview](../assets/images/git-command-overview.png)