3

I've written a book using org-mode and I'm trying to export as an HTML/website, similar to this example. That was written using R and Bookdown, but since it all ends up as CSS/HTML, I don't see why the same thing can't be replicated with org-mode.

I've been trying to use org-publish to do this, but I'm running into a few of issues.

1. I can't seem to replicate the book structure of the above example -- it all comes out as one single long HTML file. I'm using separate files for each chapter, and then a main.org file where each chapter is included via #+INCLUDE statements. What is the best way to achieve this? In other words, I want a front page with a TOC, and then each chapter to be a separate page and to have previous and next links for navigation.

2. I've been using the org-ref package to cross-reference figures/tables/sections in the book, but it doesn't seem to work across multiple files. E.g. if I am in chapter 4 and I want to reference something in chapter 2 (using the label: and ref: keywords respectively), org-ref doesn't seem to recognize it. Any way around this?

3. I suppose I could do it manually: publish each chapter separately as a HTML file and have each chapter include file links to the previous and next chapters. But this would be tedious and hard to edit afterwards. Essentially I'm looking to automate the whole process.

Any help is appreciated. Is this easily doable with org-mode, or should I just bite the bullet and learn R and Bookdown?

Improve this question
8
  • 1
    As far as I know, there is no built-in solution for an equivalent to gitbook/bookdown in org-mode. One can get a rough equivalent using a quite heavy customization in elisp and/or bash scripts. Here is an example: ima.circex.org/en/index.html; and the source is: git.lattuga.net/vix/ima-web-and-pdf. However, there is an obvious lack of an easy solution for that. Your question is of a great interest for me and I'll start a bounty for you if you don't get a proper answer.
    – Philopolis
    Jun 3, 2021 at 6:29
  • 1
    This is a great idea, and I'd be very interested in a solution. However, it is really asking multiple (related) questions, which makes it an awkward fit for this site. I suspect some of the issues may be easier to address than others; posting them as separate questions would allow us to narrow down the problem to the hardest parts.
    – Tyler
    Jun 4, 2021 at 14:15
  • 1
    Actually, all these questions are closely related, since they are all part of the whole "bookdown equivalent" question. I would be really interested as well (as my bounty may indicate :)), and I even already thought about writing an Emacs package for that. However, the question 2 (although essential in a bookdown-like workflow) could indeed be asked separately.
    – Philopolis
    Jun 4, 2021 at 14:42
  • 1
    Furthermore, another important detail. In a bookdown-like workflow, each chapter is written in a separate file (thus raising the question #2 above). If you write your book in one single huge org file, this completely solves question #2, but the two others are still perfectly relevant.
    – Philopolis
    Jun 4, 2021 at 14:44
  • 1
    I know nothing about bookdown or Rmarkdown, so I'm not quite sure whether the following helps: you can organize your book with one file per (Org mode) file and create a publishing project to publish each chapter into a separate HTML file. That much is easy. You can use the sitemap feature to get a list of links to the chapters and you can arrange e.g to have the sitemap and the chapter in separate iframes, with the links in the sitemap opening the chapter in the other iframe. The production of the sitemap will have to be modified a bit for that, but I'm pretty sure it's an easy thing to do.
    – NickD
    Jun 5, 2021 at 0:57

1 Answer 1

Reset to default
2
+50

Option 1:

Use a static website generator, such as Hugo, which is external software that natively understands Org-Mode syntax. You will have to build a template that replicates your ideal.

Natively, each Org file is an HTML file. With the ox-hugo package, you can work with one file.

Limitation: Org-Ref only works with LaTeX output.

Option 2:

Convert the Org-Mode files to markdown and use bookdown in Emacs. The ESS package lets you use R in Emacs.

Improve this answer
2
  • 1
    Thanks. Option 2 is probably what I'm going to do. I've thought of the Hugo route, but as far as I'm aware, there's not prebuilt Hugo theme that resembles Bookdown (or similar), and right now I don't think I want to put the time to make my own templates.
    – johnymm
    Jun 9, 2021 at 15:27
  • 2
    It is indeed easier to learn some R than developing a Hugo template. Both are fun to do :) Good luck.
    – Peter Prevos
    Jun 11, 2021 at 5:35

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.