Perl script to add indentation (leading horizontal space) to LaTeX files. It can modify line breaks before, during and after code blocks; it can perform text wrapping and paragraph line break removal. It can also perform string-based and regex-based substitutions/replacements. The script is customisable through its YAML interface.
GPL-3.0 License
latexindent.pl
is a perl
script to beautify/tidy/format/indent (add horizontal leading space to)
code within environments, commands, after headings and within special code blocks.
It has the ability to align delimiters in environments and commands, and can modify line breaks including text wrapping and one-sentence-per-line.
It can also perform string-based and regex-based substitutions/replacements. The script is customisable through its YAML interface.
It has support for Conda, docker and pre-commit.
latexindent.pl, version 3.24.4, 2024-07-18
Chris Hughes (cmhughes)
Before:
\begin{one}
latexindent.pl adds leading
space to code blocks.
\begin{two}
It aims to beautify .tex, .sty
and .cls files. It is customisable
via its YAML interface.
\end{two}
\end{one}
After running
latexindent.pl myfile.tex
then you receive:
\begin{one}
latexindent.pl adds leading
space to code blocks.
\begin{two}
It aims to beautify .tex, .sty
and .cls files. It is customisable
via its YAML interface.
\end{two}
\end{one}
tl;dr, a quick start section is available for those short of time.
There are many more features available, detailed in full within the documentation.
For complete details, please see:
You'll need
latexindent.pl
LatexIndent/*.pm
defaultSettings.yaml
in the same directory.
You'll need a few readily-available perl modules. Full details are given within the Appendix of the documentation; you might also like to see .appveyor.yml for Strawberry perl users.
latexindent.exe
latexindent.exe
is a standalone executable file which does not require a perl
installation.
It is available at releases page of this repository
and also from https://ctan.org/tex-archive/support/latexindent.
Please see the Linux section of the appendix
latexindent-linux
which should be saved as simply latexindent
. It is available at releases page of this repository
and also from https://ctan.org/tex-archive/support/latexindent.
Please see the Mac section of the appendix
latexindent-macos
which should be saved as simply latexindent
. It is available at releases page of this repository
and also from https://ctan.org/tex-archive/support/latexindent.
conda install latexindent.pl -c conda-forge
this will install the executable and all its dependencies (including perl) in the activate environment.
You don't even have to worry about defaultSettings.yaml
as it is included too.
Full details at using conda.
Important: the executable name is latexindent.pl
(not latexindent
).
docker pull ghcr.io/cmhughes/latexindent.pl
docker run -v /path/to/local/myfile.tex:/myfile.tex --rm -it ghcr.io/cmhughes/latexindent.pl -s -w myfile.tex
Full details at using docker.
You can use latexindent
with the pre-commit
framework by adding this to your
.pre-commit-config.yaml
:
- repo: https://github.com/cmhughes/latexindent.pl.git
rev: V3.24.4
hooks:
- id: latexindent
Full details at pre-commit users,
including a worked example
demonstrating how you can add a .latexindent.yaml
to the root of the git repo to customize the behavior.
A nice way to test the script is to navigate to the test-cases directory, and then run the command (on Linux/Mac -- sorry, a Windows test-case version is not available):
./test-cases.sh
This repository contains a vscode devcontainer configuration that allows developing and testing with GitHub codespaces or vscode devcontainers.
Using GitHub codespaces allows developing in a remote virtual container running
vscode with a preconfigured perl
installation. You can explore this
by clicking on the Code
dropdown at the top of this repository, and click
on 'Codespaces'; see the codespaces details and screenshots for more information.
This script may not work for your style of formatting; I highly
recommend that when you first use the script you use the -o
switch
to output to a separate file; something like
latexindent.pl myfile.tex -o myfile-output.tex
and then check myfile-output.tex
carefully to make sure that
nothing has been changed (or removed) in a way that will damage
your file.
I recommend using each of the following:
latexdiff myfile.tex myfile-output.tex
.I recommend using a version control system to track your files, especially if you intend
to use latexindent.pl
to modify files.
I'm happy to review feature requests, but I make no promises as to if they will be implemented; if they can be implemented, I make no promises as to how long it will take to implement them, and in which order I do so -- some features are more difficult than others! Feel free to post on the issues page of this repository, but please do use the given issue template!
I follow the development model given here: http://nvie.com/posts/a-successful-git-branching-model/ which means that latexindent.pl always has (at least) two branches:
main
develop
The main
branch always contains the released version and develop
contains the
development version. When developing a new feature or bug fix, I typically use:
git checkout develop
git checkout -b feature/name-of-feature
and then I merge it into the develop
branch using
git checkout develop
git merge feature/name-of-feature --no-ff
I align with many of the approaches and details at Dramatically increase your productivity with Atomic Git Commits.
I develop latexindent.pl on Ubuntu Linux, using perlbrew; I currently develop on perl version v5.40.0
The standalone executables latexindent.exe
, latexindent-linux
, latexindent-macos
are created and released by GitHub Actions; the
file that controls this is available within the github/workflows
directory of this repository, and you can track the actions on the actions page of this repository.
I use GitHub actions and AppVeyor
(Windows) as continuous integration services to test latexindent.pl
.
I use git
to track changes in the many test cases listed in the test-cases
directory.
You might like to checkout the following related projects on github.
Thank you to the contributors to the project!
I find that the following quotes resonate with me with regards to my approach to latexindent.pl
:
changelog.md provides details of the history of the project.