olivier/date-calculator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

WIP. inline doesn't work, but the rest does.

Browse Source
This commit is contained in:
Olivier
2025-09-19 20:52:30 -04:00
parent e2a64e0534
commit ee7be363cc
5 changed files with 3228 additions and 104 deletions
Download Patch File Download Diff File Expand all files Collapse all files

371
README.md
View File

@@ -1,94 +1,295 @@
# Obsidian Sample Plugin
# Date Calc
This is a sample plugin for Obsidian (https://obsidian.md).
This plugin adds a `date-calc` fenced code block you can embed in your notes to render date calculations.
This project uses TypeScript to provide type checking and documentation.
The repo depends on the latest plugin API (obsidian.d.ts) in TypeScript Definition format, which contains TSDoc comments describing what it does.
Example (birthday):
This sample plugin demonstrates some of the basic functionality the plugin API can do.
- Adds a ribbon icon, which shows a Notice when clicked.
- Adds a command "Open Sample Modal" which opens a Modal.
- Adds a plugin setting tab to the settings page.
- Registers a global click event and output 'click' to the console.
- Registers a global interval which logs 'setInterval' to the console.
## First time developing plugins?
Quick starting guide for new plugin devs:
- Check if [someone already developed a plugin for what you want](https://obsidian.md/plugins)! There might be an existing plugin similar enough that you can partner up with.
- Make a copy of this repo as a template with the "Use this template" button (login to GitHub if you don't see it).
- Clone your repo to a local development folder. For convenience, you can place this folder in your `.obsidian/plugins/your-plugin-name` folder.
- Install NodeJS, then run `npm i` in the command line under your repo folder.
- Run `npm run dev` to compile your plugin from `main.ts` to `main.js`.
- Make changes to `main.ts` (or create new `.ts` files). Those changes should be automatically compiled into `main.js`.
- Reload Obsidian to load the new version of your plugin.
- Enable plugin in settings window.
- For updates to the Obsidian API run `npm update` in the command line under your repo folder.
## Releasing new releases
- Update your `manifest.json` with your new version number, such as `1.0.1`, and the minimum Obsidian version required for your latest release.
- Update your `versions.json` file with `"new-plugin-version": "minimum-obsidian-version"` so older versions of Obsidian can download an older version of your plugin that's compatible.
- Create new GitHub release using your new version number as the "Tag version". Use the exact version number, don't include a prefix `v`. See here for an example: https://github.com/obsidianmd/obsidian-sample-plugin/releases
- Upload the files `manifest.json`, `main.js`, `styles.css` as binary attachments. Note: The manifest.json file must be in two places, first the root path of your repository and also in the release.
- Publish the release.
> You can simplify the version bump process by running `npm version patch`, `npm version minor` or `npm version major` after updating `minAppVersion` manually in `manifest.json`.
> The command will bump version in `manifest.json` and `package.json`, and add the entry for the new version to `versions.json`
## Adding your plugin to the community plugin list
- Check the [plugin guidelines](https://docs.obsidian.md/Plugins/Releasing/Plugin+guidelines).
- Publish an initial version.
- Make sure you have a `README.md` file in the root of your repo.
- Make a pull request at https://github.com/obsidianmd/obsidian-releases to add your plugin.
## How to use
- Clone this repo.
- Make sure your NodeJS is at least v16 (`node --version`).
- `npm i` or `yarn` to install dependencies.
- `npm run dev` to start compilation in watch mode.
## Manually installing the plugin
- Copy over `main.js`, `styles.css`, `manifest.json` to your vault `VaultFolder/.obsidian/plugins/your-plugin-id/`.
## Improve code quality with eslint (optional)
- [ESLint](https://eslint.org/) is a tool that analyzes your code to quickly find problems. You can run ESLint against your plugin to find common bugs and ways to improve your code.
- To use eslint with this project, make sure to install eslint from terminal:
- `npm install -g eslint`
- To use eslint to analyze this project use this command:
- `eslint main.ts`
- eslint will then create a report with suggestions for code improvement by file and line number.
- If your source code is in a folder, such as `src`, you can use eslint with this command to analyze all files in that folder:
- `eslint ./src/`
## Funding URL
You can include funding URLs where people who use your plugin can financially support it.
The simple way is to set the `fundingUrl` field to your link in your `manifest.json` file:
```json
{
"fundingUrl": "https://buymeacoffee.com"
}
```date-calc
type: birthday
birthday: 1992-08-16
```
If you have multiple URLs, you can also do:
Supported types and fields:
```json
{
"fundingUrl": {
"Buy Me a Coffee": "https://buymeacoffee.com",
"GitHub Sponsor": "https://github.com/sponsors",
"Patreon": "https://www.patreon.com/"
}
}
- birthday
- birthday (or birthdate or date): YYYY-MM-DD
- If not provided in the block/inline config, the plugin will also look for a `birthday` (or `birthdate`) property in the note’s frontmatter.
- Output: Age in years and time until next birthday (days, or months if > 31 days, with half-month rounding)
- countdown / until
- to (or date or until): target date/time
- from (optional): starting date/time (defaults to now)
- label (optional): prefix label
- Output: Humanized time until target, or how long ago if past
- diff
- from (or start): start date/time
- to (or end): end date/time
- Output: Humanized difference between the two dates
- since
- since (or from or date): date/time of the event
- Output: Humanized time since that date (or time until if it’s in the future)
Notes:
- Dates are interpreted in your local timezone. For birthdays, calculations use local midnight to avoid timezone inconsistencies.
- YAML inside the code block must be valid. The plugin will show an error if the YAML cannot be parsed.
More examples:
1) Birthday basics
```date-calc
type: birthday
birthday: 2000-05-21
```
## API Documentation
Aliases for the date field also work:
See https://github.com/obsidianmd/obsidian-api
```date-calc
type: birthday
birthdate: 2000-05-21
```
2) Countdown to a date (future)
```date-calc
type: countdown
label: New Year
to: 2025-12-31 23:59
```
3) Until (alias of countdown)
```date-calc
type: until
to: 2030-01-01
```
4) Countdown from a custom start time
```date-calc
type: countdown
label: Sprint ends
to: 2025-10-15 17:00
from: 2025-10-01 09:00
```
5) Since an event (past)
```date-calc
type: since
since: 2024-12-20
```
If the date is in the future, the text will say "In: ..." instead of "Since: ... ago".
6) Difference between two dates
```date-calc
type: diff
from: 2024-02-29
to: 2025-03-01
```
7) Use times as well as dates
```date-calc
type: diff
from: 2025-09-19 08:00
to: 2025-09-19 16:30
```
8) Friendly birthday messages near the day
```date-calc
type: birthday
birthday: 1992-08-16
```
- If today is the birthday: "Wish them Happy Birthday!"
- If tomorrow is the birthday: "Their birthday is tomorrow!"
- If the birthday is > 31 days away: months are shown, with a 0.5 month added when roughly half a month remains.
9) Error handling examples
Invalid YAML:
```date-calc
this: is: not: valid
```
Missing required fields:
```date-calc
type: diff
from: 2025-01-01
# missing: to
```
The plugin will show a helpful error message in these cases.
Inline usage:
- You can also use inline code like:
- `\`date-calc: birthday=1992-08-16\`` → renders a birthday summary.
- `\`date-calc: to=2025-12-31 label=NewYear\`` → renders a countdown.
- `\`date-calc: since=2024-12-20\`` → time since.
- `\`date-calc: from=2025-09-19 to=2025-09-20\`` → difference between two dates.
- Inline also accepts YAML/inline-map after the colon, e.g. `\`date-calc: {type: birthday, birthday: 1992-08-16}\``.
- For inline birthday, if no date is given, the note’s frontmatter `birthday`/`birthdate` is used when present.
Tips:
- You can style the rendered line using the CSS class `date-calc` in your snippet or theme.
- ISO-like date strings (YYYY-MM-DD or YYYY-MM-DD HH:mm) work well and are interpreted in your local timezone.
- For birthdays, calculations are normalized to local midnight to avoid off-by-one day issues due to timezones.
# Date Calc
This plugin adds a `date-calc` fenced code block you can embed in your notes to render date calculations.
Example (birthday):
```date-calc
type: birthday
birthday: 1992-08-16
```
Supported types and fields:
- birthday
- birthday (or birthdate or date): YYYY-MM-DD
- If not provided in the block/inline config, the plugin will also look for a `birthday` (or `birthdate`) property in the note’s frontmatter.
- Output: Age in years and time until next birthday (days, or months if > 31 days, with half-month rounding)
- countdown / until
- to (or date or until): target date/time
- from (optional): starting date/time (defaults to now)
- label (optional): prefix label
- Output: Humanized time until target, or how long ago if past
- diff
- from (or start): start date/time
- to (or end): end date/time
- Output: Humanized difference between the two dates
- since
- since (or from or date): date/time of the event
- Output: Humanized time since that date (or time until if it’s in the future)
Notes:
- Dates are interpreted in your local timezone. For birthdays, calculations use local midnight to avoid timezone inconsistencies.
- YAML inside the code block must be valid. The plugin will show an error if the YAML cannot be parsed.
More examples:
1) Birthday basics
```date-calc
type: birthday
birthday: 2000-05-21
```
Aliases for the date field also work:
```date-calc
type: birthday
birthdate: 2000-05-21
```
2) Countdown to a date (future)
```date-calc
type: countdown
label: New Year
to: 2025-12-31 23:59
```
3) Until (alias of countdown)
```date-calc
type: until
to: 2030-01-01
```
4) Countdown from a custom start time
```date-calc
type: countdown
label: Sprint ends
to: 2025-10-15 17:00
from: 2025-10-01 09:00
```
5) Since an event (past)
```date-calc
type: since
since: 2024-12-20
```
If the date is in the future, the text will say "In: ..." instead of "Since: ... ago".
6) Difference between two dates
```date-calc
type: diff
from: 2024-02-29
to: 2025-03-01
```
7) Use times as well as dates
```date-calc
type: diff
from: 2025-09-19 08:00
to: 2025-09-19 16:30
```
8) Friendly birthday messages near the day
```date-calc
type: birthday
birthday: 1992-08-16
```
- If today is the birthday: "Wish them Happy Birthday!"
- If tomorrow is the birthday: "Their birthday is tomorrow!"
- If the birthday is > 31 days away: months are shown, with a 0.5 month added when roughly half a month remains.
9) Error handling examples
Invalid YAML:
```date-calc
this: is: not: valid
```
Missing required fields:
```date-calc
type: diff
from: 2025-01-01
# missing: to
```
The plugin will show a helpful error message in these cases.
Inline usage:
- You can also use inline code like:
- `\`date-calc: birthday=1992-08-16\`` → renders a birthday summary.
- `\`date-calc: to=2025-12-31 label=NewYear\`` → renders a countdown.
- `\`date-calc: since=2024-12-20\`` → time since.
- `\`date-calc: from=2025-09-19 to=2025-09-20\`` → difference between two dates.
- Inline also accepts YAML/inline-map after the colon, e.g. `\`date-calc: {type: birthday, birthday: 1992-08-16}\``.
- For inline birthday, if no date is given, the note’s frontmatter `birthday`/`birthdate` is used when present.
Troubleshooting inline rendering:
- Inline replacements only run in Reading view and in Live Preview (rendered sections). In Source mode, you’ll just see the literal inline code.
- Type it exactly with a single pair of backticks, e.g. `\`date-calc:birthday\`` or `\`date-calc: birthday=1992-08-16\`` (no triple backticks).
- If it still shows as literal code, try: toggle the note to Reading view and back, or reload the app, or disable/enable the plugin. The plugin’s inline processor now runs late to avoid conflicts with other processors.
- Inline code inside fenced code blocks is intentionally ignored by the plugin so you can document examples in notes and the README.
Tips:
- You can style the rendered line using the CSS class `date-calc` in your snippet or theme.
- ISO-like date strings (YYYY-MM-DD or YYYY-MM-DD HH:mm) work well and are interpreted in your local timezone.
- For birthdays, calculations are normalized to local midnight to avoid off-by-one day issues due to timezones.