Shift margin notes if necessary

[ArquintL]

This PR adds the marginfit package that shifts margin notes similarly as the marginfix would do, however without suffering from issue #169. marginfit's documentation provides an excellent visualization of marginfit's behavior and marginfix's issues.

Just adding marginfit did not produce the desired result and, thus, I've slightly patched the package to feature \marginfit@minoffset, which is set accordingly by kao.sty.
The problem that I've fixed is that if margin notes have to be shifted up (to fit into the margin) then the lowest margin note's baseline (created by \sidecite) and the baseline of the last text line did not match. Strangely, the required offset is different for chapter-start-pages compared to non-chapter-start-pages and I took the average to be as good as possible.

[jboillot]

Hello @ArquintL,
I tried using your PR on the documentation of kaobook (in examples/documentation/) both using pdflatex and lualatex (with the \pdfsavepos renaming you mentionned on stackoverflow), but the \sidecite and marginlisting do not appear in the margins.
Did I miss something? I ran the following command latexmk -pdf -shell-escape main.tex.

Edit: Commenting out the usage of \marginpar in the \marginnote definition seems to correct that problem. I have not investigated further yet.

[ArquintL]

@jboillot I've attached the compiled documentation. I'm using the branch of this PR, ran cp -r ../../* . in examples/documentation, and use latexmk -pdf -shell-escape main.tex.
Could the difference be related to the tex version? tex --version prints TeX 3.141592653 (TeX Live 2025) for me.
In case this is useful for you, I've created two docker images on Docker Hub:

• TeX Live 2025: arquintl/texlive:2025-07-09@sha256:700c89b3bc784f12a4011b62762a73277f1117a14634ee6e1b941d392acaebcf
• TeX Live 2024: arquintl/texlive:2025-02-17@sha256:88a7f24f3476d7f8fdeec61ffd2de41410023a942b568bdc0942f1d76a1065cf

[jboillot]

@ArquintL Thank you for your detailed answer! Indeed, I was using texlive 2023 (2023.20240207-1 which corresponds to TeX 3.141592653, the one from Ubuntu 24.04). Here is the corresponding file: main.pdf.
When testing with texlive 2024 (TeX 3.141592653 (TeX Live 2024)) I get the expected result when using pdflatex, but I still get the wrong one when using latexmk -lualatex -shell-escape main.tex with the pdfsavepos renaming.
Finally, I also tried using texlive 2025 (TeX 3.141592653 (TeX Live 2025)), and that time both versions give the expected result! Moreover, the Minted related problem is also corrected.
(I used maxkratz/texlive:2024 and maxkratz/texlive:2025 images from Docker Hub)

[vbargsten]

Thank you for this modification. FYI, I had to work around a problem with TikZ externalization: the sidecites were placed on each externalized figure and I got a lot of duplicate label warnings. I'm now using the following workaround to prevent this:

\makeatletter
% fix for excluding margin stuff in externalized pictures
\tikzifexternalizing{
\def\marginfit@marginbox{}
}{}%
\makeatother

[fmarotta]

Thank you all. I'm now working on a new version which aims to solve this problem in another way, namely by allowing margin notes to "break" and continue on the next page, much like footnotes (using the package scrlayer-notecolumn from KOMA-Script). However, I'm also considering the marginfit package, since sometimes shifting the notes upwards can be desirable.

[ArquintL]

Interesting idea! However, the vast majority of my margin notes are references for which I probably wouldn‘t like them to break to the next page

[fmarotta]

Good point, I'll make sure to prevent references from breaking. In any case there will also be the option to choose between a floating, fixed, or breaking note on a case-by-case basis.