EightByTen

EightByTen is a Typst package for creating beautiful Tufte-style books with extensive support for marginalia, custom layouts, and automated figures. Ideally suited for technical books, textbooks, and long-form documents.

Features

• Tufte-Style Layout: Authentic wide margins for sidenotes, margin figures, and captions.
• Automated Book Structure: Built-in support for Parts, Chapters, Appendices, and Backmatter.
• Smart Headers & TOC: Automated running headers and Table of Contents generation.
• Code Highlighting: Integrated support for codly with custom styling for clean code blocks.
• Custom Blocks: Semantic blocks for Design Notes, Challenges, and more.
• Configurable Design: Easily customize page size, fonts, and sizes.
• Index Generation: Integrated index support via in-dexter.

Showcase

Here is a glimpse of what you can create with EightByTen:

Getting Started

Local Installation (Recommended)

Since this package is not yet published to the Typst Universe, you must install it locally:

1. Clone the repository:

   git clone https://github.com/peterfriese/eightbyten.git
   cd eightbyten

2. Install the package: This uses just to package the library and install it to your local Typst data directory (under @local/eightbyten).

   just install

3. Use it in your project: Import the package using the @local namespace:

   #import "@local/eightbyten:0.2.0": *
   
   #show: eightbyten.with(
     title: "My Awesome Book",
     authors: ("Jane Doe",),
     publisher: "Tech Press",
     book: true,
   )
   
   #chapter("Introduction")
   Welcome to my book!

Using the Template

Once installed locally, you can initialize a new project using the template:

typst init @local/eightbyten my-new-book
cd my-new-book
typst watch

Alternatively, you can manually copy the template directory to your project.

Usage

Document Structure

Wrap your content in frontmatter, main content, and backmatter:

#frontmatter[
  #dedication[To my cat.]
  #toc()
  #pagebreak()
  #list-of-design-notes
]

#mainmatter[
#mainmatter[
  #include "parts/01-beginning.typ"
  #include "parts/02-conclusion.typ"
]
]

#backmatter[
  #appendix-part("Appendices")
  #include "chapters/99-appendix.typ"

  #special-appendix("Index")
  #make-index(title: none, outlined: false)
]

Chapters & Parts

Inside the main matter, include part files. Current best practice is to put each Part in its own file (e.g., parts/01-foundations.typ) so you can add introductory text:

// parts/01-foundations.typ
#part("Foundations")

This part covers the basic building blocks...

#include "../chapters/01-basics.typ"

And inside your chapter file (e.g., chapters/01-basics.typ), start with #chapter():

// In chapters/01-basics.typ
#chapter("The Basics")

Here is the content of the chapter...

You can also add an "eyebrow" above the chapter title:

#chapter("Typography", eyebrow: "Design Principles")

Sections & Subsections

To ensure correct nesting in the PDF outline, use the provided wrapper functions instead of raw markdown signatures (like ===):

#section("Assessment")
This is a section (Level 3).

#subsection("metrics")
This is a subsection (Level 4).

#subsubsection("Failure Modes")
This is a sub-subsection (Level 5).

Marginalia

Add notes to the margin using note() or implicit placement (Tufte-style):

Here is some text with a sidenote.#note[This text appears in the margin.]

Figures

Use notefigure to place simple figures in the margin:

#notefigure(
  image("figure.png"),
  caption: [A margin figure]
)

Use wideblock for wide content that spans the main column and margin:

#wideblock[
  #table(columns: 4)[...]
]

Code Blocks

Code blocks are automatically styled using codly.

```rust
fn main() {
    println!("Hello, world!");
}
```

To disable codly support, set codly-support: false in the configuration.

Custom Blocks

The package includes several semantic blocks:

• Snippet: Use #snippet(filename: "...", info: "...") for file listings.
• Codeshot: Use #codeshot(source: path("file.swift"), image: path("shot.png"), caption: "Caption") for code blocks with a screenshot in the margin.
• Blockquote: Use #blockquote(attribution: "...") for epigraphs or quotes.
• Design Note: Use #design-note("Title") to mark design decisions (can be listed with #list-of-design-notes).
• Challenges: Use #challenges() to mark exercise sections (can be listed with #list-of-challenges).

Configuration

The eightbyten function accepts several configuration parameters:

Parameter	Type	Default	Description
title	string	"Eight by Ten"	Title of the book.
authors	array	()	List of authors.
publisher	string	"..."	Publisher name.
isbn	string	"..."	ISBN text.
book	bool	true	Format as a book (vs article).
repository	string	none	URL to the source repository.
printer-info	string	none	Text for printer info colophon.
paper	string	"8in x 10in"	Page size (e.g., "a4", "us-letter" or none for default).
fonts	dict	default-fonts	Setup for serif, sans, and mono.
debug	bool	false	Show debug frames for layout.
codly-support	bool	true	Enable codly integration.

Font Customization

You can provide your own font family names:

#show: eightbyten.with(
  fonts: (
    serif: "Linux Libertine",
    sans: "Inter",
    mono: "Fira Code"
  ),
  // ...
)

AI Agent Support

This template is AI-Agent Ready. It includes built-in instructions for AI coding assistants (like Google Gemini, Antigravity, Cursor, Windsurf, or GitHub Copilot) to help them understand the project structure and Tufte-style conventions.

• AGENTS.md: Contains a comprehensive guide for AI agents on how to write content, structure the document, and use the package's features.
• GEMINI.md: Examples or specific prompts for Google Gemini (if applicable).

To use this with your AI assistant, simply reference template/AGENTS.md in your prompt or context.

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

Local Development

To develop eightbyten locally:

1. Clone the repository.
2. Install the package locally:

   just install

3. Run the verification:

   just verify-template

License

MIT