Skip to content

Commit

Permalink
Update documents
Browse files Browse the repository at this point in the history
  • Loading branch information
@pyrochlore
pyrochlore committed Apr 7, 2021
1 parent d4319a3 commit c976906
Show file tree
Hide file tree
Showing 7 changed files with 139 additions and 91 deletions.
145 changes: 54 additions & 91 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,133 +1,96 @@
# Obsidian Tracker Plugin

![GitHub release](https://img.shields.io/github/v/release/pyrochlore/obsidian-tracker)

This is an [Obsidian](https://obsidian.md/) plugin that helps us track tags and/or texts in daily notes.
This is an [Obsidian](https://obsidian.md/) plugin that helps you track tags and/or texts in daily notes.

For example, we can track simple tag (#exercise-pushup), value-attached tag (#weight:60kg), nested tag (#finance/bank1/transfer:100000USD) and/or text ('⭐', 'love', etc...) over a specified period of time. Currently, a line chart will be generated to represent the data.
For example, one can track simple tag (#exercise-pushup), value-attached tag (#weight:60kg), nested tag (#finance/bank1/transfer:100000USD) or text ('⭐', 'love', '👍', or '👎') over a specified period of time. Currently, a line chart or a summary will be generated to represent the tracked result.

<img src="https://raw.githubusercontent.com/pyrochlore/obsidian-tracker/master/images/screenshot.png" width="800">

## Installation
1. Download Obsidian from [Obsidian Official Site](https://obsidian.md/).
2. In panel Settings (from the icon at the buttom left corner)-> Options -> Community plugins, set 'safe mode' to off.
3. In the 'Community plugins' section, click 'Browse' and find this plugin by name 'Tracker'
4. Press button 'Install', scroll down to the bottom of section 'Installed plugins', and enable the Tracker plugin.
### From Obsidian Settings Panel
1. From Settings Panel (the icon at the bottom left corner) -> Options -> Community plugins, set 'safe mode' to off.
2. In the 'Community plugins' section, click 'Browse' and find the obsidian-tracker plugin by the name 'Tracker'.
3. Press the button 'Install' and wait for the completion of the install.
4. In the section 'Installed plugins', find and enable the plugin just installed.
5. Enjoy tracking.

### Manual Install
Download the latest [release](https://github.com/pyrochlore/obsidian-tracker/releases). Extract and put the three files (main.js, manifest.json, styles.css) to folder '{{obsidian_vault}}/.obsidian/plugins/obsidian-tracker'.

## Usage
1. Have some tags or texts you want to track in dialy notes.
1. Have some tags or texts you want to track in daily notes.
2. Add a new note for displaying the tracker.
2. Place a tracker codeblock into the note (see the illustration below)
3. Inside the tracker codeblock, add YAML key-value pairs to specify the search condition and details of the output (a line chart for now). Key '**searchType**' and '**searchTarget**' are neccesary as minimum setup for a successful render.
5. Switch the view mode to 'Preview', then the codeblock will get rendered.
3. Add tracker code blocks manually or using commands. See [Commands](docs/Commands.md) for more detail.
4. Switch the document view mode to 'Preview', then the code block will get rendered.

<img src="https://raw.githubusercontent.com/pyrochlore/obsidian-tracker/master/images/usage.gif" width="400">

## Search Type and Search Target
The value of key '**searchType**' can be '**tag**' or '**text**'.
For more use cases, please take a look at [examples](https://github.com/pyrochlore/obsidian-tracker/tree/master/examples).

If '**tag**' is picked, tags in your dialy notes will be counted and evaluated. Use the tag name (the name after #) as the value of key '**searchTarget**' or use quoted tag (**"#tagName"**) to make it work.
## Concepts
This plugin was designed to read code blocks in [YAML format](https://en.wikipedia.org/wiki/YAML). The key-value pairs in the code blocks tell the plugin what data to collect and how to render the result.

Simple tag like '*#tagName*' in your dialy note will be evaluated as a constant value (default value 1.0). You can customize the value by setting key '**constValue**' in the codeblock.
[Here](docs/KeyValuePairs.md) are all the keys placed at the root of YAML content. They are used for collecting data, evaluating targets, and data-preprocessing.

For advanced usage, a provided value can be attached to any tag. For example, write your own tag in the format of '*#tagName:value*'. The value should be appended right after your tag and a extra colon without spaces. If a value is attached this way, obsidian-trakcer will use the provided value instead of the constant one.
### Collecting Data
Providing key '**searchType**' and '**searchTarget**' is the minimum requirement for a successful data collection. The value of key '**searchType**' can be '**tag**' or '**text**', while the '**searchTarget**' is the name of a tag or a piece of text you want to search.

It's worth to note that tags in frontmatter will also be counted and act like simple tags. Moreover, nested tags are supported both on simple and valued tags.
### Target Evaluation
Depends on the searchType and the format of your targets, target evaluation can be different. Obsidian-tracker supports tracking simple tags, value-attached tags, nested tags, and text.
For more information about the tag evaluation, please check [Target Evaluation](docs/TargetEvaluation.md)

If '**text**' is picked for '**searchTarget**', the provid text will be counted and simply evaluated by occurence.
### Rendering Output
Currently, obsidian-tracker provides two kinds of rendering output, 'line chart', and 'summary'.

For more information about how to use this plugin, please take a look at [examples](https://github.com/pyrochlore/obsidian-tracker/tree/master/examples).
The default rendering output is 'line chart'. If key '**summary**' is not found at the YAML root, the output will be always 'line chart', otherwise, it will render 'summary' as output. You can use [pre-defined template variables](docs/TextExpansion.md) in text template (key '**template**' under key '**summary**').

## Default Settings
You can set default folder location and date format in the plugin settings paenl. You can also override them by key '**folder**' and '**dateFormat**' in codeblock respectively.
### Plugin Settings
You can set the default folder location and date format in the plugin's settings panel. You can also override them by key '**folder**' and '**dateFormat**' in the code block respectively.

Here are the list of default settings.
Here is the list of default settings.

| Setting Item | Default | Description |
|:--------:|:-------:|:---------:|
| Default folder location | Root of this vault | The folder your dialy notes reside |
| Default date format | YYYY-MM-DD | The date format of your dialy note title |

## List of All Available Keys

### Root Keys
These keys are placed under YAML root

| Key | Default | Description |
|:--------:|:-------:|:-----------:|
| **searchType** | 'tag' or 'text' | The type of your search target |
| **searchTarget** | empty string | The tag name or text to search |
| **folder** | Default folder location | The folder path of your daily notes |
| **dateFormat** | Default date format | The date format of your dialy note title |
| **startDate** | Min date found | The start date to count |
| **endDate** | Max date found | the end date to count |
| **constValue** | 1.0 | The constant value of all simple tags |
| **ignoreAttachedValue** | false | Use constant value event if a value attached on |
| **accum** | false | Accumulatively sum the values over time |
| **penalty** | 0.0 | The value to use if search target is missing on the day |
| **line** | | All line-related keys should be placed under this key |

### Line-related Keys
These keys should be placed under key '**line**'.

| Key | Default | Description |
|:--------:|:-----------:|:-----------:|
| **title** | empty string | The title of this line chart|
| **xAxisLabel** | 'Date' | X axis label |
| **yAxisLabel** | 'Value' | Y axis label |
| **labelColor** | 'white'('black'<sup>*</sup>) | The color of labels |
| **yAxisUnit** | empty string | The unit displayed aside y axis label |
| **yMin** | Minimum Y value found | The minimum value shown on Y axis |
| **yMax** | Maximum Y value found | The maximum value shown on Y axis |
| **axisColor** | 'white'('black'<sup>*</sup>) | The color of axes |
| **lineColor** | 'white'('black'<sup>*</sup>) | |
| **lineWidth** | 1.5 | The width of line|
| **showLine** | true | Show/hide line |
| **showPoint** | true | Show/hide data point |
| **pointColor** | "#69b3a2" | The color of data point |
| **pointBorderColor** | #69b3a2 | The border color of data point |
| **pointBorderWidth** | 0 | The border width of data point |
| **pointSize** | 3 | The size of data point |
| **allowInspectData** | true | Show data value aside data point |
| **fillGap** | false | Connect points over missing data |
| Default folder location | Root of the vault | The folder your daily notes reside |
| Default date format | YYYY-MM-DD | The date format of your daily note title |

## Release Notes
### v1.1.0
- New output type 'summary'.
- Add commands help create Tracker code blocks.
- Relax the regex for searching tags, allow tags embedded in sentences.
- Fix issues.

### v1.0.2

- Fix the searching of nested tag in frontmatter
- Reduce the package size by using Obsidian internal module
- Fix the searching of nested tag in frontmatter.
- Reduce the package size by using the module from Obsidian.

### v1.0.1

- Remove dependencies to Node.js modules
- Add example markdown files
- Remove dependencies to Node.js modules.
- Add example markdown files.

### v1.0.0
First version released at 2021-03-23.

First version released at 2021-03-23

- Track simple tags, value-attached tags, and texts using codeblock
- Represent the tracked data in a customizable line chart
- Allow tracking in-line tags and tags in frontmatter
- Allow tracking nested tags
- Track simple tags, value-attached tags, and texts using code blocks.
- Represent the tracked data in a customizable line chart.
- Allow tracking in-line tags and tags in frontmatter.
- Allow tracking nested tags.

## Road Map

May not implemented in this order

- [ ] New output type 'text', analyze the input data and represent it using user-defined text template
- [ ] New output type 'table', list the search result in a formated table
- [ ] New output type 'heatmap', like Github calendar heatmap
- [ ] Support multiple tags and texts
- [ ] Add Commands to insert different types of codeblocks
- [ ] Add data post-process function like 'moving average'
- [ ] Add 'Explode' button onto rendered block, it can replace the codeblock by rendered result
- [x] New output type 'summary', analyzes the input data and represents it using a user-defined text template.
- [x] Add Commands help create Tracker blocks.
- [ ] New output type 'table', lists the search result in a formatted table.
- [ ] New output type 'heatmap', works like Github calendar heatmap.
- [ ] Support multiple targets and multiple values.
- [ ] Support searching text using regular expression.
- [ ] Add data post-process function, like 'moving average'.
- [ ] Add an 'Explode' button to the rendered blocks, it will replace the code block with the rendered result.

And more ...
P.S. Items may not be implemented in the order above.

## Support

- If you like this plugin or want to support the further development, you can [Buy Me a Coffee](https://www.buymeacoffee.com/pyrochlore).
- If you like this plugin or want to support further development, you can [Buy Me a Coffee](https://www.buymeacoffee.com/pyrochlore).
- Please report bugs and request features in [GitHub Issues](https://github.com/pyrochlore/obsidian-tracker/issues)
6 changes: 6 additions & 0 deletions docs/Commands.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
# Commands Help Add Tracker Code Block
To smooth the process of making trackers, we provide two commands, "Add Line Chart Tracker" and "Add Summary Tracker". Simply type Ctrl/Cmd+P to activate the command palette, then type "Tracker" to get the commands.

After picking a command, a tracker code block of your choice will be added to the next line below your cursor, including all keys and default values. Now it's your call to fill in data for searching and rendering.

Except for 'searchType' and 'searchTarget', Key-value pairs with default values can be removed for a concise code block.
51 changes: 51 additions & 0 deletions docs/KeyValuePairs.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# Key-Value Pairs

## Key-Value Pairs for Data Collection, Target Evaluation, and Data Preprocessing
These keys are placed under YAML root

| Key | Default | Description |
|:--------:|:-------:|:-----------:|
| **searchType** | 'tag' or 'text' | The type of your search target |
| **searchTarget** | empty string | The tag name or text to search |
| **folder** | Default folder location | The folder path of your daily notes |
| **dateFormat** | Default date format | The date format of your dialy note title |
| **startDate** | Min date found | The start date to count |
| **endDate** | Max date found | the end date to count |
| **constValue** | 1.0 | The constant value of all simple tags |
| **ignoreAttachedValue** | false | Use constant value event if a value attached on |
| **ignoreZeroValue** | false | Use constant value event if a value attached on |
| **accum** | false | Accumulatively sum the values over time |
| **penalty** | 0.0 | The value to use if search target is missing on the day |
| **line** | | All line-related keys should be placed under this key |
| **summary** | | All line-related keys should be placed under this key |


### Line Chart Related Keys
These keys should be placed under root key '**line**'.

| Key | Default | Description |
|:--------:|:-----------:|:-----------:|
| **title** | empty string | The title of this line chart|
| **xAxisLabel** | 'Date' | X axis label |
| **yAxisLabel** | 'Value' | Y axis label |
| **labelColor** | 'white'('black'<sup>*</sup>) | The color of labels |
| **yAxisUnit** | empty string | The unit displayed aside y axis label |
| **yMin** | Minimum Y value found | The minimum value shown on Y axis |
| **yMax** | Maximum Y value found | The maximum value shown on Y axis |
| **axisColor** | 'white'('black'<sup>*</sup>) | The color of axes |
| **lineColor** | 'white'('black'<sup>*</sup>) | |
| **lineWidth** | 1.5 | The width of line|
| **showLine** | true | Show/hide line |
| **showPoint** | true | Show/hide data point |
| **pointColor** | "#69b3a2" | The color of data point |
| **pointBorderColor** | #69b3a2 | The border color of data point |
| **pointBorderWidth** | 0 | The border width of data point |
| **pointSize** | 3 | The size of data point |
| **allowInspectData** | true | Show data value aside data point |
| **fillGap** | false | Connect points over missing data |

### Summary Related Keys
These keys should be placed under root key '**summary**'.

| **template** | "" | Text template |
| **style** | "" | css style for the text block |
10 changes: 10 additions & 0 deletions docs/TargetEvaluation.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# Target Evaluation
If the assigned '**searchType**' is '**tag**', tags in your daily notes will be counted and evaluated. You should use the tag name (the name after #) as the value of key '**searchTarget**' or use quoted tag ('**#tagName**') to make it work.

A simple tag is a tag in the format of '*#tagName*'. They will be evaluated as a constant value (default value 1.0). You can change the value by assigning the key '**constValue**' in the code block.

The unique feature in the obsidian-tracker is to identify the value-attached tag. Users can attach a value after the tag in the format of '*#tagName:value*'. Note the value should be appended right after your tag and an extra colon without spaces. If a value is attached this way, the obsidian-tracker will use the provided value instead of the constant one.

Nested tags are also supported. One can use them to track parent-tag and children-tags separately. It's worth noting that frontmatter tags are also included but can only be treated as simple tags. Currently, Obsidian will treat tags with different values as different tags.

If the assigned '**searchType**' is '**text**', texts will be counted and simply evaluated by occurrence.
18 changes: 18 additions & 0 deletions docs/TextExpansion.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# Text Expansion

Here is the list of pre-defined template variables. They will be expanded according to the calculation of data.

| Template variable | Description |
|:------------------:|:-----------:|
| {{min}} | Minimum value |
| {{max}} | Maximum value |
| {{sum}} | Summation |
| {{count}} | Count of not-null values |
| {{days}} | Days from startDate to endDate |
| {{maxStreak}} | Maximum Streak |
| {{maxBreak}} | Maximum Break |
| {{average}} | Average value |
| {{median}} | Median value |
| {{variance}} | Variance value |

When doing the calculation, the missing value will be ignored. Also, if 'ignoreZeroValue' is assigned true, zero value will be ignored.
0 images/screenshot.png → docs/images/screenshot.png
View file
File renamed without changes
0 images/usage.gif → docs/images/usage.gif
View file
File renamed without changes

0 comments on commit c976906

Please sign in to comment.