Back to the schedule
Previous: Emacs development update
Next: Incremental Parsing with emacs-tree-sitter

Powering-up Special Blocks

Musa Al-hassy

Download video

Download compressed .webm video (29.2M)

Users will generally only make use of a few predefined `special blocks', such as `example, centre, quote', and will not bother with the effort required to make new ones. When new encapsulating notions are required, users will either fallback on HTML or LaTeX specific solutions, usually littered with `#+ATTR' clauses to pass around configurations or parameters.

Efforts have been exerted to mitigate the trouble of producing new special blocks. However, the issue of passing parameters is still handled in a clumsy fashion; e.g., by having parameters be expressed in a special block's content using specific keywords.

We present a novel approach to making special blocks in a familiar fashion and their use also in a familiar fashion. We achieve the former by presenting ``defblock'', an anaphoric macro exceedingly similar to ``defun'', and for the latter we mimic the usual ``src''-block syntax for argument passing to support special blocks.

For instance, here is a sample declaration.

(defblock stutter () (reps 2)
  "Output the CONTENTS of the block REPS many times"
  (org-parse (s-repeat reps contents)))

Here is an invocation that passes an optional argument; which defaults to 2 when not given.

Emacs for the win ⌣̈

Upon export, to HTML or LaTeX for instance, the contents of this block are repeated (`stuttered') 5 times. The use of ``src''-like invocation may lead to a decrease in `#+ATTR' clauses.

In the presentation, we aim to show a few `practical' special blocks that users may want: A block that …

  • translates some selected text —useful for multilingual blogs
  • hides some selected text —useful for learning, quizzes
  • folds/boxes text —useful in blogs for folding away details

In particular, all of these examples will be around ~5 lines long!

We also have a larger collection of more useful block types, already implemented.

The notable features of the system are as follows.

  • Familiar ``defun'' syntax for making block —``defblock''
  • Familiar ``src'' syntax for passing arguments —e.g., ``:key value''
  • Fine-grained control over export translation phases —c.f., ``org-parse'' above
  • Modular: New blocks can be made out of existing blocks really quickly using ``blockcall'' —similar to Lisp's ``funcall''. We will show how to fuse two blocks to make a new one, also within ~5 lines.

It is hoped that the ease of creating custom special blocks will be a gateway for many Emacs users to start using Lisp.


  • Actual start and end time (EST): Start: 2020-11-29T09.19.39; Q&A: 2020-11-29T09.36.14; End: 2020-11-29T09.48.34


Should packages implement the interface to one specific format, or attempt to be conclusive to all the potential output targets?

How to share "recipes"? Will this become a "large" project, or minimal that requires you to write most customizations yourself?

Could you make slides that show the source form on the left and the output on the right? That would make understanding each capability much simpler.

Does typing in a block mess up the syntax highlighting? Usually themes use a single color inside an example block, for example.

"You found my crutch!". Colors in source code blocks within blocks are hard. Didn't have time yet to implement it. Any help is appreciated! :)

  • That's where you can get help from org-mode core developers ;)

If you export to LaTeX->PDF does that work well with beamer as well? To create slides with columns for example?

You have to format the LaTeX appropriately for the backend "beamer".

How does this relate to pandoc, which is used for converting between markup formats?

Side question about org-reveal: How do you get bespoke/multiple-column layouts without using #+HTML (and
) everywhere in the Org file?

It's a custom #begin_parallel block! See the main article linked below.

Parallel section:

What is used to produce colorful boxes around the cursor in your browser?

Commercial software called ScreenBrush.

Why did you put optional arguments in a separate list rather than using cl-style argument lists? e.g. (defblock feedback (who &optional (color "red")) …)

The first argument may take some meta-information when you define it, which is easier to handle with two arguments.

Do you intend to try to upstream this amazing work into Org? :)

No prior experience on how to upstream; suggestions and help appreciated.

  • Yes, I would suggest simply posting a short proposal for an org-defblock macro on the orgmode mailing list, and hopefully Bastien and other maintainers like Nicolas will discuss it with you. I think they would be excited to have this feature standardized in Org. +1+1+1+1 I am excited+1+1

Add a little beginner-focused documentation and this becomes another great reason to use Org over Markdown, I imagine the maintainers would love to have it.


Sunday, Nov 29 2020, ~ 9:33 AM - 9:53 AM EST
Sunday, Nov 29 2020, ~ 6:33 AM - 6:53 AM PST
Sunday, Nov 29 2020, ~ 2:33 PM - 2:53 PM UTC
Sunday, Nov 29 2020, ~ 3:33 PM - 3:53 PM CET
Sunday, Nov 29 2020, ~10:33 PM - 10:53 PM +08

Back to the schedule
Previous: Emacs development update
Next: Incremental Parsing with emacs-tree-sitter