Flowing Content

To fully separate a document's content from its design, we can make use of Flows. Flows are Papermill's way of grouping content together. For example, the body of a document might be in a Flow called "body", whereas the contents of a sidebar could be provided in a "Sidebar" Flow.

Flows are very powerful. They're essential in Papermill for content that spans pages, but they also enable a whole heap of advanced features.

Moving Content to a Flow

In our running example, the content was directly include in a page in the document description:

xml

<press>
  <document>
    <page width="21cm" height="29.7cm" page-margin="2cm">
      <h1>The Evolution of Artificial Intelligence</h1>
      <h2>Key Milestones</h2>
      <ol>
        <li>Turing Test proposed (1950)</li>
        <li>Dartmouth Conference (1956)</li>
        <li>Expert systems boom (1980s)</li>
        <li>Deep learning revolution (2012)</li>
      </ol>
      ...
    </page>
  </document>
</press>

We can achieve the same result by placing the content in a Flow and referring to that flow within the <document>:

xml

<press>

  <document>
    <page width="21cm" height="29.7cm" page-margin="2cm">
      <flow name="body" />
    </page>
  </document>

  <flows>
    <body>
      <h1>The Evolution of Artificial Intelligence</h1>
      <h2>Key Milestones</h2>
      <ol>
        <li>Turing Test proposed (1950)</li>
        <li>Dartmouth Conference (1956)</li>
        <li>Expert systems boom (1980s)</li>
        <li>Deep learning revolution (2012)</li>
      </ol>
    </body>
  </flows>

</press>

When creating the document, Papermill will paint the content into the page. Separating the body Flow makes the template much more readable. We can see exactly what this document is - a single page that contains the body content.

Using Markdown in Flows

Everyone loves markdown, and AI Models are great at generating markdown, so Papermill also supports the use of markdown as an alternative to Press for content flows:

xml

<flows>
  <body type="markdown">
    # The Evolution of Artificial Intelligence
    
    ## Key Milestones
    
    1. Turing Test proposed (1950)
    2. Dartmouth Conference (1956)
    3. Expert systems boom (1980s)
    4. Deep learning revolution (2012)       
    ...
  </body>      
</flows>

Keen-eyed markdown fans will notice that Papermill is automatically removing the indent from the markdown here.

You can also mix markdown and Press, and you can enable your AI model to generate markdown (which they're great at) but also include Press elements when you need the power and expressiveness that Press provides:

xml

  <flows>
    <body type="markdown">
      # The Evolution of Artificial Intelligence
      
      <figure>...</figure>
      
      ## Key Milestones
      
      1. Turing Test proposed (1950)
      2. Dartmouth Conference (1956)
      3. Expert systems boom (1980s)
      4. Deep learning revolution (2012)       
      ...
    </body>      
  </flows>

Flowing Content across Frames

We can now change the design without changing the content. Let's say we'd prefer a two column layout:

xml

  <document>
    <page width="21cm" height="29.7cm" page-margin="2cm">
      <frame width="100%" height="100%" direction="row">
        <frame width="45%">
          <flow name="body" />
        </frame>
        <frame width="10%" /> <!-- divider -->
        <frame width="45%">
          <flow name="body" />
        </frame>
      </frame>
    </page>
  </document>

Press will take content from the body flow until the first frame is filled, then fill the second frame from the remaining content. This enables you to create arbitrary flows of content between frames, which means you can create more interesting and professional designs.

Flowing Content across Pages

Without changing the content, we can also modify the design so that the body content runs over multiple pages:

xml

  <document>
    <repeat flow="body">
      <page width="14.8cm" height="21cm" page-margin="1cm">
        <flow name="body" />
      </page>
    </repeat>
  </document>

The <repeat> tells Press to fill pages with body content until everything in the flow has been typeset. We've replaced the A4 pages with A5 to ensure it requires multiple pages in the final example below.

Even and Odd Pages

Sometimes we want to use different layouts for different pages. In a book, for example, we might want to include the title of a document in the header for a left-hand page, and the author on the right-hand page.

xml

<press>
  <document width="14.8cm" height="21cm" page-margin="1cm">
    <repeat flow="body">
      <page>
        <frame h-align="right" margin-bottom="0.5cm">Mr P. Mill</frame>
        <flow name="body" />
      </page>
      <page>
        <frame>A History of Artificial Intelligence</frame>
        <flow name="body" />
      </page>
    </repeat>
  </document>
  <flows>
    <body>Hi there</body>
  </flows>
</press>

Putting it all together

Here's a complete example for the right-left page alternating design in A5 format:

xml

<press>
  <document width="14.8cm" height="21cm" page-margin="1cm">
    <repeat flow="body">
      <page>
        <frame width="100%" text-align="right" margin-bottom="0.5cm"
               font-color="grey">
          Mr P. Mill
        </frame>
        <flow name="body" />
      </page>

      <page>
        <frame margin-bottom="0.5cm" font-color="grey">
          A History of Artificial Intelligence
        </frame>
        <flow name="body" />
      </page>
    </repeat>
  </document>
  
  <flows>
    <body>
      <h1>The Evolution of Artificial Intelligence</h1>
      <h2>Key Milestones</h2>
      <ol>
        <li>Turing Test proposed (1950)</li>
        <li>Dartmouth Conference (1956)</li>
        <li>Expert systems boom (1980s)</li>
        <li>Deep learning revolution (2012)</li>
      </ol>
      <h2>AI Domains</h2>
      <ul>
        <li>Machine Learning</li>
        <li>Natural Language Processing</li>
        <li>Computer Vision</li>
        <li>Robotics</li>
      </ul>
      <frame width="24pt" />
      <frame>
        <img
          src="https://examples.papermill.io/images/ai-timeline.png" />
      </frame>
      <h2>Impact Timeline</h2>
      <table>
        <tr>
          <th>Decade</th>
          <th>Breakthrough</th>
        </tr>
        <tr>
          <td>1950s</td>
          <td>Theoretical foundations</td>
        </tr>
        <tr>
          <td>1980s</td>
          <td>Commercial applications</td>
        </tr>
        <tr>
          <td>2010s</td>
          <td>Human-level performance</td>
        </tr>
        <tr>
          <td>2020s</td>
          <td>Generative AI explosion</td>
        </tr>
      </table>
      <h2>Looking Forward</h2>
      <p>As we stand at the threshold of artificial general intelligence, the
        next decade promises even more dramatic changes. The foundations laid by
        pioneers like Turing continue to shape our digital future.</p>
    </body>
  </flows>
</press>

Whew, that was a lot of information! We can now paint content flows into frames on different pages with alternating headers. In the next section, we'll add a coverpage to our document, and on the way we'll see how to use page definitions and how to style elements using Press.

Flowing Content ​

Moving Content to a Flow ​

Using Markdown in Flows ​

Flowing Content across Frames ​

Flowing Content across Pages ​

Even and Odd Pages ​