A headless renderer that converts Lua-defined personal data into a single-page CV in PDF or PNG. CV files are plain Lua scripts; the renderer loads the defined tables, builds an HTML document, and hands it to a headless Chrome/Chromium browser for layout and export.
The project is a single translation unit (main.cpp) with no third-party C+
dependencies other than Lua and the system browser binary. Layout, typography,
and page layout are driven by inline CSS. The generator is designed for
regression and layout testing as well as everyday CV export.
The repository uses the following top-level directories:
main.cpp- Entry point and Lua to HTML renderer source. Builds to thecvgenexecutable.exports/- Sample generated artifacts. EachNN_...entry exists in both PNG and PDF, ordered from a compact single-page sheet to a full feature pack.gen_test.sh- End-to-end test harness. Writes Lua CV fixtures intotempCVs/, renders every fixture, and writes both PDF and PNG toexports/. Exits non-zero when a render fails.tempCVs/- Do not commit generated Lua fixtures.LICENSE- GNU Lesser General Public License, version 3.
- A C++17 compiler
- macOS: Apple Clang from Xcode Command Line Tools
- Linux: GCC 11 or Clang 14 or later
- Lua development headers and the
pkg-configfile for Lua - Headless Chrome, Chromium, Brave, Edge, or Google Chrome Canary on the host that performs the export
On macOS, homebrew is the supported distribution path for Lua. Install these
before building:
brew install lua pkg-configThe recommended build is a single command from the repository root:
clang++ -std=c++17 -O2 main.cpp -o cvgen $(pkg-config --cflags --libs lua)The resulting cvgen binary accepts two positional arguments:
./cvgen path/to/cv.lua out.pdf
./cvgen path/to/cv.lua out.png.pdfproduces an A4 print rendition with Chrome print-to-PDF..pngproduces an A4 raster at 96 DPI scaled by 2, matching the default double-resolution export used by the test harness.
The main thumbnail for the project is the first entry in exports/. It
renders the full data model on a single A4 page and is used for preview,
advertising, and documentation.
The remaining exported entries demonstrate the supported layouts and content gradients:
| Preview | File |
|---|---|
| Compact engineer | exports/01_compact_engineer.png |
| Dense graphics | exports/02_dense_graphics.png |
| Long academic | exports/03_long_academic.png |
| Minimal | exports/04_minimal.png |
| Custom sections | exports/05_custom_sections.png |
| Nested data | exports/06_nested_data.png |
| Functions and scalars | exports/07_functions_and_scalars.png |
| Wide content | exports/08_wide_content.png |
| Sparse sections | exports/09_sparse_sections.png |
| Escape and long text | exports/10_escape_and_long_text.png |
| Project heavy | exports/11_project_heavy.png |
| All features | exports/12_all_features.png |
The images display the following document states:
- Typed sections, custom sections, and repeated cards.
- Scalar values, arrays, nested tables, functions, booleans, and numbers.
- Escaped markup, long running text, and dense content.
- Wide pages, sparse sections, and full feature packs.
The CLI accepts a tight set of positional arguments. It does not parse flags for input or output, so the command form is fixed:
cvgen
<input.lua>
<output.pdf | output.png>
Options
--help
Print the usage text and exit.
--version
Print the project version and exit.
Environment
CVGEN
Override the generated binary path when invoking scripts from this
repository. The default lookup is the `cvgen` executable in the
repository root.
Default behaviour
Without arguments the tool reports missing input and does not attempt a
render. Every run expects exactly two positional arguments: a Lua CV script
and an output file whose extension determines the format.The repository ships a full end-to-end test script that renders a matrix of synthetic CVs in both PDF and PNG:
./gen_test.shThis produces tempCVs/00_showcase.lua and then renders every fixture into
exports/. The display and run steps are wrapped together so the workspace
stays in a clean generated state.
| Platform | Compiler | Lua package | Command |
|---|---|---|---|
| macOS | Apple Clang (clang++) |
brew install lua |
clang++ -std=c++17 -O2 main.cpp -o cvgen $(pkg-config --cflags --libs lua) |
| Linux | GCC 11+ / Clang 14+ | liblua-dev or luajit-dev |
g++ -std=c++17 -O2 main.cpp -o cvgen $(pkg-config --cflags --libs lua) |
| Windows | MSVC 2019+ / MinGW | Lua 5.4 or LuaJIT | cl /std:c++17 /O2 main.cpp /Fe:cvgen.exe (MSVC) or g++ -std=c++17 -O2 main.cpp -o cvgen.exe (MinGW) |
Notes:
- Lua is linked through
pkg-configon Unix. Ifpkg-configdoes not find a Lua module, specify the include and library paths manually. - Linux distributions chain Lua through the system package manager. On Debian
and Ubuntu the connector is the
liblua5.4-devpackage when targeting Lua 5.4, orluajitwhen using LuaJIT. - macOS warns about
-Weverythingin the VS Code C/C++ Runner configuration, which keeps the default Clang warning banner on. The release build uses-O2and the warning set is not forwarded into that flag set.
A CV is a Lua script that populates global tables. The renderer reads the tables and renders them in file order. The built-in sections are:
PersonalInfo- name, title, location, operating system, email, GitHub, summary. The renderer calls string-valued fields that resolve to a function at render time.Skills- grouped language, graphics, tool, and systems arrays.Education- institute, degree, and status per entry.Projects- title, role, description, and technology tags per entry.
Additional tables are supported when the generic renderer can handle them:
- Scalar values for number, string, boolean, and function fields.
- Arrays of scalars for highlighted items and lists.
- Nested records under custom section names.
- Boolean and numeric options that drive alternate visual styling.
Custom sections are rendered from a generic table walker, so users can add new named top-level keys and the renderer will render them in definition order.
- Load the Lua CV script with the bundled Lua interpreter.
- Walk the global table in definition order and schedule the built-in and custom sections.
- Generate HTML with inline CSS, embedding the same content for both PDF and PNG output.
- Launch a headless browser with a temporary user profile and a file URL.
- For PDF: request a print-to-PDF, no header or footer.
- For PNG: request a window size of 794 x 1123 pixels, force a 2x device scale factor, and write the viewport screenshot.
- Return success when the output file exists and has a non-zero size.
Temp files are created under the system temporary directory and removed after the export finishes.
The repository ships one integration harness. It regenerates the Lua fixtures, renders every fixture into both PDF and PNG, and checks the exit codes of the binary for every output file:
./gen_test.shNo test harness is included in the build for all platforms other than macOS and Linux. The Windows build uses MSVC or MinGW directly and relies on the user running the same steps from a shell that supports the Lua export scripts.
This project is licensed under the GNU Lesser General Public License, version 3 or later.
GNU Lesser General Public License
Version 3, 29 June 2007
Copyright (C) 2026 Upstage AI
This library is free software: you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library. If not, see
<https://www.gnu.org/licenses/>.
On the Apache-2.0 license page, also add the following notice:
This library is also available under the terms of the Apache 2.0
license, for the benefit of projects that require that license.
See https://www.apache.org/licenses/LICENSE-2.0 for details.
You may distribute the CVGen binary and the Lua CV scripts under the same
license, and you may link against any Libre or Open source library. The
source is in main.cpp; the vendored binaries are built from that source.
