doom.d

My Doom-Emacs configuration.

Introduction

This is my Emacs configuration, my Hotel California of Creative Writing.

It features all the bells and whistles that I could ever want from a writing environment, and nothing else.

This configuration, like most (if not all) Emacs configurations, is highly opinionated. Unlike most, I think, it is also highly focused, and does very few things outside of writing prose.

For a very detailed walk-through of what this configuration provides, see https://jacmoe.github.io/hccw/

The walk-through is currently a work in progress. This notice will be removed once it gets finished.

Prerequisites

First, make sure that you have at least Emacs 28.1 installed, and have made sure that Git and the other prerequisites of Doom-Emacs are satisfied: Doom-Emacs - Prerequisites

On my Fedora system, that was accomplished by installing:

sudo dnf install emacs fd-find ripgrep

———————————

This configuration uses the following external dependencies:

C compiler

org-roam uses a custom SQLite binary to store its database, and it will compile it when it installs. So there must be a C compiler available to Emacs.

On Linux, there is likely to be a C compiler installed.

Aspell

We use Aspell for spellchecking:

sudo dnf install aspell aspell-en

Vale

Vale.sh is used for prose linting.

The easiest way to install Vale is to download a binary release from Vale Github Releases and put the binary in your PATH. Emacs needs to be able to find the Vale binary.

Now you need to download some Vale style checkers. There is a list of the available styles here: errata-ai/packages.

I installed the following styles:

proselint : Releases · errata-ai/proselint
- “proselint places the world’s greatest writers and editors by your side, where they whisper suggestions on how to improve your prose.”
write-good : Releases · errata-ai/write-good
- “Naive linter for English prose for developers who can’t write good and wanna learn to do other stuff good too.”
alex : Releases · errata-ai/alex
- “Helps you find gender favoring, polarizing, race related, or other unequal phrasing in text.”
joblint : Releases · errata-ai/Joblint
- “Test tech job posts for issues with sexism, culture, expectations, and recruiter fails.”
readability: Releases · errata-ai/readability
- “implementation of many popular ‘readability’ metrics.”

Download and extract into a place where they can easily be found, like in ~/vale-styles for instance.

Now you can place a .vale.ini file in any top level directory where you want Vale to check your prose.

An example:

StylesPath = /path/to/vale-styles
MinAlertLevel = warning

[*]
BasedOnStyles = proselint, write-good, alex, joblint, readability

See the Vale home page for more information.

To make Emacs actually check your document, run M-x flymake-mode. Run M-x flymake-mode to turn it off again.

Mermaid

Mermaid is used to generate Gantt charts and other diagrams.

Install npm if not already installed:

sudo dnf install npm

Then, install mermaid-cli:

npm install -g @mermaid-js/mermaid-cli

The command-line client needs Chromium (or Chrome), and it needs to be told where it is.

Create a configuration file in your home directory, called puppeteerConfigFile.json:

{
  "executablePath": "/usr/bin/chromium"
}

Hugo

I use Ox-Hugo to export and generate an Epub, and to write blog posts, and if you want that, you need to install Hugo.

Get the latest version from https://github.com/gohugoio/hugo/releases/latest - choose the Extended version.

While you can find Hugo in the software repositories for your particular operating system it is often an older version, and many newer Hugo themes requires a very recent Hugo.

PDF diff and export

In order to be able to export excellent PDFs using LaTeX, we need to install TeX Live.

Installing the following satisfies the requirements of the Org-mode LaTeX / PDF exporter on my system:

sudo dnf install texlive-collection-bibtexextra texlive-collection-latexextra

Fonts

This configuration uses the Overpass font. Mono for code, and the regular font for writing. Install both (Overpass Mono and Overpass) on your system so that Emacs can use them.

For Unicode emojis, install an emoji font like Segoe UI Emoji

If you want to use your own fonts, do change the configuration, around line 32 in config.el or in .secret.el (recommended).

Maim and Gifsicle

For creating gif screencasts, we use Maim and Gifsicle. Install maim and gifsicle using your package manager of choice.

sudo dnf install maim gifsicle

Installation

Hotel California

Clone the Hotel California repository into ~/.doom.d, like this:

git clone https://github.com/jacmoe/.doom.d ~/.doom.d

Doom-Emacs

Make sure that there isn’t a .emacs.d directory on your machine. If you are running Emacs, there is, so you need to either delete or rename it.

To install Doom-Emacs, clone it into .emacs.d , and run the Doom-Emacs installation script:

git clone --depth 1 https://github.com/hlissner/doom-emacs ~/.emacs.d

~/.emacs.d/bin/doom install

Don’t try to run Emacs just yet!

What you can do, however, is check the installation by running the Doom-Emacs doctor, like so:

~./.emacs.d/bin doom doctor

It should run without errors or warnings, but if it doesn’t, you should be able to fix the issues in most cases based on what the doctor orders.

You need to change some variables around line 20 in config.el, the location of personal dictionary, bookmarks and Org folders. Also be sure to change the personal information around line 40, and enter the path to puppeteerConfigFile.json that you created earlier.

Probably a good idea to add ~./emacs.d/bin to your PATH, for example by adding it to your exports in .bashrc.

Now, fire up Emacs, and you should be looking at the Hotel California of Creative Writing starting screen.

All you need to do now is to press C-x C-f and start making yourself comfortable with your new writing environment.

You might want to read the extensive guide here: https://jacmoe.github.io/hccw/, or at least have it ready as a reference.

Happy Writing!

jacmoe / .doom.d