article.template.tex

\documentclass[a4paper]{article}
\usepackage{fullpage}
\usepackage{graphicx}
\usepackage{xcolor}


\IfFileExists{.git/gitHeadInfo.gin}{
    \usepackage[pcount,grumpy,mark,markifdirty]{gitinfo2}
}{%
    \usepackage[local,pcount,grumpy,mark,markifdirty]{gitinfo2}
}



\usepackage{minted}
\usepackage{natbib}

\usepackage{hyperref}
\usepackage{cleveref}
\title{Template Repository for Articles}
\author{Christophe Prud'homme, Thomas Saigre\thanks{Cemosis, IRMA UMR 7501, Université de Strasbourg, CNRS, France, \tt \href{mailto:christophe.prudhomme@cemosis.fr}{christophe.prudhomme@cemosis.fr},  \href{mailto:thomas.saigre@cemosis.fr}{thomas.saigre@cemosis.fr}}}
\date{\gitReln\  \gitAuthorDate\ (\gitAbbrevHash)}

% Define custom color
\definecolor{CustomBlue}{rgb}{0.25, 0.41, 0.88} % RoyalBlue
% Set up hyperref with the custom citecolor
\hypersetup{
    pdftitle={\@title},
    pdfauthor={\@author},
    pdfsubject={\@subject},
    pdfkeywords={LaTeX, GitHub Actions, Zotero, Overleaf},
    bookmarksnumbered,bookmarksopen,linktocpage,
    colorlinks=true,
    citecolor=CustomBlue,
    linkcolor=CustomBlue,
    urlcolor=blue
}

% Define colors
\definecolor{background}{RGB}{245,245,244}
\definecolor{string}{RGB}{163,21,21}
\definecolor{keyword}{RGB}{0,0,255}
\definecolor{comment}{RGB}{0,128,0}
\definecolor{identifier}{RGB}{0,0,0}
\definecolor{bashkeyword}{RGB}{0,0,128}

% Minted settings
\setminted{
    bgcolor=background,
    fontsize=\footnotesize,
    linenos,
    breaklines,
    frame=single,
    framesep=2mm,
    tabsize=2
}

\begin{document}

\maketitle
\tableofcontents

\section{Introduction}
\label{sec:introduction}

Writing scientific articles using \LaTeX{} offers numerous advantages, including precise typesetting, seamless integration of references, and robust version control.
This template repository demonstrates best practices for organizing \LaTeX{} projects, utilizing GitHub Actions for automated document compilation, managing bibliographies with Zotero, and optimizing image handling.
By following this template, researchers can enhance their workflow efficiency and ensure consistent document formatting across platforms like Overleaf and local \LaTeX{} installations.
The releases assets produced by the GitHub Actions allows to upload the article to HAL, arXiv, Zenodo, etc.



\section{Git Support}
\label{sec:git-support}

The `gitinfo2` package~\citep{brent_longborough_gitinfo2sty_2015} allows \LaTeX{} documents to include information about the current state of the Git repository, such as the commit hash, author, and date. This is particularly useful for versioning and tracking changes in scientific documents.

\subsection{Configuration}

To include `gitinfo2` in your \LaTeX{} document, add the following lines to your preamble:

\begin{minted}[bgcolor=background]{latex}
\IfFileExists{.git/gitHeadInfo.gin}{
    \usepackage[pcount,grumpy,mark,markifdirty]{gitinfo2}
}{%
    \usepackage[local,pcount,grumpy,mark,markifdirty]{gitinfo2}
}
\end{minted}

This configuration attempts to use \mintinline{sh}|.git/gitHeadInfo.gin| if it exists (indicating a Git repository) and falls back to a local file if not.

\subsection{Setting Up Git Hooks}

To automatically generate the \mintinline{sh}|.git/gitHeadInfo.gin| file with each commit, you need to set up Git hooks.
This repository includes the script \mintinline{sh}|a.cli| to simplify the installation of these hooks with the command:

\begin{minted}[bgcolor=background]{sh}
./a.cli setup
\end{minted}

\inputminted[linenos,autogobble,bgcolor=background,fontsize=\small,firstline=6,lastline=23]{sh}{a.cli}

This will copy the \mintinline{sh}|post-commit| and \mintinline{sh}|post-checkout| hook scripts to the .git/hooks directory and make them executable.
These hooks will automatically generate the \mintinline{sh}|.git/gitHeadInfo.gin| and update \mintinline{sh}|gitHeadLocal.gin| file after each commit or checkout.

The file \mintinline{sh}|gitHeadLocal.gin| is used when the document is compiled outside a Git repository, e.g., in Overleaf or in a public archive such as HAL or arXiv.


\subsection{Using GitHub Actions}

The GitHub Actions workflow is configured to run the command \mintinline{sh}|a.cli setup|, ensuring that the Git hooks are set up in the CI environment.
This allows the automated compilation of the \LaTeX{} document to include the latest Git information in the article.

The template article repository workflow uses \citep{cheng_xu_xu-chenglatex-action_2024} \mintinline{bash}{xu-cheng/latex-action} to build the latex document.

The GitHub Action workflow:
\begin{itemize}
    \item Updates the \mintinline{sh}|.git/gitHeadInfo.gin| file with the latest Git information.
    \item Update the BibTeX file from Zotero using the Zotero API, see \cref{sec:export-zotero-library:cli}
    \item Compiles the \LaTeX{} document using \mintinline{bash}{xu-cheng/latex-action} on either the \texttt{ubuntu-latest} runner or the \texttt{self-texlive} runner hosted by the \texttt{feelpp} organization.
    \item Uploads the resulting PDF and a Zip archive of the \LaTeX{} source files as artifacts that can be readily be uploaded to HAL, arXiv, Zenodo, etc.
    \item Creates a release with the PDF as an asset when a new tag is pushed of the type \texttt{v*}, e.g., \texttt{v1.0.0}.
\end{itemize}

\subsection{Full Article Workflow}
\label{sec:full-article-workflow}


Here is a summary of the full workflow for creating and maintaining a \LaTeX{} document with Git support:

\begin{enumerate}
    \item \textbf{Check out the organization:} if the organization is \texttt{feelpp} and a \texttt{self-texlive} labelled runner is online, the compilation will be done using the \texttt{self-texlive} runner other it will use the \texttt{ubuntu-latest} runner.
    \item \textbf{Clone the Repository}:
    Clone the repository to your local machine:
    \begin{minted}[bgcolor=background]{sh}
    git clone https://github.com/your-username/your-repo.git
    cd your-repo
    \end{minted}
    \item \textbf{Set Up Git Hooks}:
    Run the \mintinline[bgcolor=background]{sh}|a.cli| script to set up the necessary Git hooks:
    \begin{minted}[bgcolor=background]{sh}
    ./a.cli setup
    \end{minted}
    \item  \textbf{Compile the Document}:
    Compile the \LaTeX{} document to generate the PDF:
    \begin{minted}[bgcolor=background]{sh}
    pdflatex -shell-escape main.tex
    \end{minted}
    \item \textbf{Make Changes to Your Document}:
    Edit your \LaTeX{} document and add, commit, and push changes to the repository:
    \begin{minted}[bgcolor=background]{sh}
    git add .
    git commit -m “Update document”
    git push origin main
    \end{minted}
    \item \textbf{Create a Tag for Release}:
    Create and push a tag, using SemVer\footnote{\url{https://semver.org}},  to trigger the GitHub Actions workflow for building and releasing the document:
    \begin{minted}[bgcolor=background]{sh}
    ./a.cli create v1.0.0
    \end{minted}
    \item \textbf{Review GitHub Actions Workflow}:
    The GitHub Actions workflow will automatically compile your \LaTeX{} document and upload the resulting PDF as an artifact.
    You can download the compiled PDF from the Actions tab in your repository.
    \item \textbf{Sync with Overleaf}:
    If you are using Overleaf, sync your GitHub repository with Overleaf to ensure you always have the latest version of your document.
\end{enumerate}

By following this workflow, you can efficiently manage your \LaTeX{} documents, keep track of changes with Git, and automate the compilation and release process with GitHub Actions.

\subsection{Document Release}

The `release` script simplifies creating and listing releases for your \LaTeX{} document.

\inputminted[linenos, fontsize=\small, bgcolor=background,firstline=25,lastline=66]{sh}{a.cli}



\begin{description}
    \item[Create a New Release]: To create a new release on GitHub, use the following command:
    \begin{minted}[bgcolor=background]{sh}
        ./a.cli create v1.0.0
    \end{minted}
    \item[List All Releases]: To list all releases, use the following command:
    \begin{minted}[bgcolor=background]{sh}
        ./a.cli list
    \end{minted}
    \item[Delete a Release]: To delete a release, use the following command:
    \begin{minted}[bgcolor=background]{sh}
        ./a.cli delete v1.0.0
    \end{minted}

\end{description}

This script provides an easy interface for managing releases, automating the tagging, updating, committing, and pushing processes.


\section{Image Naming Convention}

To ensure compatibility with platforms like HAL, arXiv, and Overleaf, name your images with the \texttt{img-*} prefix and store them in the same directory as the \texttt{.tex} file.
This makes it easier to manage and upload your images along with your \LaTeX{} document.

\textbf{Example}:
\begin{itemize}
    \item \texttt{img-figure1.pdf}
    \item \texttt{img-figure2.png}
    \item \texttt{img-figure3.jpg}
\end{itemize}

\section{Using References from Zotero}

To manage your references with Zotero, you can either export your Zotero library to BibTeX using the command-line interface or the Zotero API, or you can use the Zotero integration in Overleaf.
Note that these methods are mutually exclusive, meaning you can use either one, but not both at the same time.

\subsection{Export Zotero Library to BibTeX via Command-Line}
\label{sec:export-zotero-library:cli}
\begin{enumerate}
    \item Get a key API for your Zotero account, a read-only key for the group collections is enough.
    \item Define \mintinline{sh}|ZOTERO_API_KEY| in your environment.
\begin{minted}{sh}
export ZOTER_API_KEY=your key
\end{minted}
    \item Update \mintinline{sh}|a.cli| and set \mintinline{sh}|DEFAULT_ZOTERO_GROUP_ID| at the top of the file or set the environment variable \mintinline{sh}|ZOTERO_GROUP_ID| or \mintinline{sh}|DEFAULT_ZOTERO_GROUP_ID|.
    \item Use \mintinline{sh}|a.cli| to export the references.
\begin{minted}{sh}
    bash a.cli update-bibtex
\end{minted}
\end{enumerate}

\subsection{Export Zotero Library via Online or Desktop Interface}
\label{sec:export-zotero-library:interface}
\begin{enumerate}
    \item Open Zotero and select the references you want to export.
    \item Go to \texttt{File > Export Library}.
    \item Choose \texttt{BibTeX} as the format and save the file (e.g., \texttt{references.bib}).
\end{enumerate}

\subsection{Use Zotero Integration in Overleaf}

\begin{enumerate}
    \item Ensure you have a Zotero account and that your references are properly organized in your Zotero library.
    \item In Overleaf, open your project and navigate to the left-hand menu where you can manage your bibliography.
    \item Click on \texttt{Add Bibliography} and select \texttt{Zotero}.
    \item You will be prompted to log into your Zotero account and authorize Overleaf to access your Zotero library.
    \item Once connected, you can select the specific references or entire collections you wish to import into Overleaf.
    \item Your bibliography will be automatically updated in Overleaf as you add or remove references from your Zotero library.
    \item Use standard LaTeX citation commands such as \mintinline{latex}|\cite{key}| to reference your sources directly within the document.
    \end{enumerate}

This method allows for seamless integration, with no need to manually export and upload BibTeX files, as Overleaf will handle the citation syncing automatically.
Note that changes in your Zotero library will reflect in Overleaf after you refresh the project’s bibliography.
Again this method is mutually exclusive with the command-line method or direct export from Zotero interface.

\subsection{Include the Bibliography in Your \LaTeX{} Document}

Add the following lines to your \texttt{.tex} file to include the bibliography:

\begin{minted}[bgcolor=background]{latex}
\documentclass{article}
\usepackage{graphicx}
\usepackage{natbib}
\begin{document}

% Your content here

\bibliographystyle{plainnat}
\bibliography{references}

\end{document}
\end{minted}

\subsection{Cite References in Your \LaTeX{} Document}

Use the \mintinline{latex}{\cite} command to cite references within your document. For example:

\begin{minted}[bgcolor=background]{latex}
As shown by \citet{AuthorYear}, this method is effective.
\end{minted}



\section{Steps to Use the Template Repository}

\subsection{Create a New Repository}
Use the git template repository feature to create a new repository based on this template.

\begin{figure}[h!]
\centering
\includegraphics[width=0.8\textwidth]{img-create-repo.png}
\caption{Create a New Repository}
\end{figure}

\subsection{Clone the Repository}
Clone the repository to your local machine.

\begin{minted}[bgcolor=background]{bash}
git clone https://github.com/feelpp/my-repo.git
cd my-repo
\end{minted}

\begin{figure}[h!]
\centering
\includegraphics[width=0.8\textwidth]{img-repo-test.png}
\caption{Clone the Repository}
\end{figure}

\subsection{Add Your \LaTeX{} Source Files}
Place your \texttt{.tex} file and image files (\texttt{img-*.pdf}, \texttt{img-*.png}, \texttt{img-*.jpg}) in the repository.

\subsection{Commit and Push Changes}
Commit your changes and push them to the repository.

\begin{minted}[bgcolor=background]{bash}
git add .
git commit -m "Add initial LaTeX document and images"
git push origin main
\end{minted}

The GitHub Action workflow will automatically compile your \LaTeX{} document and upload the resulting PDF as an artifact. You can download the compiled PDF from the Actions tab in your repository.

% \section{Overleaf Integration}
%
% \subsection{Sync GitHub Repository with Overleaf}
% \begin{enumerate}
%     \item In Overleaf, create a new project and select \texttt{Import from GitHub}.
%     \item Connect your GitHub account and select the repository you want to sync.
%     \item The sync will trigger the workflow and compile your \LaTeX{} document in GitHub.
% \end{enumerate}
%
% \subsection{Update References from Zotero}
% \begin{enumerate}
%     \item Periodically export your references from Zotero to \texttt{references.bib} and push the updated file to your GitHub repository.
%     \item Overleaf will automatically sync the changes, ensuring your references are up-to-date.
% \end{enumerate}

\section{Conclusion}
\label{sec:conclusion}

This template provides a comprehensive approach for creating and managing \LaTeX{} articles, integrating modern tools and workflow to enhance productivity and collaboration.
By leveraging GitHub Actions for automated compilation, Zotero for reference management, Overleaf for online editing, and VSCode using \LaTeX{} workshop extension for editing, researchers can streamline the writing process and focus more on content creation.
The structured setup ensures consistent formatting and efficient handling of images and references, making it suitable for both individual use and collaborative projects.


\bibliographystyle{plainnat}
\bibliography{references}
\end{document}