Tired of repeating yourself when writing in Org-mode for LaTeX and HTML
exports? org-special-block-extras is your magical toolkit for
creating custom Org-mode blocks and links that work seamlessly
across backends —without diving into the dark arts of raw HTML or
LaTeX!
- 🎨 Style with ease — add colors, badges, tooltips (from a dictionary, Emacs Help, or custom file), keystroke notations, inline editorial comments, or even colourful ASCII cows with fortune cookies.
- 📚 Glossary support — embed hoverable documentation with
doc:links and auto-generated glossaries. - 📦 Add interactive content: from collapsible detail sections and parallel columns to spoiler tags and equational proofs.
Use badge-style links to embed GitHub stars, Reddit subs, or custom project metadata via
shields.io.- 🛠 Use
org-defblockandorg-deflinkmacros — familiardefun-like syntax lets you define custom Org behaviours.- Create powerful custom blocks with the
defblockmacro: Define a block once and export to LaTeX and HTML effortlessly. With header-args support like like:color red :signoff "Thanks!"for locally customised exports. - Use
org-deflinkto create custom links using a syntax similar todefun.
- Create powerful custom blocks with the
🧱 Ready-to-Use Custom Blocks
| Block | Use Case |
|---|---|
details |
Foldable sections — perfect for hiding spoilers, proofs, or long explanations. |
parallel |
Display content in multiple columns — great for comparisons or saving space. |
margin |
Add subtle explanatory tooltips or side remarks — delightful for scholarly writing. |
box |
Emphasize content with nicely styled borders — great for callouts or side notes. |
spoiler |
Hide content visually until the reader chooses to see it — useful in teaching. |
tree |
Display proof trees and logical derivations — fantastic for formal logic. |
rename |
Automated text substitution — great for translation or glossary effects. |
stutter |
Repeat content multiple times — e.g., for emphasis or stylistic flair. |
solution |
Reveal answers in stages — perfect for educational content. |
org-demo |
Show Org markup alongside its rendered result — ideal for tutorials. |
latex-definitions |
Hide LaTeX-only declarations from HTML — keep your source clean. |
calc |
Step-by-step equational reasoning — beautiful for math walkthroughs. |
Ready-to-Use Custom Links
| Link | Purpose |
|---|---|
doc:label |
Glossary/dictionary tooltips —link to local or global explanations; e.g., cl-loop |
kbd: |
Stylized keybindings with tooltips — e.g., kbd:C-x_C-e. |
color: or red: |
Inline text colouring — supports both names and hex codes. |
html-export-style: |
Pick a visual theme for HTML exports — one click, new style. |
badge: |
Embed project badges — e.g., GitHub stars, Reddit subs, versioning. |
fortune: |
Insert ASCII animals saying jokes or phrases — joy in your docs! |
octoicon: |
GitHub-style icons — for styling and linking like a pro. |
link-here: |
Local anchors — create navigable sections anywhere. |
show: |
Show a variable value — dynamically insert content like your name or version. |
elisp: |
Make clickable actions — buttons that run Emacs Lisp. |
💡 Ideal For
- 🧑🏫 Educators building interactive lessons and glossaries
- 🧑💻 Developers documenting APIs with style
- 📚 Writers crafting scholarly or explorable documents
- ✨ Emacsers who want rich export without leaving Org-mode
- ✏️ Bloggers wanting powerful interactivity
- This is the reason I made this package.
- 1️⃣ Anyone who wants to keep Org-mode as the single source of truth for rich exports
🪄 Just load the package, write in Org, and let defblock handle the
rest. Now your Org-mode documents are not just structured —they're
spectacular.
- Use: “M-x org-special-block-extras-mode” to turn it on/off
Write rich Org-mode documents — one source, many formats.
The org-special-block-extras package empowers you to define and use
custom blocks and links that make your Org files export beautifully
to both HTML and LaTeX, without ever writing raw HTML or LaTeX
again.
See the HTML Article for demos and detailed uses of the block and link types provided by this package.
(An outdated PDF Article demos LaTeX export.)
This article is featured in EmacsConf2020, with slides here: No pictures, instead we use this system to make the slides have a variety of styling information; i.e., we write Org and the result looks nice. “Look ma, no HTML required!”
The following example showcases the prominent features of this library.
#+begin_parallel
[[color:orange][Are you excited to learn some Lisp?]] [[blue:Yes!]]
Pop-quiz: How does doc:apply work?
#+end_parallel
#+begin_details Answer
link-here:solution
Syntactically, ~(apply f '(x0 ... xN)) = (f x0 ... xN)~.
[[remark:Musa][Ain't that cool?]]
#+begin_spoiler aqua
That is, [[color:magenta][we can ((apply)) a function to a list of arguments!]]
#+end_spoiler
#+end_details
#+html: <br>
#+begin_box
octoicon:report Note that kbd:C-x_C-e evaluates a Lisp form!
#+end_box
#+LATEX_HEADER: \usepackage{multicol}
#+LATEX_HEADER: \usepackage{tcolorbox}
#+latex: In the LaTeX output, we have a glossary.
show:GLOSSARY
badge:Thanks|for_reading
tweet:https://github.com/alhassy/org-special-block-extras
badge:|buy_me_a coffee|gray|https://www.buymeacoffee.com/alhassy|buy-me-a-coffee
Here is what it looks like as HTML (left) and LaTeX (right):