How to allow page break inside a float environment?

Question

I'm using new float enviroment to show some examples in my document. This enviroment contains tcolorbox which provides a gray background. The main text in the enviroment is a mixture of plain text and code blocks (in lstlisting env). Each float should have it's own caption and label.

In style file:

\usepackage{newfloat}
\DeclareFloatingEnvironment[name={Example}]{suppfigure}

In the main document:

\begin{suppfigure}[!h]
\caption{Some code example}\label{suppfigure1}
\begin{tcolorbox}[arc=0mm, left=1pt, right = 1pt, boxrule=0mm,colback = {shadow-gray}] 

Text

\begin{lstlisting} 
int i = 0; 
\end{lstlisting}

Some more text

\begin{lstlisting} 
String.Format("{0,10:0.0}", -123.4567);  
\end{lstlisting}

\end{tcolorbox} 
\end{suppfigure}

How can I allow page break inside the suppfigure to extend my example to multiple pages?

Answer 1

Floats cannot be broken across pages—they will continue to float until they fit a page or the document ends, whichever comes first. It appears (from usage of !h, which is not recommended, by the way) that you're trying to absolutely position this float anyway.

So my recommendation is to use the capt-of package to place a caption on a non-floating element, since tcolorboxes can be broken across page boundaries through the use of the breakable library.

Since you did not provide a complete MWE, I have made some assumptions about your document in the following code sample.

Code

\documentclass{book} 
\usepackage{listings}
\usepackage{lipsum} % for dummy text to extend over a page break
\usepackage[breakable]{tcolorbox} % load with breakable library
\usepackage{newfloat}
\DeclareFloatingEnvironment[name={Example}]{suppfigure}
\usepackage{capt-of} % captions for non-floating elements

\begin{document}

\captionof{suppfigure}{Some code example}\label{suppfigure1} % place the caption
\begin{tcolorbox}[%
  breakable, % make the box breakable
  arc=0mm, 
  left=1pt, right = 1pt, 
  boxrule=0mm,
  colback = {gray}, % since shadow-gray was not defined
] 

Text

\begin{lstlisting} 
int i = 0; 
\end{lstlisting}

\lipsum % to extend over a page break

\begin{lstlisting} 
String.Format("{0,10:0.0}", -123.4567);  
\end{lstlisting}

\end{tcolorbox}

Referring to Example~\ref{suppfigure1} works as expected.

\end{document}

Output