docs: cut 2.0.0 docs

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!

docs/versioned_docs/version-2.0.0/commands/_category_.yml

@@ -0,0 +1,2 @@
+label: Commands
+position: 4

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.

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

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.

docs/versioned_docs/version-2.0.0/contributing/_category_.yml

@@ -0,0 +1,2 @@
+label: Contributing
+position: 6

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
+```

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<Translations> = {};
+   ```
+
+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<string, DeepPartial<Translations>> = {
+     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<Translations> = {
+  settings: {
+    rendering: {
+      header: "translation of 'Rendering'",
+    },
+  },
+};
+```

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.
+

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 `<h4>` 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
+```
+````