diff --git a/docs/docs/changelog.md b/docs/docs/changelog.md index d8fb708..07b5b05 100644 --- a/docs/docs/changelog.md +++ b/docs/docs/changelog.md @@ -12,6 +12,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## Unreleased +## v2.0.0 (2024-12-15) + :::info Help wanted! diff --git a/docs/versioned_docs/version-2.0.0/changelog.md b/docs/versioned_docs/version-2.0.0/changelog.md new file mode 100644 index 0000000..07b5b05 --- /dev/null +++ b/docs/versioned_docs/version-2.0.0/changelog.md @@ -0,0 +1,400 @@ +--- +sidebar_position: 7 +toc_max_heading_level: 2 +--- + +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## Unreleased + +## v2.0.0 (2024-12-15) + +:::info + +Help wanted! + +This release has added rudimentary support for translating the plugin into other languages. If you'd like to help out, please see the [translation contribution guide](./contributing/translation). + +::: + +:::warning + +Note: the style changes in this release mean that you may need to tweak any custom CSS or themes. The changes are designed for the +default Obsidian theme. + +::: + +### Breaking changes + +- Removed the deprecated settings for rendering the description, due date, labels, or projects. Please use the `show` property in the query. +- Removed the `group` property in queries. Please use the `groupBy` property instead. + +### ✨ Features + +- Rebuilt the task renderer from the ground up. This now resembles Todoist more closely and has improved the default styling. +- Added support for translations in the plugin +- Added a setting to control whether the embedded "Add task" button in a query should automatically add a link to the current page. + - This behaviour can now be turned off or configured to append to the task name or description. + +### 🔁 Changes + +- Tweaked the onboarding modal to hopefully be more reliable in validating the token and allowing you to save the token. +- Greatly reduced plugin startup time. This should improve your vault's load time. +- The setup button in the settings is no longer disabled except when the plugin is validating the token. + +## v1.13.0 (2024-04-10) + +### ✨ Features + +- Rebuilt the onboarding modal that users are presented with upon installing the plugin. This now offers feedback to users based on the token they've provided. + - We also no longer use a native browser alert if the token isn't present. Instead, we prefer to open the modal each time Obsidian is opened if there is no valid token. +- Rebuilt the settings page from scratch. It is now divided into sections to organize the settings. + - Now includes useful links to documentation and GitHub issues. + - API token validation is done in the settings page with an option to open the modal if the validation fails. +- You can now group by different task properties like: priority, due date, and others. Please see the [documentation](https://jamiebrynes7.github.io/obsidian-todoist-plugin/docs/query-blocks#groupBy) for more details. +- Rebuilt the add task dialog from scratch. This should fix a number of bugs with the date picker, improves the UX, and brings it inline with the native Todoist experience. +- Added a new command 'Add task with current page in task description' which offers the ability to append a link to the current page to the task description when it is created. +- Added support for adding time to due dates in the "create task" modal. + +### 🔁 Changes + +- Added rendered deprecation warnings to queries. Please follow the warnings to avoid breaking changes in the future! + +### 🐛 Bug Fixes + +- The `priorityAscending` and `priorityDescending` options now sort tasks in the correct order. + +## v1.12.0 (2024-02-09) + +> Note: the style changes in this release mean that you may need to tweak any custom CSS or themes. The changes are based on the default theme. + +### Deprecated + +- Please note that the "Render Descriptions", "Render Dates", "Render project & section", and "Render labels" settings are now deprecated. You can now control whether these render or not via the `show` property in the query itself. These will be removed in a future release. + +### ✨ Features + +- Added the option to wrap page links in parenthesis when creating tasks with the command. You may find this useful if you primarily use Todoist on mobile where links are less obvious. Thanks to [@ThDag](https://github.com/ThDag) for the contribution! +- You can now use the `{{filename}}` placeholder in the filter property. This will be replaced with the name of the file where the query is defined. + - For example, if the full file path is `My Vault/Notes/How to Take Smart Notes.md` then the replaced file name will be `How to Take Smart Notes`. +- Added "Add item" button to rendered queries. This will open the task creation modal. +- Added the ability to control which elements of the task metadata render with tasks inside the query with the `show` keyword. +- You can now sort by when the task was added to Todoist using `dateAdded` and `dateAddedAscending` sort options. +- The div rendered when there are no tasks returned by a query now has a `todoist-no-tasks` class to allow you to customize the CSS. + +### 🔁 Changes + +- You can now toggle whether or not task descriptions are rendered for each task. +- Change the style of the sync button to match the Obsidian style of the "edit" codeblock button. +- Fix intent level to match standard markdown levels in order to have consistent style. +- Aligned the grouping behaviour with Todoist's when grouping by project. This will be expanded on in a future release. +- Changed all icons to be part of the Lucide set to align with Obsidian. +- The `title` part of the query is now optional. + +### 🐛 Bug Fixes + +- Opening tasks via the context menu should now work properly on mobile devices. + +## v1.11.1 (2023-04-09) + +### 🐛 Bug Fixes + +- Task completions should now behave properly. + +## v1.11.0 (2023-04-08) + +### ✨ Features + +- You can now use YAML for writing your Todoist queries. +- Tasks that are due today now have the `task-today` CSS class. +- Task descriptions are now rendered with the task. + - If the description is multiple lines or has complex Markdown, it is rendered as a preview. + - The preview can be expanded and closed by double-clicking on the preview. +- The task description can now be set from the 'Add Todoist task' modal. + +### 🔁 Changes + +- Improved the alignment of the task metadata for the default Obsidian theme. + +### 🐛 Bug Fixes + +- Using the 'Add Todoist Task' command should correctly use the selection in an editor pane. +- Subtask lists should no longer display erroneous messages when all the subtasks are closed. +- Fixed logical bugs in handling failures when marking a task as done. + +### ⚙ Internal + +- Ensured that all API requests to Todoist have debug & error logging. + +## v1.10.1 (2022-12-22) + +### 🐛 Bug Fixes + +- Requests to Todoist's API should no longer fail CORS checks. + +## v1.10.0 (2022-10-17) + +### ✨ Features + +- You can now press 'Enter' in the create task dialog to create the task. [Thanks to @oleeskild](https://github.com/oleeskild) +- This plugin's default styles updated to the new theme in Obsidian v1.0. + +### 🔁 Changes + +- The priority CSS classes now appear on the outer `div` for a given task. This should allow you to style the entire task, not just the checkbox/description. + +### 🐛 Bug Fixes + +- The plugin should now respect your Vault configuration directory when saving your Todoist token. + +### ⚙ Internal + +- This plugin now uses the Todoist REST API v2. [Thanks to @gnapse](https://github.com/gnapse)! + +## v1.9.0 (2022-01-19) + +### ✨ Features + +- This plugin is now compatible with live preview! Please report any functionality regressions in this mode. + +### [1.8.1] - 2021-08-24 + +### 🐛 Bug Fixes + +- Token path location should no longer be incorrect on Linux machines. + +## v1.8.0 (2021-08-07) + +### ✨ Features + +- This plugin is now compatible with Obsidian on mobile devices! +- All task lists created by this plugin now also have the `todoist-task-list` CSS class on them for easier styling. +- Added the ability to fold the projects & section groupings when using the grouped task list view. +- Added an additional sorting option `dateDescending`. This behaves the opposite of the sorting option `date`. + +### 🐛 Bug Fixes + +- The date picker in the 'Add task' modal works correctly with more themes. + +## v1.7.1 (2021-06-17) + +### 🐛 Bug Fixes + +- Right-click context menu now works with the latest Obsidian version. + +## v1.7.0 (2021-01-24) + +### ✨ Features + +- Markdown within tasks is now rendered as part of the task. This means that bold, italics and inline code blocks are supported, as are links (both internal and external). +- Uncompletable tasks have a `disabled` checkbox, this may look different depending on your theme, but it will stop you completing these tasks accidentally. +- You can now template the number of tasks returned by the query in the query name by using `{task_count}` + - For example, setting the name to `Tasks ({task_count})` will render as `Tasks (10)` if there are 10 tasks returned by the query. +- Right clicking on a task will now open a context menu where you can either complete the task or open it in the browser or application. + +## v1.6.2 (2021-01-13) + +### 🔁 Changes + +- Removed built-in update checker as Obsidian has one for plugins now! + +### 🐛 Bug Fixes + +- Fixed an issue where queries didn't resolve on first load. + +## v1.6.1 (2021-01-06) + +### 🐛 Bug Fixes + +- Refreshing tasks no longer causes any existing task to disappear and then reappear. +- Use `MarkdownRenderChild` correctly to prevent potential memory leaks. + +## v1.6.0 (2020-12-31) + +### ✨ Features + +- A long awaited and requested feature is finally here! You can create Todoist tasks from within Obsidian. + - This is accessible through a command which will open a modal for the task details. + - There is a second command which will append the link to the current active page at the end of the Todoist task. + - Any selected text under the cursor will be pre-filled as the task text. + - This does _not_ support Todoist's syntax such as '#' for projects, '@' for labels, and smart date recognition. +- Improved the setup of the plugin. Now the plugin will prompt you for an API token on launch and you can set the token through the settings. +- There is now a message rendered if your query returns no tasks. +- Add default CSS for the default Obsidian theme. + +### 🔁 Changes + +- The 'Refresh Metadata' command no longer has a duplicate 'Todoist' identifier in front of it. + +### 🐛 Bug Fixes + +- JSON parsing errors are now correctly handled and displayed to the user. + +### ⚙ Internal + +- Refactored component injection to use the `MarkdownPostProcessor` API. + +## v1.5.0 (2020-10-31) + +### ✨ Features + +- This plugin is now compatible with the [official Obsidian API](https://github.com/obsidianmd/obsidian-api). It was developed against Obsidian 0.9.10. + +## v1.4.0 (2020-10-19) + +Along with this release, I've released an Obsidian theme which has built-in support for this plugin! 🎉 + +Check it out at [jamiebrynes7/moonlight-obsidian-theme](https://github.com/jamiebrynes7/moonlight-obsidian-theme)! + +### ✨ Features + +- The version of the plugin is now displayed in the settings tab along with a link to the changelog. +- You can specify that the result of a query should be grouped by project & section. To do this, add the `"group": true` field to the JSON query. + ```json + { + "name": "My Tasks", + "filter": "today | overdue", + "group": true + } + ``` +- You can now check for plugin updates in the Todoist plugin settings. +- The JSON query is now validated and errors are presented in a more user-friendly fashion. +- Any `workspace-leaf` which has an injected query will have the `contains-todoist-query` CSS class attached. This allows you to style these leafs independently of the others. + +### 🔃 Changed + +- Errors are displayed more prominently in the injected Todoist query. + +### ⚙ Internal + +- Added the ability to turn on debug logging in the plugin. + +## v1.3.1 (2020-09-18) + +### 🐛 Bug Fixes + +- Fixed an issue where the 'Render labels' setting did not work. + +## v1.3.0 (2020-09-17) + +### ✨ Features + +- Tasks now render labels under them by default. This can be toggled in the settings (along with the accompanying icon). +- Tasks now render projects & section under them by default. This can be toggled in the settings (along with the accompanying icon). + + - The layout of the project, date, and label combo can be configured in CSS. For example: + + ```css + /* To make date & project sit inline */ + .task-metadata { + display: inline; + } + + /* To make date & project sit on top of each other. */ + .task-metadata { + display: block; + } + ``` + +- There is a new command `Todoist: Refresh Metadata` which will re-fetch your projects, sections, and labels. If you add/remove/rename these, you should refresh the metadata. This is done automatically at startup. +- Added `contains-task-list` to match latest Obsidian styling. +- The entire task (`li` element) has the `task-overdue` class on it, in addition to the date element specifically. +- The task (`li` element) has either `has-time` or `has-no-time` derived from the date field. (No date or time will also have `has-no-time`). +- Add support for Obsidian v0.8.14 + +### 🐛 Bug Fixes + +- Fixed a bug where tasks with datetimes were sometimes sorted incorrectly. + +## v1.2.2 (2020-09-06) + +### 🐛 Bug Fixes + +- Fixed an issue where the `task-overdue` status would disappear if a task above it was checked off. + +## v1.2.1 (2020-09-06) + +### 🐛 Bug Fixes + +- Fixed an issue where subtasks would cause errors with sorting. + +## v1.2.0 (2020-09-05) + +### ✨ Features + +- Subtasks are now nested under their parent if both are included in the filter. If a subtask is captured by a filter, but the parent is not, it will be listed as a top level item. You may need to adjust your priority CSS to accommodate these changes. For example: + ```diff + + .todoist-p1 > input[type="checkbox"] { + - .todoist-p1 input[type="checkbox"] { + /* This matches against the input element rendered for a priority 1 task. */ + } + ``` +- Tasks now render dates under them by default. This can be toggled in the settings (along with some the accompanying icon). If you choose to use icons, I recommend you _at least_ add the following CSS to your own (tweaking may be required based on your theme): + ```css + .task-calendar-icon { + vertical-align: middle; + height: 17px; + width: 17px; + } + ``` +- Added support for controlling the ordering of the rendered tasks. This can be done by either priority or date, or a combination of them (e.g. - sort by priority, then by date). To use this feature, amend your queries: + ````markdown + ```json + { + "name": "My Tasks", + "filter": "today | overdue", + "autorefresh": 30, + "sorting": ["date", "priority"] + } + ``` + ```` + +### ⚙ Internal + +- Ported the plugin to (almost entirely) Typescript. + +## v1.1.0 (2020-08-31) + +### ✨ Features + +- Each rendered task's CSS now contains information about the task's priority. You can use this information to style each priority differently. These classes are `todoist-p1`, `todoist-p2`, `todoist-p3`, and `todoist-p4`. For example: + ```css + .todoist-p1 input[type="checkbox"] { + /* This matches against the input element rendered for a priority 1 task. */ + } + ``` +- When a task is removed or added, it now transitions with a smooth fading effect, rather than immediately being added/removed. This can be turned off in the settings. +- Added support for auto-refreshing queries. This can be set at a global level within the settings tab or overridden for each individual query. For example: + ````markdown + ```json + { + "name": "My Tasks", + "filter": "today | overdue", + "autorefresh": 30 + } + ``` + ```` +- Added a setting tab in the Obsidian setting menu. There are three settings included in this release: + - "Task fade animation" - controls whether to use the fade animation + - "Auto-refresh" - controls whether all queries should auto-refresh + - "Auto-refresh interval" - controls the default interval for auto-refreshing queries + +### 🔃 Changes + +- The rendered task list now uses the ordering as defined by the Todoist API. + +### 🐛 Bug Fixes + +- The injected Todoist query components are correctly destroyed when removed from the DOM. + +## v1.0.0 (2020-08-29) + +This was the initial release of the Obsidian x Todoist plugin. It contained the basic functionality for: + +- materializing tasks in an Obsidian note +- allowing you to check tasks off from an Obsidian note diff --git a/docs/versioned_docs/version-2.0.0/commands/_category_.yml b/docs/versioned_docs/version-2.0.0/commands/_category_.yml new file mode 100644 index 0000000..c6482d8 --- /dev/null +++ b/docs/versioned_docs/version-2.0.0/commands/_category_.yml @@ -0,0 +1,2 @@ +label: Commands +position: 4 diff --git a/docs/versioned_docs/version-2.0.0/commands/add-task-modal.png b/docs/versioned_docs/version-2.0.0/commands/add-task-modal.png new file mode 100644 index 0000000..2f0bcd7 Binary files /dev/null and b/docs/versioned_docs/version-2.0.0/commands/add-task-modal.png differ diff --git a/docs/versioned_docs/version-2.0.0/commands/add-task.md b/docs/versioned_docs/version-2.0.0/commands/add-task.md new file mode 100644 index 0000000..60e9af0 --- /dev/null +++ b/docs/versioned_docs/version-2.0.0/commands/add-task.md @@ -0,0 +1,15 @@ +--- +sidebar_position: 1 +--- + +# Add task + +![](./add-task-modal.png) + +The 'Add task' set of commands open up a modal that allows you to configure and send tasks to Todoist from Obsidian. Any text selected will be used to pre-populate the task content. + +There are a few variants of the command: + +- 'Add task', the basic version +- 'Add task with current page in task content', this option will append a link to the current page in the task content before it sends it to Obsidian. The modal will inform you it will do this, but the link is not shown to keep the modal clean. +- 'Add task with current page in task description', this option will append a link to the current page in the task description before it sends it to Obsidian. The modal will inform you it will do this, but the link is not shown to keep the modal clean. diff --git a/docs/versioned_docs/version-2.0.0/commands/sync-with-todoist.md b/docs/versioned_docs/version-2.0.0/commands/sync-with-todoist.md new file mode 100644 index 0000000..07c25b8 --- /dev/null +++ b/docs/versioned_docs/version-2.0.0/commands/sync-with-todoist.md @@ -0,0 +1,12 @@ +--- +sidebar_position: 2 +--- + +# Sync with Todoist + +The 'Sync with Todoist' command forces the plugin to re-synchronize your labels, projects, and sections with Todoist. This can be useful if you see "Unknown Project", "Unknown Section", or "Unknown Label" in any rendered tasks. + +The plugin pulls this information at startup, but will not refresh it automatically because: + +- its expected that these don't change frequently +- to help avoid hitting the Todoist API rate limit diff --git a/docs/versioned_docs/version-2.0.0/configuration.md b/docs/versioned_docs/version-2.0.0/configuration.md new file mode 100644 index 0000000..f0e689c --- /dev/null +++ b/docs/versioned_docs/version-2.0.0/configuration.md @@ -0,0 +1,60 @@ +--- +sidebar_position: 5 +--- + +# Configuration + +There are a number of options that allow you to configure the behaviour of the plugin. These are listed below, but the settings page also gives brief descriptions. + +## General + +### Todoist API token + +The API token used to connect to Todoist. This is stored in your vault at `.obsidian/todoist-token`. If you synchronize your vault, I recommend that you do _not_ sync this file for security reasons. + +## Auto-refresh + +### Auto-refresh enabled + +When enabled, all queries will auto-refresh themselves according to the interval in the settings. + +### Auto-refresh interval + +This defines, in seconds, the interval between automatic refreshes. This is only used when: + +- the auto-refresh is enabled in the settings +- the query does not define an explicit interval + +## Rendering + +### Task fade animation + +When enabled, tasks will fade-in or fade-out when tasks are added or removed respectively. Just some eye candy if you like that. + +### Render date icon + +When enabled, queries will render an icon accompanying the due date. + +### Render project & section icon + +When enabled, queries will render an icon accompanying the project & section. + +### Render labels icon + +When enabled, queries will render an icon accompanying the labels. + +## Task creation + +### Add parenthesis to page links + +When enabled, page links added to tasks created via the [command](./commands/add-task) will be wrapped in parenthesis. This may help identifying links if you primarily use Todoist on mobile platforms. + +### Add task button adds page link + +When enabled, the embedded add task button in queries will add a link to the page to the task in the specified place. This behaviour can also be disabled completely. + +## Advanced + +### Debug logging + +When enabled, the plugin will print extra information to the Developer Tools console. You generally do not need to enable this. diff --git a/docs/versioned_docs/version-2.0.0/contributing/_category_.yml b/docs/versioned_docs/version-2.0.0/contributing/_category_.yml new file mode 100644 index 0000000..cf32422 --- /dev/null +++ b/docs/versioned_docs/version-2.0.0/contributing/_category_.yml @@ -0,0 +1,2 @@ +label: Contributing +position: 6 diff --git a/docs/versioned_docs/version-2.0.0/contributing/general.md b/docs/versioned_docs/version-2.0.0/contributing/general.md new file mode 100644 index 0000000..83bdad5 --- /dev/null +++ b/docs/versioned_docs/version-2.0.0/contributing/general.md @@ -0,0 +1,57 @@ +# General + +## Prerequisites + +This plugin is built using Typescript and React. You will need the following tools installed to build and run the plugin: + +- [`git`](https://git-scm.com/downloads) +- [`npm`](https://nodejs.org/en/download/) + +Alternatively, if you use Nix, there is a flake and a `.envrc` to load the development environment for you. Simply run `direnv allow` to load the environment. + +## Building + +The plugin source is contained entirely within the `plugin` directory. To build the plugin: + +1. Run `cd plugin` +2. Run `npm install` to pull down the required dependencies +3. Run `npm run dev` to build the plugin. + +By default, this will build the plugin into `plugin/dist/`. You can manually copy the files an Obsidian vault for testing. For a smoother iteration cycle, you can tell the build process where it should place the output. The build process looks for the `VITE_OBSIDIAN_VAULT` environment variable to find a target vault. + +A simple way to configure this once is: + +1. Create a file at `plugin/.env.local`. This file is automatically loaded by the build script. +2. Add a line to this file setting the environment variable. For example: + + ```sh + export VITE_OBSIDIAN_VAULT=/Users/jamiebrynes/Documents/my-vault + ``` + +## Running tests + +Its generally a good idea to write tests to ensure that the plugin's functionality is correct. The test suite is, at the time of writing, limited - but it can be useful for developing functionality against a set of tests. To run _all_ tests, from the `plugin` directory: + +``` +npm run test +``` + +Alternatively, to run a subset of tests, you can pass in a path to filter the tests ran: + +``` +npm run test ./src/utils +``` + +## Linting + +This plugin uses [BiomeJS](https://biomejs.dev/) to format and lint our Typescript. This ensures a consistent code style across the plugin. To check the formatting, from the `plugin` directory, run: + +``` +npm run lint:check +``` + +Biome can also format code to fix most issues. Note this will modify files on disk: + +``` +npm run lint:fix +``` diff --git a/docs/versioned_docs/version-2.0.0/contributing/translation.md b/docs/versioned_docs/version-2.0.0/contributing/translation.md new file mode 100644 index 0000000..51d8bee --- /dev/null +++ b/docs/versioned_docs/version-2.0.0/contributing/translation.md @@ -0,0 +1,73 @@ +# Translations + +Before getting started, you should ensure you read the general [contribution guide](./general). This will ensure that you have a working build environment and are ready to go! + +## Architecture + +It can be useful to understand how the translation system works in this plugin. At startup, the plugin will set the language based on the `lang` attribute in the root `html` element. This ensures that it follows the language set in the general Obsidian settings. A consequence of this is that we are restricted to the [languages supported by Obsidian](https://github.com/obsidianmd/obsidian-translations#existing-languages). + +The translations are effectively a large key-value store. You can see all of the keys and the structure in `plugin/src/i18n/translations.ts`. The location of the translation phrase (or function) in the `Translations` type should give a suggestion as to where it is used. For example, `translations.settings.autoRefresh.header` refers to the header of the auto-refresh settings section. + +The plugin can consume the translations by calling the `t()` function exported from `i18n` to get the currently resolved translations. This object is marked as `readonly` so that it can't be modified. For example: + +```ts +import { t } from "@/i18n"; + +const i18n = t(); + +const getSettingsHeader = () => { + return i18n.settings.general.header; +}; +``` + +If a language does not have a translation for a particular key, the plugin will fall back to the English translation. + +## Adding a new language + +There is a guide in `plugin/src/i18n/index.ts` that explains how to add a new language. This is repeated here for convenience: + +1. Identify the language code for the language you want to add. You can find this by searching for the language in the [Obsidian translations repo](https://github.com/obsidianmd/obsidian-translations). +2. Create a file in the `plugin/src/i18n/langs` directory with language code as the filename. For example, if you were to add a translation for French, you would create `plugin/src/i18n/langs/fr.ts`. +3. Copy the template below into the new file. Make sure to replace $langCode with the language code: + + ```ts + import type { Translations } from "@/i18n/translation"; + import type { DeepPartial } from "@/utils/types"; + + export const $langCode: DeepPartial = {}; + ``` + +4. Register the language in the registry at the bottom of `plugin/src/i18n/index.ts`. The key should be the language code and the value should be the object exported in the previous step. You will need to add an import for the new file. For example: + + ```ts + // plugin/src/i18n/index.ts + import { fr } from "@/i18n/langs/fr"; + + // A bunch of things you don't need to worry about... + + const registry: Record> = { + fr: fr, + }; + ``` + +5. Proceed to [adding translated phrases](#adding-translated-phrases). + +## Adding translated phrases + +In order to add translated phrases, you will first need to identify the key for the phrase. The easiest way to do this is to search for the English phrase in the `plugin/src/i18n/langs/en.ts` file. + +For example, if I wanted to translate the phrase "Rendering" in the settings, I would search for "Rendering" in the `plugin/src/i18n/langs/en.ts` file. I would find that the key is `settings.rendering.header`. + +Then, open the file for the language you want to add the translation to. For example, if I wanted to add the translation to French, I would open `plugin/src/i18n/langs/fr.ts`. If the language doesn't exist, please see [the section above](#adding-a-new-language). + +Then I would ld add the translation to the object. You may need to create the object path if it doesn't exist. For example, let's assume that there were no translations for French, I would need to add the following structure: + +```ts +export const fr: DeepPartial = { + settings: { + rendering: { + header: "translation of 'Rendering'", + }, + }, +}; +``` diff --git a/docs/versioned_docs/version-2.0.0/overview.md b/docs/versioned_docs/version-2.0.0/overview.md new file mode 100644 index 0000000..6a8332b --- /dev/null +++ b/docs/versioned_docs/version-2.0.0/overview.md @@ -0,0 +1,12 @@ +--- +sidebar_position: 1 +--- + +# Overview + +![](../../static/img/social-card.jpg) + +The Sync with Todoist Plugin is an _**unofficial**_ plugin that allows you to integrate your Todoist tasks in your Obsidian vault. This integration is mostly one way, from Todoist into Obsidian. There is a limited ability to modify your Todoist tasks, but this functionality will be improved in the future. + +This plugin is designed to work on both desktop and mobile Obsidian clients. + diff --git a/docs/versioned_docs/version-2.0.0/query-blocks.md b/docs/versioned_docs/version-2.0.0/query-blocks.md new file mode 100644 index 0000000..2ccf76c --- /dev/null +++ b/docs/versioned_docs/version-2.0.0/query-blocks.md @@ -0,0 +1,120 @@ +--- +sidebar_position: 3 +--- + +# Query Blocks + +This plugin uses the concept of [filters](https://todoist.com/help/articles/introduction-to-filters-V98wIH) to fetch data from Todoist. To create a query block, insert a code block like the following in any note: + +```` +```todoist +filter: "today | overdue" +``` +```` + +This query will fetch all tasks that are due either today or are overdue and will render them in place of this code block. + +## Options + +The query is defined as [YAML](https://yaml.org/) and there are a number of options available. + +### `filter` + +The filter option is **required** and should be a valid [Todoist filter](https://todoist.com/help/articles/introduction-to-filters-V98wIH). Note that this must be the content of the filter, you cannot refer to a filter that already exists in your Todoist account. + +There are a few unsupported filters, these are tracked in [this GitHub issue](https://github.com/jamiebrynes7/obsidian-todoist-plugin/issues/34): + +- Wildcard filters do not work as expected. E.g. - `@*ball` +- You cannot combine multiple filters with commas. E.g. - `today | overdue, p1` + +### `name` + +If you want to have an embedded header rendered with your query, you can use the `name` option. This will render a `

` element above your tasks. + +For example: + +```` +```todoist +name: "Today & Overdue" +filter: "today | overdue" +``` +```` + +### `autorefresh` + +The `autorefresh` option allows you to specify the number of seconds between automatic refreshes. This takes precedence over the plugin level setting. Omitting this option means the query will follow the plugin level settings. + +For example: + +```` +```todoist +filter: "today | overdue" +autorefresh: 120 +``` +```` + +### `sorting` + +The `sorting` property allows you to specify the ordering for how your tasks are rendered. This is specified as a list, where we sort in the order of the properties in the list. The possible values are: + +- `date` or `dateAscending`: sorts tasks in ascending order based on due date +- `dateDescending`: sorts tasks in descending order based on due date +- `priority` or `priorityAscending`: sorting tasks in ascending order based on priority +- `priorityDescending`: sorts tasks in descending order based on priority +- `order`: sorts task according to the ordering defined in Todoist +- `dateAdded` or `dateAddedAscending`: sorts tasks in ascending order based on the date the task was added +- `dateAddedDescending`: sorts tasks in descending order based on the date the task was added + +If no sorting option is provided, tasks will be sorted by their Todoist order. + +For example: + +```` +```todoist +filter: "today | overdue" +sorting: + - date + - priority +``` +```` + +### `groupBy` + +The `groupBy` property controls how tasks are grouped when they are rendered. If omitted, there will be no grouping. The possible values are: + +- `project`: group by project, using the project order as in Todoist +- `section`: group by project and section, using the project and section order as in Todoist +- `due` or `date`: group by due date, all overdue tasks are grouped and shown together +- `labels`: group by the task labels, all unlabelled tasks are grouped together +- `priority` group by task priority, priorities are shown in high-low order + +For example: + +```` +```todoist +filter: "today | overdue" +groupBy: project +``` +```` + +### `show` + +The `show` property controls which elements of the task metadata to render. This will override the plugin level settings if provided. If omitted, all task metadata will be rendered. + +The possible values are: + +- `due` or `date`: render the due date of the task +- `description`: render the description of the task +- `project`: render the project (and section, if applicable) of the task +- `labels`: render the labels of the task + +For example: + +```` +```todoist +filter: "today | overdue" +show: + - due + - project +``` +```` diff --git a/docs/versioned_docs/version-2.0.0/setup.md b/docs/versioned_docs/version-2.0.0/setup.md new file mode 100644 index 0000000..186a940 --- /dev/null +++ b/docs/versioned_docs/version-2.0.0/setup.md @@ -0,0 +1,35 @@ +--- +sidebar_position: 2 +--- + +# Setup + +There are a few steps to get up and running with this plugin. + +## 1. Install plugin + +First we need to install the plugin. You can follow this [handy](https://obsidian.md/plugins?id=todoist-sync-plugin) link to open the plugin's page in Obsidian and install it. + +If you prefer to do it manually: + +1. Open the settings in Obsidian +2. Select 'Community Plugins' in the sidebar +3. If necessary, turn on community plugins. Make sure you are comfortable with the warnings given to you on this page +4. Select 'Browse' and search for "Todoist Sync" +5. Install the plugin + +## 2. Setup API token + +Once the plugin is installed, you'll need to enable and do some initial setup. + +1. Enable the plugin from Obsidian's setting page +2. You should get a popup asking you to provide your [API token](https://todoist.com/help/articles/find-your-api-token-Jpzx9IIlB). +3. Paste your API token into the prompt +4. The prompt will verify that the token provided is valid and will present you with a checkmark if it is +5. Select 'Submit' to complete the setup + +> Note that this token is stored in its own file inside your vault. It can be found at `.obsidian/todoist-token`. If you synchronize your vault, you may choose to explicit ignore this file to avoid the API token leaving your machine. If you choose to do this, you must perform this setup on each device you access your vault on. + +## What's next? + +Once you've set up the plugin you can explore adding [query blocks](./query-blocks), look at how to [add tasks from Obsidian](./commands/add-task), or explore the [plugin configuration](./configuration). diff --git a/docs/versioned_sidebars/version-2.0.0-sidebars.json b/docs/versioned_sidebars/version-2.0.0-sidebars.json new file mode 100644 index 0000000..caea0c0 --- /dev/null +++ b/docs/versioned_sidebars/version-2.0.0-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/docs/versions.json b/docs/versions.json index a309f97..ad6d2ab 100644 --- a/docs/versions.json +++ b/docs/versions.json @@ -1,4 +1,5 @@ [ + "2.0.0", "1.13.0", "1.12.0" ]