# Orbit Documentation

Orbit lets you interleave recurring prompts into your writing. When used well, these prompts can help people reliably remember what they read, understand complex topics more easily, and stay connected to ideas over time.

## Getting started

Orbit's designed to work anywhere on the web. At the moment, you can embed Orbit using a Web Component which can be used in any HTML page. Setup is easy: add one <script> tag, then you can use special <orbit-reviewarea> and <orbit-prompt> tags anywhere on the page to insert prompts. Here's an example:

<html>
<script type="module" src="https://js.withorbit.com/orbit-web-component.js"></script>
<body>
<orbit-reviewarea color="red">
<orbit-prompt
question="What's the working name for Andy's experimental mnemonic medium platform?"
></orbit-prompt>
<orbit-prompt
question="What's the new-ish web technology used to embed Orbit prompts into web pages?"
></orbit-prompt>
<orbit-prompt
question="Given a right triangle with legs of length $a$ and $b$, what is the length of hypotenuse $c$?"
answer="$$c = \sqrt{a^2 + b^2}$$"
></orbit-prompt>
</orbit-reviewarea>
</body>
</html>

Here's a live demo of the review area that code would produce:

That's it! You can publish that web page as it is. Your readers will be prompted to sign into Orbit if they haven't already. The prompts they answered will be saved to their account. Next time they have prompts ready for review, they'll be notified by email and provided a link to the Orbit review interface, which displays prompts aggregated from all the sites they've visited.

You don't have to do anything special to register your site, though in the future I'll allow you to register URLs so that you can see reader analytics.

## Configuring review areas

### Prompts support simple formatting

The question and answer attributes support a subset of Markdown formatting. In particular, you can use inline styling and multiple paragraphs. You can use LaTeX by enclosing inline math in $symbols and display blocks in$\$ symbols, as in the example above.

You can attach an image (PNG, GIF) to the question or answer by specifying a URL using the question-attachments or answer-attachments attribute, as in the example above. You may omit the question or answer attributes if an attachment is present. Note that you must supply an absolute URL, not a relative URL like /toffoli.png. Your image will be cached on Orbit's servers, and changes to its contents may not propage reliably. If you need to update an image, you should also change its URL.

Support for videos, multiple images, and custom layouts is forthcoming. Please let me know if these absences are blocking you to help me prioritize.

### Review areas have colors

You'll notice that review areas have a color attribute. Each site can choose the color it would like its Orbit prompts to be. Then, when readers are reviewing prompts from multiple sites, they'll see your prompts rendered in the color you chose—providing a little bit of context. The supported color values are: red, orange, brown, yellow, lime, green, turquoise, cyan, blue, violet, purple, and pink.

### Orbit relies on page metadata

When readers review one of your prompts in their follow-up sessions, Orbit provides context by displaying a link to the page containing those prompts. The interface may also display progress grouped by "source" pages. It's important to make sure that metadata is correct. Here's the information Orbit extracts from your page and how to customize it:

• Page title: Orbit will use the og:title OpenGraph meta tag if present on your page. If that's absent, it will use the value of the <title> tag.
• Canonical URL: If your content can be viewed from several URLs, it's important to inform Orbit of the canonical URL so that it can group prompts correctly. Orbit will use the canonical link element if available; otherwise, it will use the page URL.
• Site title: Orbit's interface may group prompts from different pages of your site. To label that group, it will use the og:site_name OpenGraph meta tag if present.

Here's an example <head> demonstrating these values:

<head>
<title>Obesity - Our World in Data</title>
<meta property="og:title" content="Obesity">
<meta property="og:site_name" content="Our World in Data">
</head>

### You can include multiple review areas on a single page

It's common to use several <orbit-reviewarea> tags on the same page, interleaving them every few hundred words. Orbit currently assumes that all the review areas which appear on a web page should be considered part of the same single piece of content. This works fine for long-form content but will produce confusing results in e.g. a blog layout which displays many posts' contents on one big page. Orbit will eventually allow finer-grained configuration here; please let me know if your site needs this to help me prioritize.

If you have several orbit-reviewareas in one page, you can avoid repeating the color attribute on each of them by specifying the color in the page's <head> tag, like this:

<head>
<meta property="orbit:color" content="violet" />
</head>

### The current prompt type is meant for memory practice

The existing prompt interface and scheduler are tuned to questions which help people remember and internalize what they read. I believe it's also possible to use Orbit to prompt reflection, self-authorship, texts which extend over time, and so on. Please let me know if you're interested in exploring these use cases; we can figure out how to extend the interface in a way that suits your text.

While you're writing and revising your prompts, you may want to enable a "test mode" which won't save of your actions to your account. To do this, append ?orbitDebug to your URL. So for instance, if you're viewing http://you.com/test, point your browser at http://you.com/test?orbitDebug. If the URL already has a ? in it, add &orbitDebug instead, e.g. http://you.com/test?id=4 becomes http://you.com/test?id=4&orbitDebug. And if your web server redirects http://you.com/test to http://you.com/test/, you'll want to visit http://you.com/test/?orbitDebug.