From 8a83b4d57da408c0c7756f4eff4a5c5d6492bdcf Mon Sep 17 00:00:00 2001 From: pyrochlore Date: Mon, 21 Jun 2021 20:32:51 +0800 Subject: [PATCH] Update documents --- README.md | 24 +++++++++--------------- docs/Commands.md | 2 +- docs/Concepts.md | 15 ++++++++++++--- docs/Examples.md | 28 +++++++++++++++++++++++++++- docs/InputParameters.md | 22 ++++++++++++++++++++++ docs/ReleaseNotes.md | 15 +++++++++------ docs/RoadMap.md | 11 ++++++----- docs/Settings.md | 4 ++-- docs/TargetEvaluation.md | 24 +++++++++++++----------- 9 files changed, 101 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index a545048..d7d2938 100644 --- a/README.md +++ b/README.md @@ -3,36 +3,30 @@ -This is an [Obsidian](https://obsidian.md/) plugin that helps you do tracking in notes [over dates](https://github.com/pyrochlore/obsidian-tracker/blob/master/docs/Questions.md) and represent the collected data comprehensively. +This is an [Obsidian](https://obsidian.md/) plugin that helps you do tracking in notes and represent the collected data comprehensively. [Here](https://github.com/pyrochlore/obsidian-tracker/blob/master/docs/Examples.md) is a simplified table of examples showing what you can track. ## What's New -Version 1.6.1 -1. Add new targets 'numWords', 'numChars', and 'numSentences' for input type 'fileMeta' ([examples](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestWordCounting.md)) - -Version 1.6.0 -1. Add a new input type 'fileMeta', getting meta data from a file ([examples](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestFileMeta.md)) -2. Add a new output type 'bullet', rendering a bullet chart ([examples](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestBullet.md)) -3. Accept tracking time values ([examples](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestTimeValues.md)) -4. Allow tracking nested values from front matter -5. Allow using dataset with date values as xDataset ([examples](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestXDataset.md)) -6. Add more template variables ([examples](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestXDataset.md)) -7. Allow parsing date in wiki brackets +Version 1.7.0 +- Add a new output type 'month', rendering a month view for a given dataset ([examples](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestCalendar.md)) ## Usage -1. Have some targets you want to track in daily notes. Take a look at [Target Evaluation](https://github.com/pyrochlore/obsidian-tracker/blob/master/docs/TargetEvaluation.md) for what you can track and how targets are evaluated as numbers. +1. Have some targets you want to track in daily notes. 2. Add a new note for displaying the tracker. -3. Add tracker code blocks manually or using commands. See [Commands](https://github.com/pyrochlore/obsidian-tracker/blob/master/docs/Commands.md) for more details. +3. Add tracker code blocks manually or using [commands](https://github.com/pyrochlore/obsidian-tracker/blob/master/docs/Commands.md). 4. Switch the document view mode to 'Preview', then the code block will get rendered. -For more use cases, please open the [examples](https://github.com/pyrochlore/obsidian-tracker/tree/master/examples) folder in obsidian with this plugin installed and enabled. +For more use cases, please download and open the [examples](https://github.com/pyrochlore/obsidian-tracker/tree/master/examples) folder in obsidian with this plugin installed and enabled. ## More Details You May Want to Know - [Installation](https://github.com/pyrochlore/obsidian-tracker/blob/master/docs/Installation.md): Install the plugin from Obsidian or install it manually - [Concepts](https://github.com/pyrochlore/obsidian-tracker/blob/master/docs/Concepts.md): Explain how this plugin works and what to setup + - [Target Evaluation](https://github.com/pyrochlore/obsidian-tracker/blob/master/docs/TargetEvaluation.md) + - [Input Parameters](https://github.com/pyrochlore/obsidian-tracker/blob/master/docs/InputParameters.md) + - [Template Variables](https://github.com/pyrochlore/obsidian-tracker/blob/master/docs/TemplateVariables.md) - [Examples](https://github.com/pyrochlore/obsidian-tracker/blob/master/docs/Examples.md) - [Plugin Settings](https://github.com/pyrochlore/obsidian-tracker/blob/master/docs/Settings.md) - [Release Notes](https://github.com/pyrochlore/obsidian-tracker/blob/master/docs/ReleaseNotes.md) diff --git a/docs/Commands.md b/docs/Commands.md index 0fbb182..b40905b 100644 --- a/docs/Commands.md +++ b/docs/Commands.md @@ -1,5 +1,5 @@ # Commands -To smooth the process of making trackers, obsidian-tracker provides three commands, "Add Line Chart Tracker", "Add Bar Chart Tracker", and "Add Summary Tracker; Just type Ctrl/Cmd+P to activate the command palette, then type "Tracker" to search these commands. +To smooth the process of making trackers, obsidian-tracker provides three commands (There will be more in the future release), "Add Line Chart Tracker", "Add Bar Chart Tracker", and "Add Summary Tracker; Just type Ctrl/Cmd+P to activate the command palette, then type "Tracker" to search these commands. After a command is executed, a code block will be added to the next line below your cursor position for you. The added code block will contain the most frequently used keys. To see the complete list of input parameters and description, please check [this document](https://github.com/pyrochlore/obsidian-tracker/blob/master/docs/InputParameters.md). \ No newline at end of file diff --git a/docs/Concepts.md b/docs/Concepts.md index aad2975..bf56509 100644 --- a/docs/Concepts.md +++ b/docs/Concepts.md @@ -5,16 +5,25 @@ This plugin was designed to read code blocks in [YAML format](https://en.wikiped [Here](https://github.com/pyrochlore/obsidian-tracker/blob/master/docs/InputParameters.md) are all the parameters (key-value pairs) defined in this plugin. They are used for collecting data, evaluating targets, data preprocessing, and rendering output. ### Collecting Data + Providing parameters `searchType` and `searchTarget` is the minimum requirement for a successful data collection. `searchType` can be `tag`, `frontmatter`, `wiki`, `dvField`, `table`, `fileMeta`,or `text`. Then the cooresponding `searchTarget` should be provided according to the specified type. ### Target Evaluation + Depends on the `searchType` and the `searchTarget` you provided, the evaluation of a target would be different. Simply speaking, you can track the occurrences of a target or the value attached/embedded in it. To see the detail about the target evaluation, please check the document [Target Evaluation](https://github.com/pyrochlore/obsidian-tracker/blob/master/docs/TargetEvaluation.md). ### Rendering Output -Currently, obsidian-tracker provides three kinds of rendering output, the default one 'line' for a line chart, 'bar' for a bar chart, and 'summary' for a text block. -For 'line' or 'bar' output, the plugin will generate a customizable chart. For 'summary' output, a text block based on your '**template**' parameter will be generated. You can also use [pre-defined template variables](https://github.com/pyrochlore/obsidian-tracker/blob/master/docs/TemplateVariables.md) in the template. +Currently, obsidian-tracker provides five kinds of rendering output: `line`, `bar`, `summary`, `bullet`, and `month`. You have to provide at least one output parameter in a code block. + +With output set to `line` or `bar`, Tracker plugin will generate a customizable chart. These charts are very good at seeing the variation of collected number in the notes. + +With the `summary` output, a text block based on your '**template**' parameter will be created. You can use [pre-defined template variables](https://github.com/pyrochlore/obsidian-tracker/blob/master/docs/TemplateVariables.md) like '{{sum}}' or '{{maxStreak}}' in the template parameter, to get a statistical summary of collected data. + +`bullet` output creates a [bullet chart](https://en.wikipedia.org/wiki/Bullet_graph) and could serve as a gauge showing the status (level, performance, progress) of a dataset. + +`month` output creates a month view with circled dates exceeding the given threshold and streaks showing how long it persisted. -Description for the chart and summary related paremeters can be found [here](https://github.com/pyrochlore/obsidian-tracker/blob/master/docs/InputParameters.md#parameters-for-common-chart) and [here](https://github.com/pyrochlore/obsidian-tracker/blob/master/docs/InputParameters.md#parameters-for-summary) respectively. \ No newline at end of file +Detailed description for all parameters of the output types can be found [here](https://github.com/pyrochlore/obsidian-tracker/blob/master/docs/InputParameters.md). \ No newline at end of file diff --git a/docs/Examples.md b/docs/Examples.md index 8732407..e4dcd77 100644 --- a/docs/Examples.md +++ b/docs/Examples.md @@ -33,4 +33,30 @@ The following table lists use cases with information of target location (Locatio ## Full examples -Full tracker code blocks can be found [here](https://github.com/pyrochlore/obsidian-tracker/tree/master/examples) and the corresponding notes can be found under folder 'diary' and 'data'. \ No newline at end of file +Full tracker code blocks can be found in [this folder](https://github.com/pyrochlore/obsidian-tracker/tree/master/examples) and the corresponding notes can be found under folder 'diary' and 'data'. + +List of all examples +- [Bloodpressure Tracker](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/BloodPressureTracker.md) +- [Error Messages](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/ErrorMessages.md) +- [Finance Tracker](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/FinanceTracker.md) +- [Habit Trakcer](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/HabitTracker.md) +- [Mood Tracker](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/MoodTracker.md) +- [Star Tracker](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/StarTracker.md) +- [Bar Chart](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestBarChart.md) +- [Bullet Chart](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestBullet.md) +- [Calendar](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestCalendar.md) +- [Date Formats](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestDateFormats.md) +- [Dataview Inline Field](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestDvField.md) +- [File Meta](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestFileMeta.md) +- [Legends](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestLegends.md) +- [Multiple Targets / Multiple Values](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestMultipleTargetsMultipleValues.md) +- [Scaling and Positioning](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestScalingAndPositioning.md) +- [Table](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestTable.md) +- [Template Variables](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestTemplateVariables.md) +- [Time Values](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestTimeValues.md) +- [Word Counting](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestWordCounting.md) +- [X Dataset](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestXDataset.md) +- [Regular Expression](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TrackUsingRegex.md) +- [Weight Tracker](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/WeightTracker.md) +- [Wiki](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/WikiTracker.md) + diff --git a/docs/InputParameters.md b/docs/InputParameters.md index e8c33bd..77b3479 100644 --- a/docs/InputParameters.md +++ b/docs/InputParameters.md @@ -114,3 +114,25 @@ These key-value pairs should be placed under the key `bullet`. | `showMarker` | Show marker or not (true\|false) | 1 | true | | `markerValue` | The value of the markder | 1 | 0 | | `markerColor` | The color of the marker | 1 | 'black' | + +### Parameters for Month View +These key-value pairs should be placed under the key `month`. + +| Key | Description | Number of Values | Default | +|:--------|:-------|:-----------:|:------| +| `dataset` | The index of the dataset of your interest | 1 | 0 | +| `startWeekOn` | First day of a week ('Sun'\|'Mon') | 1 | 'Sun' | +| `threshold` | The threshold to determine showing a circle on a day or not | 1 | 0 | +| `showCircle` | Circle the day label if the collected value reach the threshold (value > threshold) | 1 | true | +| `color` | Main color (can be override by other color parameters) | 1 | null | +| `dimNotInMonth` | Dim the color for days not in current month | 1 | true | +| `showStreak` | Show streaks between circles | 1 | true | +| `showTodayRing` | Show a ring on the label today | 1 | true | +| `showSelectedValue` | Show the value on the selected day | 1 | true | +| `showSelectedRing` | Show a ring on the label of the selected day | 1 | true | +| `circleColor` | The color of circles | 1 | '#69b3a2' | +| `headerYearColor` | The color of year text in header | 1 | 'white' | +| `headerMonthColor` | The color of the month text in header | 1 | 'white' | +| `dividingLineColor` | The color of the dividing line | 1 | '#69b3a2' | +| `todayRingColor` | The color of the ring on today | 1 | 'white' | +| `selectedRingColor` | The color of the ring on the selected day | 1 | 'firebrick' | \ No newline at end of file diff --git a/docs/ReleaseNotes.md b/docs/ReleaseNotes.md index 3ac740c..7bb2be1 100644 --- a/docs/ReleaseNotes.md +++ b/docs/ReleaseNotes.md @@ -1,16 +1,19 @@ # Release Notes +## v1.7.0 +- Add a new output type 'month', rendering a month view for a given dataset ([examples](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestCalendar.md)) + ## v1.6.1 -- Add new targets 'numWords', 'numChars', and 'numSentences' for input type 'fileMeta' +- Add new targets 'numWords', 'numChars', and 'numSentences' for input type 'fileMeta' ([examples](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestWordCounting.md)) ## v1.6.0 -- Add a new input type 'fileMeta', getting meta data from a file -- Add a new output type 'bullet', rendering a bullet chart +- Add a new input type 'fileMeta', getting meta data from a file ([examples](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestFileMeta.md)) +- Add a new output type 'bullet', rendering a bullet chart ([examples](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestBullet.md)) - Enhancement - - Accept tracking time values + - Accept tracking time values ([examples](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestTimeValues.md)) - Allow tracking nested values from front matter - - Allow using dataset with date values as xDataset - - Add more template variables + - Allow using dataset with date values as xDataset ([examples](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestXDataset.md)) + - Add more template variables ([examples](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestTemplateVariables.md)) - Allow parsing date in wiki brackets - Fixed bugs diff --git a/docs/RoadMap.md b/docs/RoadMap.md index 9b62485..25112dd 100644 --- a/docs/RoadMap.md +++ b/docs/RoadMap.md @@ -3,7 +3,7 @@ - Data Collecting - [x] Support tracking key-value pairs in frontmatter - [x] Support searching text using regular expression - - [x] Support multiple targets and multiple values. + - [x] Support multiple targets and multiple values - [x] Add a parameter xDataset to identify targets to be used as x values - [x] Allow tracking time values - [x] Get data from a table @@ -13,11 +13,12 @@ - [ ] Allow forced value types - [ ] Allow using non-date x values - Output Type and Graph - - [x] New output type 'summary', analyzes the input data and represents it using a user-defined text template. - - [x] New output type 'bar', rendering a bar chart. + - [x] New output type 'summary', analyzes the input data and represents it using a user-defined text template + - [x] New output type 'bar', rendering a bar chart - [x] New output type 'bullet', rendering - - [ ] New output type for calendar view, including a monthly view or a heatmap. - - [x] Add parameters for adjusting the size of the graph. + - [x] New output type 'month', rendering a month view + - [ ] New output type 'heatmap', rendering a heatmap like Github activity chart + - [x] Add parameters for adjusting the size of the graph - [ ] Multiple outputs from one code block - [ ] Support graphs showing the correlation between sets of data. - [ ] Allow a graph drawing selected dataset. diff --git a/docs/Settings.md b/docs/Settings.md index 3fc596d..32b2c6f 100644 --- a/docs/Settings.md +++ b/docs/Settings.md @@ -1,10 +1,10 @@ # Plugin Settings -The default folder to search and date format can be defined in the plugin's settings panel. If `folder` and `dateFormat` are not assigned in your code blocks, these default values will be applied automatically. +The default folder to search and the date format can be defined in the plugin's settings panel. If `folder` and `dateFormat` are not assigned in your code blocks, these default values will be applied automatically. | Setting Item | Description | Default | |:--------|:-------|:---------| | Default folder location | The folder to search | Root of the vault | | Default date format | The date format you are using | 'YYYY-MM-DD' | -For more information about the dateFormat setting, please also check the [TestDateFormats example](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestDateFormats.md) and [moment.js string format](https://momentjs.com/docs/#/parsing/string-format/). \ No newline at end of file +For more information about the dateFormat setting, please also check the [TestDateFormats example](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestDateFormats.md) and [moment.js string format](https://momentjs.com/docs/#/parsing/string-format/). \ No newline at end of file diff --git a/docs/TargetEvaluation.md b/docs/TargetEvaluation.md index cc1d80a..e5653ab 100644 --- a/docs/TargetEvaluation.md +++ b/docs/TargetEvaluation.md @@ -1,9 +1,9 @@ # Target Evaluation -According to the [input parameters](https://github.com/pyrochlore/obsidian-tracker/blob/master/docs/InputParameters.md) you provided, the search targets will be counted or evaluated as a value. Obsidian-tracker supports seven kinds of `searchType`: `tag`, `frontmatter`, `wiki`, `text`, `table`, `dvField`, and `fileMeta`, dealing with different types of searching condition. +From the [input parameters](https://github.com/pyrochlore/obsidian-tracker/blob/master/docs/InputParameters.md) you provided, the search targets dispersed in the notes will be counted or evaluated as a value. Tracker plugin supports seven kinds of `searchType`: `tag`, `frontmatter`, `wiki`, `text`, `table`, `dvField`, and `fileMeta`, dealing with different types of searching condition. ## Multiple Targets -You can provide multiple search targets by entering an array of targets separated by a comma. Each of the targets will be identified according your search condition then the corresponding value will be evaluated and form a dataset indexed by the order in the array (zero-based indexing). +You can provide multiple search targets in code block by entering an array of targets separated by a comma under parameter `searchType` and `searchTarget`. Each of the targets will be identified in order and then the values in notes will be evaluated and form a dataset indexed by that order in the array (zero-based indexing). ``` searchTarget: target0, target1, target2, ...... @@ -13,15 +13,17 @@ line: lineColor: red, blue, yellow ``` -Above is an example of multiple target searching. Multiple targets are provided and separated by a comma. If they have a different searchType, provide the same number of types in the same order. In this case, the second search target 'target1' with index 1 has type 'type1'. Other parameters that accept multiple values (e.g. lineColor) can also be provided and will be applied to the corresponding dataset. +Above is an example of multiple targets searching. In the code block, multiple targets are provided and separated by a comma. If they have a different searchType, provide the same number of types in the same order. In this case, the second search target 'target1' with index 1 has type 'type1' and name 'dataset1'. + +Many other parameters that accept multiple values (e.g. lineColor) can also be provided and the value given will be applied to the corresponding dataset. ## Multiple Values -Multiple values under a target (value tuple) separated by a slash, e.g. #bloodpressure:180/120mmHg, are also got supported in version 1.3.0. To identify a specific value as a target, use an accessor with bracket notation where the value in the bracket is the index by the order of values. In this case, they are bloodpressure[0] and bloodpressure[1]. You can find the example of this [here](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/BloodPressureTracker.md). You can also use a custom separator by using the parameter `separator`. +Multiple values under a target (value tuple) separated by a slash, e.g. #bloodpressure:180/120mmHg, are supported after version 1.3.0. To identify a specific value as a target, use an accessor with bracket notation where the value in the bracket is the index by the order of values. In this case, they are bloodpressure[0] and bloodpressure[1]. You can find the example of this [here](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/BloodPressureTracker.md). You can also use a custom separator by using the parameter `separator`. ## Search Target in Detail -## searchType: tag +### searchType: tag Simple tags in the format of '*#tagName*' in the file content are evaluated as a constant value (default value 1.0). You can override the value by assigning the key `constValue` in the code block. Use the tag name (the name after #) as the value of key `searchTarget` or use quoted tag (`#tagName`) to make it work. @@ -40,7 +42,7 @@ Nested tags with values attached could be useful for tracking children's data se If you don't want value-attached tags in your content, you can also put data in front matter and use `frontmatter` as your searchType. -## searchType: frontmatter +### searchType: frontmatter This search type is used to query the key-value pairs in the front matter. If you don't want these values been seen in your article, the front matter would be the best place to record. For example, @@ -49,12 +51,12 @@ mood: 10
......
\-\-\-
-## searchType: wiki +### searchType: wiki This search type helps you count wiki links in articles. For example, [[A]] [[B|Link to B]] -## searchType: text +### searchType: text searchType `text` is the most powerful one among all. If you simply provide text like 'love', the number of occurrences of tags will be counted. You can provide a regular expression to search for a very complicated target by wrapping it in single quotes. If you want to retrieve a value from it, use the group name in the expression. To see more detail, see [this case](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TrackUsingRegex.md). Multiple values in text search can be achieved by separate regex by comma and wrap them all in single quotes as follows: @@ -64,7 +66,7 @@ searchTarget: 'regex1, regex2' ...... ``` -## searchType: dvField +### searchType: dvField Tracker supports retrieving inline fields used with the dataview plugin. To get "targetName:: value" in your article, try the following tracker settings. @@ -85,7 +87,7 @@ separator: '@' More dvField example can be found [here](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestMultipleTargesMultipleValues.md#multiple-values-in-dvfield-dataview-inline-field). -## searchType: table +### searchType: table This search type is very much different from others because it does not search over files in the specified folder. Instead, it looks into a given file, finds the specified table, and retrieves data from specified columns. Here is an example, @@ -103,7 +105,7 @@ In this case, "data/Tables" is the path of the file of interest. The number in More table examples can be found [here](https://github.com/pyrochlore/obsidian-tracker/blob/master/examples/TestTable.md). -## searchType: fileMeta +### searchType: fileMeta With this search type, you can retrieve infomation of files. Currently, three kinds of data you can get.