Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/alhassy/org-special-block-extras
A number of new custom blocks and link types for Emacs' Org-mode ^_^
https://github.com/alhassy/org-special-block-extras
badges css emacs extension html lisp melpa org-mode pdf shields
Last synced: about 1 month ago
JSON representation
A number of new custom blocks and link types for Emacs' Org-mode ^_^
- Host: GitHub
- URL: https://github.com/alhassy/org-special-block-extras
- Owner: alhassy
- License: gpl-3.0
- Created: 2020-04-16T21:36:44.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2023-07-21T02:32:28.000Z (about 1 year ago)
- Last Synced: 2024-04-16T00:57:33.999Z (5 months ago)
- Topics: badges, css, emacs, extension, html, lisp, melpa, org-mode, pdf, shields
- Language: HTML
- Size: 10.5 MB
- Stars: 183
- Watchers: 9
- Forks: 15
- Open Issues: 15
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
A unified interface for Emacs' Org-mode block & link types (•̀ᴗ•́)و
Which is used to obtain 30 new custom blocks and 34 link types ¯\_(ツ)_/¯
Abstract
> The aim is to write something once using Org-mode markup
> then generate the markup for multiple backends.
> That is, ***write once, generate many!***
>
> In particular, we are concerned with *‘custom’, or ‘special’, blocks* which
> delimit how a particular region of text is supposed to be formatted according to
> the possible export backends. In some sense, special blocks are meta-blocks.
> Rather than writing text in, say, LaTeX environments using LaTeX commands or in
> HTML `div`'s using HTML tags, we promote using Org-mode markup in special blocks
> —Org markup cannot be used explicitly within HTML or LaTeX environments.
>
> *Special blocks*, like `centre` and `quote`, allow us to use Org-mode as the primary
> interface regardless of whether the final result is an HTML or PDF article;
> sometime we need to make our own special blocks to avoid a duplication of
> effort. However, this can be difficult and may require familiarity with
> relatively advanced ELisp concepts, such as macros and hooks; as such, users may
> not be willing to put in the time and instead use ad-hoc solutions.
>
> We present a new macro, [defblock](org-special-block-extras--defblock), which is similar in-spirit to Lisp's standard
> except that where the latter defines functions, ours defines new
> special blocks for Emacs' Org-mode —as well as, simultaneously, defining new
> Org link types. Besides the macro, the primary contribution of this effort is an
> interface for special blocks that *admits* arguments and is familar to Org users
> —namely, we ‘try to reuse’ the familiar `src`-block interface, including
> header-args, but for special blocks.
>
> It is hoped that the ease of creating custom special blocks will be a gateway
> for many Emacs users to start using Lisp.
>
> **
>
>
>
> A 5-page PDF covering ELisp fundamentals
>
>
>
> ** can be found **[here](https://alhassy.github.io/ElispCheatSheet/CheatSheet.pdf)**.
>
> This article is featured in EmacsConf2020, with slides [here](https://alhassy.github.io/org-special-block-extras/emacs-conf-2020):
> 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!”
# Table of Contents
1. [Installation Instructions](#Installation-Instructions)
2. [Minimal working example](#Minimal-working-example)
3. [Bye!](#Bye)
> The full article may be read as a [PDF](https://alhassy.github.io/org-special-block-extras/index.pdf) or as [HTML](https://alhassy.github.io/org-special-block-extras) —or visit the [repo](https://github.com/alhassy/org-special-block-extras).
> Installation instructions are .
# Installation Instructions
Manually or using [quelpa](https://github.com/alhassy/emacs.d#installing-emacs-packages-directly-from-source):
;; ⟨0⟩ Download the org-special-block-extras.el file manually or using quelpa
(quelpa '(org-special-block-extras :fetcher github :repo
"alhassy/org-special-block-extras"))
;; ⟨1⟩ Have this always active in Org buffers
(add-hook #'org-mode-hook #'org-special-block-extras-mode)
;; ⟨1′⟩ Or use: “M-x org-special-block-extras-mode” to turn it on/off
**Or** with [use-package](https://github.com/alhassy/emacs.d#use-package-the-start-of-initel):
(use-package org-special-block-extras
:ensure t
:hook (org-mode . org-special-block-extras-mode)
;; All relevant Lisp functions are prefixed ‘o-’; e.g., `o-docs-insert'.
:custom
(o-docs-libraries
'("~/org-special-block-extras/documentation.org")
"The places where I keep my ‘#+documentation’")))
Then, provide support for a new type of special block, say re-using the `src`
blocks that, say, folds up all such blocks in HTML export, by declaring the
following.
(o-defblock src (lang nil) (title nil exports nil file nil)
"Fold-away all ‘src’ blocks as ‘’ HTML export.
If a block has a ‘:title’, use that to title the ‘’."
(format " %s
%s
"
(or title (concat "Details; " lang))
raw-contents))
# Minimal working example
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:
#+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):
The above section, , presents a few puzzles to get you
comfortable with `defblock` ;-)
# Bye!
