DOCSEARCHbyAlgolia
Submit Docs

Markwhen Documentation

website·Indexed 33 days ago

https://docs.markwhen.com

Documentation for Markwhen, a journal language for creating dated entries and timelines. Includes guides on syntax, dates and ranges, and the @markwhen/mw CLI. Also covers Meridiem, a Markwhen editor featuring an OAuth API, Model Context Protocol (MCP) server, and collaborative editing, as well as Remark.ing for blogging via Markwhen documents.

Tokens
25.1K
Snippets
158
Records
200
Agent score
55%

What's inside Markwhen

  1. Overview of Aggregate Queries

    Aggregate queries allow applications to read data across multiple documents that the app is authorized to see. They are ideal for implementing feeds, search functionality, dashboards, publishing jobs, notifications, and cross-document views. Unlike regular document endpoints used for editing a single known document, aggregate endpoints return only authorized rows based on the app's scopes.

  2. Overview of available Markwhen visualizations

    Markwhen and Meridiem are designed to be extensible, allowing different visualizations to be used based on parsed text. Available visualizations include:

    • Timeline/Gantt: Combined timeline and gantt view.
    • Calendar: Calendar-based visualization.
    • Map: Geographic map visualization.
    • Resume: A specialized view for resumes (requires specific syntax).

  3. Overview of Meridiem markwhen editor

    Meridiem is a markwhen editor developed by the markwhen team. It provides an enhanced editing experience with features including syntax highlighting, bidirectional editing (where views can modify the document), event hover highlighting, integrated tag color pickers, and support for multiple views. It supports both online and offline documents, light and dark modes, and incremental reparsing. Users can customize their experience with keymaps for VS Code, Vim, and Emacs.

  4. Overview of Remark.ing

    Remark.ing is a Twitter-like blogging site that functions as an aggregation of Markwhen documents. Each entry within a Markwhen document is treated as an individual "remark." It is built on top of Meridiem and its OAuth API, allowing users to manage their content via the Remarking interface or directly through Meridiem.

  5. Choose a storage method for markwhen documents

    Meridiem provides three ways to store markwhen documents, depending on the user's needs for accessibility, privacy, and collaboration:

    1. Browser Storage (Local Storage): Uses the browser's localStorage API. Data is stored locally in the browser and is only accessible by the origin domain. It is easy to set up and works on mobile, but has a storage limit of approximately 5MB.
    2. Files: Documents are stored as regular files on the user's local computer. This is the most ubiquitous method, though browsers require explicit user permission to read/write to the file system.
    3. Cloud Storage: Documents are stored by Meridiem and associated with a user account. This enables multi-device access, live collaborative editing, API access, and calendar-like features, but generally requires an internet connection.

  6. Build a Publishing App with Meridiem

    Use this pattern for blogs, newsletters, or changelogs. Use Markwhen documents for time-based posts (with slug and status properties) and standard Markdown documents for static pages (e.g., 'About' pages).
    ---
publisher:
  site: rob-notes
  title: Rob's notes
timezone: America/Los_Angeles
---

2026-07-01: Building with Meridiem
  status: published
  slug: building-with-meridiem

The key is keeping the source document pleasant to read.

  7. Build and integrate apps with Meridiem

    Meridiem apps typically interact with markwhen documents to perform the following tasks:

    • Transform markwhen documents into focused user interfaces.
    • Append new entries via forms, buttons, automations, SMS, email, or AI agents.
    • Store app-level settings within the document header.
    • Store structured per-entry details using event properties.
    • Respond to document changes using webhooks.

    For advanced functionality like cross-document feeds, search, dashboards, and jobs, use Aggregate queries.

  8. Understand Markwhen language and rendering

    Markwhen is a language heavily inspired by Markdown but is not Markdown. Unlike Markdown, which historically produces HTML, Markwhen is agnostic to its output format and primarily produces JSON via its parser. While the timeline view is the most common way to render Markwhen, the language is designed to be independent of any specific view.

  9. Understand the Markwhen parser output structure

    The Markwhen parser converts a markwhen document into a JSON object. This intermediate object is used by various views to produce visualizations. The output consists of an array of timelines and associated metadata.
    export interface Timeline {
  ranges: Range[];
  foldables: { [index: number]: Foldable };
  events: EventGroup;
  header: any;
  ids: IdedEvents;
  metadata: TimelineMetadata;
}

export interface TimelineMetadata {
  earliestTime: DateTimeIso;
  latestTime: DateTimeIso;
  maxDurationDays: number;
  preferredInterpolationFormat: string | undefined;
}

  10. Understand markwhen document structure and file types

    A markwhen document is a simple text file. While its official content type is text/markwhen, text/plain is also supported for imports. Documents can be divided into multiple timeline pages using the page break token: _-_-_break_-_-_.

    _-_-_break_-_-_

  12. Meridiem API Overview

    The Meridiem API is hosted at https://meridiem.markwhen.com. Most /api/v1/* endpoints require an OAuth access token. Aggregate query endpoints use app credentials with Basic auth. Document-specific endpoints typically use the pattern /api/v1/docs/:user/doc/:docName. Responses include an immutable doc_id for stable identification.