Improve docs

README.md

@@ -23,7 +23,7 @@ With RenderCV, you can:
 
 - Version-control your CV — it's just text.
 - Focus on content — don't wory about the formatting.
-- Get perfect typography — kerning, spacing, hierarchy, all handled. No design skills required.
+- Get perfect typography — pixel-perfect alignment and spacing, handled for you.
 
 A YAML file like this:
 

docs/developer_guide/documentation.md

@@ -18,15 +18,15 @@ We want documentation at `docs.rendercv.com`, a proper website with navigation,
 
 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`.
+**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`.
 
-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.
+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.
 
 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)
 
-`mkdocs.yaml` controls how `mkdocs` builds the website:
+`mkdocs.yaml` controls how MkDocs builds the website:
 
 - **Site metadata:** name, description, repository
 - **Theme:** Material theme with colors and features
@@ -35,7 +35,7 @@ Once a pattern becomes that well defined, entire ecosystems form around it. Just
 
 ## Plugins
 
-`mkdocs` plugins extend functionality beyond Markdown → HTML conversion.
+MkDocs plugins extend functionality beyond Markdown → HTML conversion.
 
 ### [`mkdocstrings`](https://github.com/mkdocstrings/mkdocstrings): API Reference
 

docs/developer_guide/github_workflows.md

@@ -72,7 +72,6 @@ RenderCV has 5 workflows. Each handles a specific automation task.
 **When it runs:**
 
 - Manually (via GitHub UI)
-- When called by the release workflow
 
 **What it does:**
 
@@ -110,12 +109,11 @@ These are single-file executables that users can download and run without instal
 This is the complete release pipeline. It orchestrates everything:
 
 1. **Run tests:** Calls `test.yaml` to ensure everything works
-2. **Update files:** Calls `update-files.yaml` to regenerate schema/examples
+2. **Build package:** Installs `uv`, builds Python wheel and source distribution using `uv build`
-3. **Build package:** Installs `uv`, builds Python wheel and source distribution using `uv build`
+3. **Create executables:** Calls `create-executables.yaml` for all platforms
-4. **Create executables:** Calls `create-executables.yaml` for all platforms
+4. **Add assets to GitHub release:** Downloads and adds executables and wheel to the release
-5. **Create GitHub release:** Downloads and uploads executables and wheel to the release
+5. **Publish to PyPI:** Downloads and uploads package so users can `pip install rendercv`
-6. **Publish to PyPI:** Downloads and uploads package so users can `pip install rendercv`
+6. **Publish Docker image:** Builds and pushes Docker image to GitHub Container Registry
-7. **Publish Docker image:** Builds and pushes Docker image to GitHub Container Registry
 
 ## Learn More
 

docs/developer_guide/json_schema.md

@@ -69,9 +69,9 @@ This schema says:
 
 **Why does JSON Schema exist?**
 
-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:
+Because JSON and YAML files are **everywhere**: configuration files, API requests/responses, CI/CD workflows, application settings, data files.
 
-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**.
+You could write documentation on how to write those JSON/YAML files: "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.
 

docs/developer_guide/understanding_rendercv.md

@@ -22,9 +22,9 @@ Read a YAML file, generate a Typst file, compile it to PDF. Everything else is b
 
 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.
+Typst is a computer language. Just like Python, HTML, or JavaScript. You write Typst code to describe what a page should look like and what content it contains. You save it as a text file (`.typ` extension). When you compile a `*.typ` file with Typst compiler, you get a PDF.
 
-RenderCV generates a Typst file from your YAML and runs Typst to get your CV as a PDF.
+RenderCV generates a Typst file from your YAML and compiles it with the Typst compiler to produce your CV as a PDF.
 
 ## Step 1: Reading the YAML File
 

docs/docs_templating.py

@@ -99,11 +99,15 @@ def define_env(env):
     ]
 
     # Available themes strings (put available themes between ``)
-    themes = [f"`{theme}`" for theme in available_themes]
+    themes = [f"`{theme}`" if theme != "classic" else "`classic` (default)" for theme in available_themes]
     env.variables["available_themes"] = ", ".join(themes)
+    env.variables["theme_count"] = len(available_themes)
 
     # Available locales string
-    locales = [f"`{locale}`" for locale in available_locales]
+    locales = [
+        f"`{locale}`" if locale != "english" else "`english` (default)"
+        for locale in available_locales
+    ]
     env.variables["available_locales"] = ", ".join(locales)
 
     # Available social networks strings (put available social networks between ``)

docs/index.md

@@ -22,7 +22,7 @@ With RenderCV, you can:
 
 - Version-control your CV — it's just text.
 - Focus on content — don't wory about the formatting.
-- Get perfect typography — kerning, spacing, hierarchy, all handled. No design skills required.
+- Get perfect typography — pixel-perfect alignment and spacing, handled for you.
 
 A YAML file like this:
 

docs/user_guide/yaml_input_structure/cv.md

@@ -218,16 +218,17 @@ highlights:
   - Developed [open-source tool](https://github.com/example) with *500+ stars*
 ```
 
-| Syntax        | Result    |
+- `**text**` → **bold**
-| ------------- | --------- |
+- `*text*` → *italic*
-| `**text**`    | **bold**  |
+- `[text](url)` → hyperlink
-| `*text*`      | *italic*  |
+- `` `code` `` → `code`
-| `[text](url)` | hyperlink |
-| `` `code` ``  | `code`    |
 
 ### Using Typst
 
-All text fields support Typst math and commands.
+All text fields support
+
+- Typst math (surround with `$$` like `$$f(x) = x^2$$`)
+- Typst commands (like `#emph[emphasized]`).
 
 ```yaml
 highlights:

docs/user_guide/yaml_input_structure/design.md

@@ -2,7 +2,7 @@
 
 The `design` field controls every visual aspect of your CV: colors, fonts, spacing, and layout.
 
-## Available Themes
+## Built-in Themes
 
 RenderCV includes << theme_count >> built-in themes. To use one, simply specify the theme:
 
@@ -11,9 +11,7 @@ design:
   theme: classic
 ```
 
-Available themes: << available_themes >>
+Available themes: << available_themes >>.
-
-## How Themes Work
 
 All themes are identical except for their default values. If you specify a setting explicitly, it overrides the theme's default. This means:
 

docs/user_guide/yaml_input_structure/locale.md

@@ -11,7 +11,7 @@ locale:
   language: german
 ```
 
-Available languages: `english` (default), `french`, `german`, `hindi`, `italian`, `japanese`, `korean`, `mandarin_chinese`, `portuguese`, `russian`, `spanish`, `turkish`.
+Available languages: << available_locales >>.
 
 ## Customizing Locale