Prettifying Org Mode with CSS | Hacker News Reader

Prettifying Org Mode with CSS

sandyuraz.com

179 pointsthecsw51 comments

With some configuration it is possible to _work_ with these styles while editing in Org mode, including the use of variable-width fonts, inline images and formulas, etc. The configuration[1] describes an exemplary process.

It is also possible to tweak the Org mode export mechanism to modify its structural markup to fit projects such as Tufte CSS[2][3].

What the article doesn't explicitly mention is that #+HTML_HEAD: is an instance of In-buffer setting[4]. These can be either added to individual files, or more conveniently, to a reusable _Setup file_ many files could point to (specified by the #+SETUPFILE: in-buffer setting).

1. https://lepisma.xyz/2017/10/28/ricing-org-mode/

2. https://github.com/dakrone/ox-tufte

3. https://jnboehm.gitlab.io/blog/tufte-css/

4. https://orgmode.org/manual/In_002dbuffer-Settings.html

Looking at the screenshots and the CSS in question, and presuming that before it just wasn’t specifying fonts at all, I prefer the “before” result if I’m the consumer, mostly because I like the fonts I set in my browser, and consider Inter and Incosolata a slight regression. Also most of the other styles I disagree with; capping the width and reducing the line-height for headings is about all I actually agree with in there.

But really I think that if this is all you want to change with org-mode HTML output, it must export pretty decent HTML. (I’m not familiar with it.)

(Analysis of the things I particularly don’t like: 1.6 is too large a line-height; I prefer #000 to #444, though I’d settle for #222; image should use max-width instead of width, and have height: auto added, and what’s with the 700px instead of 900px, especially if you’re not going to block and centre it?; border-radius on images seems a bad idea; I dislike gratuitous fiddling with ::selection colours—only touch it if you have actual brand colours that you’re making it align with, like https://wesbos.com/, and be cautious even in that, as is demonstrated in the .highlight on that page which thwarts selection styling.)

Org mode html export is clean by default, yet customizable.

I like that the outline is represented in the dom as nested elements instead of a flat representation. Title, status, tags, properties, description, code and code output are well separated and easy to select through path, I’d and/or class.

Something I enjoy is the "narrow to sub tree" feature that allows to export a nice html rendered export from a part of the document.

I have been using that feature to keep all my uni assignments in the same file. Although I export to LaTeX and not html. Though I can export it as a single large webpage with all the assignments on, and it mostly work.

I mostly prefer the layout of the after, for its added vertical spacing. The one thing I really don't like, and don't understd either, is that they've made the font grey instead of black.

Grey on white has less contrast than black on white which reduces readability - I doubt it can ever increase readability. It's basic human physiology - probably basic physics.

So an open question to all those who describe themselves as UI/UX experts - why do you do this?

I would assume it has something to do with information hierarchy. The more important elements are bigger, bolder, darker. If everything is this way there's less means to draw attention to important information.

EDIT: I can't tell actually if there's differences in color between the headings and body text in this case. If not... shrug

About grey on white, it is said to decrease eye strain. [1]

[1] : https://uxmovement.com/content/why-you-should-never-use-pure...

The responses at the bottom of that article are very interesting, and not necessarily all supportive. But thanks.

If everybody settle on pure white on pure black or the reverse, I can choose the best contrast of my display for myself. Sites that use gray are annoying, and what's worse every sites doing that use a different gray.

And if I use an OLED screen in a completely dark setting, your "not really black" is annoying too: there is more light coming to my eyes, and your website will be harder to read because of the lower contrast. Way more strain on my eyes, clearly. You work against me. Don't choose for me, you don't know my setting and how my eyes work. Fortunately, Dark Reader and Dark Background and Light text both do a good job of setting the right colors to webpages and are customizable.

An extension working the same way to undo these arbitrary choices and to set the desired level of gray for a light background and a dark text would be nice.

Setting the level of gray should not be the designer's choice, because each user is different in this respect. If someone is annoyed by a too big contrast, their screen is probably too bright and they can set it.

If you as a designer try to solve this problem for me as a visitor, you are preventing me from solving this problem in the best possible way, once and for all, for every sites I visit. Please don't mess up with my contrast. I know some people don't know how to configure their display or even that this is a problem and bad display settings are what cause them headaches, but you won't this fix for them, and even may make the problem worse for some of them.

Smaller contrasts are not compliant to the Web accessibility guidelines for a reason.

Good thing that I have screens with sharp contrasts and good eyes though.

Am I missing something?

In my experience, this is completely wrong. I always strain more to read gray text on white background, no exception. I really wish this trend stops.

A darker background, on the other hand, can be helpful in some situations.

> In my experience, this is completely wrong. I always strain more to read gray text on white background, no exception.

I can't know for sure, but it's pretty likely your experience and your observations aren't quite aligned. If the contrast is too low (such that you notice), it can certainly cause more strain. But it's often the case that almost-black registers as black (and almost-white as white) and you don't even realize that's what you're seeing.

That's the entire problem with this theory. The designer does NOT know what my computer screen renders. Not every computer is a Mac with a 400+ nits display or has the same contrast ratio. The optimal "gray" therefore varies across screens.

In my case, anything above #333 is capable of producing problems, the range #333 to approx. #444 is problematic with thinner font weights and anything above #444 is easily, noticeably terrible with anything except heading weights.

I tend to find too high contrasts harder to look at.

This is the CSS included for the lazy:

    /* Originally from http://bettermotherfuckingwebsite.com */
    @import url('https://fonts.googleapis.com/css?family=Inconsolata|Inter&display=swap');
    body {
     margin: 40px auto;
     max-width: 900px;
     line-height: 1.6;
     font-size: 16px;
     color: #444;
     padding: 0 10px;
     font-family: 'Inter', sans-serif;;
    }
    h1,
    h2,
    h3 {
     line-height: 1.2;
     font-family: 'Inter', sans-serif;;
    }
    img {
     width: 750px;
     border-radius: 10px;
    }
    pre {
     font-family: 'Inconsolata', monospace;
    }
    ::selection {
     color: white;
     background: #ff4081;
    }

Org mode by default just uses your user agent stylesheet. Adding some CSS is trivial, so just write your own damn styles instead of adding a sandyuraz.com dependency for no reason.

Adding interactivity on the other hand is more involved. I recommend org-info-js which is what I use with my journals. https://orgmode.org/manual/JavaScript-support.html

The sandyuraz.com dependency might be a good starting point for people who don't know how to make CSS styles, though, or want an example to go off of!

Also, I added back/forward support to org-info-js (along with a GPL license) here: https://github.com/cosmicexplorer/org-info-js. I haven't used it in a bit, but feel free to take the code e.g. from https://github.com/cosmicexplorer/org-info-js/commit/d72b310... if you're looking to improve the default org-info-js situation.

Back/forward with b/B is built in, but I guess additional integration with history doesn’t hurt.

You seem offended someone provided some styles that help along with an easy way to integrate them.

One could easily copy those styles, extend them or host it themselves. Why the vitriol?

I would be supportive if the advice is “copy those styles, extend them or host it themselves”, not adding a dependency that’s bound to be broken sooner or later. There are way too many bloated, slow, or broken websites due to linking to random blurbs from the internet.

Not sure if this was added later, but it says exactly that...

or just use the bare CSS as a starting point to make your own (everyone has their own style)

Author here! I’m not the biggest fan of having thousands and thousands of external dependencies. I’m not too big on frontend but I have been using org mode for couple of years now. Just wanted to share some small adjustments one can make to make results prettier! If I made one for myself, literally anyone can copy it or make their own to their style

I was looking for an Org-Mode type solution for vscode, and was surprised to find that it's basically no longer being actively developed! [1]

Really surprised by this. I would have thought there would be at least a small and thriving community of people that want to use org-mode, but with vscode. What gives?

[1] https://github.com/vscode-org-mode/vscode-org-mode

I was investigating the same last night. There's a reply in the issues though: "There are still people there but not very active on this project currently. But we try to keep it alive !" https://github.com/vscode-org-mode/vscode-org-mode/issues/16...

You can use Emacs just for org mode even if you use vscode for coding.

And once there, you can also code in emacs too. Imho.

I wonder if the people who develop it for vscode... do they gradually start using emacs more and more and give up vscode? :)

Might be because org-mode outside of emacs has little worth, while markdown is more dominating. On emacs you have gazillion tools and apps enriching the org-sphere, which for vs code you would need to replicate all by yourself. And the format itself is just not good enough to survive on it's own IMHO.

The format is only a small part of org-mode. It's an outliner with lots of functionality. If I had to guess, I'd say you either use the full Emacs implementation or an app like Dynalist. A partial implementation in VS Code just doesn't have much of a market.

I use Dynalist, but would love to use FOSS for something this important (I dont use Emacs because it's hard on the eyes and seems to lack all drag and drop support).

Does org mode generally support the kind of infinite nesting Dynalist does? Mostly seeing documents with it and the vscode plugin not even coloring after level 5 anymore indicates to me "no".

Dynalist is great. I'd use it, but I've been burned enough by "free" plans in the past, and $100 a year is a lot more than I'm willing pay when org-mode is available for free. Plus I have to be online to use Dynalist.

I can't speak for the VS Code plugin, but I'm not aware any limits on depth in Emacs. I can't say I often go more than four deep. If you mean zooming (the killer feature of Dynalist IMO) it's possible in Emacs. You can turn the current subtree into its own org file.

I might try out Org mode at some point on desktop, but I also need something for mobile. I know Orgzly exists, but it seems quite clunky. When I'm in jotting-down mode I can add a bullet point every few seconds and I get the feeling that Org mode just isn't quite designed for that.

> You can turn the current subtree into its own org file.

As in "you can not just zoom in within a file"? That'd be super annoying when wanting to focus on one thing quickly.

Regarding being burned by free plans: I don't know how it works for them economically, but in general they seem like incredibly generous and wonderful people. Full export in a plain text format and OPML are one click in the app/CURL request with the right cookies to dynalist.io/backup away. They're quite responsive and nice on Twitter. When the service was down for a few hours pretty exactly a year ago (that means no sync, but the desktop app still works with local data) they gave everyone 2 weeks of premium as an apology (the main benefits are inline pictures and a sideways tree view, so it's not that appealing).

Maybe they'll make me pay at some point and I think it's worth about 5€ per month to me, beyond that it'd get me uncomfortable considering how polished, but fundamentally simple the service is. If there was such a plan I'd actually get it just to support them, since the service is quite amazing.

Long-term I'd like to have a FOSS app that can do more complex graphs than just trees, with different views and such (imagine a relational-type list of things that you can categorize by different attributes), but Dynalist is by far the best thing I have seen so far.

I fear Org mode just quite doesn't fit my use case, as I think it also doesn't save whether a node is collapsed or not.

I use Orgzly on Android, and would also love to have something similar on the desktop. I'm not l33t enough to use emacs for org-mode.

That's sad but understandable. I started using org-mode via the Android app Orgzly, then I used vscode to edit the files Orgzly produced. I found that the vscode solution wasn't able to do everything I wanted, so I switched to Spacemacs.

> That’s why I prefer Dior

What does Dior mean ?

I usually use bootstrap css when I have to publish: https://github.com/marsmining/ox-twbs

I think the author refers to the fashion house Maison Dior: https://en.wikipedia.org/wiki/Dior

Author here! That was me messing around late at night I like to keep my environment very strict and even adding my own dependency was a stretch. I just found a style that works for me and wanted to share it so maybe other people will make their own too! Just applying simple tech for everyday use

beautiful. thanks for sharing

I like the ReadTheDocs one https://github.com/fniessen/org-html-themes#readtheorg

Prettifying org mode export

Two notes:

- https://orgmode.org/ - Org mode is for keeping notes, maintaining TODO lists, planning projects, and authoring documents with a fast and effective plain-text system.

- The main style element here is the max-width setting. The original bare HTML of the 1990s was mostly read in 640 by 480 pixel 14 or 15" CRT screens, with the most fortunate using workstations with megapixel 19" screens. Document width at maximum window size was fine then.

Hmm, I don’t think I ever used a resolution lower than 800x600 in the 90s, and mostly used 1024x768. (Although I only really started being aware of these things in ‘96 or so)

It does make me wonder if the web would have been better off if we had stuck in the direction of personalised styling and simply vended html and nothing else.

Interesting, but i’ve found the html output of orgmode to be maybe too opinionated. For a project that i’ve been trying to launch for a few months now (can’t find the time and with covid-19 and no schools for kids is even worse), I wrote my own org parser and html exporter in clojure. The result is a semantic html output that looks gorgeous with mvp css[0]. I’m planning on releasing this as OSS but need to find time to fix a minor bug in the link parser.

¯\_(ツ)_/¯

[0]: https://andybrewer.github.io/mvp/

There is a solarized version as well which I've used a few times in the past. https://thomasf.github.io/solarized-css

The "before" looks so much better! I really dislike the second layout.

Then don't use this :)

FWIW, Nikola, and probably other static-site generators support Org mode as well.

I’m successfully building sulami.github.io from org-mode using Hakyll, though my setup is quite complex due to my requirements (e.g. PDF output).

I've been trying to do PDF output, from a webpage, basically the saving the output of CMD-P and save as PDF.

Do you have a good method for this?

I wouldn't call it good, but I'm using Pandoc to generate LaTeX. The whole thing is wrapped in Hakyll, which already uses Pandoc to generate the HTML from the source (org/markdown).

Feel free to dig through the source if you want to see how it works: https://github.com/sulami/sulami.github.io

Reply on news.ycombinator.com