Append multiple code blocks to a single noweb reference

By on 2024-05-05 (originally published on 2023-05-08)

Org replaces noweb references to code blocks. For example, a code named code block like this: 

#+name: articles
#+begin_src html
  <li><a href="/one/">My first article</a></li>
#+end_src

Can be added to another code block by using a noweb reference: 

#+begin_src html
A list of my articles:

<ul>
  <<articles>>
</ul>
#+end_src

Which produces an HTML snippet like this: 

A list of my articles:

<ul>
  <li><a href="/one/">My first article</a></li>
</ul>

To append multiple code blocks to a single reference, use the noweb-ref header argument for multiple code blocks: 

#+headers: :noweb-ref articles
#+begin_src html
  <li><a href="/two/">My newest article</a></li>
#+end_src

#+headers: :noweb-ref articles
#+begin_src html
  <li><a href="/one/">My first article</a></li>
#+end_src

By using the <<articles>> reference like before, both code blocks are added to the document: 

A list of my articles:

<ul>
  <li><a href="/one/">My first article</a></li>
  <li><a href="/two/">My second article</a></li>
</ul>

Block separators

By default, the included blocks are separated by a single newline. To change the separator, set the :noweb-sep header on each block that has a :noweb-ref header1: 

#+headers: :noweb-ref articles
#+headers: :noweb-sep "\n\n"
#+begin_src html
  <li><a href="/two/">My newest article</a></li>
#+end_src

#+headers: :noweb-ref articles
#+headers: :noweb-sep "\n\n"
#+begin_src html
  <li><a href="/one/">My first article</a></li>
#+end_src

Which produces the following output: 

A list of my articles:

<ul>
  <li><a href="/one/">My first article</a></li>

  <li><a href="/two/">My second article</a></li>
</ul>
  1. Technically, only setting the :noweb-ref on the first block would suffice, the separator is only added between code blocks. ↩︎