Markwhen is a text-to-timeline tool. You write markdown-ish text and it gets converted into a nice looking cascading timeline.

Related tags

Markdown markwhen
Overview

Markwhen

Markwhen is a text-to-timeline tool. You write markdown-ish text and it gets converted into a nice looking cascading timeline.

Use it here.


Get updated

If you'd like to be kept up-to-date about markwhen's feature development, add your email here.


Table of contents


Downstream repository

This repository is downstream of the main repository that the live website uses. The main, upstream repository is available to sponsors and is ~100 commits (4-6 weeks) ahead of this repository.

Issues opened in this repo can either be bugs with this repository or the live website. Please continue to open issues! They are the largest factor for determining what to work on next.

Some features in the upstream repo not yet in this repo:

  • Views (map & doc)
  • Importing and exporting markwhen files
  • Better mobile experience
  • Style changes
  • Causal dates and times (months via words like January or Dec; times like 8:30am)

You do not have to be a sponsor to use these features - they are all already on markwhen.com! However, if you want prioritized bugs or want a fork that is more up to date then you can sponsor my work, and there would be much rejoicing on my part.

And even if you don't want your own more up-to-date fork but you use markwhen.com for work, please consider having your work be a sponsor!


Timeline

A timeline is composed of an optional header and one or more events.

Header

The header of a timeline indicates things about the timeline like visual preferences and metadata. It is the first part of a timeline; that is, anything before the first event is considered the header.

Right now there are only two things you can include in the header: tag colors and date formatting. Anything else in the header area (that is, everything else before the first event that is not date formatting or tag colors) will be ignored.

Tags and colors

You can indicate the color you want certain tagged events to appear like so:

#Travel: blue
#Education: green
#Economics: #abc // hex color

CSS color literals are supported (e.g., aliceblue or mediumvioletred) as well as hex colors (e.g., #a13bbb).

So, if you have an event like the following

2012-2013: Germany and Italy #Travel

it will be colored as blue in the timeline.

Date formatting

Non-ISO8601 dates default to American formatting (Month/Day/Year). This can be changed to European formatting by adding the following line in the header area (before any event):

dateFormat: d/M/y

This is a hardcoded line, any other format attempt will not work.


Events

An event is a Date Range followed by a colon followed by an event description:

12/2012: End of the world

1961: Year after 1960
Later, 1962 would happen

1 year: 1962, just as predicted

2020-02-22T12:13:14Z-now: How long the pandemic has been going on?
12/7/1941: Pearl Harbor attacked
Launched US into WWII

2022-02-22T16:27:08.369Z: More specific thing
2021-01-02T06:27:00Z-2022: ongoing project work until the end of 2022



Date Ranges

A date range is a period from one date to another. Every event has an associated date range, whether it has an explicitly written end date or not. A date range is typically Date[-Date]; that is, one date optionally followed by a dash and another date.

If an end date is not specified, the range is as long as its granularity.

For example, the event

2001: A Space Odyssey

starts January 1, 2001, and lasts through December 31, 2001.

Example Inferred Range Explanation
2024 2024-01-01T00:00:00Z to 2025-01-01T00:00:00Z From the start of 2024 to the end of 2024
04/1776 1776-04-01T00:00:00Z to 1776-05-01T00:00:00Z From the start of July 1776 to the end of July 1776
01/01/2024 2024-01-01T00:00:00Z to 2024-01-02T00:00:00Z From the start of January 1, 2024, to the end of January 1, 2024 (the whole day).
11/11/2024-12/12/2024 2024-11-11T00:00:00Z to 2024-12-13T00:00:00Z From the start of November 11, 2024, to the end of December 12, 2024.
2031-11-19T01:35:10Z-2099-08-04T18:22:48Z 2031-11-19T01:35:10Z to 2099-08-04T18:22:48Z Exactly as specific as the ISO dates say.



Dates

A date can be expressed in a few forms. Human readable dates are supported, like 1665, 03/2222, or 09/11/2001, as well as IO8601 dates, like 2031-11-19T01:35:10Z. Human readable date formatting defaults to the American Month/Day/Year but can be changed to European formatting via the header.


Relative Dates

If you have events that are based off of, or relative to, other events, you can describe their relationship to get the range you want.

For example, say you are working on a project tracker. You could outline the phases of your project by using absolute dates, like the following:

// To indicate we are using European date formatting
dateFormat: d/M/y

// 2 weeks
01/01/2023 - 14/01/2023: Phase 1 #Exploratory

// Another 2 weeks
15/01/2023 - 31/01/2023: Phase 2 #Implementation

// 1 month
02/2023: Phase 3 #Implementation

// 3 days, after a one week buffer
07/03/2023 - 10/03/2023: Phase 4 - kickoff! #Launch

However, as soon as something changes (say something slips or an estimate was wrong), you would have to go through all events and change their dates manually. This would be especially troublesome if the change is early on.

With relative dates, we can express the same timeline like so:

// 2 weeks
01/01/2023 - 2 weeks: Phase 1 #Exploratory

// Another 2 weeks
2 weeks: Phase 2 #Implementation

// 1 month
1 month: Phase 3 #Implementation

// One week after phase 3 ends, a 3 days kickoff event
1 week - 3 days: Phase 4 - kickoff! #Launch

Relative dates base themselves off the previous date, and this goes all the way back to our first date, 01/01/2023.

This works well enough for serial dates that are each dependent on the last, but what if we have multiple events that are all dependent on the same event? We can do that using event ids:

// Event ids are represented by an exclamation point followed
// by the id - like !Phase1
01/01/2023 - 2 weeks: Phase 1 #Exploratory !Phase1

// Another 2 weeks
after !Phase1 2 weeks: Phase 2, in parallel with Phase 3 #Implementation

// 1 month
after !Phase1 1 month: Phase 3, in parallel with Phase 2 #Implementation

// 3 days, after a one week buffer
1 week - 3 days: Phase 4 - kickoff! #Launch

The word after is optional, we could say !Phase1 2 weeks: Phase 2, in parallel with Phase 3 #Implementation to have the same effect.

Relative dates will first attempt to refer to the event that was specified by a provided event id. For !Phase1 2 weeks: Phase 2, the event with the id Phase1 is looked for, is checked for when it ends, and is used as the reference upon which 2 weeks is based.

If we can't find the event id, or no event id is given, the relative date is instead based upon the last date in the timeline - "last" here meaning most recently written, as the timeline is parsed from top to bottom. So if we have a timeline like this:

2020: Pandemic
2021 - 2023: More pandemic
1 year: Less pandemic?

1 year is based off the last date seen, which would be 2023, or, more specifically, the end of 2023.

This also means that we can base our end date off of our start date:

12/25/2022: Christmas
5 days - 3 days: New Years' stuff

Here, 5 days is five days after the previously seen date (12/25/2022), which would make it 12/30/2022, while 3 days is three days after the previous date, which is our start date of 12/30/2022.

Two relative dates together, like x days - y weeks: ..., can therefore essentially be read as x days after the previous event and lasts for y weeks.

The only exception to this is the shorthand singular relative date, like x years:..., which means immediately after the last event and lasts for x years.


Event Description

An event description is everything after the date range of the event, up to the next event. Event descriptions can span multiple lines. For 12/2012: End of the world, the event description is just End of the world. For the following event:

1961: Year after 1960
Later, 1962 would happen

the event description is

Year after 1960
Later, 1962 would happen

Everything not on the first line (where the date range is specified) up to the next event will be put in an overflow box that can be expanded by clicking on the event. Such an overflow is indicated in the timeline with an ellipsis (...). Event descriptions can include tags, links, locations, photos, and references.


Tags

Events can be tagged to visually indicate they belong to some category. Simply add your tag text in any part of an event's description to tag it:

2022: Happy 95th Birthday Queen Elizabeth #UK #Royalty

A list of all tags appears at the bottom of the screen to allow for filtering by tags.


Links

Links are similar to markdown links: link dislpay text in brackets followed by the url in parentheses:

2018 - 3 years: [Google](www.google.com)

Locations

Events can have zero or more locations associated with them, indicated with the following syntax: [name of location](map|location)

09/2018: Road trip to Seattle
[Devil's Tower](location)
[Glacier National Park](map)
[Seattle](map)

Photos

An event may include a shareable, public google photos link that will be displayed once the event is clicked on. Only one photos link per event is supported.


References

Link to other timelines with the @ syntax:

1919: Treaty of Versailles @wwi

Percent

Indicate that an event is some percent complete by including 0-100% in your event, and the event bar will be partially filled in to show the completion percentage.


Groups and Sections

Events can be grouped. To indicate a group, write group at the beginning of a line. All events up to the start of the next group, the end of the timeline, or the keyword endGroup (whichever of these three comes first) are in the group.

For example,

group The 90s // The title for this group is "The 90s"

1991: Desert Storm
1994: Friends premiered
05/14/1998: Series finale of Seinfeld

// Since we're defining a new group here,
// the preceding group ends and is comprised of the
// previous three events.
group The 2000s

03/2005: Premiere of The Office (US)

// Explicitly end the group
endGroup

// This event is not part of a group
2020: Pandemic

...

If you want an event group to start out collapsed, indent the group line definition.

2001: John is born

// The space here before `group`
// means the group will appear collapsed at first
  group Less important events #StillCoolThough

2003: Someone else is born
...

endGroup

Sections behave similarly though extend to the width of the entire timeline and are activated by the section and endSection keywords:

Sorting

Timelines can be sorted one of three ways: how they were originally written (default), ascending, or descending. Event groups will be sorted internally and then they themselves sorted based on their collective earliest and latest dates.


Header Quick Reference

Item Syntax Example
Coloring tags #[tag name]: #Movies: aquamarine
Date format. Change the formatting to European style. dateFormat: d/M/y dateFormat: d/M/y

Event Quick Reference

Item Syntax Example
Event [DateRange]:[EventDescription] 08/2015-05/2017: CS degree #Education
DateRange [Date][-Date] 1998-06/01/2000
Date. now is a special keyword which means what you think it does [HumanDate|ISO8601|RelativeDate|now] 01/30/1888
HumanDate. Defaults to American formatting (Month/Day/Year, can be overridden in header) [m/d-]yyyy 2002 or 01/2002 or 12/25/1901
ISO8601 format. The T and Z are required. YYYY-MM-DDTHH:MM:SS:MSZ 1859-05-09T12:01:01Z
Relative Date (base this date off of another) [after] [!eventId] Amount after !Birthday 3 weeks 2 days, 2 days - 3 months 4 days 8 seconds, !ww1 21 years - 6 years
Amount (used in relative dates) [digit] [milliseconds|seconds|minutes|hours|days|weeks|months|years] after !Birthday 3 weeks, 2 days - 3 months, !ww1 21 years - 6 years
Event description ([text]|[Tag]|[Location]|[Link]|[Photos])* 07/2014: 4th of July in DC https://photos.app.goo.gl/d418j6GSkCD5LGmY8 #Travel @sue @greg [Washington, DC](location)
Tag #[tag name] 1999: The Matrix #Movies
Location [location name](location|map) 02/23/1836: Battle of the Alamo (The Alamo, TX)[map]
Link [display text](link) 05/25/2021: [cascade.page](https://cascade.page) featured on [Hacker News](https://news.ycombinator.com/item?id=27282842)
Photos. Has to be a public link! Currently only one photo link per event is supported. 07/2017: 4th of July in DC https://photos.app.goo.gl/d418j6GSkCD5LGmY8
Reference. Reference and link to other timelines. @[other timeline name] 09/2019: Dinner with @karl or 2020-2022: COVID-19 Pandemic @jenny/covid @covidtimeline
Comment //[text] // this is a comment

Saving and sharing

To save a timeline to your computer, click the Save... button while on the Editor tab of the sidebar. It will be saved locally, and you can come back and edit or view it later, as long as it's on the same device.

You can view timelines that you've saved from the profile tab of the sidebar.

To share a timeline with a link, you will need to make an account. You can make an account by sending yourself a signin link from the profile page. Once signed in, you will need to choose a username from which your timelines will be hosted. For example, if you choose the name jeff, all your timelines will be accessible from https://markwhen.com/jeff/.... If you share a timeline with the same name as your username, it will be accessible from https://markwhen.com/[your username]/, otherwise, it will be accessible from https://markwhen.com/[your username]/[timeline name].

All in all, the steps are:

  1. Send yourself a signin link from the profile tab.
  2. Click the link to login.
  3. Choose a username - all your shared timelines will be available from https://markwhen.com/[your username]/...
  4. Share your timeline

Public by default

Any timeline you share is public by default - anyone could view it. Any timeline you save locally only on your computer is, of course, only accessible on that device.

Comments
  • Nested groups and sections

    Nested groups and sections

    Thank you for the great tool! I love it! I noticed that the group and section features don't support nesting. It would be great to have that functionality so that more structure could be provided entries!

    opened by jceb 6
  • Use Arbitrary Counter as Timeline

    Use Arbitrary Counter as Timeline

    I want to be able to use a counter (that represents an arbitrary thing, not just dates) as the basis for events. For example,

    5-20: Event 1 90-150: Event 2 45-68: Event 3

    etc.

    When I tried this in the live example, it treated it like a percentage and only went up to 100. It won't let me zoom out any more

    image
    opened by frakman1 4
  • Bug: I can't create a username

    Bug: I can't create a username

    Clicking on the Create Username button doesn't do anything. This makes cascade pretty much useless for me.

    Chrome: Version 96.0.4664.110 (Official Build) (64-bit).

    I'll take a look at the code

    opened by mark-hahn 4
  • Support [x] check box to indicate completion

    Support [x] check box to indicate completion

    There isn't a single agreed standard about notating tasks in Markdown, but many tools now support something like

    - [ ] incomplete task
    * [x] complete task
    

    You have % completion. In order to improve interoperability with markdown used in other editors and task systems (e.g. NotePlan), please consider supporting at least the [x] syntax to indicate 100% completion.

    opened by jgclark 3
  • [feature request] autosave versions

    [feature request] autosave versions

    It would be awesome if the markwhen.com site could autosave and could present a list of timestamped autosave versions with an ability to jump back to an earlier version.

    opened by Kevin-Hamilton 2
  • Feature request: allow tasks with duration in “work days”

    Feature request: allow tasks with duration in “work days”

    Hi. The tool is really good. I just have this feature req, which I believe many people would find useful.

    In many cases events or project tasks need to have set their duration in a number of “workdays” ignoring weekends and maybe Public holidays. You could define your own public holidays in some array.

    The idea is to set task durations in for example 7 workdays which will translate into a whole week plus 2 days long … so 9 natural days long.

    Then if something moves in the project everything can be updated accordingly… discounting weekends.

    opened by frantortosa 2
  • Long-term plans for markwhen

    Long-term plans for markwhen

    I love this project. Apologies if you've already explained elsewhere, but should any assumptions be made on how long the server app will be up and running? In other words, is this an experiment, or is it meant to last for the long term? Many thanks.

    opened by dlovins 2
  • Supporting working-back-from-immovable-deadline planning

    Supporting working-back-from-immovable-deadline planning

    I've tried and so far failed to be able to express my plan in Markwhen. The challenge in this case is it's not a forward-waterfall plan, but a working-back-from-an-immovable-deadline plan.

    Ideally I want to write something like:

    title: Annual Meetings 2023 (Markwhen plan)
    description: A summary of what's needed and when
    dateFormat: d/M/y
    #announcements: red
    
    before !ACM 2 month: revise voting eligibility list
    before !ACM 6 weeks: publish notice of ACM #announcements
    before !ACM 2 weeks: publish revised voters list
    10/4/2023: ANNUAL CHURCH MEETING !ACM
    after 1 week: publish results of elections #announcements
    

    The 'before' syntax isn't available, so I tried negative relative dates:

    title: Annual Meetings 2023 (Markwhen plan)
    description: A summary of what's needed and when
    dateFormat: d/M/y
    #announcements: red
    ---
    after !ACM -2 month: revise voting eligibility list
    after !ACM -6 weeks: publish notice of ACM #announcements
    after !ACM -2 weeks: publish revised voters list
    10/4/2023: ANNUAL CHURCH MEETING !ACM
    after 1 week: publish results of elections #announcements
    

    but this doesn't work.

    Is there an existing way to do this? If not, please add support for this kind of use case.

    opened by jgclark 2
  • VS Code extenstion

    VS Code extenstion

    It would be great to have a VS Code extension, like PlantUML has, to edit and generate timelines in the IDE. It will make it quicker to iterate timelines.

    opened by PrernaWeb 2
  • Site can become unresponsive Firefox/Ubuntu

    Site can become unresponsive Firefox/Ubuntu

    ~~When changing Tabs the site can become unresponsive on Firefox/Ubuntu.~~

    By unresponsive I mean, that I can no longer input text in the editor and I can also no longer click anything in the UI/renderer.

    I don't know whether they are related but I'm also getting several errors in Console saying: Uncaught ReferenceError: TouchEvent is not defined r NuxtJS These errors are being thrown when I move the cursor.

    I also get the following error: Error: Promised response from onMessage listener went out of scope

    opened by Tommyten 2
  • Expandable timelines

    Expandable timelines

    Foremost: I love this project. I have been playing around with it for hours and I want to use it for many things both private and at work. I would love it, if I could specify expandable / nested dates. Usecases are: Changing position at the same company, creating some kind of high/low level structure. I am not expecting you to implement this, after all, you have already selflessly open sourced this great project. Just in case you are looking for additions worth implementing, I would vote for this one!

    opened by brasilikum 2
  • [Feature Request] Project Dependencies

    [Feature Request] Project Dependencies

    Hi, thanks so much for this very nice tool. One thing that is missing is the ability to mark one task as dependent on another task. I think this is a fairly common feature and it can be quite useful as well. For example, I am imagining that you could have something like

    11/2022-12/2022: Create Project Plan #Plan
    2/2023-12/2023: Do project #after:Plan
    

    and then you will get an arrow from the end of the "Create Project Plan" bar to the start of the "Do project" bar. Though I'm not sure how hard it would be to implement, I think it would be quite useful.

    opened by Alex7Li 0
  • [Feature Request] Markdown-style images

    [Feature Request] Markdown-style images

    Currently, an event only supports Google Photo links, but it would be natural to support Markdown-style images as well.

    I had looked into the code a bit and found it easy to implement within 30 lines using existing infrastructure (tested locally): https://github.com/utensil-contrib/markwhen/commit/aa046c277328ae9db4f68fd53c12ac931c2c7ac2 .

    Since this repo is behind the developing repo, just post the code here to see if it could be useful somehow.

    opened by utensil 1
  • [Feature Request] Navigational shortcuts

    [Feature Request] Navigational shortcuts

    I may have missed this somewhere, but it would be nice if there were a button or keyboard shortcut to go back to "now" or whatever the current date/time is.

    It would also be nice if you could command + click or ctrl + click to go to beginning or end of an event or time range so one could more easily jump around.

    Then after jumping around, easily go back to "now".

    opened by mlebrun 7
  • `.pdf` export does not complete (stuck on loading symbol)

    `.pdf` export does not complete (stuck on loading symbol)

    Screenshot 2022-10-11 at 06 45 58

    TImeline in question (<50 events). The same behaviour applies to the .png export.

    According to the documentation:

    Be patient, it could take up to 30 seconds to generate as this is a server side opertion.

    However, no output is generated even after 3 minutes.

    opened by michaelweinold 1
  • Support for returning events or events with breaks

    Support for returning events or events with breaks

    Trying Markwhen now and love it!

    However, the timeline I’m trying to do needs many instances of the same event on the same line returning several times in time, with breaks/cuts. Syntax-wise, it could be done with a comma:

    1991-04 / 2009-08, 2010-06 / 2010-08, 2014-07 / 2015-02: Event name // This event returns a three different date ranges
    

    Any name, colour, location, image added to the event will be kept across all the returns of the events. It would be laid out on the same line.

    Apologies if this is already possible but I missed it or if it has already been discussed somewhere else.

    opened by nclm 0
Owner
Rob Koch
Rob Koch
Runtime markdown processor with support for injecting your custom Vue components into your markdown text.

vue-components-markdown Not tested with Vue3 yet What is vue-components-markdown? vue-components-markdown is a runtime markdown processor with support

Ivan Jolic 2 Sep 6, 2022
Vue Markdown component, can parse local or remote .md files and markdown strings into HTML display

Vue Markdown component, parse local or remote .md files and markdown strings into HTML display

socialuni 1 Nov 3, 2022
perfect-markdown is a markdown editor based on Vue & markdown-it.

A markdown editor based on Vue & markdown-it

null 41 Jun 23, 2022
A markdown component and independent markdown compiler.

A markdown component and independent markdown compiler.

Lazybones 1 May 5, 2022
A book builder which supports markdown and vue in markdown file.

Introductions Mac only for now. Windows support later. It is a command cli. It will process markdown files into website. You can write vue code in mar

hoperyy 1 Mar 8, 2019
Convert Markdown file to Vue Component using markdown-it.

vue-antd-md-loader md-loader based on vue-markdown-loader Convert Markdown file to Vue Component using markdown-it. Example ant-design-vue Installatio

vueComponent 7 Aug 12, 2022
A simple markdown parser for Vue using markdown-it.

vue-markdown-render is a simple and lightweight wrapper for markdown-it with full TypeScript support.

null 22 Nov 9, 2022
ServiceStack Markdown Editor is a developer-friendly Markdown Editor for Vuetify Apps

ServiceStack Markdown Editor is a developer-friendly Markdown Editor for Vuetify Apps which is optimized GitHub Flavored Markdown where it supports popular short-cuts for editing and documenting code like tab block un/indenting, single-line and code and comments blocks.

ServiceStack 8 Jun 24, 2020
KOKK - a tool that fetches a Markdown file and renders it as a beautiful one-page documentation.

Create a beautiful doc from a markdown file. You can insert a vue component into the doc as well.

怡潼 55 Sep 15, 2021
This project is a markdown template generator tool via Vite + Vue 🤓

Markdown Manager This project is a markdown template generator · View App ?? About This project is a markdown template generator app. I developed this

Yasin ATEŞ 15 Jun 12, 2022
A Powerful and Highspeed Markdown Parser for Vue

vue-markdown If you want vue-markdown for vue1.X.X, please checkout vue-markdown1.X.X. A Powerful and Highspeed Markdown Parser for Vue. Quick start:

Chao Lee 1.8k Nov 16, 2022
A Simple and Highspeed Markdown Parser for Vue

VueSimpleMarkdown A Simple and Highspeed Markdown Parser for Vue Installation npm install --save vue-simple-markdown Usage Bundler (Webpack, Rollup) i

Vivify Ideas 81 Oct 29, 2022
A Markdown application powered by vue, vditor and element.

A Markdown application powered by vue, vditor and element. This app is a pure web page without any backend for data interactions. Thus, it's convenient to build your own markdown app.

null 7 Mar 24, 2022
Vue markdown editor and marked

Vue markdown editor and marked

orh 1 Jun 11, 2021
A Minimal and Highspeed Markdown Parser for Vue

This fork is intended to work with Webpack 4 and Babel 7, it's open for issues and help is welcome, for now: Added : markdown-it-container markdown-it

Zeth 0 Feb 15, 2020
A vite plugin to import a Markdown file in various formats like Front Matter, HTML, ToC, and React/Vue Component

A vite plugin to import a Markdown file in various formats like Front Matter, HTML, ToC, and React/Vue Component

Kengo Hamasaki 143 Nov 25, 2022
Markdown parse and component

Markdown content vue Based on @nuxt/content code. View instructions on link Features Parse content Html Vue components Codeblocks (Prismjs) Install np

Jero Soler 2 Feb 26, 2022
A Powerful and Highspeed Markdown Parser for Vue

A Powerful and Highspeed Markdown Parser for Vue

GuOJ 1 Jun 14, 2022