{"id":15017065,"url":"https://github.com/richardsl/heatmap-calendar-obsidian","last_synced_at":"2025-04-14T06:05:34.296Z","repository":{"id":37097908,"uuid":"461638752","full_name":"Richardsl/heatmap-calendar-obsidian","owner":"Richardsl","description":"An Obsidian plugin for displaying data in a calendar similar to the github activity calendar","archived":false,"fork":false,"pushed_at":"2025-02-10T20:51:41.000Z","size":5193,"stargazers_count":753,"open_issues_count":44,"forks_count":108,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-14T06:05:10.689Z","etag":null,"topics":["calendar","obsidian-md","obsidian-plugin","vizualisation"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Richardsl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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":"2022-02-20T22:56:10.000Z","updated_at":"2025-04-12T18:32:00.000Z","dependencies_parsed_at":"2024-01-17T06:09:37.465Z","dependency_job_id":"a088ba95-c89b-45e5-b00c-7875bb844cf4","html_url":"https://github.com/Richardsl/heatmap-calendar-obsidian","commit_stats":{"total_commits":134,"total_committers":9,"mean_commits":14.88888888888889,"dds":0.08955223880597019,"last_synced_commit":"91c6c555562f4c53b37f30829be05f53e10b39f5"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":"obsidianmd/obsidian-sample-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Richardsl%2Fheatmap-calendar-obsidian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Richardsl%2Fheatmap-calendar-obsidian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Richardsl%2Fheatmap-calendar-obsidian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Richardsl%2Fheatmap-calendar-obsidian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Richardsl","download_url":"https://codeload.github.com/Richardsl/heatmap-calendar-obsidian/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248830396,"owners_count":21168272,"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":["calendar","obsidian-md","obsidian-plugin","vizualisation"],"created_at":"2024-09-24T19:49:47.787Z","updated_at":"2025-04-14T06:05:34.258Z","avatar_url":"https://github.com/Richardsl.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Heatmap Calendar plugin for Obsidian\n\nVisualize your data in a heatmap calendar similar to the github activity calendar using this [Obsidian](https://obsidian.md/) plugin.\n\n\n\nUseful for tracking progress for exercise, finances, social time, project progression, passions, vices etc.   \n\nTo be used with [Obsidian Dataview](https://blacksmithgu.github.io/obsidian-dataview/), but could be used standalone or with other plugins aswell (if you know some javascript).\n\n\u003cp\u003e\n    \u003cpicture\u003e\n      \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://github.com/Richardsl/heatmap-calendar-obsidian/blob/master/github-images/heatmap_examples_dark.gif?raw=true\"\u003e\n      \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://github.com/Richardsl/heatmap-calendar-obsidian/blob/master/github-images/heatmap_examples_light.gif?raw=true\"\u003e\n      \u003cimg alt=\"Shows a black logo in light color mode and a white one in dark color mode.\" src=\"https://user-images.githubusercontent.com/25423296/163456779-a8556205-d0a5-45e2-ac17-42d089e3c3f8.png\"\u003e\n    \u003c/picture\u003e\n\u003c/p\u003e\n\n\u0026nbsp;\n## Howto\n\n1. Annotate the data you want to track in your daily notes (see [Dataview annotation documentation](https://blacksmithgu.github.io/obsidian-dataview/data-annotation/)) \n\n2. Create a [DataviewJS block](https://blacksmithgu.github.io/obsidian-dataview/api/intro/) where you want the Heatmap Calendar to display.  \n\n3. Collect the data you want to display using [DataviewJS](https://blacksmithgu.github.io/obsidian-dataview/api/code-reference/)\n\n4. Pass the data into Heatmap Calendar using  **renderHeatmapCalendar()**  \n\n#### Video Tutorial\nSomeone on the internet made a video tutorial:)  \n[https://www.youtube.com/watch?v=2U4kizMyEEc](https://www.youtube.com/watch?v=2U4kizMyEEc)\n\n\n\u0026nbsp;\n\n*Visualized Concept:*\n![heatmap calendar example](https://github.com/Richardsl/heatmap-calendar-obsidian/blob/master/github-images/heatmap-calendar-howto3.jpg?raw=true)\n\n\n## Full Example Code:\n\n~~~javascript\n\\```dataviewjs // PS. remove backslash \\ at the very beginning!\n\ndv.span(\"** 😊 Title  😥**\") /* optional ⏹️💤⚡⚠🧩↑↓⏳📔💾📁📝🔄📝🔀⌨️🕸️📅🔍✨ */\nconst calendarData = {\n\tyear: 2022,  // (optional) defaults to current year\n\tcolors: {    // (optional) defaults to green\n\t\tblue:        [\"#8cb9ff\", \"#69a3ff\", \"#428bff\", \"#1872ff\", \"#0058e2\"], // first entry is considered default if supplied\n\t\tgreen:       [\"#c6e48b\", \"#7bc96f\", \"#49af5d\", \"#2e8840\", \"#196127\"],\n\t\tred:         [\"#ff9e82\", \"#ff7b55\", \"#ff4d1a\", \"#e73400\", \"#bd2a00\"],\n\t\torange:      [\"#ffa244\", \"#fd7f00\", \"#dd6f00\", \"#bf6000\", \"#9b4e00\"],\n\t\tpink:        [\"#ff96cb\", \"#ff70b8\", \"#ff3a9d\", \"#ee0077\", \"#c30062\"],\n\t\torangeToRed: [\"#ffdf04\", \"#ffbe04\", \"#ff9a03\", \"#ff6d02\", \"#ff2c01\"]\n\t},\n\tshowCurrentDayBorder: true, // (optional) defaults to true\n\tdefaultEntryIntensity: 4,   // (optional) defaults to 4\n\tintensityScaleStart: 10,    // (optional) defaults to lowest value passed to entries.intensity\n\tintensityScaleEnd: 100,     // (optional) defaults to highest value passed to entries.intensity\n\tentries: [],                // (required) populated in the DataviewJS loop below\n}\n\n//DataviewJS loop\nfor (let page of dv.pages('\"daily notes\"').where(p =\u003e p.exercise)) {\n\t//dv.span(\"\u003cbr\u003e\" + page.file.name) // uncomment for troubleshooting\n\tcalendarData.entries.push({\n\t\tdate: page.file.name,     // (required) Format YYYY-MM-DD\n\t\tintensity: page.exercise, // (required) the data you want to track, will map color intensities automatically\n\t\tcontent: \"🏋️\",           // (optional) Add text to the date cell\n\t\tcolor: \"orange\",          // (optional) Reference from *calendarData.colors*. If no color is supplied; colors[0] is used\n\t})\n}\n\nrenderHeatmapCalendar(this.container, calendarData)\n\n```\n~~~\n \n\n\u0026nbsp;\n\n## Colors:\n\nThe heatmap uses a green color scheme by default, just like Github.\n\n\n**Default Color: green (no color specified)**\n\n![heatmap calendar custom colors example](https://github.com/Richardsl/heatmap-calendar-obsidian/blob/master/github-images/colors_defaultColorExample.png?raw=true)\n\n\u0026nbsp;\n\n\n**Custom Color**\n\nYou can customize the colors of the heatmap by supplying a color array to **calendarData.colors**:\n\n![heatmap calendar custom colors example](https://github.com/Richardsl/heatmap-calendar-obsidian/blob/master/github-images/colors_customColorExample.png?raw=true)\n\n\u0026nbsp;\n\n\u003cdetails\u003e\n\u003csummary\u003eMore color options\u003c/summary\u003e\n\n\u0026nbsp;\n\n\u003cb\u003eMulti-Color:\u003c/b\u003e\n\nYou can use multiple colors to display different data-entries in the same heatmap.\nSpecifying the name you gave the color in calendarData.colors (eg. \"blue\", \"pink\" etc).\n\n![heatmap calendar custom colors example](https://github.com/Richardsl/heatmap-calendar-obsidian/blob/master/github-images/colors_multiDataSingleHeatmap.png?raw=true)\n\n\n\n\u003cb\u003eStyling Background (empty days):\u003c/b\u003e\n\nUse Obsidian's built in \"CSS snippets\" for custom styling including styling the empty days (aka the background cells).  \n\nBut remember this will affect all of you heatmaps in all of your notes.\n![heatmap calendar custom colors example](https://github.com/Richardsl/heatmap-calendar-obsidian/blob/master/github-images/snippetCodeExample.png?raw=true)\n\n![heatmap calendar custom colors example](https://github.com/Richardsl/heatmap-calendar-obsidian/blob/master/github-images/colors_cssSnippetsBeforeAfterEmptyDays.png?raw=true)\n\n\n\n\u003cb\u003eGlobal color schemes via settings:\u003c/b\u003e\n\nYou can also add a color scheme via the Settings panel. This scheme which will be available everywhere.\n\nIn order to do so go to `Obsidian Settings \u003e Heatmap Calendar`, you will see a list of available colors, and you can add your own. You must specify a “Color name” by which you will reference it in your render call, and provide a valid array of colors.\n\nWhen you do so, you can now reference your scheme everywhere by passing your name to the `colors` option. For example, let's say you have defined a new color called `githubGreen`. Now, in your code, you can reference it like so:\n\n~~~javascript\n```dataviewjs\nconst calendarData = {\n\tcolors: \"githubGreen\",\n\tentries: [],\n}\n\nrenderHeatmapCalendar(this.container, calendarData)\n```\n~~~\n\n\u0026nbsp;\n\n\u0026nbsp;\n\n\n\u003ci\u003eThe color schemes used in the examples were created at [leonardocolor.io](https://leonardocolor.io).\u003c/i\u003e\n\u003cbr\u003e\n\n---\n\n\u003c/details\u003e\n\n\n\u0026nbsp;\n\n\n## Data Intensity:\nSet which intensity of color to use (eg. from light-green to dark-green etc).\n\n![heatmap calendar custom colors example](https://github.com/Richardsl/heatmap-calendar-obsidian/blob/master/github-images/intensity_example.png?raw=true)\n\n\u003cdetails\u003e\n\u003csummary\u003eMore\u003c/summary\u003e\n\u003cbr\u003e\nThey color-range will be distributed between the highest and lowest number you pass to \"intensity\".\n\nIf the number range 0-100 is used, numbers between 1-20 would map to the lightest color, 40-60 would map to mid intensity color, and 80-100 would map to max intensity.\nYou can add more intensities in order to increase color resolution; simply supply more colors to \u003cb\u003ecalendarData.colors.yourcolor\u003c/b\u003e\n\nDataview's time variables are supported without any conversion, as they return milliseconds by default.  \n\u003cb\u003e[time:: 1 hours, 35 minutes] =\u003e intensity: page.time\u003c/b\u003e\n\n\n\u003c/details\u003e\n\n\n\u0026nbsp;\n\n--- \n\n\n## Other Notes:\n- See the [EXAMPLE VAULT](https://github.com/Richardsl/heatmap-calendar-obsidian/tree/master/EXAMPLE_VAULT) if you want to test out the examples.\n- Week start day is configurable\n- Date format is YYYY-MM-DD, if your daily note filename is something else, [you can use JS to change it in the loop](https://github.com/Richardsl/heatmap-calendar-obsidian/discussions/2)\n- Use Obsidian CSS snippets for custom styling. See [snippet examples](https://github.com/Richardsl/heatmap-calendar-obsidian/tree/master/EXAMPLE_VAULT/.obsidian/snippets).\n\n\u0026nbsp;\n\n## Development (Windows):\n\n ```npm run dev``` - will start an automatic TS to JS transpiler and automatically copy the generated JS/CSS/manifest files to the example vault when modified (Remember to run ```npm install``` first).\n\n After the files have been transpiled, the **hot-reload plugin** (https://github.com/pjeby/hot-reload) then reloads Obsidian automatically.\n Hot-reload is installed in the example vault by default. its used to avoid restarting obsidian after every change to code.  \n *(remember to add an empty *.hotreload* file to \"EXAMPLE_VAULT/.obsidian/plugins/heatmap-calendar/\" if not already present, as this tells hot-reload to watch for changes)*\n\n\n```npm run build``` generates the files ready for distribution.\n\n\u0026nbsp;\n\nTip: ```ctrl-shift-i``` opens the devtools inside Obsidian.\n\n\u0026nbsp;\n\n\n\n## Technical Explanation\nAll the plugin does, is add the function ***renderHeatmapCalendar()*** to the global namespace of you vault.\n\n**\"this.container\"** is passed as the first argument because the plugin needs to know where to render the calendar. You don't have to worry about this.\n\n\"renderHeatmapCalendar()\" then takes **\"calendarData\"** as the secondary argument. This is the javascript object you have to create yourself in order to give plugin instructions and data. Most of the properties are optional, but you have to supply an entries array as an absolute minimum.  \n\nSee the beginning of the readme for the full code example.\n\n**absolute minimum code example:**\n~~~javascript\n\\```dataviewjs\n\nconst calendarData = {\n    entries: [],                \n}\n\nrenderHeatmapCalendar(this.container, calendarData)\n\n```\n~~~\n\n\n\u0026nbsp;\n\n\n\u0026nbsp;\n\u003cbr\u003e\n---\n\n### What's New:\n\u003cbr\u003e\n\n**Version [0.7.1] - 2024-06-28**\n\u003cdetails\u003e\n\u003csummary\u003efix styling bug\u003c/summary\u003e\n\n\u003cbr\u003e\n\u003c/details\u003e\n\n\u003cbr\u003e\n\n**Version [0.7.0] - 2024-06-04**\n\u003cdetails\u003e\n\u003csummary\u003eNew \"First day of the week\" setting, Thanks @antosha417\u003c/summary\u003e\n\u003cbr\u003e\nNew setting for changing the first day of the week, ie. Sunday/Monday.  \n\nFor the American users :-)\n\n![heatmap calendar custom colors example](https://github.com/Richardsl/heatmap-calendar-obsidian/blob/master/github-images/settings_startOfWeek.png?raw=true)\n\nThanks @antosha417\n\n---\n\n\u003cbr\u003e\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eAlternating Month Styling, Thanks @lksrpp\u003c/summary\u003e\n\u003cbr\u003e\nThe months now how their own classes so that they can be styled individually.\n\nThe example CSS Snippet below can be found in the EXAMPLE_VAULT in the \"./obsidian/snippets\" folder:\n\n![heatmap calendar custom colors example](https://github.com/Richardsl/heatmap-calendar-obsidian/blob/master/github-images/style_alternate_month.png?raw=true)\n\nThanks @lksrpp\n\n---\n\n\u003cbr\u003e\n\u003c/details\u003e\n\n\n\u003cdetails\u003e\n\u003csummary\u003eTighter Heatmap Margins/paddings, Thanks @Chailotl\u003c/summary\u003e\n\u003cbr\u003e\nNew setting for \n\n![heatmap calendar custom colors example](https://github.com/Richardsl/heatmap-calendar-obsidian/blob/master/github-images/paddingReducedBefore.png?raw=true)\n\n![heatmap calendar custom colors example](https://github.com/Richardsl/heatmap-calendar-obsidian/blob/master/github-images/paddingReducedAfter.png?raw=true)\n\nThanks @Chailotl\n\n---\n\n\u003cbr\u003e\n\u003c/details\u003e\n\n\n\n\u003cbr\u003e\n\n**Version [0.6.0] - 2023-04-12**\n- Feature: Add ability to define global colors via settings @sunyatasattva pull #74\n- Feature: Add more versatile custom styling of the \"content\" passed to date cell @sunyatasattva pull #73\n\n\u003cbr\u003e\n\n**Version [0.5.0] - 2022-06-30**\n- Feature: Add darkmode support\n\n\u003cbr\u003e\n\n**Version [0.4.0] - 2022-06-25**\n- Feature: Add hover preview feature courtesy of @arsenty from issue #12.  \nto enable - add **content: await dv.span(`[](${page.file.name})`)** to entries, and enable **Settings** -\u003e **Core Plugins** -\u003e **Page Preview**.   \nOptionally install plugin [Metatable](https://github.com/arnau/obsidian-metatable) to display metadata/frontmatter in the preview window aswell.  \nSee examples for more details. Note: if you enabled **Use [[Wikilinks]]** under **Settings** -\u003e **Files and links**, you have to use the respective link structure: **content: await dv.span(`[[${page.file.name}|]]`)**\n\n\u003cbr\u003e\n\n**Version [0.3.0] - 2022-06-25**\n- Feature: Can add more intensities in order to increase color resolution. simply supply more colors to **calendarData.colors.yourcolor**\n- Feature: Can set custom range on the intensity scaling using *intensityScaleStart* and *intensityScaleEnd*\n- Bugfix: Entries from other years would show up in the calendar\n\n\u003cbr\u003e\n\n**Version [0.2.0] - 2022-06-05**\n- Feature: Add border around todays box to indicate what day it is. Can be removed by setting *showCurrentDayBorder* to false\n- Feature: Add better development solution/workflow by using automated file copying instead of symlinks\n\n\u003cbr\u003e\n\n**Version [0.1.1] - 2022-03-18**\n- Bugfix: fix major date problem where year would render with incorrect number of days for different timezones [issue#4](https://github.com/Richardsl/heatmap-calendar-obsidian/issues/4).\n- Bugfix: fix problem with certain entries not showing up in the correct month\n- Bugfix: fix grid cells not scaling correctly with browser width, especially content in grid cells\n\n\u003cbr\u003e\n\n**Version [0.1.0] - 2022-02-23**\n- initial release\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frichardsl%2Fheatmap-calendar-obsidian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frichardsl%2Fheatmap-calendar-obsidian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frichardsl%2Fheatmap-calendar-obsidian/lists"}