Zero to Emacs and Org-roam: a step-by-step guide on Windows 10

[nobiot]

Zero to Emacs and Org-roam: a step-by-step guide on Windows 10

---

• [2020-06-23] Added chapter on Org-ref and ORB
• [2020-06-27] Added chapter on exporting to MS Word with citations and bibliography
• [2020-06-28] Added chapter on getting and setting up a spell checker (Hunspell)
• [2020-07-11] Added auto-install script and a section on how to use it
• [2020-07-18] Added chapter on org-protocol, org-graph, and org-roam-server including editing the Windows registry
• [2020-09-18] Added chapter on working with PDF files in Emacs with PDF-Tools, Org-noter, and ORB
• [2020-12-20] Added a special chapter on making vanilla Emacs look like Doom
• [2021-01-07] Added chapter on inserting an image from the clipboard, or the Snipping Tool on Windows, including in-line display resizing without Imagemagick

---

Hi all, I took the liberty of creating a step-by-step guide for people new to Emacs. I have written this with Windows users with no Linux or programming background in mind, zero about Emacs.

I am hoping this will complement the big efforts @zaeph and the project have been putting in to create quality tutorial series (I’m really looking forward to it).

It will be great if you can let me know your thoughts – constructive critique, correction, feedback for improvement, etc. – I’ll think about a better way of publishing the content for readability. Take this as the first iteration…

Audience and purpose in mind

The audience I have had in mind are:

• New to Emacs
• Windows users (Emacs part should be useful for others, I hope)
• No programming or Linux background
• Looking to use Org-roam / Emacs to help write long-form material (essays / papers about life, humanities, or some qualitative social sciences, etc.) as opposed to math and programming

The guide aims to get you going real quick, starting with downloading Emacs with vanilla configuration (no Doom, no Spacemacs).

Even if you are already down the path of using a framework like Doom, I hope stepping back a little and actually finishing configuration from scratch will help you understand how things fit together – it’s a bit like DIY making stuff; completing one thing from start to finish seems to help you leap to the next level of understanding and confidence for some reason.

What is the outcome?

At the end of Chapter 4 (available now in my repo below), you can get from zero to this:

Where is it?

nobiot/Zero-to-Emacs-and-Org-roam

What’s in it?

I have added a script that automates installation of packages that I describe in this guide up to Chapter 6 on ORB.

Let me know how you go.

Special

Perhaps in time for Christmas, I have changed the gear a bit, and added some decoration to vanilla Emacs.

Extra 2. Make vanilla Emacs look like Doom

Part 1

1. Get Emacs for Windows
2. Use Emacs to write some text (including copy & paste)
3. Set up Org-roam (including sqlite3)
4. Improve quality-of-life with your font, theme, and minimal select packages
5. Some more quality-of-life improvements for your typography – font variations and line-spacing – and other things

The config file at the end of Part 1 is located in this repo, too. Refer to its history if you wish to see the incremental changes as we move along advanced chapters.

Part 2

6. Set up Org-ref and Org-roam-bibtex (ORB)
7. Export to MS Word
8. Set up a spell checker (Hunspell, including how to get it)

Part 3

I consider the following “extra” features because they require a certain level of “hacking the system”. I suggest that you selectively decide whether or not you would like to take on the challenges, depending on your familiarity wth the technical stuff on Windows.

9. Set up org-protocol , org-roam-graph , and org-roam-server (incl. Windows registry)
10. Work with PDF files in Emacs with PDF-Tools, Org-noter, and ORB
11. Insert an image from the clipboard, or the Snipping Tool on Windows (incl. in-line display resizing without Imagemagick)
12. (maybe) How to swap CapsLock with Ctrl
13. (maybe) Export to PDF

[ianian]

It is really helpful for the windows user to use org-roam. BTW I think the graph setup was missing?

I am also looking forward for the step-by-step guide for using the org-roam.

Thank you again for the time and effort.

[nobiot]

Oh, I see, the graph! Slipped my mind. I’ll give it a shot.

Do you use graph?

I don’t use it; I am judging without using it, but I don’t find it useful for me. Maybe I’ll change my opinion after trying it.

Thank you for your comments

[bruce]

There’s a philosophical, and practical, question at the heart of an effort like this, which I applaud: does it really make sense to focus on vanilla Emacs for newbies?

Perhaps so, but I’d at least mention Doom (which makes it easy to set up OR, and much more), and possibly Spacemacs.

[nobiot]

Thank you, bruce. I might come back to Doom, adding a section for it. I use Doom Emacs myself.

Personally, I do not find Doom beginner-friendly.
This is hlissner, the author’s comment:

Generally, if you’re new to the terminal, to programming, or Emacs and/or vim, then Doom (and Emacs, for that matter) will be a rough place to start. Neither Doom nor Emacs are particularly beginner friendly. Emacs’ main draw is its unparalleled extensibility, but anything so extensible has a learning curve.

… But then again, Emacs itself is not user-friendly until you get used to it, I think.

My hope is by sharing my experience of frustration (“my config does not work!?” and wasted time (“how do I copy and paste text in this thing!?”), some of the others can save their time.

[bruce]

@nobiot

… But then again, Emacs itself is not user-friendly until you get used to it, I think.

Yes, this.

[nobiot]

@ianian, Just did a quick set up:

It “sort of” works, but I don’t know if I like the efforts to get to this point. And the program (org-roam-graph.el) may need patching for Windows (for this, I’ll need to dig deeper to confirm my suspicion).

Another issue I see for Windows is, you seem to need an additional layer of complexity if you want to click on the box to navigate into the corresponding note – org-protocol. It’s not a path I would like to tread.

I think I will document as far as I have got, and leave it at it for now. I might come back to org-protocol later, but I’m not super thrilled with changing Window’s register, etc.

[ianian]

Acctually It really make sense. I use Emacs only because of org mode. So I use vanila Emacs. I think there are more users like me.

But of course it is great there is more tutorial for Doom or Spacemacs.

[ianian]

I managed to view the graph on chrom. But I stucked at the org-protocol. I think I could use org-roam at the current condition. I will wait for the futher improvement.

I am looking forward for the full completion of your tutorial with eager.

[nobiot]

Just wanted to let those interested know that I have updated the chapter on Org-ref and ORB. If you have not got them working, this guide might give you a push.

[nobiot]

Published chapter 7 on exporting Org notes to Microsoft Word (.docx) files with using Pandoc and Pandoc-mode. It also talks about how you can personalise your citation style with CSL and Word format with a custom reference template, both with Pandoc.

Exported from the same Org file. Left: customised Word format with an IEEE citation style. Right: Pandoc default.

Also… Completely outside my comfort zone, but I tried putting in a mathematical equation, just to see if it renders well – I cannot really judge this, but here it is:

[nobiot]

Published chapter 8 on getting and setting up a spell checker for Emacs (I use Hunspell).

I also touch on how to switch dictionary languages in Emacs, and (though really not comprehensive) how you might get different languages.

This ends the main body of the guide – from zero to using Org-roam, including some elementary functions that you would expect from a modern text editor for long-form writing (bibliography, export, and spell check). I think my updates from here will become more sparse, but will certainly want to add more. Thank you for your interest!

[ianian]

Please have a new chapter for org-protocol. Or it could be combined in set up the graph function within Org-roam.

Thank you.

[nobiot]

@ianian I’ll see what I can do. Like I said before, I’m not really comfortable with changing registers. But i’m interested, too. I might just give it a shot.

[cobblepot]

Nobiot, great work on this. When I added your org-ref config block to my Doom setup, I got the following error or restart: Error in post-command-hook (org-roam-buffer--update-maybe): (void-variable bibtex-completion-find-note-functions). Also, after trying to insert a citation using M-x org-ref and selecting ‘Insert citation’, I get the error eval-after-load-helper: Symbol’s value as variable is void: bibtex-completion-find-note-functions. Any suggestions to fix?

[nobiot]

I think your error means bibtex-completion-find-note-functions has not been defined at the time Org-roam expects it (org-roam-buffer—update-maybe).

For Doom, you might like to look at ORB’s documentation; they have just added a section on installation for Doom.

Also… It’s strange that bibtex-completion-find-note-functions is void, not nil. ORB defines it in its code. So… ORB may not have been loaded for Org-roam. If you wish to follow the “vanilla” way described in my guide, you might also like to check if you correctly put require ‘org-roam-bibtex like in my example config in the guide, and org-roam is enabled at after-init-hook; the load sequence seems to be a cause of your issue.

[cobblepot]

Thanks. I still have the error after config changes and doom sync/update. Maybe you can comment on the relevant sections of my config:

packages.el:

(package! org-ref)
(package! org-roam-bibtex
  :recipe (:host github :repo "org-roam/org-roam-bibtex"))

;; When using org-roam via the `+roam` flag
(unpin! org-roam company-org-roam)

;; When using bibtex-completion via the `biblio` module
(unpin! bibtex-completion helm-bibtex ivy-bibtex)

config.el:

;; ORG-REF config
;; Set up bibliography
(setq org-ref-default-bibliography '("~/org/zlib.bib"))
(setq bibtex-completion-bibliography "~/org/zlib.bib")
(global-set-key (kbd "<f6>") #'org-ref-helm-insert-cite-link)


;;; BIBLIO config
(setq! +biblio-pdf-library-dir "~/Zotero/Storage/"
       +biblio-default-bibliography-files '("~/org/zlib.bib")
       +biblio-notes-path "~/org/roam/")
;;(setq ivy-bibtex-default-action 'ivy-bibtex-insert-key)

;;; ORG-ROAM config

(defvar my-roam-dir (concat org-directory "roam/"))
; (after! org-roam

(setq org-roam-directory "~/org/roam/"
        org-roam-link-title-format "R:%s" ;;Distinguish internal Roam links from external links
        org-roam-graphviz-executable "/usr/bin/dot" ;; Visualize the relationships with notes
        org-roam-buffer-window-parameters nil)

(setq org-roam-capture-templates
        '(("d" "default" plain (function org-roam--capture-get-point)
           "%?"
           :file-name "${slug}"
           :head "#+TITLE: ${title}\n\n"
           :unnarrowed t)))

;;; ORG-ROAM-BIBTEX config

(require `org-roam-bibtex)
(add-hook 'after-init-hook #'org-roam-bibtex-mode)
(define-key org-roam-bibtex-mode-map (kbd "C-c n a") #'orb-note-actions)

(setq orb-templates
      '(("r" "ref" plain (function org-roam-capture--get-point) ""
      :file-name "~/org/roam/${citekey}"
      :head "#+TITLE: ${title}\n#+ROAM_KEY: ${ref}\n"
      :unnarrowed t)))

;; If you cloned the repository
(use-package org-roam-bibtex
  :after org-roam
  :load-path "~/org/roam/" ;Modify with your own path
  :hook (org-roam-mode . org-roam-bibtex-mode)
  :bind (:map org-mode-map
         (("C-c n a" . orb-note-actions))))

[nobiot]

Hard to tell. I don’t use +roam flag, so I may confuse this further.

Where exactly do you enable Org-roam?
I think your error is caused by the load sequence of Org-roam and ORB. Both need to be loaded at the time when you get the error. Judging from your description, you have only Org-roam loaded.

My humble suggestion is remove +roam for now.
And then you either follow Org-roam’s documentation, and put something like this:

(use-package org-roam
      :ensure t
      :hook
      (after-init . org-roam-mode))

Or equivalently (I think), you put:

(add-hook 'after-init-hook 'org-roam-mode)

[cobblepot]

Removing the +roam flag seemed to break it. The backlinks panel stopped functioning. Maybe @zaeph will have a suggestion?

[nobiot]

OK. I had a look myself.

You can keep +roam.

This should be where Doom enables org-roam-mode

(use-package! org-roam
  :hook (org-load . org-roam-mode)
  :hook (org-roam-backlinks-mode . turn-on-visual-line-mode)
  :commands (org-roam-buffer-toggle-display
             org-roam-dailies-date
             org-roam-dailies-today
             org-roam-dailies-tomorrow
             org-roam-dailies-yesterday)

After looking at your config and others a bit closer, probably your error is cased by either Emacs not knowing where org-roam-bibtex is installed, or load sequence of Org-roam and ORB is confused.

In your config, you doubled up activation of ORB, one is after-init-hook, with org-roam-mode-hook.

(require `org-roam-bibtex)
(add-hook 'after-init-hook #'org-roam-bibtex-mode)
[...]
(use-package org-roam-bibtex
  :after org-roam
  :load-path "~/org/roam/" ;Modify with your own path
  :hook (org-roam-mode . org-roam-bibtex-mode)
  :bind (:map org-mode-map
         (("C-c n a" . orb-note-actions))))

Try the following:

• Remove (add-hook 'after-init-hook #'org-roam-bibtex-mode).
  I think you can keep (require 'org-roam-bibtex)
• Remove :load-path "~/org/roam/".
  You use package! to install org-roam-bibtex, so unless you are sure you have org-roam-bibtex installed in this directory (I suspect it is not), I don’t think you need it there
• If this does not solve the problem, try different :hook

Your config block should look something like below.

(require `org-roam-bibtex) ; not sure if you really need this, but keep for now
(use-package org-roam-bibtex
  :after org-roam
  :hook (org-roam-mode . org-roam-bibtex-mode)
  :bind (:map org-mode-map
         (("C-c n a" . orb-note-actions))))

Or using Doom’s use-package! macro (notice the “!”):

(require `org-roam-bibtex) ; not sure if you really need this, but keep for now
(use-package! org-roam-bibtex
  :after org-roam
  :hook (org-roam . org-roam-bibtex-mode)
  :bind (:map org-mode-map
         (("C-c n a" . orb-note-actions))))

Or…

(require `org-roam-bibtex) ; not sure if you really need this, but keep for now
(use-package! org-roam-bibtex
  :after org-roam
  :hook (org-load . org-roam-bibtex-mode)
  :bind (:map org-mode-map
         (("C-c n a" . orb-note-actions))))

If you still have the same error, then I believe ORB needs to be loaded explicitly before Org-roam.
Then try :hook (ater-init . org-roam-bibtex-mode)

Hopefully, one of them should work.