mirror/rendercv
1
0
Fork 0
mirror of https://github.com/rendercv/rendercv.git synced 2025-12-23 13:38:01 -05:00
Code Issues Packages Projects Releases Wiki Activity

Polish docs

Browse Source
This commit is contained in:
Sina Atalay
2025-12-10 15:36:17 +03:00
parent 0facddf0c9
commit 33d15d0f91
23 changed files with 853 additions and 714 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@@ -101,7 +101,7 @@ design:
alignment: justified
date_and_location_column_alignment: right
font_family: Source Sans 3
# ...and more
# ...and much more
```
![Design Options of RenderCV](https://raw.githubusercontent.com/rendercv/rendercv/main/docs/assets/images/design_options.gif)

40
docs/changelog.md
View File

@@ -8,7 +8,7 @@ hide:
All notable changes to this project will be documented in this file.
[Click here to see the unreleased changes.](https://github.com/rendercv/rendercv/compare/v2.3...HEAD)
[Click here to see the unreleased changes.](https://github.com/rendercv/rendercv/compare/v2.4...HEAD)
<!--
### Added
@@ -17,6 +17,42 @@ All notable changes to this project will be documented in this file.
### Removed
-->
## [2.4] - December 10, 2025
> **Full Changelog**: [v2.3...v2.4]
### Added
- A new optional `cv.headline` field has been added to display a position title at the top of the CV ([#442](https://github.com/rendercv/rendercv/issues/442)).
- Built-in locale defaults for 11 languages have been added: French, German, Hindi, Italian, Japanese, Korean, Mandarin Chinese, Portuguese, Russian, Spanish, and Turkish. Users can now use these locales without writing all the translations themselves.
- Nested bullet points are now supported in highlights ([#177](https://github.com/rendercv/rendercv/issues/177)).
- WhatsApp has been added as a social network type ([#319](https://github.com/rendercv/rendercv/issues/319)).
- The `cv.custom_connections` field has been added to allow users to define custom header connections with a placeholder (displayed text), optional URL, and Font Awesome icon name ([#408](https://github.com/rendercv/rendercv/issues/408)).
- Support for multiple email addresses, websites, and phone numbers has been added ([#541](https://github.com/rendercv/rendercv/issues/541)).
- A CLI option to disable the welcome message on render has been added ([#394](https://github.com/rendercv/rendercv/issues/394)).
### Changed
- RenderCV now uses its own [Typst package](https://typst.app/universe/package/rendercv), making Typst templates much clearer and simpler. The package is maintained at [rendercv/rendercv-typst](https://github.com/rendercv/rendercv-typst).
- The [documentation](https://docs.rendercv.com) has been completely rewritten, including the user guide and developer guide.
- The `design` field structure has been completely redesigned for better clarity and organization.
- The `locale` field structure has been completely changed.
- The `rendercv_settings` field has been renamed to `settings`.
- The `rendercv_settings.date` field has been renamed to `settings.current_date`.
### Fixed
- Image paths are now correctly handled when providing a full image path for the photo field ([#361](https://github.com/rendercv/rendercv/issues/361)).
- The less than symbol `<` no longer causes an "unclosed label" error ([#364](https://github.com/rendercv/rendercv/issues/364)).
- Typst commands with parentheses (e.g., `#h(1cm)`) are now properly recognized and not escaped ([#383](https://github.com/rendercv/rendercv/issues/383)).
- `C++` and other strings ending with `++` or special characters are now formatted correctly ([#388](https://github.com/rendercv/rendercv/issues/388), [#446](https://github.com/rendercv/rendercv/issues/446)).
- Rendering issues when modifying `design.entry_types` templates have been fixed ([#413](https://github.com/rendercv/rendercv/issues/413)).
- The `--watch` option now correctly triggers re-rendering when the YAML file changes ([#513](https://github.com/rendercv/rendercv/issues/513)).
- `bold_keywords` are now properly applied to `PublicationEntry` authors ([#516](https://github.com/rendercv/rendercv/issues/516)).
- Calling `rendercv` with invalid arguments now displays help text instead of raising a TypeError ([#526](https://github.com/rendercv/rendercv/issues/526)).
- Page margin parsing issues in v2.3 have been resolved ([#531](https://github.com/rendercv/rendercv/issues/531)).
- Arbitrary keys in entries are now correctly recognized and substituted in templates ([#334](https://github.com/rendercv/rendercv/issues/334), [#376](https://github.com/rendercv/rendercv/issues/376), [#534](https://github.com/rendercv/rendercv/issues/534)).
## [2.3] - October 29, 2025
> **Full Changelog**: [v2.2...v2.3]
@@ -534,6 +570,7 @@ RenderCV has transitioned from using $\LaTeX$ to Typst. RenderCV is now much fas
The first release of RenderCV.
[v2.3...v2.4]: https://github.com/rendercv/rendercv/compare/v2.3...v2.4
[v2.2...v2.3]: https://github.com/rendercv/rendercv/compare/v2.2...v2.3
[v2.1...v2.2]: https://github.com/rendercv/rendercv/compare/v2.1...v2.2
[v2.0...v2.1]: https://github.com/rendercv/rendercv/compare/v2.0...v2.1
@@ -565,6 +602,7 @@ The first release of RenderCV.
[v0.3...v0.4]: https://github.com/rendercv/rendercv/compare/v0.3...v0.4
[v0.2...v0.3]: https://github.com/rendercv/rendercv/compare/v0.2...v0.3
[v0.1...v0.2]: https://github.com/rendercv/rendercv/compare/v0.1...v0.2
[2.4]: https://github.com/rendercv/rendercv/releases/tag/v2.4
[2.3]: https://github.com/rendercv/rendercv/releases/tag/v2.3
[2.2]: https://github.com/rendercv/rendercv/releases/tag/v2.2
[2.1]: https://github.com/rendercv/rendercv/releases/tag/v2.1

6
docs/developer_guide/dockerfile.md
View File

@@ -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.

26
docs/developer_guide/documentation.md
View File

@@ -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:**

8
docs/developer_guide/github_workflows.md
View File

@@ -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.

3
docs/developer_guide/index.md
View File

@@ -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

36
docs/developer_guide/json_schema.md
View File

@@ -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.

20
docs/developer_guide/project_management.md
View File

@@ -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

6
docs/developer_guide/testing.md
View File

@@ -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]`.

16
docs/developer_guide/understanding_rendercv.md
View File

@@ -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

2
docs/docs_templating.py
View File

@@ -84,7 +84,7 @@ def define_env(env):
"yaml": dictionary_to_yaml(entry),
"figures": [
{
"path": f"../assets/images/{theme}/{entry_name}.png",
"path": f"../../assets/images/{theme}/{entry_name}.png",
"alt_text": f"{proper_entry_name} in {theme}",
"theme": theme,
}

2
docs/index.md
View File

@@ -100,7 +100,7 @@ design:
alignment: justified
date_and_location_column_alignment: right
font_family: Source Sans 3
# ...and more
# ...and much more
```
![Design Options of RenderCV](./assets/images/design_options.gif)

91
docs/user_guide/cli.md
View File

@@ -1,91 +0,0 @@
---
toc_depth: 1
---
# CLI Reference
## `rendercv`
Show version:
```bash
rendercv --version
```
Show help:
```bash
rendercv --help
```
## `rendercv new`
Create a new CV YAML input file
```bash
rendercv new "John Doe"
```
### Options
| Option | Description |
| ----------------------------- | ---------------------------------------------------------------- |
| `--theme THEME` | Use a built-in theme: << available_themes >>. Default: `classic` |
| `--locale LOCALE` | Use a locale: << available_locales >>. Default: `english` |
| `--create-typst-templates` | Generate Typst template files for advanced customization |
| `--create-markdown-templates` | Generate Markdown template files for advanced customization |
## `rendercv render`
Render a CV from a YAML file.
```bash
rendercv render John_Doe_CV.yaml
```
### Options
All output paths are relative to the input file.
| Option | Short | Description |
| -------------------------- | --------- | -------------------------------------------------------- |
| `--watch` | `-w` | Re-render automatically when the YAML file changes |
| `--quiet` | `-q` | Suppress all output messages |
| `--design FILE` | `-d` | Load `design` field from a separate YAML file |
| `--locale-catalog FILE` | `-lc` | Load `locale` field from a separate YAML file |
| `--settings FILE` | `-s` | Load `rendercv_settings` field from a separate YAML file |
| `--pdf-path PATH` | `-pdf` | Custom path for PDF output |
| `--typst-path PATH` | `-typ` | Custom path for Typst source output |
| `--markdown-path PATH` | `-md` | Custom path for Markdown output |
| `--html-path PATH` | `-html` | Custom path for HTML output |
| `--png-path PATH` | `-png` | Custom path for PNG output |
| `--dont-generate-pdf` | `-nopdf` | Skip PDF generation |
| `--dont-generate-typst` | `-notyp` | Skip Typst generation (implies `-nopdf`, `-nopng`) |
| `--dont-generate-markdown` | `-nomd` | Skip Markdown generation (implies `-nohtml`) |
| `--dont-generate-html` | `-nohtml` | Skip HTML generation |
| `--dont-generate-png` | `-nopng` | Skip PNG generation |
### Overriding YAML values
Override any field in the YAML file from the command line:
```bash
rendercv render John_Doe_CV.yaml --cv.phone "+1-555-555-5555"
```
```bash
rendercv render John_Doe_CV.yaml --cv.sections.education.0.institution "MIT"
```
Useful for keeping sensitive information (phone, address) out of version control.
## `rendercv create-theme`
Create a custom theme with Typst templates you can modify.
```bash
rendercv create-theme "mytheme"
```
Creates a `mytheme/` directory in the current folder with all template files.

158
docs/user_guide/cli_reference.md Normal file
View File

@@ -0,0 +1,158 @@
---
toc_depth: 1
---
# CLI Reference
RenderCV provides a command-line interface with three main commands:
- **`rendercv new`** - Generate a sample CV to get started
- **`rendercv render`** - Generate PDF, Markdown, HTML, and PNG from your YAML input
- **`rendercv create-theme`** - Create a custom theme with editable templates
!!! tip "New to command line?"
Commands are typed in your terminal/command prompt. Options starting with `--` modify behavior:
```bash
rendercv new "John Doe" --theme moderncv
```
**You can combine multiple options** in a single command:
```bash
rendercv render CV.yaml --watch --dont-generate-html --dont-generate-png
```
This renders your CV with auto-reload enabled, skipping HTML and PNG generation.
## `rendercv`
Check your installed version:
```bash
rendercv --version
```
Get help anytime:
```bash
rendercv --help
```
## `rendercv new`
Generate a sample CV file to start editing.
**Basic usage:**
```bash
rendercv new "John Doe"
```
This creates `John_Doe_CV.yaml` in your current folder.
**Choose a different theme:**
```bash
rendercv new "John Doe" --theme moderncv
```
Available themes: << available_themes >>
**Use a different language:**
```bash
rendercv new "John Doe" --locale french
```
Available locales: << available_locales >>
**For advanced users - generate editable templates:**
```bash
rendercv new "John Doe" --create-typst-templates
```
This creates template files you can customize for complete design control. See [Override Default Templates](how_to/override_default_templates.md) for details.
## `rendercv render`
Generate your CV outputs (PDF, Markdown, HTML, PNG) from a YAML file.
**Basic usage:**
```bash
rendercv render John_Doe_CV.yaml
```
This creates a `rendercv_output` folder with all formats.
### Common Scenarios
**Auto-reload while editing:**
```bash
rendercv render John_Doe_CV.yaml --watch
```
The CV regenerates automatically whenever you save changes. Great for live preview!
**Only generate PDF:**
```bash
rendercv render John_Doe_CV.yaml --dont-generate-markdown --dont-generate-html --dont-generate-png
```
Or use the short form:
```bash
rendercv render John_Doe_CV.yaml -nomd -nohtml -nopng
```
**Custom output location:**
```bash
rendercv render John_Doe_CV.yaml --pdf-path ~/Desktop/MyCV.pdf
```
### All Options
| Option | Short | What it does |
| -------------------------- | --------- | -------------------------------- |
| `--watch` | `-w` | Re-render when file changes |
| `--quiet` | `-q` | Hide all messages |
| `--design FILE` | `-d` | Load design from separate file |
| `--locale-catalog FILE` | `-lc` | Load locale from separate file |
| `--settings FILE` | `-s` | Load settings from separate file |
| `--pdf-path PATH` | `-pdf` | Custom PDF location |
| `--typst-path PATH` | `-typ` | Custom Typst location |
| `--markdown-path PATH` | `-md` | Custom Markdown location |
| `--html-path PATH` | `-html` | Custom HTML location |
| `--png-path PATH` | `-png` | Custom PNG location |
| `--dont-generate-pdf` | `-nopdf` | Skip PDF generation |
| `--dont-generate-typst` | `-notyp` | Skip Typst generation |
| `--dont-generate-markdown` | `-nomd` | Skip Markdown generation |
| `--dont-generate-html` | `-nohtml` | Skip HTML generation |
| `--dont-generate-png` | `-nopng` | Skip PNG generation |
**Override any YAML value:**
Use dot notation to change specific fields. This overrides values in the YAML without editing the file.
```bash
rendercv render CV.yaml --cv.phone "+1-555-555-5555"
rendercv render CV.yaml --cv.sections.education.0.institution "MIT"
rendercv render CV.yaml --design.theme "moderncv"
```
## `rendercv create-theme`
Create your own theme with full control over the design.
**Basic usage:**
```bash
rendercv create-theme "mytheme"
```
This creates a `mytheme/` folder with template files you can edit. See [Override Default Templates](how_to/override_default_templates.md) for details.

4
docs/user_guide/how_to/override_default_templates.md
View File

@@ -13,8 +13,8 @@ Use template overriding when you need to:
For simpler customizations, try these first:
- [`design`](../yaml_input_structure.md#design) for colors, fonts, spacing
- [`design.templates`](arbitrary_keys_in_entries.md) for changing entry text layout
- [`design`](../yaml_input_structure/design.md) for colors, fonts, spacing
- [`design.templates`](../yaml_input_structure/design.md) for changing entry text layout
## Two Methods

6
docs/user_guide/index.md
View File

@@ -40,9 +40,9 @@
rendercv new "Your Name"
```
This creates a YAML input file called `Your_Name_CV.yaml`. This file contains the content, design options, translations and settings for RenderCV. See [YAML Input Structure](yaml_input_structure.md) for the full reference.
This creates a YAML input file called `Your_Name_CV.yaml`. This file contains the content, design options, translations and settings for RenderCV. See [YAML Input Structure](yaml_input_structure/index.md) for the full reference.
See the [CLI Reference](cli.md#rendercv-new) for the complete list of options available for the `new` command.
See the [CLI Reference](cli_reference.md#rendercv-new) for the complete list of options available for the `new` command.
!!! tip
To get started with another language or theme, you can use the `--locale` and `--theme` options:
@@ -66,7 +66,7 @@
- `John_Doe_CV.md`: Your CV as Markdown
- `John_Doe_CV.html`: Your CV as HTML (generated from the Markdown)
See the [CLI Reference](cli.md#rendercv-render) for the complete list of options available for the `render` command.
See the [CLI Reference](cli_reference.md#rendercv-render) for the complete list of options available for the `render` command.
!!! tip
To re-render automatically whenever you save changes, use the `--watch` option:

543
docs/user_guide/yaml_input_structure.md
View File

@@ -1,543 +0,0 @@
# The YAML Input File
RenderCV uses a single YAML file to generate your CV. This file has four top-level fields:
```yaml title="Your_Name_CV.yaml"
cv:
...
# Your content (name, sections, entries)
...
design:
...
# Visual styling (theme, colors, fonts, spacing)
...
locale:
...
# Language strings (month names, "present", etc.)
...
settings:
...
# RenderCV behavior (current date, bold keywords)
...
```
Only `cv` is required. The others have sensible defaults.
!!! Tip
To maximize your productivity while editing the input YAML file, set up RenderCV's JSON Schema in your IDE. It will validate your inputs on the fly and give auto-complete suggestions.
=== "Visual Studio Code"
1. Install the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml).
2. Name your file ending with `_CV.yaml`. The schema activates automatically.
3. Press `Ctrl + Space` for suggestions.
=== "Other Editors"
1. Add this line at the top of your file:
```yaml
# yaml-language-server: $schema=https://github.com/rendercv/rendercv/blob/main/schema.json?raw=true
```
2. Press `Ctrl + Space` for suggestions (if your editor supports JSON Schema).
## The `cv` Field
### Header Information
The `cv` field begins with your personal information. All fields are optional. RenderCV adapts to whatever you provide.
```yaml
cv:
name: John Doe
headline: Machine Learning Engineer
location: San Francisco, CA
email: john@example.com # (1)!
phone: +14155551234 # (2)!
website: https://johndoe.dev # (3)!
photo: photo.jpg
social_networks:
- network: LinkedIn # (4)!
username: johndoe
- network: GitHub
username: johndoe
custom_connections:
- placeholder: Book a call # (5)!
url: https://cal.com/johndoe
fontawesome_icon: calendar-days
```
1. Multiple emails can be provided as a list.
2. Multiple phone numbers can be provided as a list.
3. Multiple websites can be provided as a list.
4. << available_social_networks >>
5. Custom connections let you add any extra link (or plain text if `url` is omitted) with your own display text (`placeholder`) and a Font Awesome icon name (e.g., `calendar-days`, `envelope`).
### Sections
The `sections` field holds the main content of your CV. It's a dictionary where:
- **Keys** are section titles (displayed as headings). Section titles can be anything.
- **Values** are lists of entries
```yaml
cv:
name: John Doe
sections:
summary:
- Software engineer with 10 years of experience in distributed systems.
experience:
- company: Acme Corp
position: Senior Engineer
start_date: 2020-01
end_date: present
highlights:
- Led migration to microservices architecture
- Reduced deployment time by 80%
education:
- institution: MIT
area: Computer Science
degree: BS
start_date: 2012-09
end_date: 2016-05
skills:
- label: Languages
details: Python, Go, Rust, TypeScript
- label: Infrastructure
details: Kubernetes, Terraform, AWS
```
!!! info "Section names don't dictate entry types"
**Any of the << entry_count >> entry types can be used in any section.** The section name is just a title. RenderCV doesn't enforce which entry type you use.
For example, an `experience` section could use `NormalEntry` instead of `ExperienceEntry`:
```yaml
sections:
experience: # Using NormalEntry, not ExperienceEntry
- name: Acme Corp — Senior Engineer
start_date: 2020-01
end_date: present
highlights:
- Led migration to microservices architecture
```
Or even `BulletEntry` for a minimal approach:
```yaml
sections:
experience:
- bullet: "**Acme Corp** — Senior Engineer (2020–present)"
- bullet: "**StartupXYZ** — Founding Engineer (2018–2020)"
```
Choose the entry type that best fits your content, not the section name.
!!! warning "One entry type per section"
Each section must contain only one type of entry. You cannot mix `ExperienceEntry` and `EducationEntry` in the same section.
## Entry Types
RenderCV provides << entry_count >> entry types:
{$ for entry_name in entry_names $}
<< loop.index >>. << entry_name >>
{$ endfor $}
each designed for different kinds of content.
{$ for entry_name, entry in sample_entries.items() $}
### << entry_name >>
{$ if entry_name == "EducationEntry" $}
For academic credentials.
| Field | Required | Description |
| ------------- | -------- | ---------------------------------------- |
| `institution` | Yes | School or university name |
| `area` | Yes | Field of study |
| `degree` | No | Degree type (BS, MS, PhD, etc.) |
| `date` | No | Custom date string (overrides start/end) |
| `start_date` | No | Start date |
| `end_date` | No | End date (or `present`) |
| `location` | No | Institution location |
| `summary` | No | Brief description |
| `highlights` | No | List of bullet points |
{$ elif entry_name == "ExperienceEntry" $}
For work history and professional roles.
| Field | Required | Description |
| ------------ | -------- | ---------------------------------------- |
| `company` | Yes | Employer name |
| `position` | Yes | Job title |
| `date` | No | Custom date string (overrides start/end) |
| `start_date` | No | Start date |
| `end_date` | No | End date (or `present`) |
| `location` | No | Office location |
| `summary` | No | Role description |
| `highlights` | No | List of accomplishments |
{$ elif entry_name == "PublicationEntry" $}
For papers, articles, and other publications.
| Field | Required | Description |
| --------- | -------- | ------------------------------------------------ |
| `title` | Yes | Publication title |
| `authors` | Yes | List of author names (use `*Name*` for emphasis) |
| `doi` | No | Digital Object Identifier |
| `url` | No | Link to the publication |
| `journal` | No | Journal, conference, or venue name |
| `date` | No | Publication date |
{$ elif entry_name == "NormalEntry" $}
A flexible entry for projects, awards, certifications, or anything else.
| Field | Required | Description |
| ------------ | -------- | ---------------------------------------- |
| `name` | Yes | Entry title |
| `date` | No | Custom date string (overrides start/end) |
| `start_date` | No | Start date |
| `end_date` | No | End date (or `present`) |
| `location` | No | Associated location |
| `summary` | No | Brief description |
| `highlights` | No | List of bullet points |
{$ elif entry_name == "OneLineEntry" $}
For compact key-value pairs, ideal for skills or technical proficiencies.
| Field | Required | Description |
| --------- | -------- | ------------------ |
| `label` | Yes | Category name |
| `details` | Yes | Associated details |
{$ elif entry_name == "BulletEntry" $}
A single bullet point. Use for simple lists.
| Field | Required | Description |
| -------- | -------- | --------------- |
| `bullet` | Yes | The bullet text |
{$ elif entry_name == "NumberedEntry" $}
An automatically numbered entry.
| Field | Required | Description |
| -------- | -------- | ----------------- |
| `number` | Yes | The entry content |
{$ elif entry_name == "ReversedNumberedEntry" $}
A numbered entry that counts down (useful for publication lists where recent items come first).
| Field | Required | Description |
| ----------------- | -------- | ----------------- |
| `reversed_number` | Yes | The entry content |
{$ elif entry_name == "TextEntry" $}
Plain text without structure. Just write a string.
{$ endif $}
```yaml
<< entry["yaml"] >>
```
{$ for figure in entry["figures"] $}
=== "`<< figure["theme"] >>` theme"
![<< figure["alt_text"] >>](<< figure["path"] >>)
{$ endfor $}
{$ endfor $}
### Using Markdown
All text fields support basic Markdown:
```yaml
highlights:
- Increased revenue by **$2M** annually
- Developed [open-source tool](https://github.com/example) with *500+ stars*
```
| Syntax | Result |
| ------------- | --------- |
| `**text**` | **bold** |
| `*text*` | *italic* |
| `[text](url)` | hyperlink |
| `` `code` `` | `code` |
### Using Typst
All text fields support Typst math and commands.
```yaml
highlights:
- Showed that $$f(x) = x^2$$ is a parabola
- "This is an #emph[emphasized] text"
```
### Arbitrary Keys
You can add arbitrary keys to any entry. By default, they're ignored, but you can reference them in custom templates (see `design.templates`). See [Arbitrary Keys in Entries](../user_guide/how_to/arbitrary_keys_in_entries.md) for more information.
```yaml hl_lines="6"
experience:
- company: Startup Inc
position: Founder
start_date: 2020-01
end_date: present
revenue: $5M ARR # Custom field
highlights:
- Built product from zero to profitability
```
## The `design` Field
The `design` field controls the visual appearance of your CV. Start by choosing a theme:
```yaml
design:
theme: classic
```
Available themes: << available_themes >>
Each theme has different default styling, but all options can be customized. The themes share the same underlying template. You can recreate any theme by adjusting the design options.
!!! tip "Use the JSON Schema"
The design options are extensive. Use an editor with JSON Schema support to explore all available options with autocomplete.
Below is a fully specified `design` field showing all available options:
```yaml
design:
theme: classic
page:
size: us-letter # (1)!
top_margin: 0.7in
bottom_margin: 0.7in
left_margin: 0.7in
right_margin: 0.7in
show_footer: true
show_top_note: true
colors:
body: rgb(0, 0, 0)
name: rgb(0, 79, 144)
headline: rgb(0, 79, 144)
connections: rgb(0, 79, 144)
section_titles: rgb(0, 79, 144)
links: rgb(0, 79, 144)
footer: rgb(128, 128, 128)
top_note: rgb(128, 128, 128)
typography:
line_spacing: 0.6em
alignment: justified # (2)!
date_and_location_column_alignment: right
font_family: # (11)!
body: Source Sans 3 # (9)!
name: Source Sans 3
headline: Source Sans 3
connections: Source Sans 3
section_titles: Source Sans 3
font_size:
body: 10pt
name: 30pt
headline: 10pt
connections: 10pt
section_titles: 1.4em
small_caps:
name: false
headline: false
connections: false
section_titles: false
bold:
name: true
headline: false
connections: false
section_titles: true
links:
underline: false
show_external_link_icon: false
header:
alignment: center # (3)!
photo_width: 3.5cm
photo_position: left # (8)!
photo_space_left: 0.4cm
photo_space_right: 0.4cm
space_below_name: 0.7cm
space_below_headline: 0.7cm
space_below_connections: 0.7cm
connections:
phone_number_format: national # (7)!
hyperlink: true
show_icons: true
display_urls_instead_of_usernames: false
separator: ''
space_between_connections: 0.5cm
section_titles:
type: with_partial_line # (4)!
line_thickness: 0.5pt
space_above: 0.5cm
space_below: 0.3cm
sections:
allow_page_break: true
space_between_regular_entries: 1.2em
space_between_text_based_entries: 0.3em
show_time_spans_in: # (5)!
- experience
entries:
date_and_location_width: 4.15cm
side_space: 0.2cm
space_between_columns: 0.1cm
allow_page_break: false
short_second_row: true
summary:
space_above: 0cm
space_left: 0cm
highlights:
bullet: • # (6)!
nested_bullet: •
space_left: 0.15cm
space_above: 0cm
space_between_items: 0cm
space_between_bullet_and_text: 0.5em
templates: # (10)!
footer: '*NAME -- PAGE_NUMBER/TOTAL_PAGES*'
top_note: '*LAST_UPDATED CURRENT_DATE*'
single_date: MONTH_ABBREVIATION YEAR
date_range: START_DATE – END_DATE
time_span: HOW_MANY_YEARS YEARS HOW_MANY_MONTHS MONTHS
one_line_entry:
main_column: '**LABEL:** DETAILS'
education_entry:
main_column: |-
**INSTITUTION**, AREA
SUMMARY
HIGHLIGHTS
degree_column: '**DEGREE**'
date_and_location_column: |-
LOCATION
DATE
normal_entry:
main_column: |-
**NAME**
SUMMARY
HIGHLIGHTS
date_and_location_column: |-
LOCATION
DATE
experience_entry:
main_column: |-
**COMPANY**, POSITION
SUMMARY
HIGHLIGHTS
date_and_location_column: |-
LOCATION
DATE
publication_entry:
main_column: |-
**TITLE**
AUTHORS
URL (JOURNAL)
date_and_location_column: DATE
```
1. << available_page_sizes >>
2. << available_body_alignments >>
3. << available_alignments >>
4. << available_section_title_types >>
5. Sections that show duration (e.g., "2 years")
6. << available_bullets >>
7. << available_phone_number_formats >>
8. `left`, `right`
9. << available_font_families >>
10. Advanced: customize entry rendering
11. Font family can be directly specified as a string as well.
## The `locale` Field
The `locale` field lets you customize all language-specific strings. This is how you create a CV in any language.
```yaml
locale:
language: german
last_updated: Zuletzt aktualisiert am
month: Monat
months: Monate
year: Jahr
years: Jahre
present: heute
month_abbreviations:
- Jan
- Feb
- März
- Apr
- Mai
- Juni
- Juli
- Aug
- Sept
- Okt
- Nov
- Dez
month_names:
- Januar
- Februar
- März
- April
- Mai
- Juni
- Juli
- August
- September
- Oktober
- November
- Dezember
```
| Field | Description |
| --------------------- | --------------------------------------- |
| `language` | Language name (for your reference only) |
| `last_updated` | Text before the date in the top note |
| `month` / `months` | Singular/plural for duration display |
| `year` / `years` | Singular/plural for duration display |
| `present` | Text shown when `end_date` is `present` |
| `month_abbreviations` | 12 abbreviated month names (Jan–Dec) |
| `month_names` | 12 full month names |
## The `settings` Field
The `settings` field configures RenderCV's behavior.
```yaml
settings:
current_date: '2025-12-03'
render_command:
design:
locale:
typst_path: rendercv_output/NAME_IN_SNAKE_CASE_CV.typ
pdf_path: rendercv_output/NAME_IN_SNAKE_CASE_CV.pdf
markdown_path: rendercv_output/NAME_IN_SNAKE_CASE_CV.md
html_path: rendercv_output/NAME_IN_SNAKE_CASE_CV.html
png_path: rendercv_output/NAME_IN_SNAKE_CASE_CV.png
dont_generate_markdown: false
dont_generate_html: false
dont_generate_typst: false
dont_generate_pdf: false
dont_generate_png: false
bold_keywords:
- AWS
- Python
```

251
docs/user_guide/yaml_input_structure/cv.md Normal file
View File

@@ -0,0 +1,251 @@
# `cv` Field
## Header Information
The `cv` field begins with your personal information. All fields are optional. RenderCV adapts to whatever you provide.
```yaml
cv:
name: John Doe
headline: Machine Learning Engineer
location: San Francisco, CA
email: john@example.com # (1)!
phone: +14155551234 # (2)!
website: https://johndoe.dev # (3)!
photo: photo.jpg
social_networks:
- network: LinkedIn # (4)!
username: johndoe
- network: GitHub
username: johndoe
custom_connections:
- placeholder: Book a call # (5)!
url: https://cal.com/johndoe
fontawesome_icon: calendar-days
```
1. Multiple emails can be provided as a list.
2. Multiple phone numbers can be provided as a list.
3. Multiple websites can be provided as a list.
4. Available social networks: << available_social_networks >>
5. Custom connections let you add any extra link (or plain text if `url` is omitted) with your own display text (`placeholder`) and a Font Awesome icon name (e.g., `calendar-days`, `envelope`). For the list of available icons, see [fontawesome.com/search](https://fontawesome.com/search).
## Sections
The `sections` field holds the main content of your CV. It's a dictionary where:
- **Keys** are section titles (displayed as headings). Section titles can be anything.
- **Values** are lists of entries
```yaml
cv:
name: John Doe
sections:
summary:
- Software engineer with 10 years of experience in distributed systems.
experience:
- company: Acme Corp
position: Senior Engineer
start_date: 2020-01
end_date: present
highlights:
- Led migration to microservices architecture
- Reduced deployment time by 80%
education:
- institution: MIT
area: Computer Science
degree: BS
start_date: 2012-09
end_date: 2016-05
skills:
- label: Languages
details: Python, Go, Rust, TypeScript
- label: Infrastructure
details: Kubernetes, Terraform, AWS
```
**Section names are just titles.** You can use any of the << entry_count >> entry types in any section. Choose what works best for your content.
For example, `experience` section could use `NormalEntry`:
```yaml
sections:
experience:
- name: Acme Corp — Senior Engineer
start_date: 2020-01
end_date: present
highlights:
- Led migration to microservices architecture
```
Or `BulletEntry` for a minimal style:
```yaml
sections:
experience:
- bullet: "**Acme Corp** — Senior Engineer (2020–present)"
- bullet: "**StartupXYZ** — Founding Engineer (2018–2020)"
```
!!! warning "One entry type per section"
Each section must contain only one type of entry. For example, you cannot mix `ExperienceEntry` and `EducationEntry` in the same section.
## Entry Types
RenderCV provides << entry_count >> entry types:
{$ for entry_name in entry_names $}
<< loop.index >>. << entry_name >>
{$ endfor $}
each rendered differently on the PDF.
{$ for entry_name, entry in sample_entries.items() $}
### << entry_name >>
{$ if entry_name == "EducationEntry" $}
For academic credentials.
| Field | Required | Description |
| ------------- | -------- | ---------------------------------------- |
| `institution` | Yes | School or university name |
| `area` | Yes | Field of study |
| `degree` | No | Degree type (BS, MS, PhD, etc.) |
| `date` | No | Custom date string (overrides start/end) |
| `start_date` | No | Start date |
| `end_date` | No | End date (or `present`) |
| `location` | No | Institution location |
| `summary` | No | Brief description |
| `highlights` | No | List of bullet points |
{$ elif entry_name == "ExperienceEntry" $}
For work history and professional roles.
| Field | Required | Description |
| ------------ | -------- | ---------------------------------------- |
| `company` | Yes | Employer name |
| `position` | Yes | Job title |
| `date` | No | Custom date string (overrides start/end) |
| `start_date` | No | Start date |
| `end_date` | No | End date (or `present`) |
| `location` | No | Office location |
| `summary` | No | Role description |
| `highlights` | No | List of accomplishments |
{$ elif entry_name == "PublicationEntry" $}
For papers, articles, and other publications.
| Field | Required | Description |
| --------- | -------- | ------------------------------------------------ |
| `title` | Yes | Publication title |
| `authors` | Yes | List of author names (use `*Name*` for emphasis) |
| `doi` | No | Digital Object Identifier |
| `url` | No | Link to the publication |
| `journal` | No | Journal, conference, or venue name |
| `date` | No | Publication date |
{$ elif entry_name == "NormalEntry" $}
A flexible entry for projects, awards, certifications, or anything else.
| Field | Required | Description |
| ------------ | -------- | ---------------------------------------- |
| `name` | Yes | Entry title |
| `date` | No | Custom date string (overrides start/end) |
| `start_date` | No | Start date |
| `end_date` | No | End date (or `present`) |
| `location` | No | Associated location |
| `summary` | No | Brief description |
| `highlights` | No | List of bullet points |
{$ elif entry_name == "OneLineEntry" $}
For compact key-value pairs, ideal for skills or technical proficiencies.
| Field | Required | Description |
| --------- | -------- | ------------------ |
| `label` | Yes | Category name |
| `details` | Yes | Associated details |
{$ elif entry_name == "BulletEntry" $}
A single bullet point. Use for simple lists.
| Field | Required | Description |
| -------- | -------- | --------------- |
| `bullet` | Yes | The bullet text |
{$ elif entry_name == "NumberedEntry" $}
An automatically numbered entry.
| Field | Required | Description |
| -------- | -------- | ----------------- |
| `number` | Yes | The entry content |
{$ elif entry_name == "ReversedNumberedEntry" $}
A numbered entry that counts down (useful for publication lists where recent items come first).
| Field | Required | Description |
| ----------------- | -------- | ----------------- |
| `reversed_number` | Yes | The entry content |
{$ elif entry_name == "TextEntry" $}
Plain text without structure. Just write a string.
{$ endif $}
```yaml
<< entry["yaml"] >>
```
{$ for figure in entry["figures"] $}
=== "`<< figure["theme"] >>` theme"
![<< figure["alt_text"] >>](<< figure["path"] >>)
{$ endfor $}
{$ endfor $}
## Text Formatting & Features
### Using Markdown
All text fields support basic Markdown:
```yaml
highlights:
- Increased revenue by **$2M** annually
- Developed [open-source tool](https://github.com/example) with *500+ stars*
```
| Syntax | Result |
| ------------- | --------- |
| `**text**` | **bold** |
| `*text*` | *italic* |
| `[text](url)` | hyperlink |
| `` `code` `` | `code` |
### Using Typst
All text fields support Typst math and commands.
```yaml
highlights:
- Showed that $$f(x) = x^2$$ is a parabola
- "This is an #emph[emphasized] text"
```
### Arbitrary Keys
You can add arbitrary keys to any entry. By default, they're ignored, but you can reference them in `design.templates` field. See [Arbitrary Keys in Entries](../how_to/arbitrary_keys_in_entries.md) for more information.
```yaml hl_lines="6"
experience:
- company: Startup Inc
position: Founder
start_date: 2020-01
end_date: present
revenue: $5M ARR # Custom field
highlights:
- Built product from zero to profitability
```

192
docs/user_guide/yaml_input_structure/design.md Normal file
View File

@@ -0,0 +1,192 @@
# `design` Field
The `design` field controls every visual aspect of your CV: colors, fonts, spacing, and layout.
## Available Themes
RenderCV includes << theme_count >> built-in themes. To use one, simply specify the theme:
```yaml
design:
theme: classic
```
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:
- If you specify all design options in your YAML, changing the theme has no effect
- If you leave settings unspecified, changing the theme completely changes the design (because it uses different defaults)
- You can start with any theme and customize only what you want to change
## Customizing Design
You can override any field to fine-tune the theme:
```yaml
design:
theme: classic
colors:
name: rgb(255, 0, 0) # Override just the name color
```
Or specify all options for complete control:
```yaml
design:
theme: classic
page:
size: us-letter # (1)!
top_margin: 0.7in
bottom_margin: 0.7in
left_margin: 0.7in
right_margin: 0.7in
show_footer: true
show_top_note: true
colors:
body: rgb(0, 0, 0)
name: rgb(0, 79, 144)
headline: rgb(0, 79, 144)
connections: rgb(0, 79, 144)
section_titles: rgb(0, 79, 144)
links: rgb(0, 79, 144)
footer: rgb(128, 128, 128)
top_note: rgb(128, 128, 128)
typography:
line_spacing: 0.6em
alignment: justified # (2)!
date_and_location_column_alignment: right
font_family: # (11)!
body: Source Sans 3 # (9)!
name: Source Sans 3
headline: Source Sans 3
connections: Source Sans 3
section_titles: Source Sans 3
font_size:
body: 10pt
name: 30pt
headline: 10pt
connections: 10pt
section_titles: 1.4em
small_caps:
name: false
headline: false
connections: false
section_titles: false
bold:
name: true
headline: false
connections: false
section_titles: true
links:
underline: false
show_external_link_icon: false
header:
alignment: center # (3)!
photo_width: 3.5cm
photo_position: left # (8)!
photo_space_left: 0.4cm
photo_space_right: 0.4cm
space_below_name: 0.7cm
space_below_headline: 0.7cm
space_below_connections: 0.7cm
connections:
phone_number_format: national # (7)!
hyperlink: true
show_icons: true
display_urls_instead_of_usernames: false
separator: ''
space_between_connections: 0.5cm
section_titles:
type: with_partial_line # (4)!
line_thickness: 0.5pt
space_above: 0.5cm
space_below: 0.3cm
sections:
allow_page_break: true
space_between_regular_entries: 1.2em
space_between_text_based_entries: 0.3em
show_time_spans_in: # (5)!
- experience
entries:
date_and_location_width: 4.15cm
side_space: 0.2cm
space_between_columns: 0.1cm
allow_page_break: false
short_second_row: true
summary:
space_above: 0cm
space_left: 0cm
highlights:
bullet: • # (6)!
nested_bullet: •
space_left: 0.15cm
space_above: 0cm
space_between_items: 0cm
space_between_bullet_and_text: 0.5em
templates: # (10)!
footer: '*NAME -- PAGE_NUMBER/TOTAL_PAGES*'
top_note: '*LAST_UPDATED CURRENT_DATE*'
single_date: MONTH_ABBREVIATION YEAR
date_range: START_DATE – END_DATE
time_span: HOW_MANY_YEARS YEARS HOW_MANY_MONTHS MONTHS
one_line_entry:
main_column: '**LABEL:** DETAILS'
education_entry:
main_column: |-
**INSTITUTION**, AREA
SUMMARY
HIGHLIGHTS
degree_column: '**DEGREE**'
date_and_location_column: |-
LOCATION
DATE
normal_entry:
main_column: |-
**NAME**
SUMMARY
HIGHLIGHTS
date_and_location_column: |-
LOCATION
DATE
experience_entry:
main_column: |-
**COMPANY**, POSITION
SUMMARY
HIGHLIGHTS
date_and_location_column: |-
LOCATION
DATE
publication_entry:
main_column: |-
**TITLE**
AUTHORS
URL (JOURNAL)
date_and_location_column: DATE
```
1. **Page size options:** << available_page_sizes >>
2. **Body text alignment:** << available_body_alignments >>
`justified` spreads text across the full width, `justified-with-no-hyphenation` does the same without breaking words
3. **Header alignment:** << available_alignments >>
4. **Section title styles:** << available_section_title_types >>
`with_partial_line` adds a line next to the title, `with_full_line` spans the page, `without_line` has no line, `moderncv` uses ModernCV style
5. **Show time spans:** Specify which sections should display duration calculations (e.g., "2 years 3 months")
6. **Bullet characters:** << available_bullets >>
7. **Phone number formats:** << available_phone_number_formats >>
`national` formats for domestic use, `international` includes country code, `E164` is the standard international format
8. **Photo position:** `left` or `right` of the header text
9. **Available fonts:** << available_font_families >>. Also, any system font can be used. Custom fonts can be used as well. See [Custom Fonts](../how_to/custom_fonts.md) for more information.
10. **Templates:** Advanced customization - define how each entry type is rendered using placeholders like NAME, COMPANY, DATE, etc.
11. **Font family shorthand:** You can specify `font_family: "Latin Modern Roman"` directly instead of using nested options to apply the same font everywhere

52
docs/user_guide/yaml_input_structure/index.md Normal file
View File

@@ -0,0 +1,52 @@
# The YAML Input File
RenderCV uses a single YAML file to generate your CV. This file has four top-level fields:
```yaml title="Your_Name_CV.yaml"
cv:
...
# Your content (name, sections, entries)
...
design:
...
# Visual styling (theme, colors, fonts, spacing)
...
locale:
...
# Language strings (month names, "present", etc.)
...
settings:
...
# RenderCV behavior (current date, bold keywords)
...
```
Only `cv` is required. The others have sensible defaults.
Explore the detailed documentation for each field:
- [`cv` Field](cv.md)
- [`design` Field](design.md)
- [`locale` Field](locale.md)
- [`settings` Field](settings.md)
## JSON Schema
To maximize your productivity while editing the input YAML file, set up RenderCV's JSON Schema in your IDE. It will validate your inputs on the fly and give auto-complete suggestions.
![JSON Schema in action](../../assets/images/json_schema.gif)
=== "Visual Studio Code"
1. Install the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml).
2. Name your file ending with `_CV.yaml`. The schema activates automatically.
3. Press `Ctrl + Space` for suggestions.
=== "Other Editors"
1. Add this line at the top of your file:
```yaml
# yaml-language-server: $schema=https://github.com/rendercv/rendercv/blob/main/schema.json?raw=true
```
2. Press `Ctrl + Space` for suggestions (if your editor supports JSON Schema).

63
docs/user_guide/yaml_input_structure/locale.md Normal file
View File

@@ -0,0 +1,63 @@
# `locale` Field
The `locale` field lets you create a CV in any language by customizing month names, date formatting, and other language-specific text.
## Built-in Locales
RenderCV includes translations for 12 languages. To use one, simply specify the language:
```yaml
locale:
language: german
```
Available languages: `english` (default), `french`, `german`, `hindi`, `italian`, `japanese`, `korean`, `mandarin_chinese`, `portuguese`, `russian`, `spanish`, `turkish`.
## Customizing Locale
You can override any field to fine-tune the translations:
```yaml
locale:
language: german
present: jetzt # Override just this field
```
Or create a completely custom locale:
```yaml
locale:
language: english
last_updated: Last updated in
month: month
months: months
year: year
years: years
present: present
month_abbreviations:
- Jan
- Feb
- Mar
- Apr
- May
- June
- July
- Aug
- Sept
- Oct
- Nov
- Dec
month_names:
- January
- February
- March
- April
- May
- June
- July
- August
- September
- October
- November
- December
```

31
docs/user_guide/yaml_input_structure/settings.md Normal file
View File

@@ -0,0 +1,31 @@
# `settings` Field
The `settings` field configures RenderCV's behavior, including output paths, file generation, and text formatting.
```yaml
settings:
current_date: '2025-12-03' # (5)!
render_command:
design: path/to/design.yaml # (1)!
locale: path/to/locale.yaml # (2)!
typst_path: rendercv_output/NAME_IN_SNAKE_CASE_CV.typ # (3)!
pdf_path: rendercv_output/NAME_IN_SNAKE_CASE_CV.pdf
markdown_path: rendercv_output/NAME_IN_SNAKE_CASE_CV.md
html_path: rendercv_output/NAME_IN_SNAKE_CASE_CV.html
png_path: rendercv_output/NAME_IN_SNAKE_CASE_CV.png
dont_generate_markdown: false
dont_generate_html: false
dont_generate_typst: false
dont_generate_pdf: false
dont_generate_png: false
bold_keywords: # (4)!
- AWS
- Python
```
1. You can optionally split your YAML into multiple files. This file contains the `design` field.
2. You can optionally split your YAML into multiple files. This file contains the `locale` field.
3. Available placeholders are: `NAME`, `NAME_IN_SNAKE_CASE`, `NAME_IN_LOWER_SNAKE_CASE`, `NAME_IN_UPPER_SNAKE_CASE`, `NAME_IN_KEBAB_CASE`, `NAME_IN_LOWER_KEBAB_CASE`, `NAME_IN_UPPER_KEBAB_CASE`, `MONTH_NAME`, `MONTH_ABBREVIATION`, `MONTH`, `MONTH_IN_TWO_DIGITS`, `YEAR`, `YEAR_IN_TWO_DIGITS`.
4. These keywords will be bolded wherever they appear in your CV text (highlights, summaries, etc.).
5. Date used for file naming (when using date placeholders), the "last updated" text in the top note, and time span calculations for ongoing events (entries with `end_date: present`)

9
mkdocs.yaml
View File

@@ -53,8 +53,13 @@ nav:
- User Guide:
- Welcome: index.md
- Get Started: user_guide/index.md
- YAML Input Structure: user_guide/yaml_input_structure.md
- CLI: user_guide/cli.md
- CLI Reference: user_guide/cli_reference.md
- YAML Input Structure:
- Overview: user_guide/yaml_input_structure/index.md
- cv Field: user_guide/yaml_input_structure/cv.md
- design Field: user_guide/yaml_input_structure/design.md
- locale Field: user_guide/yaml_input_structure/locale.md
- settings Field: user_guide/yaml_input_structure/settings.md
- How-To Guides:
- Set Up VS Code for RenderCV: user_guide/how_to/set_up_vs_code_for_rendercv.md
- Arbitrary Keys in Entries: user_guide/how_to/arbitrary_keys_in_entries.md