@ewwmy/cv-builder

CV Builder

💻 A CLI utility to generate a well-formatted CV in PDF format 📕 based on JSON CV data and a Handlebars template.

Dependencies

• fs-extra for convenient filesystem interactions
• handlebars as the template processor
• marked to provide Markdown support
• puppeteer to generate PDFs
• sharp to preload and process images
• yargs to manage and process command-line arguments conveniently
• chokidar to provide file watching
• tslog to make logging more pretty and functional
• inversify to handle dependency injection and improve code modularity.

Why?

This project was inspired by JSON Resume. The main idea of this project is to provide you a convenient way to store the information about your work experience, achievments, and other CV data separately from its representation, in multiple languages, in one place, and to easily generate good-looking multilingual CVs in PDF format in one command.

For example, you might get tired of managing multiple CV versions in office document files. You want to add a new record in your CV and you might get confused which version is more actual or you need to add this record into all the versions. This application solves that problem.

Advantages

• No strict JSON schema
  • Special fields enable features like Markdown support, translations, icons, or images
• Markdown support
• Multilingual support (provide multiple translations in dedicated JSON fields)
• Ready to use without complex setup
• Fully functional example included out of the box
• Clear separation of data and presentation
  • You can include private data that won't appear in the final output
  • Allows focus either on the data or on the design separately
• Privacy-oriented (no data is processed or collected outside your computer).

Disadvantages

• Requires basic knowledge of HTML, CSS, and Handlebars
• Some dependencies, such as Puppeteer, are resource-heavy.

Installation

From NPM Registry (if available)

npm install -g @ewwmy/cv-builder

From GitHub Repository

mkdir cv-builder
cd cv-builder
git clone [e-mail]:ewwmy/cv-builder.git .
npm ci
npm install -g .

Uninstallation

npm uninstall -g @ewwmy/cv-builder

Note: The application directory located at ~/.config/ewwmy/cv-builder and all its contents will be preserved.

How it works

After installation, the utility creates all the necessary files and folders in ~/.config/ewwmy/cv-builder.

They are:

• icons: default base folder for icons (in case of relative paths); includes a set of common icons
• images: default base folder for images (in case of relative paths); includes an example AI-generated user photo
• templates: default folder for templates; includes an example template
• cv-example.json: example JSON CV data
• out: default folder for generated PDF files
• settings/settings.json: configuration file with the user preferences.

When you run the program, it:

• reads the configuration to determine what files to use, where they are stored and where to save the results
• reads the input CV JSON file
• reads selected templates
• consider seleted languages
• compiles PDF based on the CV JSON data and selected templates and languages; amount of the result PDF files is amount of the selected templates multiplied by amount of the selected languages.

Usage

Basics

Once installed, you can call the utility from anywhere using cv-builder command.

You can run it immediately with no additional setup:

cv-builder

This builds the included example.

As a common practice for CLI utilities, you can also check the version or access helpful usage information:

cv-builder --version
cv-builder --help

Command-line options

Main command-line options:

• -l, --locales: locales (languages) to build (e.g., -l en-US -l ru-RU or -l en-US ru-RU)
• -t, templates: template files to build without .hbs suffix (e.g., -t example -t main -t another-cool-template or -t example main another-cool-template)
• -i, --input: path to the JSON file with the data of your CV (e.g., -i /home/user/my-cv.json)
• -o, --output: directory for the built PDF files (e.g., -o /home/user/my-cv)
• -d, --templates-dir: directory for the templates (e.g., -o /home/user/my-cv-templates)
• -w, --watch: watch the CV JSON file and the templates directory for changes and rebuild PDFs when it changes (for live updates)

Command-line options override settings defined in settings/settings.json. For detailed information about the configuration, please refer to the Default Configuration section.

If you accidentally misconfigure something, you can restore the default setup:

cv-builder --restore

Note: cv-builder --restore does not overwrite existing files. To force overwrite, use:

cv-builder --restore --force

Default Configuration

Default settings file: ~/.config/ewwmy/cv-builder/settings/settings.json. You should not move or rename it.

These are configuration options and their corresponding command-line options:

Option	Command-line	Type	Description
LOCALES	-l, --locales	array	Locales (languages) to build
TEMPLATES	-t, templates	array	Template files to build (omit the .hbs extension)
INPUT_CV_FILE_PATH	-i, --input	string	Path to the JSON file containing CV data
OUTPUT_DIR	-o, --output	string	Directory for the generated PDF files
TEMPLATES_DIR	-d, --templates-dir	string	Directory containing the templates
BASE_IMAGES_DIR	--images-base-dir	string	Base directory for relative image paths in the JSON CV data
BASE_ICONS_DIR	--icons-base-dir	string	Base directory for relative icon paths in the JSON CV data

CV JSON File

The example file at ~/.config/ewwmy/cv-builder/cv-example.json is used by default. It demonstrates all features and provides a template for organizing your data. It's highly recommended to explore it.

You can create any structure, use any valid JSON data, but some field names are reserved for specific features. Refer to the Features Overview section for details.

Templates

CV Builder uses the Handlebars template engine and includes a couple of templates out of the box:

• default.hbs — a basic template that demonstrates most of the features.
• international-strict.hbs — a template which is considered one of the best for IT specialists in 2025 (looks similar to well-known Jake's Resume).

By default they're both on. Default location of the templates: ~/.config/ewwmy/cv-builder/templates.

You can create as many templates as needed. Template files must have the .hbs extension. Specify templates you need to generate PDF with in the TEMPLATES setting or via command-line options. Similarly, the directory for templates can be configured via the TEMPLATES_DIR setting or command-line options.

Please, refer to the Handlebars Guide for more information on using Handlebars.

Note: The options provided via command-line override the options from the settings/settings.json configuration file.

Watch Mode

The -w (--watch) option can be used to watch the CV JSON file and the templates directory for changes and rebuild PDFs when they change. This is useful for live updates (e.g., to develop templates, or to monitor changes in the JSON data).

Features

Logical Expressions

You can use additional logical operators, such as eq, ne, lt, gt, lte, gte, and, or to make your templates much more flexible:

• {{#if (eq foo "bar")}} → if (foo === "bar")
• {{#if (ne foo "bar")}} → if (foo !== "bar")
• {{#if (lt foo 3)}} → if (foo < 3)
• {{#if (gt foo 3)}} → if (foo > 3)
• {{#if (lte foo 3)}} → if (foo <= 3)
• {{#if (gte foo 3)}} → if (foo >= 3)
• {{#if (and (eq foo "bar") (lt baz 10))}} → if (foo === "bar" && baz < 10)
• {{#if (or (eq foo "bar") (lt baz 10))}} → if (foo === "bar" || baz < 10)

Template Usage

The content will only show if either section1 or section2 is present:

{{#if (or section1 section2)}}
  {{content}}
{{/if}}

The content will only show if either section1 === "foo" or section2 !== "bar":

{{#if (or (eq section1 "foo") (ne section2 "bar"))}}
  {{content}}
{{/if}}

Practical Example

{{#each data.experience}}
  {{#if (lt @index 3)}}
    {{!-- Show only 3 latest jobs --}}
  {{/if}}
{{/each}}

First and Last items

You can use @first and @last aliases in templates to refer the first and the last array elements accordingly.

Example

{{#each data.certificates}}
  {{#if @first}}
    {{!-- Show the latest certificate only --}}
  {{/if}}
{{/each}}

Markdown Support

You can use Markdown anywhere in your JSON data. To render Markdown in templates, use the {{markdown}} helper.

JSON Example

{
  "description": "This is **bold** and _italic_"
}

Template Usage

{{markdown description}}

Note: The markdown is the special helper name and the description refers to the name of the JSON field.

Image Handling

To include an image, use a specific JSON structure and the {{{image}}} helper in the template.

JSON Example

{
  "profilePicture": {
    "type": "image",
    "path": "profile.jpg",
    "scale": 0.5
  }
}

• type: required; must be "image"
• path: required; relative to the base image folder or an absolute path
• scale: optional; reduces image size; defaults to 1; useful if the original image is too large and can cause aliasing while

Template Usage

{{{image profilePicture width='150px' height='150px' roundness=1}}}

• width: optional; a valid CSS value for the resulting image in the generated PDF
• height: optional; a valid CSS value for the resulting image in the generated PDF
• roundness: optional; defaults to 0 which means no roundness; 1 means an ideal circle.

Note: The image is the special helper name and the profilePicture refers to the name of the JSON field.

Icons Support

Icons are loaded from SVG files. Use the icon field in your JSON and the {{{icon}}} helper in a template.

JSON Example

{
  "social": {
    "icon": "linkedin-logo.svg"
  }
}

The path must be either absolute or relative to the base icons directory which is specified in the configuration or command-line.

Template Usage

{{{icon social.icon}}}

Multilingual Support

You can include translations for any field in JSON using locale keys (e.g., en, ru). Specify the locales when building the CV or set up the default locales in the configuration.

The locale determines which translation is used. If you have 2 translations in your JSON (e.g., en, ru) and specify both in the configuration or in command-line, it will create 2 PDF files with each translation provided.

JSON Example

{
  "greeting": {
    "en": "Hello",
    "ru": "Привет"
  }
}

Template Usage

{{greeting}}

Date Formatting

Dates are formatted based on the specified locale. Use the {{date}} helper for pretty printing (year and month). Use the {{year}} helper to extract the year only from a date.

JSON Example

{
  "startedAt": "2020-12-31"
}

The date must be in YYYY-MM-DD format.

Template Usage

Typical date:

{{date startedAt}}

Year only:

{{year startedAt}}

Hidden Items

Any object with the property "hidden": true will be excluded from the output, even if it's called from a template, ensuring it never passes to the output. You can use it to safely store your notes (e.g., comments) in your JSON data that should never be visible in the result PDF.

JSON Example

{
  "value": "Hidden text",
  "hidden": true
}

It's especially useful in arrays to exclude some elements:

[
  {
    "email": "[e-mail]"
  },
  {
    "phone": "+0 [phone]",
    "hidden": true
  }
]