{"id":13911078,"url":"https://github.com/April-Gras/obsidian-auto-timelines","last_synced_at":"2025-07-18T10:32:20.342Z","repository":{"id":153245978,"uuid":"620953557","full_name":"April-Gras/obsidian-auto-timelines","owner":"April-Gras","description":"Simple timeline generator plugin for story tellers using obsidian","archived":false,"fork":false,"pushed_at":"2024-10-14T07:36:52.000Z","size":784,"stargazers_count":126,"open_issues_count":21,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-25T20:39:28.015Z","etag":null,"topics":["obsidian-plugin","typescript","vuejs3"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/April-Gras.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-29T17:42:08.000Z","updated_at":"2024-11-25T06:08:49.000Z","dependencies_parsed_at":"2024-05-04T11:28:29.891Z","dependency_job_id":"946c8cf1-90ba-44f0-8206-c0e292ed4543","html_url":"https://github.com/April-Gras/obsidian-auto-timelines","commit_stats":null,"previous_names":[],"tags_count":44,"template":false,"template_full_name":"obsidianmd/obsidian-sample-plugin","purl":"pkg:github/April-Gras/obsidian-auto-timelines","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/April-Gras%2Fobsidian-auto-timelines","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/April-Gras%2Fobsidian-auto-timelines/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/April-Gras%2Fobsidian-auto-timelines/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/April-Gras%2Fobsidian-auto-timelines/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/April-Gras","download_url":"https://codeload.github.com/April-Gras/obsidian-auto-timelines/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/April-Gras%2Fobsidian-auto-timelines/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265742410,"owners_count":23820836,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["obsidian-plugin","typescript","vuejs3"],"created_at":"2024-08-07T00:01:56.406Z","updated_at":"2025-07-18T10:32:20.062Z","avatar_url":"https://github.com/April-Gras.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# Aprils automatic timelines\n\nA theme agnostic timeline generator for [obsidian](https://obsidian.md/)\n\n\u003cimg src=\"https://user-images.githubusercontent.com/1866440/232319031-7eeb18ef-da01-488d-b0cc-f528e7760574.png\" width=480 /\u003e\n\nThis plugins allows you to tag notes to generate timelines. It's designed with story telling in mind.\n\n## Sample vault with basic examples\n\n[TimelineSampleVault.zip](https://github.com/April-Gras/obsidian-auto-timelines/files/14350147/TimelineSampleVault.zip)\n\nHere's a zip file of a obsidian vault with various basic examples to help you build timelines.\nAlternatively [Josh Plunkett](https://www.youtube.com/@JoshPlunkett) did [a tutorial video](https://www.youtube.com/watch?v=992o1j8zRSk) covering the basics\n\n### How to use\n\nStart by adding some metadata to the notes that you want to appear in your timeline.\n\n```yml\naat-event-start-date: 359 # Required\naat-event-end-date: 435 # Optional, can be set to `true` if you want it to span throughout the entire timeline\naat-render-enabled: true # Enables this note to be rendered in a timeline\ntimelines: [timeline, event] # This note should be rendered in the timeline with the name \"timeline\" or \"event\"\n```\n\nOnce you tagged at least one note create a new note and add a new markdown code block using three backquotes and flagging it as `aat-vertical` and adding the name of the timeline as it's content.\nYou can also give multiple names to your timeline by separating the values with a `,` (This value can be changed in the settings)\n\n![image](https://github.com/April-Gras/obsidian-auto-timelines/assets/1866440/78de88e6-7048-47a6-b943-fe7bbae58c69)\n\nThis will scan the vault for all notes flagged to render inside the `timeline` timeline\n\nBehind the scenes the plugin will parse the content and generate a card for each note. The only manual content needed to create a card in a timeline is the start date.\n\n#### Additional metadata keys\n\nSometimes the content of a note is not exactly what you want to appear in the card.\nTo remedy that, the plugin exposes three keys that are by default:\n\n```yml\naat-event-title: New title # Used to override the title of a generated card.\naat-event-body: New card body # Used to override the text content of a generated card.\naat-event-picture: https://f4.bcbits.com/img/a1344871335_65 #Some external link, support for internal links is missing for now\n```\n\n#### Advanced date formats\n\nSometimes good old `year-month-day` timeformat just doesn't cut it for your world and you have a more complex timesystem in use.\nThe plugin exposes 3 majors settings to help achieve your desired time format.\nBefore getting into too many details make sure you're familiar with RegExps and named capture groups within them. If this is not the case fireship.io has a [great video for beginners](https://www.youtube.com/watch?v=sXQxhojSdZM) to start your learning journey.\n\n##### Date Parser Regex\n\nBy default the plugin will rely on this RegExp\n\n```regex\n(?\u003cyear\u003e-?[0-9]*)-(?\u003cmonth\u003e-?[0-9]*)-(?\u003cday\u003e-?[0-9]*)\n```\n\nAs you can see it will capture any date that follows the following format: `numbers-numbers-numbers`.\nBut there's a little subtlety here. The named capture groups `\u003cyear\u003e` `\u003cmonth\u003e` and `\u003cday\u003e`. These will become important latter down the line.\n\n##### Date Parser Group Priority\n\nThis setting should be built directly off the previously created RegExp. In the case of the default regex we have 3 main tokens. `year` `month` and `day`. You can find them in the named capture groups.\n\nIn this setting you should order the tokens per weights. So in our case: `year,month,day`\nEvery token should follow same syntax used in the named capture groups from the previous RegExp and be separated by a single comma (`,`).\n\n##### Date Display Format\n\nThe most straight forward of all three date format settings. This is the template for the actually in card display. Just wrap every token in `{}` and format it the way you like. For example to display `yyyy-MM-dd` we'll write: `{year}-{month}-{day}`.\n\n##### Example fantasy date formats.\n\n###### cycle-moon-phase-day\n\nLet's get a little wild and imagine a world where time is tracked this way\n\n-   `Cycles` are the hightest value of time, each cycle can see 3 moons come and go.\n-   `Moons` are more frequent than cycles and are comprised of phases.\n-   `Phases` are more frequent than moons per cycle and are comprised of days.\n-   `Days` are the lowest relevant time unit in this system.\n\nLet's say in our metadata we want to store the value as such\n\n```yml\n# 14 phases \u0026 23 days on the 2'nd moon of the 687'th cycle\naat-event-start-date: 14\u002623-2M-687C\n```\n\nOur regex would look something like this\n\n```regexp\n(?\u003cphase\u003e[0-9]*)\\\u0026(?\u003cday\u003e[0-9]*)-(?\u003cmoon\u003e[0-9]*)M-(?\u003ccycle\u003e[0-9]*)C\n```\n\nOne capture group per date token can be found.\nNow to set our date parser group priority:\n`cycle,moon,phase,day`\n\nAnd let's say we want a fairly minimal display format where only the cycle and the moon are displayed.\n\n```\ncycle {cycle}, {moon}\n```\n\nThe end result for our initially declared metadata would look something like: `cycle 687, 2`.\n\n##### Date token types\n\nIn some cases numbers displaying your dates as plain numbers won't really cut it. This is where date token types come in. For now they come in two flavors\n\n-   `numerical`: These date tokens should be displayed as default, for example the day and the year in `06 july 2018` are numerical date tokens. The `day` token has a minimal length of `2` and the `year` token has a minimal length of `4`.\n-   `string`: These are a bit more cumbersome to configure but add great visibility. For instance in our previous example (`06 july 2018`) the `month` token is a `string` date token.\n    To configure your date tokens head to the plugins settings and use the `Date Format Settings` setup flow or edit them using advanced mode.\n\n##### Timeline specific settings override\n\nIn some cases the output format used defined in the settings is too broad for some timelines. Let's say we defined the following tokens:\n\n-   year\n-   month\n-   day\n-   hour\n-   minute\n\nWe could set our default output format to `{day} {month} {year}` and cover a lot of use cases. But let's say we have a timeline full of events that are potentially minutes apart.\nInstead of trying to compromise with other timelines display we could just write\n![image](https://github.com/April-Gras/obsidian-auto-timelines/assets/1866440/6ce32770-7ba6-4fe6-b1f8-eb629d960114)\nThis will override the globals settings but just for this one timeline line\nThe syntax is as follow: `dateDisplayFormat: whatever {token-name} some more whatever {other-token-name}`. You can use as many and as little tokens as you want as long as they where defined earlier in the global settings.\n\n---\n\n## In-line events\n\nIn-line events are enabled by default but if you don't need them you can always disable them to shave a couple processing cycles off each note.\nWith this feature you can define events from inside a note. The event will ignore anything above it's position in a note, and parse the note from there on. This means you could describe all events for a single timeline inside one note.\nThe following example could be in the middle of your note. Or at the end of it. Or anywhere really. Just not before the frontmatter\n\n```markdown\n%%aat-inline-event\naat-event-start-date: 54\naat-event-end-date: true\naat-render-enabled: true\ntimelines: [timeline-name]\n%%\n```\n\nThe keys are the ones you setup in your settings. Check the [sample vault](https://github.com/April-Gras/obsidian-auto-timelines#sample-vault-with-basic-examples) for more examples on this.\n\n---\n\n## Conditional token formatting\n\nThis feature has a bit of an overwhelming name but it basically allows for date system to incorporate token based formatting. I think an example would be 10x easier to understand.\nFor example some people use `B.C.` and `A.D.` to annotate their dates. This can be configured in the settings of the plugin. For a more in dept example refer to the [Sample vault](https://github.com/April-Gras/obsidian-auto-timelines#sample-vault-with-basic-examples) chapter named `07 - Condition based token formats`.\n\n## Development\n\nAs per obsidians [unofficial documentation](https://marcus.se.net/obsidian-plugin-docs/getting-started):\n\n-   clone the repository in a test vault\n-   `npm install` to install dependencies\n-   `npm run dev` to launch development watcher\n\n## Testing\n\nBefore launching the unit tests, make sure to install the dependencies with `npm run install` and use `npm run prepare-vitest` to setup some changes for vitests to work correctly with obsidians package.\n\nOnce that's out of the way use `npm run test` to just launch the tests.\n`npm run test-ui` to run the UI and see coverage in your browser.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FApril-Gras%2Fobsidian-auto-timelines","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FApril-Gras%2Fobsidian-auto-timelines","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FApril-Gras%2Fobsidian-auto-timelines/lists"}