docs: Major update of Getting Started page (#1392)

* docs: Add headings & contents to Getting Started page

* docs: Note that tasks in comments are ignored.

* docs: Add formatting to warnings, to make topics stand out

* docs: Update warning now tags can be mixed with signifiers

* docs: Much fuller explanation of parsing emojis in tasks

And how to troubleshoot any emojis not read.

* docs: Document reading tasks in numbered lists.

* docs: Improve wording, for consistency with next section

docs/getting-started/index.md

@@ -5,8 +5,23 @@ nav_order: 3
 has_children: true
 ---
 
+{: .no_toc }
+
+<details open markdown="block">
+  <summary>
+    Table of contents
+  </summary>
+  {: .text-delta }
+1. TOC
+{:toc}
+</details>
+
+---
+
 # Getting Started
 
+## Finding tasks in your vault
+
 Tasks tracks your checklist items from your vault.
 The simplest way to create a new task is to create a new checklist item.
 The markdown syntax for checklist items is a list item that starts with spaced brackets: `- [ ] take out the trash`.
@@ -20,18 +35,28 @@ To list all open tasks in a markdown file, simply add a [query]({{ site.baseurl
     ```
 ````
 
+## Adding data to your tasks (optionally)
+
 Now you have a list of all open tasks! This is enough to get started with tasks.
 You can _optionally_ start using one or more of the other features that Tasks offers.
-Like, for example, [priorities]({{ site.baseurl }}{% link getting-started/priority.md %}) or [dates]({{ site.baseurl }}{% link getting-started/dates.md %}#start-date)
+Like, for example, [priorities]({{ site.baseurl }}{% link getting-started/priority.md %}) or [dates]({{ site.baseurl }}{% link getting-started/dates.md %}#start-date).
+
+## Easy editing of tasks
 
 A more convenient way to create a task is by using the `Tasks: Create or edit` command from the command palette.
 You can also bind a hotkey to the command.
 The command will parse what's on the current line in your editor and pre-populate a modal.
 In the modal, you can change the task's description, its due date, and a recurrence rule to have a repeating task.
-See below for more details on due dates and recurrence.
+
+You can find out more in [‘Create or edit Task’ Modal]({{ site.baseurl }}{% link getting-started/create-or-edit-task.md %}).
+
+See other pages in 'Getting Started' for more details on due dates and recurrence, and many other features.
+
 You cannot toggle a task (un)done in the modal.
 For that, do one of the following.
 
+## Completing tasks
+
 There are two ways to mark a task done:
 
 1. In preview mode, click the checkbox at the beginning of the task to toggle the status between "todo" and "done".
@@ -43,16 +68,18 @@ There are two ways to mark a task done:
 A "done" task will have the date it was done appended to the end of its line.
 For example: `✅ 2021-04-09` means the task was done on the 9th of April, 2021.
 
+## Limitations and warnings
+
 <div class="code-example" markdown="1">
 Warning
 {: .label .label-yellow}
-Whenever Tasks behaves in an unexpected way, please try restarting Obsidian.
+Whenever Tasks behaves in an unexpected way, **please try restarting Obsidian**.
 
 ---
 
 Warning
 {: .label .label-yellow}
-Tasks only supports single-line checklist items.
+Tasks only supports **single-line checklist items**.
 
 The task list rendered through this plugin **and** the checklist items
 from which the task list is built render only the first line of the item.
@@ -80,7 +107,29 @@ The following _does not work:_
 
 Warning
 {: .label .label-yellow}
-Tasks can read tasks that are inside blockquotes or [Obsidian's built-in callouts](https://help.obsidian.md/How+to/Use+callouts).
+Tasks can read tasks that are in **numbered lists**.
+
+> Reading tasks inside numbered lists was introduced in Tasks 1.20.0.
+
+For example:
+
+```markdown
+1. [ ] Do first step
+2. [ ] Do next step
+3. [ ] Do following step
+```
+
+Editing and toggling tasks in numbered lists works fine: the original number is preserved.
+
+However, when these tasks are displayed in tasks blocks they are displayed as ordinary bullet list items.
+
+This is because they will usually be displayed in a completely different order than in the original list, often mixed in with tasks from bullet lists. The original numbers in this case just don't make sense.
+
+---
+
+Warning
+{: .label .label-yellow}
+Tasks can read tasks that are inside **blockquotes** or [Obsidian's built-in callouts](https://help.obsidian.md/How+to/Use+callouts).
 
 > Reading tasks inside callouts and blockquotes was introduced in Tasks 1.11.1
 
@@ -99,13 +148,25 @@ Completing a task by clicking its checkbox from a `tasks` query block _will_ wor
 Warning
 {: .label .label-yellow}
 
-Tasks cannot read tasks that are inside code blocks, such as the ones used by the Admonitions plugin. Use Obsidian's built-in callouts instead.
+Tasks cannot read tasks that are **inside code blocks**, such as the ones used by the **Admonitions plugin**. Use Obsidian's built-in callouts instead.
 
 ---
 
 Warning
 {: .label .label-yellow}
-Tasks can only render inline footnotes. Regular footnotes are not supported.
+
+Obsidian supports two styles of **comments**:
+
+- `<!-- I am text in a comment -->`
+- `%% I am text in a comment %%`
+
+Tasks does read any tasks that are inside these comments, because Obsidian does not read them.
+
+---
+
+Warning
+{: .label .label-yellow}
+Tasks can only render **inline footnotes**. Regular footnotes are not supported.
 
 ```markdown
 -   [ ] This is a task^[with a working inline footnote]
@@ -116,13 +177,13 @@ Tasks can only render inline footnotes. Regular footnotes are not supported.
 
 Warning
 {: .label .label-yellow}
-Tasks' support for block quotes inside tasks is limited. It renders correctly, but since Tasks only supports a single line, the meta-data of the task will be inside the block quote.
+Tasks' support for **block quotes inside tasks** is limited. It renders correctly, but since Tasks only supports a single line, the meta-data of the task will be inside the block quote.
 
 ---
 
 Warning
 {: .label .label-yellow}
-Tasks won't render spaces around list items if you have a list with empty lines.
+Tasks won't render **spaces around list items** if you have a list with empty lines.
 
 ```markdown
 -   [ ] First task before the empty line
@@ -134,15 +195,25 @@ Tasks won't render spaces around list items if you have a list with empty lines.
 
 Warning
 {: .label .label-yellow }
-You can only put block links (`^link-name`) after metadata such as dates. Anything else will break the parsing of dates, priorities and recurrence rules.
+
+Tasks reads task lines **backwards from the end of the line**, looking for metadata emojis with values, tags and block links. As soon as it finds a value that it does not recognise, it stops reading.
+
+This means that you can only put **block links** (`^link-name`) and **tags** after metadata such as dates, priorities, recurrence rules. Anything else will break the parsing of dates, priorities and recurrence rules.
 
 ```markdown
--   [ ] Task with priority placed before tag _priority will not be recognized_ 🔼 #tag
--   [ ] Task with date placed before tag _date will not be recognized_ 📅 2021-04-09 #tag
+-   [ ] Task with priority placed before tag _priority will be recognized_ 🔼 #tag
+-   [ ] Task with date placed before tag _date will be recognized_ 📅 2021-04-09 #tag
+-   [ ] Task with date placed before other text _date will be not recognized_ 📅 2021-04-09 other text
 -   [ ] Task with block link _works_ 📅 2021-04-09 ^e5bebf
--   [ ] Task with tag before priority _works_ #tag 🔼
 ```
 
+If you are concerned that some values in a task are not being parsed as you intended, perhaps because a task is not being found by Tasks searches, you can view the task in the [‘Create or edit Task’ Modal]({{ site.baseurl }}{% link getting-started/create-or-edit-task.md %}).
+
+If there are any **Tasks emojis visible in the Description field**, close the modal and delete or move to the left any unrecognised text.
+
+![Create or Edit Modal](../images/modal-showing-unparsed-emoji.png)
+<br>The `Tasks: Create or edit` modal showing a due date that was not parsed, due to trailing `other text`.
+
 ---
 
 Warning