Emacs org-mode examples and cookbook (2017) | Hacker News Reader

Emacs org-mode examples and cookbook (2017)

ehneilsen.net

258 pointsddtaylor78 comments

Org mode is my documentation secret weapon. I write books, presentations, technical documentation, and even literate data migration scripts.

Some added tips: ditaa is cool but you can also integrate mermaid [0] well and display inline images. There's a well-done revealjs [1] exporter. And you can also use results blocks as input to other code blocks!

PDF export is excellent and integrates well with some scripts I wrote to publish them to my remarkable. Great for writing and then reviewing specs on the go.

The drawback is that sharing the document sources with a team is hard since so few people on a team are likely going to be emacs users. Only work around I have for that is to run emacs in batch mode to generate/export docs... or just export to markdown and maintain in markdown if the team uses a different tool or dislikes the org syntax.

[0] https://mermaid-js.github.io/mermaid/#/

[1] https://github.com/yjwen/org-reveal

I am breaking the guidelines [0] in good faith to link to a mirror. Host limit exceeded on the author's blog (Thu 11 Mar 2021 01:07:37 AM UTC).

https://web.archive.org/web/20210122070120/http://ehneilsen....

[0] https://news.ycombinator.com/newsguidelines.html

This is a nicely timed article, i'm thirsty for emacs.

I dived into emacs in janurary 2021 fully using doom emacs. I started doing scrum and meeting notes in org, then find myself slowly switching existing notes over to it.

i keep all my emacs configs from ~/.doom.d in git and can easily bounce from machine to machine. Setup is pretty easy and i've found to have the same emacs experience where I go.

Don't you think an org-mode for TeXmacs would be even better?

Why would it be better?

Org-mode can generate latex output but the whole point is to be a more human-readable markup format than latex. Org-mode can also convert your equations to images and display them inline.

TeXmacs is a great looking piece of software, but I've never understood the name. I don't think it uses TeX underneath the hood, nor does it use Emacs.

I switched to Spacemacs around the same time you picked up Doom and dropped Spacemacs for Doom around a month ago.

I'm not really a note taker, and I haven't picked up org yet. I actually uninstalled it before I realized that all the Doom docs are written in it and without org-mode you can't follow links XD

I've been using spacemacs for a while, haven't looked into doom. Mind telling me why you decided to switch?

I also switched from Spacemacs to DOOM. I've decided to stay.

Reasons:

- DOOM Emacs is fast. Fast to start `emacs --daemon`, fast UX with the default config.

- I've experienced DOOM Emacs to be more cohesive than Spacemacs

I still keep my Spacemacs config around, but I haven't touched it in ... almost a year now.

The startup speed of DOOM Emacs is outstanding, as others have noted.

Additionally, I've found adding my own customizations is much easier in Doom than Spacemacs. While the Spacemacs "layers" approach is nice for setup, it can become very brittle when you start hacking on it yourself. Some of that could also be due to my own lack of skill with elisp, though.

I enjoy the way Doom is organized. You can overcome any startup timing problems in emacs by using daemon mode whether it's doom, space, or stock.

I tried to do a dive into emacs in the Dec 2020 because of what i read a bout Org, but i just hit too many stability issues on my MBP with Doom - just went back to vimwiki after 2 wasted evenings. :/ Maybe someday.

Didn't click for me until I needed to work on a Pinebook Pro that didn't have the juice for VSCode. After a full day of working with Emacs I'm a convert. The hardest things to grok were minibuffers and how every named command run with M-x is just an Elisp subroutine. After that Emacs just feels like a huge library of text manipulation functions, ergo, Editor MACroS.

I love org. I wish it was used by more apps as portable storage/format across platforms. I recently scratched my own itch and wrote an iOS habit tracker app, backed by org mode https://news.ycombinator.com/item?id=26306018

I've came to love asciidoc too, much simpler and clearer syntax. But the support is still too limited (and require a ton of libraries)

Well, org-mode obviously has very powerful features; but I am rather avoiding Emacs and prefer my https://github.com/rochus-keller/CrossLine for note taking and information management; I can already generate navigable HTML pages for hand-out and I intend to implement an Asciidoc and LuaTeX export too.

That looks as great application, thank you. I am not now hot to download all dependencies, and especially Qt as dependency is overkill. Did you see Leo editor? It works similar. Emacs works well on console and in GUI, so it is not just GUI application, that is big advantage. If you develop SQL application like that, I suggest you develop API in the same time and have the editor rather use the API, so that any other language can access the Outline structure you are creating. I wish I could run it, try it out, but dependencies are too much.

The two available binary downloads for Windows (see http://software.rochus-keller.info/CrossLine_win32.zip) and Linux i386 are static builds with Qt statically linked, so no other dependencies; the Windows binary also works well with Wine on Linux and Mac; both only a few megabytes uncompressed.

Didn't know Leo; will have a look at it. My preferred IDE is Qt Creator 3.x.

I have tried it, it says something like: bash no file found, and there is no -h or --help option to know more about invokation. In general, it does not work on GNU Hyperbola/Linux-libre free OS, based on Arch Linux.

Have you tried the Windows version with Wine? Never had an issue with that.

Maybe you can check the Linux version with ldd and file, i.e. whether it misses a specific system library version or maybe your system is 64 bit and not all required i386 parts are present.

Org mode is plain text. Basic text editing in Org style may be done with any editor. Let us say those features to enter TODO or change state from TODO to DONE or PENDING, could work faster if then in other editor exists macro function. With macro functions you can pretty fast prepare basic Org functions. Folding headings is maybe something that cannot be easily implement in other editors.

Vim has Org mode too https://github.com/jceb/vim-orgmode

Those mobile editors usually do not have macro functionality. But as soon as you have editor with macros it is possible within some 30 minutes to make few macros to add tags, change TODO states, add SCHEDULED or DEADLINE stamps or similar basic features.

Org mode has a lots of features. Many people likely use just a small subset of features but it is also likely that these subsets differ for different people.

I like simple outline mode. In the Emacs development version it folds now with TAB on the heading, so that is maybe one of major options. I could insert "TODO" but is not necessary. Org integrates many things together. But it is not my main note taking application. I am using PostgreSQL for note taking and exporting assignments, tasks, etc. from the database into the Org mode. It is quite different workflow.

Org is not collaborative, database is collaborative, redundant, it offers way easier development then trying to handle database things by using text.

By the way, people speak "Org mode is plain text", that is was back in time, today Org mode is everything else but plain text.

That looks pretty sweet! I might send you an email.

Couple questions first, if you don't mind:

- What's the sync integration surface like? My ~/org lives in Dropbox, so I'm hoping that's an option.

- Any plans for Siri and notifications integration? Sounds like that might be outside your use cases, so a "no" here is totally fair, but I'm still curious.

Side question, do you have any especially good resources around Swift and/or iOS UI/UX design that you might want to recommend? Asking because it looks very much like I'm about to pivot into app dev via React Native, and I'm looking to make the most of the opportunity, especially as it comes to iOS.

Thanks in advance, and here's hoping your habits app becomes everything you want it to be!

> I might send you an email.

Sure! Ping flathabitsatxenodium.com for a TestFlight invite.

> - What's the sync integration surface like?

Relies on other apps to sync. If iOS Files app can get access to it, the habits app will too (including conflict resolution). Dropbox seems to work. I could use more testing in this space if you’re keen.

> - Any plans for Siri and notifications integration?

Notifications are supported. Hadn’t considered Siri. Will give it more thought.

> Asking because it looks very much like I'm about to pivot into app dev via React Native

The app is native SwiftUI.

You likely know all these... WWDC videos are great. Generally, hackingwithswift.com is great too. Also dimsumthinking.com has high quality material.

Discussed at the time:

Emacs org-mode examples and cookbook - https://news.ycombinator.com/item?id=13828732 - March 2017 (161 comments)

https://web.archive.org/web/20210122070120/http://ehneilsen....

Org is great. I recently hooked up my working notes directory to our gitlab instance at work. With git auto-commit-mode I can show my colleagues nicely formatted notes. When I need to export to word I can do that with pandoc.

I wish I used babel more. Last I used was to give live examples for some external API interactions we needed to document.

gotta admit using external code as org-table formula was a nice trick

http://ehneilsen.net/notebook/orgExamples/org-examples.html#...

also, even though calc rpn stack is cute, having it in SRC blocks is quite dandy

This is excellent. Been using Emacs/org for all my writing projects for a year now, and this site gives a wonderful overview of many things I have learned the hard way. - Thank you for sharing this.

I like orgmode and emacs and wish to convert more activities into orgmode.

One thing I found tricky was switching computers or getting a new computer can be very disruptive to the emacs/orgmode workflow because of the amount of customizations that build over years of using a specific orgmode workflow. Apps, on the other hand, are very portable between devices (phone, table, laptop).

Are there easy solutions to make emacs and orgmode set ups more portable between machines?

Depends. checkin to a vc repo?

Emacs config in github, org notes in dropbox.

I did this for a little while, but now I just use org notes on my work computer, and the ios notes app for personal things. Org need not consume everything.

I've found that using use-package in my init.el to manage, install and customize my packages helps me run a reasonably similar emacs setup across my Linux and Windows computers. I use git to synchronise it across systems.

  (use-package wordnut
    :ensure t  ;; install package if it doesn't exist
    :config
    (global-set-key (kbd "C-c w") 'wordnut-search))

If I want a package to only load on Linux or windows, I can do it so:

  (use-package xclip
    :if (eq system-type 'gnu/linux)
    :ensure t
    :config
    (xclip-mode 1))

  (use-package w32-browser
    :if (eq system-type 'windows-nt)
    :ensure t)

I wish there were a way to pin/lock the version of dependencies. Each time I update all packages something new breaks, and I have to spend time tracking it down and fixing or reverting it. So I've just been syncing my entire .emacs.d folder.

If you are using Linux, you can already do with with Guix-installed emacs packages. Otherwise, I think straight.el is adding this feature in the future.

Thanks, I didn't know about straight.el. Looking into that and the Doom distribution that is built on top of it. Looks far more sane.

> So I've just been syncing my entire .emacs.d folder.

That's one solution.

I've got mine under Git. It's a bit more "work" in that when I upgrade packages (which I don't do all the time) I need to commit what's been deleted/added but I can at any time go back to any past working setup.

Then I just use Git across user accounts / machines to synch my Emacs setup.

Others are using Nix.

> Each time I update all packages something new breaks...

Don't know what's the "proper" way to do it but I upgrade packages manually and never all at once. That is: I never start from an empty Emacs. There are some tradeoffs I guess but I never have to track down which package is problematic and reverting is basically checking out the last commit.

I'm not saying it's the best way to do it but it just works.

In addition to nix and guix, which have been mentioned, you can also use straight.el[0]. It's a functional package manager for emacs, so you'd use it instead of package.el. It checks out the git repo for each package and maps package name->commit hash in a nice little file, which you can then commit to git. Then, on a new machine, it will check out that specific rev for all your packages.

It even has nice use-package integration, so if you're already using that you likely won't have to change all your config.

[0]https://github.com/raxod502/straight.el

Plus 1 to this. I've adopted straight.el a little while ago and I've been especially loving how easy it makes hacking on my installed packages. Now that they're version controlled, I can easily try things and back them out if they don't work. And more importantly I can remember the tweaks I've made, because there's a readily-available diff. With regular package.el it was nearly impossible to keep track of little changes I had made and preserve them across upgrades or transfer them to another machine.

I want to love org-mode, but I made the early mistake of trying to export some of my data in a coherent format. It seems okay for keeping organized, but it's a disaster as an archive or a publishing platform, in no small part because of the workflow issues you mentioned.

Yes that's currently my problem as well. What kind of things were you trying to export?

Try Doom emacs (lots of sane defaults) plus vc repo with hostname dependent config (so email or use specific things don't spill).

This doesn't solve the direct issue, but I use emacs --daemon and either use it to edit files on other computers, or ssh into my main computer to access the daemon directly. It really simplified my workflow trying to get configurations in sync.

I've used syncthing. Other than occasional "i forgot to save on one machine" issues it works great.

If you are on Windows, my understanding is that it's pretty easy to create a portable emacs setup that you store in, say, your Dropbox or $preferred-sync-platform that would keep things central.

But yeah, otherwise, it's a problem. I've grown very dependent on org and emacs, but access anywhere but my two laptops is kind of painful and kludgy.

I can use BeOrg, but BeOrg seems to have been built to support an orgmode use pattern that is very different from mine.

I can also ssh into my Ubuntu vm from my iPad, and obviously THAT experience is fine, but it's also more of a production than I'd really like if I just want to briefly interact with the org files.

Honestly, I don't really try to integrate everything into Org-mode. I use it very heavily for planning and tasking of programming projects, for example, because if I'm programming something, I'm already doing that in Emacs anyway. Likewise for time tracking in contract work, or projects where that's othwrwise needed. And I use Org for writing, for much the same reason: I do that in Emacs, anyway. But for general-purpose calendaring, reminders, and so on, it's much easier and more convenient to just run a CalDAV/CardDAV service that everything else integrates with OOTB.

I do keep my ~/org in Dropbox and have a phone app I can use to make quick edits, and which I have used for longer writing on trains and such. But it's definitely not a first-class UI, and I don't try to use it as such.

(On the other hand, I'm getting ready to redo my blog in Jekyll rather than Wordpress, not least to improve the authoring workflow by being able to bring it into Emacs...)

We're in kind of the same place. Org is indispensable for my work life, but it's not EVERYTHING and isn't the core of my overall life, because it's not really a great option for on-the-go.

I use an Exchange calendar for work, and I don't have appointments as part of my agenda in Org. I carry a notebook with me when I'm out and about for jotting things down. Like you, I can get to my corpus of org files via Dropbox from my phone and whatever editor I want to use there, but that's more of an "in a pinch" kind of use case than anything I'd want to do on the regular.

If I need to write something real on the go, I just do it in Notes on the iPad, and then migrate it into org if that's where it needs to go when I'm back at my computer.

I still blog, too, but I use a dedicated tool called MarsEdit on my Mac to do it. I haven't seen a reason to move that into Emacs, though I'm sure it's technically possible.

You should be able to cover the 99% cases by making your ~/.emacs.d a Git repo and cloning it as part of setting up a new machine. This will bring along all your installed packages as well; 'package-list is a customization and thus preserved with your init, and #'package-initialize will install any missing packages it finds when called.

(Speaking of preserved customizations, by default those are written into ~/.emacs.d/init.el. As part of setting up for a version-controlled ~/.emacs.d/, I'd strongly recommend setting 'custom-file to e.g. ~/.emacs.d/custom.el, so that those are stored separately from your init logic proper - it's not a huge issue either way, but customizations are a fertile field for merge conflicts due to the way they're written and stored, and I find this makes those conflicts significantly more comfortable to resolve.)

You could in theory also add init logic to check for the presence of needed external binaries and, if necessary, install them via Homebrew, apt, or some Windows equivalent - I've thought about doing this since I already do have some platform-specific logic in my init, but it hasn't been enough overhead to bother since I rarely need to spin up a new workstation machine.

(Also, of course, ensure that you store any secrets like passwords or other credentials in a separate file, not checked into version control.)

To ensure you reliably have a specific version of Org, you can add the orgmode.org ELPA [1] to your 'package-archives and install a given version from there, rather than relying on whatever comes with a given Emacs build. I do this myself and recommend it to others; Org changes a good deal between versions in my experience, so version pinning helps avoid unexpected behavior that has otherwise been fairly common.

In the same spirit, it can be worth building Emacs from source on a new machine. I also do this, again in order to ensure the behaviors of a specific version to which I've become accustomed; I generally upgrade only when a major new feature or bug fix makes it strongly worthwhile, and then on all my machines at once. (It's a manual process, but not a difficult one. I guess I could automate it, but for something I do a few times a decade, that hasn't seemed worth it so far.)

[1] https://orgmode.org/elpa.html

(Just to add a quick corrigendum here - you need to separately invoke #'package-install-selected-packages, after #'package-initialize and adding your ELPA repos, to install missing packages. Sorry for the error! It had been a few years since I needed to set up Emacs on a fresh machine, until last weekend when I did so and discovered the omission.)

Yes, keep your ~/.emacs.d in Dropbox. I have been doing that for I think 10 years or so. It works very well.

I haven't used drop box before, how do you keep synced? Do you access it the .emacs.d through a symlink? do you copy it over to ~ and copy back when you make changes? Do you use it directly from the Dropbox "local" folder? I'm currently using git to push/pull but it would be nice if it was more automated.

Dropbox keeps it synced, that is its function. I simlink from ~/.emacs.d into Dropox. Its fairly seamless, you change it in one machine and it just pops up in the other.

I have been using Emacs (Python and C/C++) and Org for a few years now. Org's HTML export is a godsend feature.

I use org-mode all the time and do a lot of plotting with Python and matplotlib and for some reason the snippet

  #+BEGIN_SRC python :var fname="delseepy.png" :var delsee=delsee :results file
  import matplotlib.pyplot as plt
  
  x, y, z = zip(\*delsee)
  
  fig = plt.figure()
  axes = fig.add_subplot(1,1,1)
  axes.plot(y, z, marker='o')
  fig.savefig(fname)
  
  return fname
  #+END_SRC

has never worked for me. I have to remove the "return" keyword on the last line. Not sure if this is an org-mode issue or related to the Python version (the author seems to be using Python 2).

Is each block converted into a function? Otherwise it's a syntax error.

Yes they are, for me that exact snippet is fine

This has been my limited experience with everything related to Emacs - fragmented tutorials on how to do x that work with someone's specific setup. And when you start looking around for fixes you get solutions for "this is how I do this with Prelude", "this is built-in", "my customized Spacemacs setup..." and at that point I throw my hands in the air, admit to myself that I'm not a real man and go back to VSCode.

It is so. Emacs contains the full Emacs manual, non-fragmented, compact and complete, including the full Org mode manual, non-fragmented. It is self-documenting program. Users can learn what is built-in feature and what exists before starting to use extensions.

If you try to do too much at once, of course, you are prone to give up as you started on a too high gradient.

I think I'm a pretty adept emacs user, and I've relied at least ten times more on crappy informal documentation in blogs, StackOverflow etc. than on the real stuff.

I do that too, but out of habit from other pursuits rather than a real necessity. Recently, I've found myself going to Emacs and packages' internal help first, and I usually find what I'm looking for. Despite me spending several years not believing it, it's really good documentation for the most part.

> admit to myself that I'm not a real man

Note, many emacs users aren't men at all.

I know. It's a figure of speech, not a reference to the demographics of emacs users.

certainly not, they are gods

You might have to check the value of =org-babel-python-wrapper-method=, which defines the format of the created temporary file to which the source block is exported so it can be executed properly.

After installing matplotlib using pip3 and changing =org-babel-python-command= to python3 I was able to execute this example without a problem.

The value of =org-babel-python-wrapper-method= for me is:

  def main():
  %s

  open('%s', 'w').write( str(main()) )"

I have found that over time org documents tend to become coupled somewhat to your Emacs configuration and are not generally portable. I guess this is the reason why many org example snippets on the net do not really work exactly the same.

There is a package which lets you interact with ipython kernels instead. You might want to check that out.

https://github.com/nnicandro/emacs-jupyter

I have tried with both python 2.7.18 and python 3.8.6 using Emacs 27.1 and the excerpt works without issue for me; I have no configuration (emacs -Q) beyond pointing org to my virtual environment and allowing python evaluation in org-babel:

  (org-babel-do-load-languages 'org-babel-load-languages '((python . t)))
  (setq org-babel-python-command "~/mpl-venv/bin/python")

Are you perhaps on an outdated version of Emacs?

There have been a few different fixes around the "last line" return value over the years[0][1] but I can't really remember something like your example not working for me personally.

[0]: https://lists.gnu.org/archive/html/emacs-orgmode/2017-11/msg...

[1]: https://orgmode.org/list/87pnfdo88v.fsf@gmail.com/t/#u

I used to use Markdown for all my personal notes. Now I use org-mode. Part of what made this possible was finding Working Copy on iOS so I could view and edit my org-mode documents.

It makes me very happy that GitHub supports formatting your README in org-mode.

I've been dreaming of a full Lisp port of Emacs to get rid of all the baremetal C routines and GNU libraries. Just write the whole thing in Racket or something similar.

It's been done:

https://en.wikipedia.org/wiki/Multics_Emacs

> Multics Emacs is an early implementation of the Emacs text editor.[1] It was written in Maclisp by Bernard Greenberg at Honeywell's Cambridge Information Systems Lab in 1978, as a successor to the original 1976 TECO implementation of Emacs and a precursor of later GNU Emacs.

https://en.wikipedia.org/wiki/EINE_and_ZWEI

> EINE and ZWEI are two discontinued Emacs-like text editors developed by Daniel Weinreb and Mike McMahon for Lisp machines in the 1970s and 1980s.

[snip]

> Unlike the original TECO-based Emacs, but like Multics Emacs, EINE was written in Lisp. It used Lisp Machine Lisp.

The only one you might be able to run natively now is Hemlock:

https://en.wikipedia.org/wiki/Hemlock_(text_editor)

> Hemlock is a free Emacs text editor for most POSIX-compliant Unix systems. It follows the tradition of the Lisp Machine editor ZWEI and the ITS/TOPS-20 implementation of Emacs, but differs from XEmacs or GNU Emacs, the most popular Emacs variants, in that it is written in Common Lisp rather than Emacs Lisp and C—although it borrows features from the later editors.

Anyone know if it's possible to tag a paragraph, or non-heading element, in org?

I do this in a sort of roundabout way, by actually using a new heading for each paragraph (helps with outlining). You can make this work by adding the :ignore: tag to the headings, which means that the heading titles won't be exported when you export the document, but the text under them will. Basically, you get an invisible outline of your document that you can tag however you like.

It requires some light setup to get working, since it's not part of the base functionality of Org. First, add these lines to your config (more details on StackExchange[1]):

  (require 'ox-extra)
  (ox-extras-activate '(ignore-headlines))

Now you can add the :ignore: tag, and any other tags you want, to the heading for any paragraph. When you export, you'll just get the paragraphs, not the headings or tags.

[1] https://emacs.stackexchange.com/questions/38184/org-mode-ign...

That's pretty neat, thank you! I'll give that a go.

I suppose radio target links function a bit like inline tags, in a way, in that wrapping a string in <<<angle brackets>>> and C-c'ing it turns every use of that string in the file into a C-o'able link to the original radio target. Definitely not as featureful as proper :tags: but also has it's uses...

As a sibling parent mentioned, you can tag an element by inserting it into it's own heading and adding the :ignore: tag.

I feel this functionality is overlooked, and it is in my opinion one of the most powerful features implemented in org, as it allows you to add "meta" groupings to your org document without any effect on the content.

Without the :ignore: tag, there is a strict semantic relation between org-mode document headings, as physically indicated by the * at the beginning of a line, and the corresponding hierarchical level of the heading's content.

With the :ignore: tag, however, you separate content from form. Headings with :ignore: work just as headings for your file.org document: you can search for headings, link to them, add IDs and properties and whatever else you can do with headings. But when you export your document, the heading no longer exists and thus has no impact on the hierarchical level of its content.

Why is this interesting? Well, because if content is separated from form, we can build things where the same content assume multiple forms depending on whatever context we define.

I used this in combination with other org-mode tags, "#+exclude_tags" and "#+include" directives to build my Ph.D. thesis with org mode and have my thesis chapters be exportable both as thesis chapters as well as standalone publications. Shameless plug: https://github.com/dangom/org-thesis

It should be straightforward to extend the idea to presentations and other formats as well.

Very inspiring! Thank you.

Is there a way to view live preview of org file? Say in the next window.

Despite being a plain-text format, it can be made very human-readable with minimal configuration. If you want to auto-export to your preferred format on save, say, and view it live in a parallel window, you can accomplish that with a single line of Emacs Lisp. This is what Emacs is all about: if you can do anything with a tiny little elisp function, there isn't exactly a clear bulleted list of what the "features" of an application are. Some people really like that.

Reply on news.ycombinator.com