Polish docs

docs/developer_guide/dockerfile.md

@@ -10,8 +10,6 @@ Docker lets software carry **its entire working environment** with it: the right
 
 When you run an image, Docker creates a **container**: a live, isolated instance of that environment running on your machine. When you're done, you can delete it without a trace. Your actual system stays untouched.
 
-## Why Docker Is Useful for RenderCV
-
 ## Why Docker for RenderCV?
 
 RenderCV installs easily with `pip install rendercv` if you have Python. Most users don't need Docker.
@@ -24,14 +22,14 @@ But Docker makes sense if you want:
 
 The RenderCV Docker image is a ready-made environment with Python and RenderCV pre-installed. Just run:
 ```bash
-docker run -v "$PWD":/work -w /work ghcr.io/rendercv/rendercv render Your_CV.yaml
+docker run -v "$PWD":/work -w /work ghcr.io/rendercv/rendercv new "Your Name"
 ```
 
 ## How the Image Gets Published
 
 Docker images are stored in **registries**, which are servers that host images so anyone can download and run them. Docker Hub is the most popular, but GitHub has its own called GitHub Container Registry (GHCR).
 
-When you publish a GitHub release, the [`release.yaml` workflow](https://github.com/rendercv/rendercv/blob/main/.github/workflows/release.yaml) automatically builds and publishes the RenderCV image to GHCR at `ghcr.io/rendercv/rendercv`.
+When RenderCV publishes a GitHub release, the [`release.yaml` workflow](https://github.com/rendercv/rendercv/blob/main/.github/workflows/release.yaml) automatically builds and publishes the RenderCV image to GHCR at `ghcr.io/rendercv/rendercv`.
 
 When users run `docker run ghcr.io/rendercv/rendercv`, Docker automatically pulls the image from the registry if it's not already on their machine.
 

docs/developer_guide/documentation.md

@@ -12,21 +12,17 @@ We want documentation at `docs.rendercv.com`, a proper website with navigation,
 
 1. HTML/CSS/JavaScript files
 2. A server hosting those files
-3. A domain pointing to that server
+3. A domain (e.g. `docs.rendercv.com`) pointing to that server
 
-**The problem:** Writing HTML/CSS/JavaScript manually for documentation is impractical. You want to write content in Markdown and have it become a professional website automatically.
+**The problem:** We don't want to develop a web app (writing HTML/CSS/JavaScript). We just want to put some content online.
+
+What if we could write content in Markdown and use some software to automatically generate HTML/CSS/JavaScript files from it? 
 
 **The solution:** [`mkdocs`](https://github.com/mkdocs/mkdocs) with [Material theme](https://github.com/squidfunk/mkdocs-material). You write Markdown in `docs/`, `mkdocs` generates HTML/CSS/JavaScript, and GitHub Pages hosts it at `docs.rendercv.com`.
 
-```mermaid
-flowchart LR
-    A[Markdown in docs/] --> B[MkDocs + Material]
-    B --> C[HTML/CSS/JS files]
-    C --> D[GitHub Pages hosting]
-    D --> E[docs.rendercv.com]
-```
+Tools like `mkdocs` exist because documentation sites follow a stable, well-understood pattern. They aren’t open-ended web applications with unique interfaces or behaviors; they’re a specific kind of website with predictable needs: structured pages, cross-page navigation, search, consistent styling, and readable content.
 
-**This means:** Editing Markdown files in `docs/` updates the website at `docs.rendercv.com`.
+Once a pattern becomes that well defined, entire ecosystems form around it. Just as you reach for Python rather than designing a new programming language, you reach for MkDocs rather than hand-assembling HTML, CSS, and JavaScript files for a documentation site.
 
 ## Configuration: [`mkdocs.yaml`](https://github.com/rendercv/rendercv/blob/main/mkdocs.yaml)
 
@@ -43,15 +39,15 @@ flowchart LR
 
 ### [`mkdocstrings`](https://github.com/mkdocstrings/mkdocstrings): API Reference
 
-Generates API reference from Python docstrings. The entire [API Reference](../api_reference/index.md) section is auto-generated from `src/rendercv/`.
+Generates the API reference from Python docstrings. The entire [API Reference](../api_reference/index.md) section is auto-generated from `src/rendercv/`.
 
 ### [`mkdocs-macros-plugin`](https://mkdocs-macros-plugin.readthedocs.io/): Dynamic Content
 
-Lets you inject code-generated values into Markdown. [`docs/docs_templating.py`](https://github.com/rendercv/rendercv/blob/main/docs/docs_templating.py) runs during build. It imports values directly from RenderCV's code and exposes them as variables. It's heavily used in [YAML Input Structure](../user_guide/yaml_input_structure.md) page.
+Lets you inject code-generated values into Markdown. [`docs/docs_templating.py`](https://github.com/rendercv/rendercv/blob/main/docs/docs_templating.py) runs during the build. It imports values directly from RenderCV's code and exposes them as variables. It's heavily used in [YAML Input Structure: `cv` Field](../user_guide/yaml_input_structure/cv.md) page.
 
 ## Entry Type Figures
 
-The [YAML Input Structure](../user_guide/yaml_input_structure.md) page shows visual examples of each entry type rendered in each theme.
+The [YAML Input Structure: `cv` Field](../user_guide/yaml_input_structure/cv.md) page shows example images of each entry type rendered in each theme.
 
 These are auto-generated PNG images. Run `just update-entry-figures` to regenerate them from [`docs/user_guide/sample_entries.yaml`](https://github.com/rendercv/rendercv/blob/main/docs/user_guide/sample_entries.yaml).
 
@@ -67,7 +63,7 @@ Starts a local server at `http://127.0.0.1:8000` with live reload. Edit Markdown
 just build-docs
 ```
 
-Generates the final website in `site/` directory. Mainly used by GitHub workflows for final deployment (see [GitHub Workflows](github_workflows.md)).
+Generates the final website in the `site/` directory. Mainly used by GitHub workflows for final deployment (see [GitHub Workflows](github_workflows.md)).
 
 ## Deployment
 
@@ -77,7 +73,7 @@ Every push to `main` triggers automatic deployment.
 
 1. **Trigger:** Runs on every push to `main`
 2. **Build step:**
-      - Installs dependencies (`uv`, `just`)
+      - Installs `uv` and `just`
       - Runs `just build-docs` to generate the website
       - Uploads the `site/` directory as an artifact
 3. **Deploy step:**

docs/developer_guide/github_workflows.md

@@ -9,7 +9,7 @@ toc_depth: 3
 Every software project has repetitive tasks that must run consistently:
 
 - **On every update:** Run tests, redeploy documentation
-- **On every release:** Run tests, update `schema.json` and examples, build executables for 4 platforms, build package, upload to PyPI, push Docker image
+- **On every release:** Run tests, update `schema.json` and examples, build executables for 4 platforms, build package, upload to PyPI, publish Docker image
 
 You could do these manually. But manual means:
 
@@ -18,7 +18,7 @@ You could do these manually. But manual means:
 
 **What if you could write down these tasks once, and have them run automatically every time?**
 
-That's what **CI/CD (Continuous Integration/Continuous Deployment)** is. And **GitHub Actions** is GitHub's system for it.
+That's what **CI/CD (Continuous Integration/Continuous Deployment)** is. And **GitHub Actions** is GitHub's platform for it.
 
 ## What are GitHub Actions?
 
@@ -119,5 +119,5 @@ This is the complete release pipeline. It orchestrates everything:
 
 ## Learn More
 
-- [GitHub Actions Documentation](https://docs.github.com/en/actions): Official docs
-- [`.github/workflows/`](https://github.com/rendercv/rendercv/tree/main/.github/workflows): RenderCV's workflow files
+- See [`.github/workflows/`](https://github.com/rendercv/rendercv/tree/main/.github/workflows) for RenderCV's workflow files
+- See [GitHub Actions Documentation](https://docs.github.com/en/actions) for the official documentation.

docs/developer_guide/index.md

@@ -8,7 +8,7 @@ toc_depth: 1
 
 You need two tools to develop RenderCV:
 
-- **[`uv`](https://docs.astral.sh/uv/)**: Package and project manager. RenderCV uses `uv` to manage dependencies. It also handles Python installations, so you don't need to install Python separately.
+- **[`uv`](https://docs.astral.sh/uv/)**: Package and project manager. It also handles Python installations, so you don't need to install Python separately.
 - **[`just`](https://github.com/casey/just)**: Command runner. Development commands are defined in the [`justfile`](https://github.com/rendercv/rendercv/blob/main/justfile), and you need `just` to run them.
 
 Install them by following their official installation guides:
@@ -54,6 +54,7 @@ That's it! You're now ready to start developing RenderCV.
 - `just sync`: Sync all dependencies (including extras and dev groups)
 - `just format`: Format code with black and ruff
 - `just check`: Run all checks (ruff, pyright, pre-commit)
+- `just lock`: Update `uv.lock` file
 
 ### Testing
 

docs/developer_guide/json_schema.md

@@ -6,7 +6,7 @@ toc_depth: 3
 
 ## The Problem
 
-You've encountered this everywhere, even if you didn't realize it was the same problem:
+You may have encountered this before, even if you didn't realize it:
 
 **VS Code settings** (`settings.json`):
 ```json
@@ -30,7 +30,7 @@ VS Code doesn't just "know" what's valid in `settings.json`. GitHub Actions work
 
 **Someone had to tell your editor:** "Here are all the valid fields, their types, and what they mean."
 
-That "someone" is **JSON Schema**.
+That "someone" is [**JSON Schema**](https://json-schema.org).
 
 ## What is JSON Schema?
 
@@ -71,8 +71,6 @@ This schema says:
 
 Because JSON and YAML files are **everywhere**: configuration files, API requests/responses, CI/CD workflows, application settings, data files. They all share the same problem:
 
-**How do you communicate what's valid?**
-
 You could write documentation: "The `name` field is required and must be a string. The `age` field is optional and must be a non-negative integer." But **documentation is for humans to read, not machines**.
 
 JSON Schema is the **same information in machine-readable format** so editors can understand it.
@@ -83,9 +81,7 @@ This is why:
 
 - **Microsoft publishes a JSON Schema for VS Code settings:** your editor fetches it and provides autocomplete
 - **GitHub publishes a JSON Schema for Actions workflows:** that's how you get field suggestions
-- **Thousands of tools do the same:** Kubernetes, Docker, Terraform, ESLint, package.json, tsconfig.json, the list goes on
-
-JSON Schema is **infrastructure for editor tooling**.
+- **Thousands of tools do the same:** Kubernetes, Docker, Terraform, ESLint, `package.json`, `tsconfig.json`, the list goes on
 
 ## RenderCV's JSON Schema
 
@@ -95,17 +91,23 @@ RenderCV has the same problem. Users write their CVs in YAML, and we want them t
 
 ![JSON Schema of RenderCV](../assets/images/json_schema.gif)
 
-That's why [`schema.json`](https://github.com/rendercv/rendercv/blob/main/schema.json) exists in the repository. Same universal problem, same universal solution.
+That's why [`schema.json`](https://github.com/rendercv/rendercv/blob/main/schema.json) exists in the repository.
 
-## How the Schema is Generated
+## How the Schema is Generated?
 
 We don't write `schema.json` by hand. **It's automatically generated from Pydantic models.**
 
 RenderCV's entire data structure is defined using Pydantic models (see [Understanding RenderCV](understanding_rendercv.md) for details). Pydantic has a built-in feature: `model_json_schema()`, which generates JSON Schema from your models.
 
-That's what [`src/rendercv/schema/json_schema_generator.py`](https://github.com/rendercv/rendercv/blob/main/src/rendercv/schema/json_schema_generator.py) does. It calls `model_json_schema()` on our top-level model and writes the result to `schema.json`.
+Whenever data models change, run:
 
-## How Editors Know to Use RenderCV's Schema
+```bash
+just update-schema
+```
+
+This runs [`scripts/update_schema.py`](https://github.com/rendercv/rendercv/blob/main/scripts/update_schema.py), which regenerates `schema.json`.
+
+## How Editors Know to Use RenderCV's Schema?
 
 There are two ways editors discover and use RenderCV's schema:
 
@@ -134,16 +136,6 @@ In SchemaStore, RenderCV's schema is configured to automatically activate for fi
 - And your editor uses SchemaStore (VS Code with YAML extension does)
 - You get autocomplete automatically, no comment needed
 
-## When is the Schema Generated?
-
-During development, whenever data models change, run:
-
-```bash
-just update-schema
-```
-
-This runs [`scripts/update_schema.py`](https://github.com/rendercv/rendercv/blob/main/scripts/update_schema.py), which regenerates `schema.json`.
-
 ## Learn More
 
-- [Pydantic JSON Schema](https://docs.pydantic.dev/latest/concepts/json_schema/): How Pydantic generates schemas from models
+See [Pydantic JSON Schema](https://docs.pydantic.dev/latest/concepts/json_schema/) for how Pydantic generates schemas from models.

docs/developer_guide/project_management.md

@@ -73,7 +73,7 @@ The rest of this guide explains what each file does.
 
 ### [`pyproject.toml`](https://github.com/rendercv/rendercv/blob/main/pyproject.toml)
 
-The project definition file. This is the standard way to configure a Python project.
+The project definition file. This is the [standard way to configure a Python project](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/).
 
 This file defines:
 
@@ -81,7 +81,7 @@ This file defines:
 - Dependencies (what packages RenderCV needs)
 - Entry points (makes `rendercv` a command)
 - Build configuration (how to package RenderCV)
-- Tool settings (ruff, pyright, pytest, etc.)
+- Tool settings (`ruff`, `pyright`, `pytest`, etc.)
 
 Open the file to see the full configuration with detailed comments.
 
@@ -103,16 +103,14 @@ just serve-docs     # Builds and serves documentation locally
 just update-schema  # Regenerates schema.json
 ```
 
-This is why `just sync` works so elegantly. It's a standardized command that does exactly the same thing for everyone.
-
 ### [`scripts/`](https://github.com/rendercv/rendercv/tree/main/scripts)
 
-Python scripts that automate some repetitive tasks.
+Python scripts that automate some repetitive tasks that are not part of RenderCV's functionality.
 
 **Why do we need it?** Some tasks need to be done repeatedly but are too complex for simple shell commands:
 
-- `update_schema.py`: Generate `schema.json` from pydantic models
-- `update_examples.py`: Regenerate all example YAML files and PDFs in `examples/` folder
+- `update_schema.py`: Generate `schema.json` (see [JSON Schema](json_schema.md) for more details) from pydantic models
+- `update_examples.py`: Regenerate all example YAML files and PDFs in [`examples/`](https://github.com/rendercv/rendercv/tree/main/examples) folder
 - `create_executable.py`: Build standalone executable of RenderCV
 
 These scripts are called by `just` commands (`just update-schema`, `just update-examples`, etc.).
@@ -121,17 +119,15 @@ These scripts are called by `just` commands (`just update-schema`, `just update-
 
 Configuration file for [`pre-commit`](https://pre-commit.com/), a tool that runs code quality checks.
 
-**Why do we need it?** Pre-commit's value is **fast CI/CD**. [pre-commit.ci](https://pre-commit.ci/) (free for open-source projects) automatically runs checks on every push and pull request. Forgot to format your code? The workflow fails, making it immediately obvious. Without pre-commit, we'd have to set up our own workflow to run these checks.
-
-Run `just check` locally to check your code before committing. We don't use pre-commit as git hooks (that run before every commit). We prefer manual checks when ready.
+**Why do we need it?** Pre-commit's value is **fast CI/CD**. [pre-commit.ci](https://pre-commit.ci/) (free for open-source projects) automatically checks if the source code has any `ruff` or `pyright` errors on every push and pull request. Forgot to format your code? The workflow fails, making it immediately obvious.
 
 ### [`uv.lock`](https://github.com/rendercv/rendercv/blob/main/uv.lock)
 
-A dependency lock file. This is a record of the exact version of every package RenderCV uses (including dependencies of dependencies).
+A dependency lock file. This is a record of the exact version of every package RenderCV uses (including dependencies of dependencies of dependencies...).
 
 **Why do we need it?** Remember development environment problem? This file solves it. When you run `just sync`, `uv` reads this file and installs the exact same versions everyone else has, not "the latest version", but "the exact version that's known to work". Without this file, developers would get different package versions and environments would drift apart.
 
-**Never edit this manually.** `uv` generates and updates it automatically. **Always commit it to git.** That's how everyone gets identical environments.
+**Never edit this manually.** Use `just lock` to update it. **Always commit it to git.** That's how everyone gets identical environments.
 
 ## Learn More
 

docs/developer_guide/testing.md

@@ -4,7 +4,7 @@ toc_depth: 2
 
 # Testing
 
-Tests check if your code does what it's supposed to do. Every time you change something, you need to verify it still works. Instead of manually checking everything, you write test code once and rerun it automatically.
+Tests check if your code does what it's supposed to do. Every time you change something, you need to verify it still works. Instead of manually checking everything, you can write test code once and rerun it after each change.
 
 Here's a simple example:
 
@@ -28,8 +28,6 @@ All of the tests of RenderCV are written in [`tests/`](https://github.com/render
 
 **How does it work?** When you run `pytest`, it searches for files matching `test_*.py` in the `tests/` directory and executes all functions starting with `test_`.
 
-**Configuration:** `pytest` reads settings from `pyproject.toml` under `[tool.pytest.ini_options]`.
-
 ## Running RenderCV Tests
 
 Whenever you make changes to RenderCV's source code, run the tests to ensure everything still works. If all tests pass, your changes didn't break anything.
@@ -75,5 +73,3 @@ This generates two outputs:
 
 - **Terminal:** Overall coverage percentage
 - **HTML report:** Open `htmlcov/index.html` to see exactly which lines are covered (green) and which aren't (red)
-
-**Configuration:** Coverage settings are in `pyproject.toml` under `[tool.coverage.run]` and `[tool.coverage.report]`.

docs/developer_guide/understanding_rendercv.md

@@ -18,7 +18,13 @@ flowchart LR
 
 Read a YAML file, generate a Typst file, compile it to PDF. Everything else is built on top of this foundation.
 
-Let's understand each step.
+## What is Typst?
+
+Before we dive into the steps, let's understand what [Typst](https://typst.app/) is.
+
+Typst is a computer language. Just like Python, HTML, or JavaScript. You write code in Typst to describe what a page should look like and what content it contains. You save it as a text file (`.typ` extension). When you run Typst code, you get a PDF. That's it. Typst's sole purpose is generating PDFs.
+
+RenderCV generates a Typst file from your YAML and runs Typst to get your CV as a PDF.
 
 ## Step 1: Reading the YAML File
 
@@ -43,8 +49,6 @@ We need to:
 
 ### [`ruamel.yaml`](https://github.com/pycontribs/ruamel-yaml): YAML Parser
 
-First problem: reading YAML files.
-
 Python doesn't have a built-in YAML library. To read YAML files, you need a library. **We use `ruamel.yaml`**, one of the best YAML parsers available.
 
 What does it do? Simple: **converts YAML text into Python dictionaries.**
@@ -306,6 +310,6 @@ Everything else (Markdown support, watch mode, PNG output, HTML export) builds o
 
 ## Learn More
 
-1. [`src/rendercv/cli/render_command/run_rendercv.py`](https://github.com/rendercv/rendercv/blob/main/src/rendercv/cli/render_command/run_rendercv.py): The complete flow
-2. [`src/rendercv/schema/models/rendercv_model.py`](https://github.com/rendercv/rendercv/blob/main/src/rendercv/schema/models/rendercv_model.py): The top-level Pydantic model
-3. [`src/rendercv/renderer/templater/templater.py`](https://github.com/rendercv/rendercv/blob/main/src/rendercv/renderer/templater/templater.py): Template rendering
+- [`src/rendercv/cli/render_command/run_rendercv.py`](https://github.com/rendercv/rendercv/blob/main/src/rendercv/cli/render_command/run_rendercv.py): The complete flow
+- [`src/rendercv/schema/models/rendercv_model.py`](https://github.com/rendercv/rendercv/blob/main/src/rendercv/schema/models/rendercv_model.py): The top-level Pydantic model
+- [`src/rendercv/renderer/templater/templater.py`](https://github.com/rendercv/rendercv/blob/main/src/rendercv/renderer/templater/templater.py): Template rendering