The current section explains on how to get started with the \Moderncv package, i.e. how to install required packages.
% \emph{Note that it is assumed that you know how to install \Latex packages in case some are missing.}
Section \ref{section:moderncvTemplate} explains how to work with the \Moderncv template file step by step.
Section \ref{section:customization} details the customizations that the user can make: the different styles, their options, colors and tips and tricks.
Section \ref{section:implementationDetails} details the packages that \Moderncv uses, known problems and possible solutions to those problems.
\subsection{Installation instructions}
If the \Moderncv package does not ship with your \Latex distribution or if the installed version is too old, grab the \Moderncv code from \Ctan or \github:
\begin{tabular}{l}
\moderncvCtan\\% [.5ex]
\moderncvGithub
\end{tabular}
\note Depending on your \Latex distribution, you may have to install some additional packages.
Section \ref{section:implementationDetails:requiredPackages} lists all the packages that \Moderncv requires to be installed on your system.
\section{The \texttt{moderncv} template step by step}
This section is a quick reference to the \Moderncv package and should contain enough information to typeset a first working CV.
\label{section:moderncvTemplate}
The easiest way to get started with \Moderncv is to use the template that comes with the package.
If \Moderncv is part of your \Latex distribution, search for the folder \Moderncv on your system, which should contain all the files for the package.
In this folder, there should be a file called \cvtemplate.
If you downloaded the package from \Github or \ctan, look for \Cvtemplate in the folder of the newly downloaded (and possibly extracted) package.
\note If you downloaded \Moderncv from \Github or \Ctan and moved \Cvtemplate to another folder, make sure to adjust the \code{TEXINPUTS} variable to find the newly downloaded package.
Otherwise, either the package version provided by your \Latex distribution gets used or \Latex throws an error if there is no other version installed.
Test your setup by compiling \Cvtemplate and looking at the result.
\note The \Moderncv package should compile with \code{pdflatex}, \code{lualatex} and \code{xelatex}.
However, not all icons are available when using \code{pdflatex}, so using either \code{lualatex} or \code{xelatex}\emph{is highly recommended.}
\subsection{Basic setup}
A document using the \Moderncv document class is set up like any other document class.
We will go through the template step by step.
\subsubsection*{Configuring document class options}
The \Moderncv document class is loaded as per usual, by
\begin{lstlisting}
\documentclass[<options>]{moderncv}
\end{lstlisting}
where at most one value for each option can be passed to the document class:
\note Some of the styles take additional options to fine-tune their appearance.
To keep this overview short, these options will be described in section \ref{section:customization:stylesAndOptions}.
\subsubsection*{Font family and page numbering}
The default font family is set by the line \code{\\renewcommand\{\\familydefault\}\{\\sfdefault\}} in \cvtemplate.
Use \code{\\sfdefault} for the default sans-serif font, \code{\\rmdefault} for the default roman font, and likewise for any \TeX{} font name.
The general syntax is
\begin{lstlisting}
\renewcommand{\familydefault}{<fontfamily>}
% \nopagenumbers{}
\end{lstlisting}
Uncommenting \code{\%\\nopagenumbers\{\}} suppresses automatic page numbering for CVs longer than one page.
\subsubsection*{Adjusting input encoding}
If you are not using \code{xelatex} or \code{lualatex}, which both use \code{utf8} encoding by default, uncomment the \code{\\usepackage[utf8]\{inputenc\}} import and change the encoding as needed.
\subsubsection{Language-specific setup}
The \code{babel} package can be loaded in the preamble of your CV.
\note\Moderncv doesn't work with \code{babel} in Spanish (see this \href{https://github.com/moderncv/moderncv/issues/103}{GitHub issue}).
For CJK users, uncomment the \code{\\usepackage\{CJKutf8\}} import.
\subsection{Personal data}
Edit the personal data section to reflect your personal information.
This data will appear in the header of the first page of the CV and/or in the footer of every page, as well as on the cover letter.
Most of the commands are optional, so try out what you like and see what you need.
\paragraph{\code{\\name}}
A command for your name. Takes the given name and surname as arguments.
\begin{lstlisting}
\name{<given name>}{<surname>}
\end{lstlisting}
\paragraph{\code{\\title}}
A command for a document title. Could be used for a generic CV title, job title, etc.
\begin{lstlisting}
\title{<title>}
\end{lstlisting}
\paragraph{\code{\\born}}
A command for a birth date.
\begin{lstlisting}
\born{<birth date>}
\end{lstlisting}
\paragraph{\code{\\address}}
A command for a three-lined street address.
\begin{lstlisting}
\address{<street address>}{<city and postcode>}{<country>}
\end{lstlisting}
\paragraph{\code{\\phone}}
A command for a phone number. Takes the phone type as an optional argument.
\begin{lstlisting}
\phone[<type>]{<phone number>}
\end{lstlisting}
The allowed values for \code{<type>} are \code{fax}, \code{fixed} and \code{mobile}.
\paragraph{\code{\\email}}
A command for an email address.
\begin{lstlisting}
\email{<email address>}
\end{lstlisting}
\paragraph{\code{\\homepage}}
A command for a personal website.
\begin{lstlisting}
\homepage{<web address>}
\end{lstlisting}
\paragraph{\code{\\social}}
A command for a social media account.
Takes the platform as an optional argument.
\begin{lstlisting}
\social[<platform>]{<username or handle>}
\end{lstlisting}
The following values are supported for \code{<platform>}:
\note{Long names and URLs can break some CVs and cover letters depending on the used style. Manually inserting line breaks for names with \code{\\\\} can help for \texttt{oldstyle} or \texttt{fancy}. Adjusting lengths as described in section \ref{subsection:adjusting:lengths} could help to mitigate issues with long URLs.}
For some occasions you may need to include pictures besides the portrait photo. For this task it is helpful to know basic lengths used in \moderncv. For a more detailed description of lengths see section \ref{subsection:adjusting:lengths}.
For instance, pictures can be included with \code{\\includegraphics}:
By default, no labels are shown for bibliography entries.
Uncommenting the line \code{\%\\renewcommand*\{\\bibliographyitemlabel\}\{[\\arabic\{enumiv\}]\}}
allows one to fine-tune the labels.
Uncommenting the line \code{\%\\renewcommand\{\\refname\}\{Articles\}} allows one to redefine the bibliography heading string ``Publications'' that is shown by default.
Finally, adjustments using the \code{multibib} package can be done in the last two lines shown here.
\note\Biblatex is currently not supported.
\subsection{Modifying CV content}
\subsubsection{Structuring the CV}
As with any other document style, the CV can be structured into sections and subsections using \code{\\section} and \code{\\subsection}.
The \Moderncv package provides some macros to add content to your CV.
The easiest way to understand their intended use is to look at how they're used in the template.
Nonetheless, we list the macros here along with a short description of their intended use.
\subsubsection{General macros}
\paragraph{\code{\\cvitem}}
A flexible command for a single CV entry.
Takes the descriptor and body text as required arguments.
Can be used to list job experiences and similar.
\begin{lstlisting}
\cvitem{<descriptor>}{<body>}
\end{lstlisting}
\paragraph{\code{\\cvdoubleitem}}
A two-column variation of \code{\\cvitem}.
Takes four required arguments: the descriptor and body text of the first column and the descriptor and body text of the second column.
Can be used to enter skills, such as computer skills or language skills, in a two-column fashion.
In order to provide additional information for a job application, {\moderncv} provides a motivation letter. Define the following recipient data fields to customize your letter:
An optional command to include your signature after the closing. This feature is defined using the \code{\\includegraphics}. The first argument is the scale and the second argument is the filename of your scanned signature.
\enclosure[<optional alternative label>]{<list of documents>}
\end{lstlisting}
\note If typesetting the resume in Chinese using CJK an additional \code{\\clearpage} is required after the \code{\\makeletterclosing} command. This helps \code{fancyhdr} to work correctly with CJK. Otherwise it will remove the page numbering by making \code{lastpage} undefined.
Enables or disables the inclusion of a QR code of your personal website.
\end{tabular}
\note For the \code{contemporary} style it is recommended to use the \code{\\moderncvcolor\{cerulean\}} color scheme. The \code{contemporary} style is even more appealing with reduced margins. Use this in your preamble:
\note The color theme must be loaded \emph{before}\code{\\moderncvstyle}, i.e.
\begin{lstlisting}
\moderncvcolor{blue}
\moderncvstyle{casual}
\end{lstlisting}
\paragraph{Base colors.}
Each style defines three main colors: \code{color0}, \code{color1} and \code{color2}.
\code{color0} is black and the main text color.
\code{color1} is the main theme color, like blue, green, etc.
\code{color2} is a some form of grey used for the user data, etc.
These colors can be redefined by using either \code{\\definecolor} or \code{\\colorlet}:
\begin{lstlisting}
\definecolor{color1}{rgb}{0.55, 0.55, 0.55}% dark grey
\colorlet{color1}{black}
\end{lstlisting}
Any mechanism for naming and defining colors used by the \code{xcolor} package can be used to redefine the colors of a \Moderncv style.
\paragraph{Fine tuning.}
If an even finer control over the color scheme of the style is desired, the following color settings are used internally for the \code{casual} style and can be redefined:
\begin{lstlisting}
% Head and footer
\colorlet{lastnamecolor}{color1}
\colorlet{namecolor}{lastnamecolor}
\colorlet{headrulecolor}{color1}
\colorlet{firstnamecolor}{lastnamecolor!50}
\colorlet{titlecolor}{color2}
\colorlet{addresscolor}{color2}
\colorlet{quotecolor}{color1}
\colorlet{pictureframecolor}{color1}
% Body
\colorlet{bodyrulecolor}{color1}
\colorlet{sectioncolor}{color1}
\colorlet{subsectioncolor}{color1}
\colorlet{hintstylecolor}{color0}
% Letter
\colorlet{letterclosingcolor}{color2}
% Skill matrix
\colorlet{skillmatrixfullcolor}{color1}
\colorlet{skillmatrixemptycolor}{color2!30}
\end{lstlisting}
\subsection{Modifying symbols and icons}
\subsubsection{Icons}
As stated in section \ref{section:customization:stylesAndOptions}, the use of icons is toggled by the \code{symbols} option that can be passed to \code{\\moderncvstyle}.
The icons used in the display of the personal data (phone numbers, email, fax, social media accounts, etc.) can be customized by redefining the internal commands for the symbols:
The possible options for \code{<\\symbol>} depend on the package that is used.
By default, the \code{marvosym} package is loaded if \code{pdflatex} is used, and the \code{academicons} and \code{fontawesome5} packages are loaded if either \code{lualatex} or \code{xelatex} is used.
Full lists of all available symbols and icons can be found in the documentation of each respective package:
If one wanted to use the dingbat fonts to replace the default phone symbol, one should load the \code{pifont} package in the preamble and then substitute the default symbol with the dingbat symbol \ding{38}\ with
In case you do not want \texttt{symbols} (default) for the icons, there is also the option to replace icons with \texttt{letters} instead. This is set by the macro \code{\\moderncvicons}, which must be called after setting the style in the preamble.
This mechanism is also used to determine the icon set. In principle the \code{\\moderncvicons} can be used to determine the icon set with the possible values \texttt{marvosym}, \texttt{awesome} or \texttt{academic}, but it is recommended to let {\moderncv} decide the correct icon set due to differing \Latex compiler support.
\item Redefining \code{\\labelitemi}, \code{\\labelitemii}, \code{\\labelitemiii} and \code{\\labelitemiv} changes the labels for \code{itemize} environments as well as for \code{cvlistitem} and \code{cvlistdoubleitem}, e.g.
\begin{lstlisting}
\renewcommand{\labelitemi}{-}
\end{lstlisting}
\item Redefining \code{\\listitemsymbol} changes the labels for \code{cvlistitem} and \code{cvlistdoubleitem} but \emph{not} for \code{itemize} environments, e.g.
The spacing between the list symbol and the text item of \code{\\cvlistitem} and \code{\\cvlistdoubleitem} can be adjusted by setting \code{\\listitemsymbolspace} in the preamble. The default value is set to \code{0pt}.
The width of the footer can be adjusted by setting \code{\\footwidth}. Due to internal calculations \code{\\renewcommand} is needed. The default value is \code{0.8\\textwidth}.
The width of the quote can be adjusted by setting \code{\\quotewidth}. Due to internal calculations \code{\\renewcommand} is needed. The default value is \code{0.65\\textwidth}.
% where \code{<length>} are \code{maincolumnwidth}, \code{doubleitemmaincolumnwidth}, \code{listitemsymbolwidth}, \code{listdoubleitemmaincolumnwidth},
\subsection{Page breaks and orphaned section headers}
If \Latex breaks pages just after \code{\\section} or \code{\\subsection} commands, try adjusting the stretchability of the page with \code{\\cvsectionstretchability} or \code{\\cvsubsectionstretchability}:
These two lengths tell \Latex how much extra length it needs after \code{\\section} and \code{\\subsection} commands.
By default, \Moderncv sets both lengths to \code{0.9\\baselineskip}.
This should solve orphaned \code{\\section} and \code{\\subsection} commands that are used alone for most users.
However, \Latex does not check for content.
For example, writing
\begin{lstlisting}
\section{blub}
\subsection{blubblub}
\end{lstlisting}
one after the other may cause \Latex to place the section and subsection headers on separate pages.
Since \Latex considers the subsection header to not be orphaned, it may place the section header at the bottom of a page if there is enough space to do so while placing the subsection header on the next page.
One solution is to increase \code{\\cvsectionstretchability} to force the break of the section header.
However, this changes the behaviour for all \code{\\section} commands in your CV and might cause unnecessary page breaks.
It is therefore recommended to force the page break manually with a \code{\\newpage} in this case.
\paragraph{Experts only:}
Internally, \Moderncv uses a custom \code{\\needspace} command:
\vskip\z@skip % hide the previous |\vskip| from |\addvspace|
\endgroup
}
\end{lstlisting}
Thus, instead of setting \code{\\cvsectionstretchability} and/or \code{\\cvsubsectionstretchability}, page break behavior can be adjusted by redefining the following internal penalties:
Currently {\moderncv} ships with six different styles: \texttt{casual} (default), \texttt{classic}, \texttt{banking}, \texttt{oldstyle}, \texttt{fancy} and \texttt{contemporary}. Internally, these styles are numbered 1, 2, 3, 4, 5 and 6, respectively. All styles except \texttt{oldstyle} and \texttt{fancy} possess additional option parameters which were described in section \ref{section:customization:stylesAndOptions}.
Different styles' head, body and foot can be combined to create custom styles. This is done by setting \code{\\moderncvhead}, \code{\\moderncvbody} and \code{\\moderncvfoot} in the preamble. Here is an example of a custom style with a \texttt{banking} head, an \texttt{oldstyle} body and a \texttt{casual} foot:
Furthermore, options for each part of {\moderncv} parts can be set as well in such combinations. To get a CV with a \texttt{classic} head and a \texttt{banking} body with full rules, define the following in the preamble:
Most of these packages should be included in your \Latex distribution of choice.
\subsection{Known conflicts with other packages}
\begin{enumerate}
\item\Moderncv is incompatible with \code{biber}.
\item\Moderncv is incompatible with \biblatex.
\item\Moderncv is incompatible with \code{babel} in Spanish
\end{enumerate}
\subsection{Known bugs}
\begin{enumerate}
\item Skill matrices don't break automatically in \texttt{fancy} style.
\item Long names break the \texttt{oldstyle} style and possibly other styles (needs testing).
\item Long URLs in \texttt{classic} style can make the name break line.
Fixed width for the address part must be implemented.
\item When using the \texttt{fancy} style, undesired space is added between the bibliography head and the first entry, as well as after the last entry.
\item Footnotes generate errors, but the output seems correct when running with \code{-interaction=nonstopmode}.
\item When using CJK, the last \code{\\clearpage} required for the \code{fancyhdr} package to work properly kills the ``lastpage'' counter, and therefore also the page numbering.
\item\Moderncv produces the error ``\code{lonely \\item--perhaps a missing list environment}'' when used with the \code{bibentry} package, though the output is actually correct.
Among other things, this causes compilation by LyX to stop.
\item The space after a \code{\\cventry} gets eaten up when the last argument contains a nested \code{itemize} environment.
An ugly hack and incomplete solution was implemented by including a \code{\\strut} in every item label, but this doesn't solve the problem for multi-line items.
Ideally, the \code{\\strut} should end the item, but there seems to be no way to do this.
