circagraph
Sign inSign up

Sharing timelines

Timelines, and the events (moments and durations), searches and views in them, have addresses that open them, previews for social sites and search engines, and embeds for other websites. Everything here applies to timelines on the server; anyone can follow a link to a public timeline, while a private one opens only for its members.

Addresses

Profiles and timelines have addresses like GitHub's (#148):

AddressIs
/<username>A profile: its public timelines and favorites.
/<username>/<slug>A timeline, once its owner has given it a slug.
/<username>/<id>A timeline without a slug. Its ID is a detail of it, so this is its address until then.
/timelines/<id>Any timeline, as before. It leads to the timeline's address.

Everything under a timeline's page is under its address too: /<username>/<slug>/history, …/pulls, …/settings, and its moments' and durations' pages below.

  • Choosing a slug: its owner sets it in Sharing & settings, under Address. A slug is 1–64 lowercase letters, digits, hyphens or underscores, starting with a letter or digit, and unique among its owner's timelines. The field suggests one made from the title. Use its ID removes it.
  • Other addresses lead to it: its ID, /timelines/<id>, a slug it had before and capitals all redirect to the address, with the rest of the path and the query. A slug it had before keeps leading to it until another of its owner's timelines takes that slug.
  • Private timelines: the redirect happens only once the reader may open it, so an address reveals nothing of a private timeline to anyone else. Its pages are not found for them at any address.
  • Names the site uses: usernames that are, or may become, the site's own pages (login, admin, timelines, users, settings and others; RESERVED_NAMES in src/addresses.ts) can't be registered. An account that already has one, such as a first administrator named admin, keeps its profile at /users/<username> and its timelines at /timelines/<id>. /users/<username> otherwise redirects to /<username>.
  • Names that would pass for the site or its staff can't be registered either (#184): root, moderator, staff, support, noreply, postmaster and others (OFFICIAL_NAMES in src/addresses.ts), any name starting with openchronology, and any of these or the site's own names spelled with hyphens, underscores or a number after them (ad_min, sign-in, admin1, root-2). Accounts that already have such a name keep it and their addresses. The first administrator's name, ADMIN_USERNAME, is the operator's choice and may be any of them.
  • Preview images and embeds stay at the timeline's ID (/timelines/<id>/opengraph-image, /embed/<id>).

A timeline's page is at its address. A fragment after it names what to look at:

FragmentOpens
#moment/<id>The timeline centred on the moment, with its details open.
#duration/<id>The timeline around the duration, with its details open.
#search/<words>Search, with these words and their results.
#view/<left>..<right>The timeline between two exact coordinates (#view/-5/2..1.5).

IDs and words are percent-encoded (#moment/leg%3A2 for leg:2). The address follows what is open: opening a moment adds its fragment, and closing it removes it, so the address bar can be copied at any time. Events also have pages of their own, /<username>/<slug>/moments/<id> and /<username>/<slug>/durations/<id>, which open the timeline at them the same way. They are what Share offers, because social sites and search engines read pages but not fragments.

Following a link to an event scrolls the page to the timeline, so it is in view behind the event's details. A moment that the view would count in a group is zoomed into until it is drawn on its own, unless other moments share its time.

The same fragments work for embeds (/embed/<id>#moment/…) and in the editor's own address (#timeline/<id>/moment/…). A link to an event that no longer exists opens the timeline and says so.

Share

Share above the timeline, in an event's details, under search results and, for the current view, in the timeline's context menu (Share this view) opens the share dialog:

  • Copy link, and the device's own share sheet where the browser has one.
  • Facebook, X, LinkedIn, Reddit, Bluesky and email: links to each site's own share page; no script of theirs runs on the platform.
  • Embed on a website: the HTML of an embed, in three sizes.

Social sites and embeds are offered for public timelines only. For a private timeline the dialog gives the link (which only members can follow) and, to its owner, a way to make it public. Unsaved moments and edits cannot be shared until they are saved.

Timeline, moment and duration pages describe themselves for link previews (Open Graph and Twitter cards) and search engines. Each has:

  • a title: a moment's or duration's own, then its timeline's, then the site's name. Search results show about 60 characters, so the page's <title> fits in that (#469). It tries, in turn: the timeline by its name before a subtitle, without the site's name, the timeline's name cut between words, and the event's title alone, cut if need be. Link previews keep the whole title. The site's own pages fit theirs the same way;
  • a description: the timeline's description, or how many moments it has, over what time and by whom; for a moment or duration, its time and notes;
  • the canonical address;
  • a 1200 × 630 preview image. The image shows the title and a strip of the timeline's moments, with the shared event marked on it. A timeline with an image of its own previews its page with that image instead, linked where it is hosted.

Facebook, X, LinkedIn, Slack, Discord, iMessage and others show these as a card with a large image.

The site's other pages (the landing page, profiles, help and the rest) preview with the site's own card, /previews/site.png, which each server draws for itself at 1200 × 630: the logo and "Circagraph", what it is in one sentence, and the server's name (PLATFORM_NAME) or address, over a strip of the ancient Rome timeline cut from /social-preview.jpg, a screenshot of the editor. Each audience's page has a card of its own, /previews/<audience>.png, with its heading and promise in place of the sentence, so a link to /for/educators speaks to teachers. Each has its size and a description for screen readers. A private timeline's preview is the site's card too. Every preview image's address is absolute, on the site's address (APP_ORIGIN).

Previews are made as a guest sees the timeline: a private timeline's preview image is the site's card, and its pages ask search engines not to index them, so nothing private appears in a preview even when a member shares the link.

A timeline with sensitive-content labels previews as its title and what it is labelled as containing, without its moments or description, and its oEmbed answer has no thumbnail: it opens behind its warning. Its moment and duration pages are described by their labels instead of their notes, and ask search engines not to index them.

Search engines

  • /robots.txt lets crawlers read pages but not the API, accounts, the bare editor or embeds, and names the sitemap. It does let them read the editor's frame, /editor/frame, which answers X-Robots-Tag: noindex, indexifembedded: indexed only as part of the page that frames it (#428).
  • A timeline's page arrives with its heading: the frame its page shows is asked for with ?timeline=<id>, and for someone who may read that timeline it is served with the timeline's image, title, description (its Markdown rendered) and moment count already in place, which the editor keeps while it loads the timeline. A comparison, a timeline still being prepared and a timeline with sensitive-content labels arrive without it.
  • /sitemap.xml is a sitemap index: it names the pages of the sitemap under /sitemap/, so it covers the site however many timelines it has.
    • /sitemap/pages.xml lists the site's own pages (the dashboard, plugins, download, the API reference, the help and each of its pages, the terms, privacy policy and legal notices); with the landing page on, also /explore, /for and each audience's page.
    • /sitemap/timelines-<id>.xml pages list every public timeline, 45,000 to a page. /sitemap/profiles-<id>.xml pages list every profile that owns one (an account that isn't suspended). Each address has when it last changed, and the index gives each page the latest change on it, so a crawler can tell which pages to read again.
    • /sitemap/entities-<id>.xml pages list the pages of moments and durations (#335), several timelines to a page and never more than 45,000 addresses, each with its timeline's last change.
    • Which timelines' entities are listed: public timelines without sensitive-content labels, that are not comparisons, with at most 5,000 moments, and not set to list none. For each, its first 5,000 entities by kind and ID (durations, then moments) of those its setting lists (below).
      • A timeline with more moments (a log import can have millions) is left out altogether. Its own page is listed, and links to its first 50 moments.
      • On a server, SITEMAP_TIMELINE_ENTITIES sets the limit, from 1 to 45,000.
      • Private timelines, and timelines restricted by moderators (which become private), list nothing, as everywhere in the sitemap.
    • Each page is read from its first ID on, by an index range, and the index reads each public timeline's ID once; neither skips through rows, so they stay quick with millions of timelines.
    • A timeline's entities are read by the primary key of its search rows (see search), as a guest sees them, so its size costs nothing beyond the addresses listed.
  • For AI engines and agents (#482): /llms.txt (llmstxt.org) says in Markdown what the site is (its name, and that it runs Circagraph), and links its main pages, every help page, the API reference and its OpenAPI description, and up to ten featured public timelines, each with a line from its description. /llms-full.txt holds every help page's Markdown in one file. Both are generated from the help and the site's settings, so they follow the docs; every page's footer links /llms.txt, and the sitemap lists it.
  • The FAQ (/help/faq) also describes itself as a schema.org FAQPage (#483): each heading that asks a question, with its answer's first paragraph as plain text, so the data says what the page says.
  • To tell Google about it, open Search Console for the site's domain (verified by a DNS record or an HTML file), choose Sitemaps, and submit sitemap.xml. Google reads the index and then each page it names; the report shows how many addresses it found. robots.txt names the sitemap too, which other search engines (and Google) also follow.
  • With IndexNow on, Bing, Yandex and the other engines that take it are told within minutes which of the sitemap's timeline, profile, moment and duration pages were added, changed or removed, rather than waiting for their next crawl. Editing one moment sends its timeline's page and that moment's. Adding or removing a link to another timeline sends the pages of both its ends.
  • Each timeline page includes its title, description, owner and first 50 moments as text, for screen readers and crawlers. Each moment links to its own page. Up to 50 moments and durations on other timelines that link to it as a whole are listed under Linked from, each linked to its own page.
  • Moment and duration pages' descriptions, which search results and link previews show, are its time as the timeline writes it, then its notes as plain text without their Markdown, cut between words near 155 characters (#466).
  • Moment and duration pages as text: each includes, as text:
    • its title;
    • its time or extent as the timeline displays it, each time at its own precision ("539 BCE", "1975-03 CE"), with the ISO date for machines on a timeline of Gregorian dates in years 1–9999;
    • its tags and notes;
    • what its timeline's plugins record, such as dating notes, and their links, such as sources (https only, marked ugc nofollow);
    • up to 50 of the moments and durations related to it, each linked to its own page;
    • up to 50 of its links to other timelines, each linked to the other moment's or duration's page, or the other timeline's. A link appears on the pages of both its ends, so each leads to the other. Only links to timelines the reader may read are shown, so crawlers see those between public timelines;
    • a link into the timeline open at it.
  • A timeline's structured data: a public, unlabelled timeline's page describes it as a schema.org CreativeWork in JSON-LD: its title, description, own image, tags as keywords, when it was made and last changed, and its owner as author.
  • Structured data: each moment and duration page also describes itself as schema.org JSON-LD:
    • a CreativeWork whose temporalCoverage is its time in ISO 8601 (#468): a date as precise as the timeline writes it (1975, 1975-03, 1975-03-14, or a full timestamp), and for a duration an interval start/end, both ends at the finer of their precisions. Years count as ISO 8601 does, so 539 BCE is -0538 and 1 BCE 0000, from -9999 to 9999. A timeline of other times, such as a fictional calendar's years or a plain number line, gives none;
    • with its notes, tags as keywords, and the timeline and its owner (isPartOf);
    • never an Event, which search engines take for a happening to attend, and fault for lacking a place, tickets and organizer.
    • Private and labelled timelines' pages have none.
  • Trails and kinds of page (#474): a moment's or duration's page also has a BreadcrumbList (its timeline's owner, the timeline, then it), which search results can show in place of its address, and it previews as an article rather than a website. Help pages have one too (Help, then the page), and the audience pages' WebPage carries the trail they show above their heading. Explore is a CollectionPage, and Download describes the SoftwareApplication with its version.

Which events search engines list

Every moment and duration of a public timeline has a page, but search engines don't get them all (#467). Thousands of pages that say little, such as a log's lines, would lower how search engines rate the site's other pages. Sharing & settings → Search engines chooses for each timeline:

SettingLists
Automatically (default)Events with at least 150 characters of notes and a title no other event of the timeline has. None when most of its notes are one template (below).
All of themEvery event
NoneOnly the timeline's own page

An event that isn't listed keeps its page, and its timeline's page still links to it. It is left out of the sitemap and of IndexNow, and its page asks search engines not to index it (noindex).

Templated notes: notes a program wrote, such as "At 02:35:04 UTC, nginx on web-1 emitted an info record…", are long but tell search engines nothing new from one event to the next. To find them, the server takes a sample of up to 200 of a timeline's events with notes long enough to list, chosen by a hash of their IDs. It reduces each note to its first 12 words without numbers, addresses, code and quoted text. If at least 20 notes are sampled and half of them reduce to the same words, the timeline lists none automatically. All of them lists them anyway. The verdict is kept until the timeline's next save. A plan for a model to judge this more finely is #476.

Embedding

/embed/<id> is a public timeline for other sites to frame: the timeline and its title, with search, zoom, Fit all and an Open on Circagraph link that follows what is open. It is read-only, and anonymous: it sends no cookies, so it shows what a guest sees even to a visitor who is signed in and owns the timeline. A private timeline is not embedded. The Embed on a website code is an iframe:

<iframe
  src="https://circagraph.org/embed/<id>#moment/<moment>"
  title="…"
  width="100%"
  height="480"
  style="border:0;max-width:100%"
  loading="lazy"
  allow="fullscreen"
></iframe>

An embed is light or dark as the visitor's system is set (the page it sits in can't tell it more), whatever they chose on this site. To fix it to one, add ?theme=light or ?theme=dark to its address, before any fragment: /embed/<id>?theme=dark#moment/<moment>. The oEmbed answer below leaves it to the system; add the parameter to its iframe's address to fix it. A timeline's own theme keeps its colors either way.

Any site may frame embeds unless the operator sets EMBED_FRAME_ANCESTORS to a list of origins (see deployment). Every other page of the platform, including comparisons, the legal pages and pages that don't exist, refuses to be framed at all (frame-ancestors 'none'), and sends no referrer to other sites; only the site's own pages frame the editor (/editor/frame). Over https, embeds and the editor's frame ask browsers to keep to https (HSTS), as every other page does.

In other pages and AI chats

A timeline doesn't need to be on a server to be shown elsewhere. The <och-timeline> element, published on npm as @openchronology/timeline, is the offline editor in a frame of its own, opened at a timeline written inside it as .ochx JSON. Pages, documentation sites and the HTML an AI chat writes into a reply or an artifact can use it, loading it from jsDelivr or unpkg:

<script src="https://cdn.jsdelivr.net/npm/@openchronology/timeline@<version>/dist/timeline.js"></script>
<och-timeline mode="view" height="480">
  <script type="application/json">
    {
      "title": "Moon landings",
      "presentation": "gregorian",
      "events": [
        { "id": "luna9", "time": "-123379200/1", "metadata": { "title": "Luna 9 lands" } },
        { "id": "apollo11", "time": "-14182940/1", "metadata": { "title": "Apollo 11 lands" } }
      ]
    }
  </script>
</och-timeline>
  • What it shows: the timeline and its tools, without the editor's header. A timeline with a default view opens at it. mode="view" opens it in View mode; without it, it opens for editing.
  • What leaves it: nothing is saved. Export downloads the timeline as an .ochx file, which opens on this site (Import), in the desktop app or in the offline file.
  • What it fills in: the format, version and an empty description when left out, and a presentation named only by its mode ("gregorian", where times are seconds from 1970).
  • What it can reach: nothing. Its frame is sandboxed in an origin of its own and makes no network requests, so neither the page nor the timeline can reach the other.

Its attributes (height, theme, src) and script use are in the package's README.

oEmbed

Timeline, moment and duration pages announce an oEmbed endpoint, so services that discover oEmbed from a page (such as Iframely and Embedly, and the sites and editors that use them) can turn a pasted link into the timeline itself:

GET /api/oembed?url=https://circagraph.org/<username>/<slug>&maxwidth=600&format=json

It answers a rich embed with the iframe above (opening at the page's event, or at the link's fragment), its size (at most 800 × 480, within maxwidth and maxheight), the title and owner, and the preview image as its thumbnail (the timeline's own image, when it has one whose size its settings measured). Any of a timeline's addresses will do. Only json is available; addresses of other sites, and timelines that are not public, are not found.

This page is docs/sharing.md in the source code, as this server runs it.