Zanzibar Annotated

Zanzibar Annotated is a hosted copy of the paper presented at USENIX ATC 2019 describing the Zanzibar authorization system. It includes annotations that provide commentary on notable portions of the paper.

Looking for further discussion of the paper? Join our Discord.

Looking to contribute? See CONTRIBUTING.md.

Getting Started

First, run the development server:

cp .env.example .env.local
pnpm install
pnpm dev

Open http://localhost:3000 with your browser to see the paper.

Configuration

All configuration is through environment variables, documented in .env.example. None are required for local development.

Variable	Description
PREVIEW_ENDPOINT	Public base URL of the site, used in share preview image URLs. Defaults to https://$VERCEL_URL on Vercel, and otherwise to http://localhost:$PORT. Set it when self-hosting so previews use your public URL.

Overview

The paper is presented by a reader app developed using the NextJS framework, Tailwind CSS for styling, and MDX for markdown integration in React. The markdown support also includes math typesetting using Katex and GitHub flavored features with remark-gfm.

Features

Paper Content and Layout

Paper content is written in Markdown using GitHub flavored syntax and Katex. The paper viewer app provides additional components that are used to provide layout instructions to emulate the actual published paper. This is in order to preserve the ability to refer to specific column and page numbers of the paper.

Shareable Highlights

A shareable URL is created when paper contents are selected and a visitor to that URL will be navigated directly to that portion of the paper. This functionality is based on the deeplinks.js library.

Annotations

Annotations to paper content can be shown along side the related part of the paper. Additionally, specific parts of the paper can be visibily highlighted and associated with an annotation.

The paper layout component expects an annotations context. The default annotation provider implementation uses YAML files to store all annotations and provides hooks for components to get annotations and annotation related state.

A collection of annotations can be organized into sets. Each set can be toggled on and off and can contain additional metadata to be displayed along side the paper.

YAML format

One YAML file per annotation set.

Annotation YAML file format:

id: <An identifier unique across annotation sets>
label: The short, human readable version of the id
title: The descriptive name for the set
subtitle: Additional description of the set
cta: Short Markdown string for a call to action or link to additional info.
description: Markdown string for additional information about the set.
highlightColor: A tailwind color class name used to color code the annotations and highlights for this set. See https://tailwindcss.com/docs/customizing-colors

(Annotations are organized into groups. Each group has an id such as "page-1-col-2" and each annotation has an id such as "across-applications".)
groups:
  page-1-col-2:
    across-applications:
    ...
  page-2-col-1:
    ...

See the content directory for example.

Linking

An annotation set can be directly linked using a URL fragment in the format:

#annotations/<annotation set id>

An individual annotation can be directly linked using:

#annotations/<annotation set id>/<annotation entry id>

Open Graph Support

Preview images for selections are generated with next/og, and preview text is generated using NextJS server side rendering and JSDOM. This provides a rich preview of the paper content when a shareable link is posted to another site.

The server renders the paper in-process to resolve selections, so no configuration is needed in the dev environment.

Note: The paper viewer app relies on a serverless function to generate the previews. Currently, Vercel is the only tested hosting service.

Host Your Own Paper

Other papers can be hosted using this reader app by providing the paper contents in MDX and deploying on Vercel.

Contribute and get in touch if you do!