How to structure a book project?

Questions
,
1

After reviewing Gaétan Lepage’s thesis (https://forum.typst.app/t/typst-for-a-phd/5098/1) and searching the forum posts and documentation (including that provided for templates), I am still left wondering how best to structure a book project (with front-, main-, and back-matter, endnotes, bibliography, indices, figures, acronyms and glossaries).

I would expect a structure that separates content from layout and isolates external dependencies (as Andrew shows at issues linked from https://forum.typst.app/t/how-to-manage-package-dependencies-in-a-single-place/5767/3).

Also good would be something adaptable to other-than-pdf output formats (html and eventually epub).

Can anyone provide further pointers?

4 Likes
2

I hate to say it, but Typst is not good for source EPUB is a target. EPUB requires content that can reflow, so page numbers won’t be used. I suspect solid EPUB support may not come to Typst for a while.

I’d recommend Asciidoc, or Pandoc-flavored markdown – possibly converting PDF using a Pandoc Template that uses Typst as an intermediate format.

Asciidoc has native support for many more features that books require, but may be limited in regard to styling when compared to LaTeX or Typst.

Markdown → Typst → PDF will give you a lot of control over the final output, but the source doesn’t support complex tables, admonitions, headings that are not included in the TOC, etc. If you are willing to maintain multiple branches, you can have one branch for EPUB that uses HTML for tables and one branch that uses inline Typst for the PDF output. You can also use pandoc filters to add other features like page breaks, abbreviations, acronyms, diagrams, cross-references, figures for tables, footnotes, etc., but this isn’t very easy to set up. While I’ve used this tool for reports and technical documentation, I haven’t used it to create a book.

I created ptp (Pandoc Typst PDF) to help run pandoc with filters for this purpose. You’re welcome to take it. I haven’t packaged my Pandoc → Typst templates and filters anywhere yet. This is similar to Quarto, but something I can understand and targeted towards documentation.

I started down this path after reading this:

https://brainbaking.com/post/2022/11/writing-a-tufte-book-in-markdown/

You could also look at the following process, but XSLT would be a challenge:

  1. AsciiDoc → EPUB
  2. AsciiDoc → DocBook → XSLT → Typst → PDF
3

EPUB export is on the roadmap. For the time being converting the output of Typst’s HTML export (which is greatly improving with each version) to EPUB seems like the simplest, most effective route for producing EPUB files from Typst documents ad the moment.

TBH I really don’t understand the reason behind the detours you mentioned, using other, mediating formats. Why not just write everything in Typst, which is both easy to use and powerful, giving you the full capability of document-specific scripting and existing packages? I see no advantage of converting less capable formats to Typst, only many disadvantages and making the whole process cumbersome.

2 Likes
4

Good to know, but most other tools that support PDF and EPUB either have very limited formatting capability (chapter titles, headings, bold, italic, raster images) to support EPUB (the lowest common denominator) or the source is semantically as in the case of AsciiDoc/DocBook, and the export tools handle styling, and the user is limited in customization so that EPUB and PDF will work well enough.

Given this, I think EPUB will only support a limited subset of the Typst syntax, so you’ll need separate source files for each output target if you want to customize the PDF version heavily. You can manage this with git via branches and selective merging, but it won’t be as simple as AsciiDoc.

5

I’m not exactly sure what you are asking.

When I wrote my PhD thesis (in LaTeX; it was some years ago), I had a hierarchical structure with directories and files (see the source files). Do you mean something like that?

6

I am looking for typst-centric recommendations for structuring the hierarchy.

Gaétan Lepage’s thesis represents one such structuring. Perhaps it is overkill, perhaps not – I would love to see a document describing the purpose of each of the various subdirectories, _indexes, and such.

Other projects as well appear to follow some general mechanisms to separate the content from the underlying scaffolding. Such separation may better enable restructuring of the document for different output mechanisms (pdf, html, some day epub, …) and re-use with other content while preserving the structure, which is useful for a series of publications.

The post is simply a request for what folks consider best practices, and for documentation of how those practices are implemented.

As to recommendations to look to other authoring tools, that is just kicking the ball down the road. There is still need for structure.

Markdown in its various forms, AsciiDoc, and other tools are fine to a point, but they are incapable of producing high-quality typography on their own. Typst offers that as a possibility, and with each iteration gets closer to realizing it. Most of those tools as well are limited in their ability to automatically manage multiple heading styles, complex data handling, chart generation, sophisticated indexing, and such. Again, Typst has that promise.

1 Like
7

Hi, I think that’s a great question!
My understanding is that you’re looking for a boilerplate project, like a template.
Also, the answer must address requirements for the book structure, the page layout, source code directory structure, and others, which is a challenge on their own, let alone in combination.

Book structure

A few years ago I looked at an answer in the TeX StackExchange (link below), I’ll summarize:

Frontmatter:
Cover page
Title page
copyright, ISBN, cataloguing details
Table of contents
List of figures
List of tables

Mainmatter:
Chapters
chapter-01
chapter-02
...

Backmatter:
Appendices
Bibliography
Index

I should also add information specific to PDF files: tags, author, date, etc.

page layout

I think that the Tufte examples are state of the art, but this is a matter of style.

Also, headers and footers can be useful for reports, but not necessarily for general fiction or non-fiction books.
It would be better to consider this information, and remove if not required.

source code directory / file structure

00-style
header.typ
footer.typ
page.typ
pdf-info.yml or pdf-info.typ // perhaps this file belongs to a separate directory?

01-frontmatter

02-mainmatter // multi file structure, separate directory content from images
chapter-01
|-index.typ
|-chapter-01.typ // chapter 01 content
|-chapter-01.md // see comment below
|-images-01
  |-img-01-01.svg

chapter-02
...

03-backmatter
bibliography.typ
bibliography.bib // if the author already has a bibliography database

comment

I also like the idea to completely separate the content from the scaffolding. If this is the case, I wouldn’t dismiss the idea that the author writes the content in Markdown and then converts to typst, using for example pandoc.

conclusion

Simple question, but not so simple answer!

Unfortunately I’m not competent enough in typst, or LaTeX, to show any code, but I would start from the excellent case of Gaétan Lepage which you shared already. In any case, I can help and support, as this can be a project on its own.
Let me know what you think.

references:

https://ctan.org/pkg/memoir

8

Thank you for that, 4_K. I am indeed looking for a template which generates the appropriate directories and perhaps populates some basic components.

Your StackExchange snip largely addresses the format of the book, and not of the typst apparatus that surrounds it.

I am looking for information on typst-related project structures that support the book – how should external resource be marshalled (already answered, I think, but the mechanism Andrew outlined and I referred to in the initial post)? Where do the customizations for the ToC outline go? For the Lists of Figures and Tables (and those need customization – the default settings replicate footnotes from captions.)

In the past I have used LaTeX with the memoir package. I still primarily work with ConTeXt, which I find much easier to use than LaTeX.

My current non-fiction project when presented as a book has a pretty formal traditional structure with an epigraph page, foreward, contents, preface, bastard title, and such at the beginning, and endnotes, biographies, bibliographies, and topic and person indexes on the back side. There is English (mostly modern, but many early modern English extracts), French, Biblical Hebrew, ancient Greek (for some definition of ancient), and more, all of which have different presentation requirements. An html version might look very different from the book, but as much as possible those differences should be reflected in and managed by the external appratus, and not the content sections.

(As to your comment on headings, with 60+ pages of endnotes, you definitely need to be able to fashion headings like “Notes for pages 230 to 236” and, when there is a lot of cross-referencing, headers in the body that reflect section names may be called for as well.)

Markdown may have been used for some of the initial chapter content, but it does not lend itself to semantic markup, whereas the macro capabilities of typst (and tex) provide much greater flexibility. Markdown does not lend itself to automatic generation of text, as generating acronym dictionaries from json/yaml/csv files. Markdown text also requires significant editing for note insertion, quote formatting, citations, indexing, and cross-referencing. Whether it is easier to start with typst (or tex), or start with some markdown flavor, is not a clear-cut choice.

Markdown is fine, however, for less complex documents and I do use that (with Pandoc and custome template files) for memoranda and such.