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

improve readme

Browse Source
This commit is contained in:
Olivier
2026-01-04 21:36:38 -05:00
parent 4dc6901ba8
commit fe6a1cb968
1 changed files with 123 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

175
README.md
View File

@@ -4,14 +4,14 @@ An Obsidian plugin that adds dynamic date calculations to your notes using `date
## Todo
- [x] Make inline work
- [ ] Add a non-verbose birthday type? Just show the age, with decimals, maybe? Like "3.7 years old"
- [ ]
- [ ] Make everything work not only in Live Preview, but Reading also.
- [ ] Add custom language (default to Obsidian language, overridable)
## Features
### Fenced Code Blocks
Add `date-calc` code blocks to your notes for rich date calculations:
```date-calc
@@ -19,7 +19,9 @@ type: birthday
birthday: 1992-08-16
```
### Inline Code
Use inline code for quick calculations: `date-calc: birthday=1992-08-16`
**Note about Live Preview**: Inline code works in both Reading view and Live Preview mode. In Live Preview, the result appears after the inline code (e.g., `date-calc: birthday=1992-08-16` → Age: 32 years old...). However, inline code does **not** work for live-preview in Source mode - you'll see the literal code until you switch to Reading view or Live Preview mode.
@@ -27,22 +29,21 @@ Use inline code for quick calculations: `date-calc: birthday=1992-08-16`
## Supported Calculation Types
### Birthday (`birthday`)
Calculates age and time until next birthday with enhanced personalization features.
**Fields:**
- `birthday` (or `birthdate`, `date`): Birth date in YYYY-MM-DD format
- `name` (optional): Person's name for personalized output
- `gender` (optional): `male`/`m`, `female`/`f`, or `neutral` for appropriate pronouns
- `label` (optional): Custom label (defaults to "Age:")
**Frontmatter Support:** If not provided in the code block, the plugin will look for `birthday`/`birthdate`, `name`, and `gender` properties in the note's frontmatter.
**Frontmatter Support:** If not provided in the code block, the plugin will look for `birthday`/`birthdate`, and `name` properties in the note's frontmatter.
**Examples:**
```date-calc
type: birthday
name: Alice
birthday: 1992-08-16
gender: female
```
```date-calc
@@ -51,15 +52,19 @@ birthday: 2000-05-21
label: "John's age:"
```
### Countdown (`countdown` or `until`)
Shows time remaining until a target date.
**Fields:**
- `to` (or `date`, `until`): Target date/time
- `from` (optional): Starting date/time (defaults to now)
- `label` (optional): Prefix label for the output
**Examples:**
```date-calc
type: countdown
label: New Year
@@ -73,26 +78,34 @@ to: 2025-10-15 17:00
from: 2025-10-01 09:00
```
### Since (`since`)
Shows time elapsed since an event (or time until if the event is in the future).
**Fields:**
- `since` (or `from`, `date`): Event date/time
**Example:**
```date-calc
type: since
since: 2024-12-20
```
### Difference (`diff`)
Calculates the time difference between two specific dates.
**Fields:**
- `from` (or `start`): Start date/time
- `to` (or `end`): End date/time
**Examples:**
```date-calc
type: diff
from: 2024-02-29
@@ -103,7 +116,8 @@ to: 2025-03-01
type: diff
from: 2025-09-19 08:00
to: 2025-09-19 16:30
```
```
## Inline Usage
@@ -115,65 +129,122 @@ You can use inline code for quick calculations:
- `date-calc: from=2025-09-19 to=2025-09-20` → Date difference
**YAML Format:** Inline code also accepts YAML/inline-map format:
`date-calc: {type: birthday, birthday: 1992-08-16, name: Alice}`
`date-calc: {type: birthday, birthday: 1992-08-16}`
**Frontmatter Integration:** For inline birthday calculations, if no date is provided, the plugin will use the note's frontmatter `birthday`/`birthdate` property.
## Date Formats
- **Dates:** YYYY-MM-DD (e.g., `2025-12-31`)
- **Date + Time:** YYYY-MM-DD HH:mm (e.g., `2025-12-31 23:59`)
- **Timezone:** All calculations use your local timezone
- **Birthday Calculations:** Normalized to local midnight to avoid timezone inconsistencies
## Error Handling
## Configuration Options
The plugin provides helpful error messages for common issues:
### Verbose Output
- **Invalid YAML:** Shows parsing error details
- **Missing Required Fields:** Indicates which fields are needed
- **Invalid Dates:** Warns about unrecognizable date formats
Control output verbosity globally via settings or per-calculation:
**Global:** Settings → Date Calc → Verbose output
**Per-calculation override:**
Example of invalid YAML:
```date-calc
this: is: not: valid
type: countdown
to: 2026-12-31
verbose: true
```
Example of missing field:
```date-calc
type: diff
from: 2025-01-01
# Error: missing required "to" field
**Inline:** ```date-calc: countdown to=2026-12-31 verbose=true```
- `verbose: true` → "Countdown: 1 year, 2 months, 15 days"
- `verbose: false` → "1y 2mo 15d"
### Hide While Editing
Settings → "Hide result while cursor inside" prevents rendered output from showing while you're editing the code, keeping the raw syntax visible.
## Date Formats
| Format | Example | Use Case |
| :---------- | :-------------------- | :-------------------- |
| Date only | `2026-12-31` | Birthdays, countdowns |
| Date + time | `2026-12-31 23:59` | Precise countdowns |
| ISO 8601 | `2026-12-31T23:59:00` | Also supported |
All dates use your local timezone. Birthday calculations normalize to midnight to avoid timezone edge cases.
## Field Reference
### Birthday
- `birthday` / `birthdate` / `date` — Birth date
- `verbose` — Override output format (optional)
### Countdown
- `to` / `until` / `date` — Target date/time
- `from` — Start date (defaults to now)
- `label` — Custom prefix
- `verbose` — Override output format
### Since
- `since` / `from` / `date` — Event date/time
- `verbose` — Override output format
### Diff
- `from` / `start` — Start date/time
- `to` / `end` — End date/time
- `verbose` — Override output format
## Type Aliases
For convenience, use these shortcuts:
- `birthday` = `bday`
- `countdown` = `until`
- `diff` = `difference`
## Inline Syntax Formats
All three formats work:
**Key=value:** ```date-calc: birthday=1992-08-16```
**YAML-like:** ```date-calc: type: birthday, birthday: 1992-08-16```
**Compact:** ```date-calc: {type: birthday, birthday: 1992-08-16}```
## Custom Styling
Target these CSS classes in your snippets:
```css
/* Fenced block results */
.date-calc-block {
color: var(--text-accent);
font-weight: 500;
}
/* Inline code results */
.date-calc-inline {
background: var(--background-secondary);
padding: 2px 6px;
border-radius: 3px;
}
```
## Live Preview and Rendering
- **Fenced Code Blocks:** Work in all view modes (Source, Live Preview, Reading)
- **Inline Code:** Works in Reading view and Live Preview mode
- In Live Preview: Shows result after the inline code with an arrow (→)
- In Source mode: Shows literal code until you switch views
- **Code Inside Fenced Blocks:** Intentionally ignored to allow documentation examples
## Commands
## Troubleshooting Inline Code
- **Toggle debug** — Log decoration activity to console
- **Toggle verbose** — Switch global verbose mode
If inline code isn't rendering:
1. **Check View Mode:** Switch to Reading view or Live Preview mode
2. **Syntax:** Use single backticks (not triple): `date-calc: birthday=1992-08-16`
3. **Refresh:** Try toggling the note view or reloading the app
4. **Plugin Status:** Disable and re-enable the plugin if needed
The plugin's inline processor runs late in the processing chain to avoid conflicts with other processors.
## Styling
You can customize the appearance of date calculations using the CSS class `date-calc` in your snippets or theme.
For inline calculations, use the class `date-calc-inline`.
## Tips
- Use ISO date format (YYYY-MM-DD) for best compatibility
- Birthday calculations handle leap years and timezone edge cases
- For personalized birthday messages, add `name` and `gender` to your note's frontmatter
- The plugin integrates with Obsidian's metadata cache for frontmatter access