{"id":13895151,"url":"https://github.com/alhassy/org-special-block-extras","last_synced_at":"2025-04-13T07:50:18.239Z","repository":{"id":39712843,"uuid":"256335447","full_name":"alhassy/org-special-block-extras","owner":"alhassy","description":"A number of new custom blocks and link types for Emacs' Org-mode ^_^","archived":false,"fork":false,"pushed_at":"2024-12-27T01:25:20.000Z","size":11526,"stargazers_count":205,"open_issues_count":16,"forks_count":16,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-04-04T05:08:31.325Z","etag":null,"topics":["badges","css","emacs","extension","html","lisp","melpa","org-mode","pdf","shields"],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alhassy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-04-16T21:36:44.000Z","updated_at":"2025-02-09T23:26:15.000Z","dependencies_parsed_at":"2024-04-16T00:39:52.662Z","dependency_job_id":"756f7619-f7c6-4e0f-a79f-a358c1110c00","html_url":"https://github.com/alhassy/org-special-block-extras","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alhassy%2Forg-special-block-extras","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alhassy%2Forg-special-block-extras/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alhassy%2Forg-special-block-extras/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alhassy%2Forg-special-block-extras/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alhassy","download_url":"https://codeload.github.com/alhassy/org-special-block-extras/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248681494,"owners_count":21144700,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["badges","css","emacs","extension","html","lisp","melpa","org-mode","pdf","shields"],"created_at":"2024-08-06T18:02:02.025Z","updated_at":"2025-04-13T07:50:18.214Z","avatar_url":"https://github.com/alhassy.png","language":"HTML","funding_links":["https://www.buymeacoffee.com/alhassy"],"categories":["HTML"],"sub_categories":[],"readme":"\u003ch1\u003e A unified interface for Emacs' Org-mode block \u0026 link types (•̀ᴗ•́)و \u003c/h1\u003e\n\n\u003ch2\u003e Which is used to obtain 30 new custom blocks and 34 link types ¯\\_(ツ)_/¯ \u003c/h2\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n\u003cdiv class=\"org-center\"\u003e\n\u003cp\u003e\n\n\u003c/p\u003e\n\n\n\n\n\n\u003ca href=\"https://github.com/alhassy/org-special-block-extras/blob/master/tests.el\"\u003e\n\u003cimg src=\"https://github.com/alhassy/org-special-block-extras/actions/workflows/main.yml/badge.svg\"\u003e\u003c/a\u003e\n\n\n\n\n\u003cp\u003e\n\u003ca href=\"https://www.gnu.org/software/emacs\"\u003e\u003cimg src=\"https://img.shields.io/badge/Emacs-27-green?logo=gnu-emacs\"\u003e\u003c/a\u003e\n\u003ca href=\"https://orgmode.org\"\u003e\u003cimg src=\"https://img.shields.io/badge/Org-9.4-blue?logo=gnu\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cspan\u003e\n\n\u003cp\u003e\n\u003ca href=\"https://github.com/alhassy/org-special-block-extras\"\u003e\u003cimg src=\"https://img.shields.io/badge/org--special--block--extras-4.0-informational?logo=Gnu-Emacs\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003ca href=\"https://melpa.org/#/org-special-block-extras\"\u003e\u003cimg alt=\"MELPA\" src=\"https://melpa.org/packages/org-special-block-extras-badge.svg\"/\u003e\u003c/a\u003e\n\n\u003c/span\u003e\n\n\u003cp\u003e\n\u003ca href=\"https://www.gnu.org/licenses/gpl-3.0.en.html\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-GNU_3-informational?logo=read-the-docs\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/alhassy/emacs.d#what-does-literate-programming-look-like\"\u003e\u003cimg src=\"https://img.shields.io/badge/docs-literate-success?logo=read-the-docs\"\u003e\u003c/a\u003e\n\u003ca href=\"https://twitter.com/intent/tweet?text=This looks super neat (•̀ᴗ•́)و::\u0026url=https://github.com/alhassy/org-special-block-extras\"\u003e\u003cimg src=\"https://img.shields.io/twitter/url?url=https://github.com/alhassy/org-special-block-extras\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/alhassy/org-special-block-extras/issues\"\u003e\u003cimg src=\"https://img.shields.io/badge/contributions-welcome-green?logo=nil\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n\u003ca href=\"https://alhassy.github.io/\"\u003e\u003cimg src=\"https://img.shields.io/badge/author-musa_al--hassy-purple?logo=nintendo-3ds\"\u003e\u003c/a\u003e\n\u003ca href=\"https://www.buymeacoffee.com/alhassy\"\u003e\u003cimg src=\"https://img.shields.io/badge/-buy_me_a%C2%A0coffee-gray?logo=buy-me-a-coffee\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n\u003ca href=\"https://alhassy.github.io/about\"\u003e\u003cimg src=\"https://img.shields.io/badge/Hire-me-success?logo=nil\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n\u003ca href=\"https://youtu.be/BQdNhtJSbqk\"\u003e\u003cimg src=\"https://img.shields.io/badge/EmacsConf-2020-informational?logo=youtube\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003c/div\u003e\n\n\u003cdiv class=\"org-center\"\u003e\n\u003cp\u003e\n\u003cb\u003eAbstract\u003c/b\u003e\n\u003c/p\u003e\n\u003c/div\u003e\n\n\u003e The aim is to write something once using Org-mode markup\n\u003e then generate the markup for multiple backends.\n\u003e That is, ***write once, generate many!***\n\u003e\n\u003e In particular, we are concerned with *‘custom’, or ‘special’, blocks* which\n\u003e delimit how a particular region of text is supposed to be formatted according to\n\u003e the possible export backends.  In some sense, special blocks are meta-blocks.\n\u003e Rather than writing text in, say, LaTeX environments using LaTeX commands or in\n\u003e HTML `div`'s using HTML tags, we promote using Org-mode markup in special blocks\n\u003e \u0026#x2014;Org markup cannot be used explicitly within HTML or LaTeX environments.\n\u003e\n\u003e *Special blocks*, like `centre` and `quote`, allow us to use Org-mode as the primary\n\u003e interface regardless of whether the final result is an HTML or PDF article;\n\u003e sometime we need to make our own special blocks to avoid a duplication of\n\u003e effort.  However, this can be difficult and may require familiarity with\n\u003e relatively advanced ELisp concepts, such as macros and hooks; as such, users may\n\u003e not be willing to put in the time and instead use ad-hoc solutions.\n\u003e\n\u003e We present a new macro, [defblock](org-special-block-extras--defblock), which is similar in-spirit to Lisp's standard\n\u003e \u003cdefun\u003e except that where the latter defines functions, ours defines new\n\u003e special blocks for Emacs' Org-mode \u0026#x2014;as well as, simultaneously, defining new\n\u003e Org link types. Besides the macro, the primary contribution of this effort is an\n\u003e interface for special blocks that *admits* arguments and is familar to Org users\n\u003e \u0026#x2014;namely, we ‘try to reuse’ the familiar `src`-block interface, including\n\u003e header-args, but for special blocks.\n\u003e\n\u003e It is hoped that the ease of creating custom special blocks will be a gateway\n\u003e for many Emacs users to start using Lisp.\n\u003e\n\u003e **\n\u003e\n\u003e \u003cspan style=\"color:green;\"\u003e\n\u003e\n\u003e A 5-page PDF covering ELisp fundamentals\n\u003e\n\u003e \u003c/span\u003e\n\u003e\n\u003e ** can be found **[here](https://alhassy.github.io/ElispCheatSheet/CheatSheet.pdf)**.\n\u003e\n\u003e This article is featured in EmacsConf2020, with slides [here](https://alhassy.github.io/org-special-block-extras/emacs-conf-2020):\n\u003e No pictures, instead we use this system to make the  slides\n\u003e have a variety of styling information; i.e., we write Org\n\u003e and the result looks nice. “Look ma, no HTML required!”\n\n![img](images/minimal-working-example-multiforms.png \"Write in Emacs using Org-mode, export beautifully to HTML or LaTeX\")\n\n\u003c!--\n\n\u003e 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) \u0026#x2014;or visit the [repo](https://github.com/alhassy/org-special-block-extras).\n\u003e Installation instructions are .\n\n--\u003e\n\n\n# Table of Contents\n\n1.  [Installation Instructions](#Installation-Instructions)\n2.  [Minimal working example](#Minimal-working-example)\n3.  [Bye!](#Bye)\n\n\u003e 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) \u0026#x2014;or visit the [repo](https://github.com/alhassy/org-special-block-extras).\n\u003e Installation instructions are .\n\n\u003c/div\u003e\n\n\n\u003ca id=\"Installation-Instructions\"\u003e\u003c/a\u003e\n\n# Installation Instructions\n\nManually or using [quelpa](https://github.com/alhassy/emacs.d#installing-emacs-packages-directly-from-source):\n\n    ;; ⟨0⟩ Download the org-special-block-extras.el file manually or using quelpa\n    (quelpa '(org-special-block-extras :fetcher github :repo\n    \"alhassy/org-special-block-extras\"))\n\n    ;; ⟨1⟩ Have this always active in Org buffers\n    (add-hook #'org-mode-hook #'org-special-block-extras-mode)\n\n    ;; ⟨1′⟩ Or use: “M-x org-special-block-extras-mode” to turn it on/off\n\n**Or** with [use-package](https://github.com/alhassy/emacs.d#use-package-the-start-of-initel):\n\n    (use-package org-special-block-extras\n      :ensure t\n      :hook (org-mode . org-special-block-extras-mode)\n      ;; All relevant Lisp functions are prefixed ‘o-’; e.g., `o-docs-insert'.\n      :custom\n        (o-docs-libraries\n         '(\"~/org-special-block-extras/documentation.org\")\n         \"The places where I keep my ‘#+documentation’\")))\n\nThen, provide support for a new type of special block, say re-using the `src`\nblocks that, say, folds up all such blocks in HTML export, by declaring the\nfollowing.\n\n    (o-defblock src (lang nil) (title nil exports nil file nil)\n      \"Fold-away all ‘src’ blocks as ‘\u003cdetails\u003e’ HTML export.\n    If a block has a ‘:title’, use that to title the ‘\u003cdetails\u003e’.\"\n      (format \"\u003cdetails\u003e \u003csummary\u003e %s \u003c/summary\u003e \u003cpre\u003e %s \u003c/pre\u003e\u003c/details\u003e\"\n              (or title (concat \"Details; \" lang))\n              raw-contents))\n\n\n\u003ca id=\"Minimal-working-example\"\u003e\u003c/a\u003e\n\n# Minimal working example\n\nThe following example showcases the prominent features of this library.\n\n    #+begin_parallel\n    [[color:orange][Are you excited to learn some Lisp?]] [[blue:Yes!]]\n\n    Pop-quiz: How does doc:apply work?\n    #+end_parallel\n\n    #+begin_details Answer\n    link-here:solution\n    Syntactically, ~(apply f '(x0 ... xN)) = (f x0 ... xN)~.\n\n    [[remark:Musa][Ain't that cool?]]\n\n    #+begin_spoiler aqua\n    That is, [[color:magenta][we can ((apply)) a function to a list of arguments!]]\n    #+end_spoiler\n\n    #+end_details\n\n    #+html: \u003cbr\u003e\n    #+begin_box\n    octoicon:report Note that kbd:C-x_C-e evaluates a Lisp form!\n    #+end_box\n\n    #+LATEX_HEADER: \\usepackage{multicol}\n    #+LATEX_HEADER: \\usepackage{tcolorbox}\n    #+latex: In the LaTeX output, we have a glossary.\n\n    show:GLOSSARY\n\n    badge:Thanks|for_reading\n    tweet:https://github.com/alhassy/org-special-block-extras\n    badge:|buy_me_a coffee|gray|https://www.buymeacoffee.com/alhassy|buy-me-a-coffee\n\nHere is what it looks like as HTML (left) and LaTeX (right):\n\n![img](images/minimal-working-example.png)\n\nThe above section, , presents a few puzzles to get you\ncomfortable with `defblock` ;-)\n\n\n\u003ca id=\"Bye\"\u003e\u003c/a\u003e\n\n# Bye!\n\n\u003cimg src=\"https://img.shields.io/badge/thanks-for_reading-nil?logo=nil\"\u003e\n\u003ca href=\"https://twitter.com/intent/tweet?text=This looks super neat (•̀ᴗ•́)و::\u0026url=https://github.com/alhassy/org-special-block-extras\"\u003e\u003cimg src=\"https://img.shields.io/twitter/url?url=https://github.com/alhassy/org-special-block-extras\"\u003e\u003c/a\u003e\n\u003ca href=\"https://www.buymeacoffee.com/alhassy\"\u003e\u003cimg src=\"https://img.shields.io/badge/-buy_me_a%C2%A0coffee-gray?logo=buy-me-a-coffee\"\u003e\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falhassy%2Forg-special-block-extras","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falhassy%2Forg-special-block-extras","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falhassy%2Forg-special-block-extras/lists"}