%!TeX root=../tikz-shields-doc.tex
\section{Basic usage}

\paragraph{Syntax:}
\begin{verbatim}
\drawBadge[<options>]{<left text>}{<right text>}
\end{verbatim}

\paragraph{Arguments:}
\begin{itemize}
    \item \texttt{[<options>]} (optional): Key-value options to customize the badge appearance, see next section.
    \item \texttt{\{<left text\}} (required): Text displayed in the left part of the badge.
    \item \texttt{\{<right text\}} (required): Text displayed in the right part of the badge.
\end{itemize}

\begin{tcblisting}{title={\tikzshields}, lower separated=false}
\drawBadge{Any text}{you like}
\end{tcblisting}


\section{Optional arguments}
\label{sec:args}

Some optional arguments can be passed to the macro \texttt{\textbackslash{}drawBadge} (as well as the other ones described in this document):

\begin{center}
    \begin{tblr}{
        colspec = {Q[c,m, cmd=\texttt,0.18\textwidth]X[0.5\textwidth,m]X[0.17\textwidth,c,m]X[0.04\textwidth,c,m]},
        row{1} = {cmd=\textbf, bg=default-blue, fg=white},
        vlines, hlines,
        width = \textwidth,
    }
    Name & Description & Default value & Pkg \\
    baseline & Baseline of the badge & \texttt{0mm} & \\
    color & Background color of the right part of the badge & \showColor{default-blue} & \checkmark \\
    colorLeft & Text color of the left part of the badge & \showColor{white} & \checkmark \\
    colorRight & Text color of the right part of the badge & \showColor{white} & \checkmark \\
    font & Font used in badges & \texttt{\textbackslash sf} & \checkmark \\
    labelColor & Background color of the left part of the badge & \showColor{default-left} & \checkmark \\
    logo & Logo displayed before the text & & \\
    logoColor & Color of the logo & \showColor{white} & \checkmark \\
    link & Clickable link & & \\
    showlink & Draw the \textsf{hyperref} border around the badge & \texttt{false} & \\
    style & Style of the badge. Possible values are: \texttt{flat}, \texttt{flat-square}, \texttt{plastic}, \texttt{for-the-badge}, \texttt{social} & \texttt{flat} & \checkmark \\
    \end{tblr}
\end{center}

If the last column is ticked, then the option can be specified as default option for the whole library, that can be passed when loading it, for instance
\mintinline[breaklines]{tex}{\usepackage[labelColor=red]{tikz-shields}}.

Note that anything can be used as a logo, even a text or a personalized command that you would have created (in an example described in Section~\ref{sec:special-badges}
\mintinline[breaklines]{tex}{\def\checkmark{\tikz\fill[scale=0.4] (0,.35) -- (.25,0) -- (1,.7) -- (.25,.15) -- cycle;}}).

\vspace{\baselineskip}

The Section~\ref{sec:examples} presents some examples of badges that can be generated, while Section~\ref{sec:special-badges} shows some preset badges.





%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Examples}
\label{sec:examples}

\subsection{Customize badges}

The colors of backgrounds and texts can be customized, the default color being \showColor{default-left} and \showColor{default-blue},
for the left and right part respectively.
Following the names from \url{img.shields.io}, the options are:

\begin{center}
    \begin{tblr}{
        colspec = {Q[c,m, cmd=\textbf, bg=default-blue!40]Q[c,m,cmd=\texttt]Q[c,m,cmd=\texttt]},
        row{1} = {cmd=\textbf, bg=default-blue, fg=white},
        vlines, hlines,
        width = \textwidth,
    }
     & Left bloc & Right bloc  \\
    Background & labelColor & color \\
    Text & colorLeft & colorRight \\
    \end{tblr}
\end{center}


\begin{tcblisting}{title={Change color}, lower separated=false}
\drawBadge[color=red]{Any text}{you like}
\drawBadge[labelColor=white, colorLeft=red]{Any text}{you like}
\drawBadge[labelColor=pink, color=black, colorRight=yellow]{Any text}{you like}
\end{tcblisting}

Custom logos can be employed, as in the previous example where an image is loaded to use the logo%
\footnote{Logo of \CTAN is a courtesy of \href{https://gitlab.com/comprehensive-tex-archive-network/ctan-site/-/blob/master/src/artwork/logo/ctan-book-animation-globe.xcf}{\CTAN}.}.

\begin{tcblisting}{title={Customize logo}, lower separated=false}
\drawBadge[logo=\faFilm]{Movie}{5~\faStar}
\drawBadge[logoColor=black, logo=\faHistory, labelColor=yellow]{Any text}{you like}
\def\ctan{\includegraphics[height=1em]{doc/img/ctan-white.pdf}}
\drawBadge[logo=\ctan]{\CTAN}{tikz-shields}
\end{tcblisting}


\vspace{\baselineskip}

The style of the badge can also be chosen:

\begin{tcblisting}{title={Style of badges}, lower separated=false}
\drawBadge[style=flat]{Any text}{you like}
\drawBadge[style=flat-square]{Any text}{you like}
\drawBadge[style=plastic]{Any text}{you like}
\drawBadge[style=for-the-badge]{Any text}{you like}
\drawBadge[style=social]{Any text}{you like}
\end{tcblisting}

As you can see in previous example, the badges are not aligned vertically.
At this point, only \drawBadge[style=social]{social}{badges} are automatically aligned with surrounding text (option \texttt{tcbox raise base} which does not work with \texttt{\textbackslash tcbsidebyside}).

The option \texttt{basline} allows to manually set a vertical shift of the badges, but depend on the text present in the badge, by default it is null.

\begin{tcblisting}{
    title={Baseline%
        \footnote{The implementation of the macro \texttt{\textbackslash showbaseline} is taken from \drawBadge[link=https://tex.stackexchange.com/a/432196/243474, logo=\faStackExchange, baseline=1.8mm]{tex.stackexchange.com}{\texttt{432196/243474}}.}},
    lower separated=false}
\showbaseline{Hello, I'm
\drawBadge[baseline=1.8mm]{Arthur}{Pendragon},
and not
\drawBadge[baseline=1mm]{Louis}{XIV}.
}
\end{tcblisting}

The font used inside the badges can also be changed, either by using the \texttt{font} option where both text will be written with the same font;
either by hard setting the text font.

\begin{tcblisting}{title={Font}, lower separated=false}
\drawBadge[font=\bf, baseline=1mm]{Boldface}{font}
\drawBadge[font=\tt, style=social]{Monospaced}{font}
\drawBadge[style=social]{\texttt{Personalized}}{\textsc{Fonts}}
\end{tcblisting}



\subsection{Clickable badges}


Clickable links can also be set, using the option \texttt{link}.
Another option, \texttt{showlink}, can be used to set whether the colored frame around the button appear.
Note, for document where the links are hidden by default with \textsf{hyperref} (as the present document), this option won't have any effect.

\begin{tcblisting}{title={Clickable badges}, lower separated=false}
\drawBadge[logo=\faWikipediaW, link=https://www.wikipedia.org]{}{Wikipedia}
\drawBadge[logo=\faWikipediaW, showlink=true, link=https://www.wikipedia.org]{}{Wikipedia}
\end{tcblisting}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{Special badges}
\label{sec:special-badges}


Some presets are available.
For each one of them, the default options can be used to overwrite default values (as logo for instance).

\subsection{Git repository}

The \texttt{\textbackslash githubBadge} command creates a badge showing path to a given repository.
By default, the badge is clickable to \texttt{https://github.com/<repo path>} is done.


\paragraph{Syntax:}
\begin{verbatim}
\githubBadge[<options>][<left text>]{<repo path>}
\end{verbatim}

\paragraph{Arguments:}
\begin{itemize}
    \item \texttt{[<options>]} (optional): Key-value options to customize the badge appearance, see above.
    \item \texttt{[<left text>]} (optional): Text displayed on the left side of the badge, by default \texttt{github} (or \texttt{gitlab} or empty for the other commands).
    \item \texttt{\{<repo path>\}} (required): Path to the repository.
\end{itemize}

The prototype is the same for \texttt{\textbackslash gitlabBadge} and \texttt{\textbackslash forgeBadge}.
In the first case, the link redirects to \texttt{https://gitlab.com/<repo path>},
and in the second to \texttt{https://<repo path>}.


\begin{tcblisting}{title={Github badge}, lower separated=false}
\githubBadge{thomas-saigre/tikz-shields}
\githubBadge[logo=\faGit][]{thomas-saigre/tikz-shields}
\end{tcblisting}

\begin{tcblisting}{title={Gitlab badge}, lower separated=false}
\gitlabBadge[color=orange]{inkscape/inkscape}
\gitlabBadge[color=orange][]{inkscape/inkscape}
\end{tcblisting}

\begin{tcblisting}{title={Custom forge badge}, lower separated=false}
\forgeBadge[labelColor=black, logo=\faCode]{code.videolan.org/videolan/vlc}
\forgeBadge[logo=\checkmark][VLC]{code.videolan.org/videolan/vlc}
\end{tcblisting}

In all cases, the generated badge is clickable and redirect to the repository provided.
The icon can be customized, as well as the color.

\subsection{License}


The \texttt{\textbackslash licenseBadge} command creates a badge displaying a license name, optionally with custom options and left-side text.
By default, a clickable badge directing to \texttt{https://creativecommons.org/<license name>} is done.
Note that this webpage may not exist, but the link can either be manually changed, or an empty link can be provided.

\paragraph{Syntax:}
\begin{verbatim}
\licenseBadge[<options>][<left text>]{<license name>}
\end{verbatim}

\paragraph{Arguments:}
\begin{itemize}
    \item \texttt{[<options>]} (optional): Key-value options to customize the badge appearance, see above.
    \item \texttt{[<left text>]} (optional): Text displayed on the left side of the badge (defaults to \texttt{license} in lowercase).
    \item \texttt{\{<license name>\}} (required): Name of the license to display.
\end{itemize}


\begin{tcblisting}{title={License badges}, lower separated=false}
\licenseBadge[link=https://github.com/thomas-saigre/tikz-shields/blob/main/LICENSE]{GPL-3.0-1}
\licenseBadge[][LICENSE]{cc0}
\licenseBadge[link=]{WTFPL}
\end{tcblisting}


\subsection{Publication badges}

The commands \texttt{\textbackslash doiBadge} (as well as \texttt{\textbackslash arxivBadge}, \texttt{\textbackslash halBadge} and \texttt{\textbackslash arxivBadge}) create that redirect to the publication webpage from the provided identification number.

\paragraph{Syntax:}
\begin{verbatim}
\doiBadge[<options>][<left text>]{<id>}
\end{verbatim}

\paragraph{Arguments:}
\begin{itemize}
    \item \texttt{[<options>]} (optional): Key-value options to customize the badge appearance, see above.
    \item \texttt{[<left text>]} (optional): Text displayed on the left side of the badge (defaults to \texttt{DOI}, \texttt{arXiv} or \texttt{HAL}).
    \item \texttt{\{<id>\}} (required): Number of identification of the publication.
\end{itemize}

Other commands with the same prototype are also provided and redirect to different publication platforms, as shown in the following table:

\begin{center}
    \begin{tblr}{
        colspec = {Q[c,m, cmd=\texttt]Q[c,m, cmd=\texttt]},
        row{1} = {cmd=\textbf, bg=default-blue, fg=white},
        vlines, hlines,
        width = \textwidth,
    }
    Macro & Redirection link \\
    \textbackslash doiBadge & https://doi.ord/<id> \\
    \textbackslash arxivBadge & https://arxiv.org/abs/<id> \\
    \textbackslash halBadge & https://hal.science/hal-<id> \\
    \textbackslash pubmedBadge & https://pubmed.ncbi.nlm.nih.gov/<id> \\
    \end{tblr}
\end{center}


\begin{tcblisting}{title={Publication badge}, lower separated=false}
\doiBadge{10.1002/cnm.3864}
\arxivBadge{2503.22907v1}
\halBadge{04918559}
\pubmedBadge{35955000}
\end{tcblisting}