v0.19.4

* docs: update docs/index.md [skip ci]

* docs: update readme.md [skip ci]

* docs: update .all-contributorsrc [skip ci]

Co-authored-by: allcontributors[bot] <46447321+allcontributors[bot]@users.noreply.github.com>

.all-contributorsrc

@@ -914,6 +914,24 @@
       "contributions": [
         "code"
       ]
+    },
+    {
+      "login": "infogulch",
+      "name": "Joe Taber",
+      "avatar_url": "https://avatars.githubusercontent.com/u/133882?v=4",
+      "profile": "https://github.com/infogulch",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "readingsnail",
+      "name": "Woosuk Park",
+      "avatar_url": "https://avatars.githubusercontent.com/u/1904967?v=4",
+      "profile": "https://www.readingsnail.pe.kr",
+      "contributions": [
+        "doc"
+      ]
     }
   ],
   "contributorsPerLine": 7,

docs/.vscode/settings.json

@@ -25,5 +25,6 @@
   ],
   "files.exclude": {
     "_site/**": true
-  }
+  },
+  "files.insertFinalNewline": true
 }

docs/dev/about-docs.md

@@ -0,0 +1,20 @@
+# Developing documentation
+
+The best way to develop docs for the Foam repo is to directly open the `$foam-repo/docs/` as the root folder in a new vscode window.
+This automatically configures vscode with the necessary settings enabled (like [[link-reference-definitions]]) to effiniently write this documentation.
+
+## Organization
+
+The Foam documentation is organized into two areas:
+
+* User docs, located at `$foam-repo/docs/user/*`, which are copied in their entirety into `$foam-template-repo/docs`.
+* Developer docs, located at `$foam-repo/docs/dev/*`
+
+New user docs should be added to the User docs folder in the main Foam repo, then copied over to the Foam Template repo.
+
+> [[todo]]: Automate this process. Idea: github action to open a PR on any change to `/docs/user`
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[link-reference-definitions]: ../user/features/link-reference-definitions.md "Link Reference Definitions"
+[todo]: todo.md "Todo"
+[//end]: # "Autogenerated link references"

docs/dev/contribution-guide.md

@@ -93,8 +93,8 @@ Feel free to modify and submit a PR if this guide is out-of-date or contains err
 ---
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[principles]: principles.md "Principles"
+[principles]: ../principles.md "Principles"
 [code-of-conduct]: code-of-conduct.md "Code of Conduct"
-[recipes]: recipes/recipes.md "Recipes"
-[recommended-extensions]: recommended-extensions.md "Recommended Extensions"
+[recipes]: ../user/recipes/recipes.md "Recipes"
+[recommended-extensions]: ../user/getting-started/recommended-extensions.md "Recommended Extensions"
 [//end]: # "Autogenerated link references"

docs/dev/foam-file-format.md

@@ -12,5 +12,5 @@ Here are a few specific constraints, mainly because our tooling is a bit fragmen
 - **In addition to normal Markdown Links syntax you can use `[[MediaWiki]]` links.** See [[wikilinks]] for more details.
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[wikilinks]: ../wikilinks.md "Wikilinks"
+[wikilinks]: ../user/features/wikilinks.md "Wikilinks"
 [//end]: # "Autogenerated link references"

docs/dev/good-first-task.md

@@ -5,5 +5,5 @@ See the backlinks of this page for good first contribution opportunities.
 [[materialized-backlinks]] would help here.
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[materialized-backlinks]: materialized-backlinks.md "Materialized Backlinks (stub)"
+[materialized-backlinks]: proposals/materialized-backlinks.md "Materialized Backlinks (stub)"
 [//end]: # "Autogenerated link references"

docs/dev/mdx-by-default.md

@@ -6,5 +6,5 @@ If you're interested in working on it, please start a conversation in [GitHub is
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
 [todo]: todo.md "Todo"
-[roadmap]: roadmap.md "Roadmap"
+[roadmap]: proposals/roadmap.md "Roadmap"
 [//end]: # "Autogenerated link references"

docs/dev/meeting-notes/foam-core-2020-07-11.md

@@ -123,6 +123,6 @@ How others solve this:
 - Unique ids -- could support optionally as part of file name or front matter metadata. Should not be required.
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: ../dev/todo.md "Todo"
-[Index]: ../index.md "Foam"
+[todo]: ../todo.md "Todo"
+[Index]: ../../index.md "Foam"
 [//end]: # "Autogenerated link references"

docs/dev/proposals/foam-core.md

@@ -9,7 +9,7 @@
   - Visualizations
     - Tag clouds
     - Graph
-    - Should we have a package for visualisation?
+    - Should we have a package for visualization?
       - [[build-vs-assemble]]
       - Not everything needs to live in the Foam repo
   - Web based UI (Monaco)
@@ -65,7 +65,7 @@ Here are some example use cases that the core should support. They don't need to
   - [Frontmatter](https://jekyllrb.com/docs/front-matter/)
 - Finding all documents with `#tag`
 - Finding all documents with instances of `[[link]]`
-- Visualisations
+- Visualizations
 - Full text search
 
   - Or, if search is too expensive/complex, when given a list of file names and line/column positions from VS Code search API, can return the document context (e.g. full paragraph, preceding/following line etc)
@@ -96,12 +96,12 @@ Useful for knowing what needs to be supported. See [[feature-comparison]].
 - [[foam-core-2020-07-11]]
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[workspace-janitor]: ../features/workspace-janitor.md "Janitor"
-[cli]: ../features/cli.md "Command Line Interface"
-[build-vs-assemble]: build-vs-assemble.md "Build vs Assemble"
-[wikilinks]: ../wikilinks.md "Wikilinks"
-[link-reference-definitions]: ../features/link-reference-definitions.md "Link Reference Definitions"
+[workspace-janitor]: ../../user/tools/workspace-janitor.md "Janitor"
+[cli]: ../../user/tools/cli.md "Command Line Interface"
+[build-vs-assemble]: ../build-vs-assemble.md "Build vs Assemble"
+[wikilinks]: ../../user/features/wikilinks.md "Wikilinks"
+[link-reference-definitions]: ../../user/features/link-reference-definitions.md "Link Reference Definitions"
 [materialized-backlinks]: materialized-backlinks.md "Materialized Backlinks (stub)"
-[todo]: todo.md "Todo"
+[todo]: ../todo.md "Todo"
 [foam-core-2020-07-11]: ../meeting-notes/foam-core-2020-07-11.md "Foam Core 2020-07-11"
 [//end]: # "Autogenerated link references"

docs/dev/proposals/link-reference-definition-improvements.md

@@ -137,7 +137,7 @@ UI-wise, the publish targets could be picked in some similar fashion as the run/
 - [tracking issue on GitHub](https://github.com/foambubble/foam/issues/16)
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[wikilinks]: ../wikilinks.md "Wikilinks"
-[link-reference-definitions]: ../features/link-reference-definitions.md "Link Reference Definitions"
-[backlinking]: ../features/backlinking.md "Backlinking"
+[wikilinks]: ../../user/features/wikilinks.md "Wikilinks"
+[link-reference-definitions]: ../../user/features/link-reference-definitions.md "Link Reference Definitions"
+[backlinking]: ../../user/features/backlinking.md "Backlinking"
 [//end]: # "Autogenerated link references"

docs/dev/proposals/materialized-backlinks.md

@@ -12,6 +12,6 @@ The idea would be to automatically generate lists of backlinks (and optionally,
 - Make Foam notes more portable to different apps and long-term storage
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo.md "Todo"
+[todo]: ../todo.md "Todo"
 [roadmap]: roadmap.md "Roadmap"
 [//end]: # "Autogenerated link references"

docs/dev/proposals/roadmap.md

@@ -83,22 +83,21 @@ The community is working on a number of automated scripts to help you migrate to
 - [[refactoring-via-language-server-protocol]]
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[build-vs-assemble]: build-vs-assemble.md "Build vs Assemble"
-[recipes]: ../recipes/recipes.md "Recipes"
+[build-vs-assemble]: ../build-vs-assemble.md "Build vs Assemble"
+[recipes]: ../../user/recipes/recipes.md "Recipes"
 [contribution-guide]: ../contribution-guide.md "Contribution Guide"
-[git-integration]: ../features/git-integration.md "Git Integration"
-[wikilinks]: ../wikilinks.md "Wikilinks"
-[foam-file-format]: foam-file-format.md "Foam File Format"
-[unlinked-references]: unlinked-references.md "Unlinked references (stub)"
-[make-backlinks-more-prominent]: ../recipes/make-backlinks-more-prominent.md "Make Backlinks More Prominent"
+[wikilinks]: ../../user/features/wikilinks.md "Wikilinks"
+[foam-file-format]: ../foam-file-format.md "Foam File Format"
+[unlinked-references]: ../unlinked-references.md "Unlinked references (stub)"
+[make-backlinks-more-prominent]: ../../user/recipes/make-backlinks-more-prominent.md "Make Backlinks More Prominent"
 [materialized-backlinks]: materialized-backlinks.md "Materialized Backlinks (stub)"
-[automatic-git-syncing]: ../recipes/automatic-git-syncing.md "Automatically Sync with Git"
-[link-reference-definitions]: ../features/link-reference-definitions.md "Link Reference Definitions"
-[predefined-user-snippets]: ../recipes/predefined-user-snippets.md "Pre-defined User Snippets"
-[mdx-by-default]: mdx-by-default.md "MDX by Default(stub)"
-[publishing-permissions]: publishing-permissions.md "Publishing Permissions(stub)"
-[cli]: ../features/cli.md "Command Line Interface"
-[migrating-from-roam]: ../recipes/migrating-from-roam.md "Migrating from Roam (stub)"
-[migrating-from-obsidian]: ../recipes/migrating-from-obsidian.md "Migrating from Obsidian (stub)"
-[migrating-from-onenote]: ../recipes/migrating-from-onenote.md "Migrating from OneNote"
+[automatic-git-syncing]: ../../user/recipes/automatic-git-syncing.md "Automatically Sync with Git"
+[link-reference-definitions]: ../../user/features/link-reference-definitions.md "Link Reference Definitions"
+[predefined-user-snippets]: ../../user/recipes/predefined-user-snippets.md "Pre-defined User Snippets"
+[mdx-by-default]: ../mdx-by-default.md "MDX by Default(stub)"
+[publishing-permissions]: ../publishing-permissions.md "Publishing Permissions(stub)"
+[cli]: ../../user/tools/cli.md "Command Line Interface"
+[migrating-from-roam]: ../../user/recipes/migrating-from-roam.md "Migrating from Roam (stub)"
+[migrating-from-obsidian]: ../../user/recipes/migrating-from-obsidian.md "Migrating from Obsidian (stub)"
+[migrating-from-onenote]: ../../user/recipes/migrating-from-onenote.md "Migrating from OneNote"
 [//end]: # "Autogenerated link references"

docs/dev/publishing-permissions.md

@@ -11,5 +11,5 @@ If you're interested in working on it, please start a conversation in [GitHub is
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
 [todo]: todo.md "Todo"
-[roadmap]: roadmap.md "Roadmap"
+[roadmap]: proposals/roadmap.md "Roadmap"
 [//end]: # "Autogenerated link references"

docs/dev/releasing-foam.md

@@ -10,13 +10,11 @@
    - `git add *`
    - `git commit -m"Preparation for next release"`
 4. Update version
-   - `$ cd packages/foam-vscode`
-   - `foam-vscode$ yarn lerna version <version>` (where `version` is `patch/minor/major`) 
-   - `cd ../..`
+   - `$ yarn version-extension <version>` (where `version` is `patch/minor/major`) 
 5. Package extension
-   - `$ yarn vscode:package-extension`
+   - `$ yarn package-extension`
 6. Publish extension
-   - `$ yarn vscode:publish-extension`
+   - `$ yarn publish-extension`
 7. Update the release notes in GitHub
    - in GitHub, top right, click on "releases"
    - select "tags" in top left

docs/dev/todo.md

@@ -14,6 +14,6 @@ Features belong on the [[roadmap]].
 For more things to do, check backlinks for Pages that annotate [[todo]].
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[roadmap]: roadmap.md "Roadmap"
+[roadmap]: proposals/roadmap.md "Roadmap"
 [todo]: todo.md "Todo"
 [//end]: # "Autogenerated link references"

docs/dev/unlinked-references.md

@@ -16,5 +16,5 @@ Implementing this is on the [[roadmap]], but for the time being you can achieve
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
 [todo]: todo.md "Todo"
-[roadmap]: roadmap.md "Roadmap"
+[roadmap]: proposals/roadmap.md "Roadmap"
 [//end]: # "Autogenerated link references"

docs/features/daily-notes.md

@@ -1,49 +0,0 @@
-# Daily notes
-
-Automatically create a Daily Note by executing the "Foam: Open Daily Note" command. If a Daily Note for today's date already exists, the command opens the existing note.
-
-![Daily note feature in action](../assets/images/daily-note.gif)
-
-## Keyboard shortcut
-
-The default keyboard shortcut for "Open Daily Note" is `alt`+`d`. This can be overridden using the [VS Code Keybindings editor](https://code.visualstudio.com/docs/getstarted/keybindings).
-
-## Configuration
-
-By default, Daily Notes will be created in a file called `yyyy-mm-dd.md` in the workspace root, with a heading `yyyy-mm-dd`.
-
-These settings can be overridden in your workspace or global `.vscode/settings.json` file, using the [**dateformat** date masking syntax](https://github.com/felixge/node-dateformat#mask-options):
-
-```jsonc
-  "foam.openDailyNote.directory": "journal", // a relative directory path will get appended to the workspace root. An absolute directory path will be used unmodified.
-  "foam.openDailyNote.filenameFormat": "'daily-note'-yyyy-mm-dd",
-  "foam.openDailyNote.fileExtension": "mdx",
-  "foam.openDailyNote.titleFormat": "'Journal Entry, ' dddd, mmmm d",
-```
-
-The above configuration would create a file `journal/note-2020-07-25.mdx`, with the heading `Journal Entry, Sunday, July 25`.
-
-## Daily Note Templates
-
-Daily notes can also make use of [templates](note-templates.md), by defining a special `.foam/templates/daily-note.md` template.
-
-See [Note Templates](note-templates.md) for details of the features available in templates.
-
-## Roam-style Automatic Daily Notes
-
-Foam provides an option for automatically opening your Daily Note when you open your Foam workspace. You can enable it by specifying the following configuration in your `.vscode/settings.json`:
-
-```json
-{
-  // ...Other configurations
-  "foam.openDailyNote.onStartup": true
-}
-```
-
-## Extend Functionality (Weekly, Monthly, Quarterly Notes)
-
-Please see [[note-macros]]
-
-[//begin]: # 'Autogenerated link references for markdown compatibility'
-[note-macros]: ../recipes/note-macros.md 'Custom Note Macros'
-[//end]: # 'Autogenerated link references'

docs/features/graph-visualisation.md

@@ -1,62 +0,0 @@
-# Graph Visualisation
-
-Foam comes with a graph visualisation of your notes. To see the graph execute the `Foam: Show Graph` command.
-
-The graph will:
-
-- allow you to highlight a node by hovering on it, to quickly see how it's connected to the rest of your notes
-- allow you to select one or more (by keeping `SHIFT` pressed while selecting) nodes by clicking on them, to better understand the structure of your notes
-- allow you to navigate to a note by clicking on it while pressing `CTRL` or `CMD`
-- automatically center the graph on the currently edited note, to immediately see it's connections
-
-## Custom Graph Styles
-
-Currently, custom graph styles are supported through the `foam.graph.style` setting.
-
-![Graph style demo](../assets/images/graph-style.gif)
-
-A sample configuration object is provided below:
-
-```json
-"foam.graph.style": {
-    "background": "#202020",
-    "fontSize": 12,
-    "lineColor": "#277da1",
-    "lineWidth": 0.2,
-    "particleWidth": 1.0,
-    "highlightedForeground": "#f9c74f",
-    "node": {
-        "note": "#277da1",
-        "placeholder": "#545454",
-    }
-}
-```
-
-### Style nodes by type
-
-It is possible to customize the style of a node based on the `type` property in the YAML frontmatter of the corresponding document.
-
-For example the following `backlinking.md` note:
-
-```
----
-type: feature
----
-# Backlinking
-
-...
-```
-
-And the following `settings.json`:
-
-```json
-"foam.graph.style": {
-    "node": {
-        "feature": "red",
-    }
-}
-```
-
-Will result in the following graph:
-
-![Style node by type](../assets/images/style-node-by-type.png)

docs/features/key-bindings.md

@@ -1,11 +0,0 @@
-# Key Bindings
-
-## [[todo]]
-
-- [ ] Document [supported key bindings](#supported-key-bindings)
-- [ ] Currently we rely on various key bindings provided by VS Code plugins. Would be nice to harmonise these
-- [ ]
-
-[//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: ../dev/todo.md "Todo"
-[//end]: # "Autogenerated link references"

docs/features/tags.md

@@ -1,25 +0,0 @@
-# Tags
-
-Foam supports tags.
-
-## Creating a tag
-
-There are two ways of creating a tag:
-
-- adding a `#tag` anywhere in the text of the note
-- using the `tags: tag1, tag2` property in frontmatter
-
-Tags can also be hierarchical, so you can have `#parent/child`.
-
-## Navigating tags
-
-It's possible to navigate tags via the Tag Explorer panel.
-In the future it will be possible to explore tags via the graph as well.
-
-## Styling tags
-Inline tags can be styled using custom CSS with the selector `.foam-tag`.
-
-## An alternative to tags
-
-Given the power of backlinks, some people prefer to use them also as tags.
-For example you can tag your notes about books with [[book]].

docs/inbox.md

@@ -29,6 +29,6 @@ Uncategorised thoughts, to be added
   - Foam Compiler?
 - Should support Netlify deploys out of the box
 - Foam should tick at the same frequency as your brain, and the Foam graph you build should match the mental model you have in your head, making navigation effortless.
-  - Maps have persistent topologies. As the graph grows, you should be able to visualise where an idea belongs. Maybe a literal map? And island? A DeckGL visualisation?
+  - Maps have persistent topologies. As the graph grows, you should be able to visualise where an idea belongs. Maybe a literal map? And island? A DeckGL visualization?
 
 Testing: This file is served from the /docs directory.

docs/index.md

@@ -36,7 +36,7 @@ Whether you want to build a [Second Brain](https://www.buildingasecondbrain.com/
 1. Create a single **Foam** workspace for all your knowledge and research following the [Getting started](#getting-started) guide.
 2. Write your thoughts in markdown documents (I like to call them **Bubbles**, but that might be more than a little twee). These documents should be atomic: Put things that belong together into a single document, and limit its content to that single topic. ([source](https://zettelkasten.de/posts/overview/#principles))
 3. Use Foam's shortcuts and autocompletions to link your thoughts together with `[[wikilinks]]`, and navigate between them to explore your knowledge graph.
-4. Get an overview of your **Foam** workspace using a [[graph-visualisation]] (⚠️ WIP), and discover relationships between your thoughts with the use of [[backlinking]].
+4. Get an overview of your **Foam** workspace using a [[graph-visualization]] (⚠️ WIP), and discover relationships between your thoughts with the use of [[backlinking]].
 
 Foam is a like a bathtub: _What you get out of it depends on what you put into it._
 
@@ -234,6 +234,8 @@ If that sounds like something you're interested in, I'd love to have you along o
   </tr>
   <tr>
     <td align="center"><a href="https://github.com/lingyv-li"><img src="https://avatars.githubusercontent.com/u/8937944?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Larry Li</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=lingyv-li" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/infogulch"><img src="https://avatars.githubusercontent.com/u/133882?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Joe Taber</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=infogulch" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://www.readingsnail.pe.kr"><img src="https://avatars.githubusercontent.com/u/1904967?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Woosuk Park</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=readingsnail" title="Documentation">📖</a></td>
   </tr>
 </table>
 
@@ -251,11 +253,11 @@ If that sounds like something you're interested in, I'd love to have you along o
 Foam is licensed under the [MIT license](LICENSE.txt).
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[graph-visualisation]: features/graph-visualisation.md "Graph Visualisation"
-[backlinking]: features/backlinking.md "Backlinking"
-[recommended-extensions]: recommended-extensions.md "Recommended Extensions"
-[recipes]: recipes/recipes.md "Recipes"
-[frequently-asked-questions]: frequently-asked-questions.md "Frequently Asked Questions"
+[graph-visualization]: user/features/graph-visualization.md "Graph Visualization"
+[backlinking]: user/features/backlinking.md "Backlinking"
+[recommended-extensions]: user/getting-started/recommended-extensions.md "Recommended Extensions"
+[recipes]: user/recipes/recipes.md "Recipes"
+[frequently-asked-questions]: user/frequently-asked-questions.md "Frequently Asked Questions"
 [principles]: principles.md "Principles"
-[contribution-guide]: contribution-guide.md "Contribution Guide"
+[contribution-guide]: dev/contribution-guide.md "Contribution Guide"
 [//end]: # "Autogenerated link references"

docs/principles.md

@@ -49,8 +49,8 @@ While Foam uses tools popular among computer programmers, Foam should be inclusi
 - **Foam is for everyone** As a foam user, you support everyone's quest for knowledge and self-improvement, not only your own, or folks' who look like you. All participants in Foam repositories, discussion forums, physical and virtual meeting spaces etc are expected to respect each other as described in our [[code-of-conduct]]. **Foam is not for toxic tech bros.**
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[recipes]: recipes/recipes.md "Recipes"
-[recommended-extensions]: recommended-extensions.md "Recommended Extensions"
-[contribution-guide]: contribution-guide.md "Contribution Guide"
-[code-of-conduct]: code-of-conduct.md "Code of Conduct"
+[recipes]: user/recipes/recipes.md "Recipes"
+[recommended-extensions]: user/getting-started/recommended-extensions.md "Recommended Extensions"
+[contribution-guide]: dev/contribution-guide.md "Contribution Guide"
+[code-of-conduct]: dev/code-of-conduct.md "Code of Conduct"
 [//end]: # "Autogenerated link references"

docs/user/features/backlinking.md

@@ -8,8 +8,8 @@ When using [[wikilinks]], you can find all notes that link to a specific note in
 - Finding backlinks in published Foam workspaces via [[materialized-backlinks]] is on the [[roadmap]] but not yet implemented.
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[wikilinks]: ../wikilinks.md "Wikilinks"
+[wikilinks]: wikilinks.md "Wikilinks"
 [make-backlinks-more-prominent]: ../recipes/make-backlinks-more-prominent.md "Make Backlinks More Prominent"
-[materialized-backlinks]: ../dev/materialized-backlinks.md "Materialized Backlinks (stub)"
-[roadmap]: ../dev/roadmap.md "Roadmap"
+[materialized-backlinks]: ../../dev/proposals/materialized-backlinks.md "Materialized Backlinks (stub)"
+[roadmap]: ../../dev/proposals/roadmap.md "Roadmap"
 [//end]: # "Autogenerated link references"

docs/user/features/custom-markdown-preview-styles.md

@@ -28,4 +28,4 @@ Foams offers the functionality to include other notes in your note. This will be
 <div class="foam-cyclic-link-warning">
   Cyclic link detected for wikilink: ${wikilink}
 </div>
-```
+```

docs/user/features/custom-snippets.md

@@ -5,6 +5,6 @@ You can add custom snippets whilst the default set of snippets are decided by fo
 1. `Cmd` + `Shift` + `P` (`Ctrl` + `Shift` + `P` for Windows), type `snippets` and select `Preferences: Configure User Snippets`.
 2. The command palette will remain in focus. Search for `markdown` and select the entry entitled `markdown.json (Markdown)`.
 3. A JSON file will open. You can author your own snippets using the [documentation](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_create-your-own-snippets) to help you, or if you're using a snippet shared by another Foam user then you can copy and paste it in, as the below GIF demonstrates:
-   ![Demonstrating adding a custom snippet](../assets/images/custom-snippet.gif)
+   ![Demonstrating adding a custom snippet](../../assets/images/custom-snippet.gif)
 
 To get started, you might consider replacing the entire contents of the `markdown.json` file opened by the steps above with the JSON in [this comment](https://github.com/foambubble/foam/pull/192#issuecomment-666736270).

docs/user/features/daily-notes.md

@@ -0,0 +1,55 @@
+# Daily Notes
+
+Daily notes allow you to quickly create and access a new notes file for each day. This is a surpisingly effective and increasingly common strategy to organize notes and manage events.
+
+View today's note file by running the `Foam: Open Daily Note` command, by using the shortcut `alt+d` (note: shortcuts can be [overridden](https://code.visualstudio.com/docs/getstarted/keybindings)), or by using [#snippets](#Snippets). The name, location, and title of daily notes files is [#configurable](#Configuration).
+
+## Roam-style Automatic Daily Notes
+
+You can automatically open today's note on startup by setting the `Foam › Open Daily Note: On Startup` setting to `true`.
+
+## Daily Note Templates
+
+Daily notes can also make use of [[Note Templates]], by defining a special `.foam/templates/daily-note.md` template.
+
+## Snippets
+
+Create a link to a recent daily note using [snippets](https://code.visualstudio.com/docs/editor/userdefinedsnippets). Type `/today` and press `enter` to link to today's note. You can also write:
+
+| Snippet      | Date          |
+| ------------ | ------------- |
+| `/tomorrow`  | tomorrow      |
+| `/yesterday` | yesterday     |
+| `/monday`    | next Monday   |
+| `/+1d`       | tomorrow      |
+| `/-3d`       | 3 days ago    |
+| `/+1w`       | in a week     |
+| `/-1m`       | one month ago |
+| `/+1y`       | in one year   |
+
+## Configuration
+
+By default, Daily Notes will be created in a file called `yyyy-mm-dd.md` in the workspace's `journals` folder, with a heading `yyyy-mm-dd`.
+
+These settings can be overridden in your workspace or global `.vscode/settings.json` file, using the [**dateformat** date masking syntax](https://github.com/felixge/node-dateformat#mask-options):
+
+It's possible to customize path and heading of your daily notes, by following the [dateformat masking syntax](https://github.com/felixge/node-dateformat#mask-options).
+The following properties can be used:
+
+```json
+  "foam.openDailyNote.directory": "journal",
+  "foam.openDailyNote.filenameFormat": "'daily-note'-yyyy-mm-dd",
+  "foam.openDailyNote.fileExtension": "mdx",
+  "foam.openDailyNote.titleFormat": "'Journal Entry, ' dddd, mmmm d",
+```
+
+The above configuration would create a file `journal/daily-note-2020-07-25.mdx`, with the heading `Journal Entry, Sunday, July 25`.
+
+## Extend Functionality (Weekly, Monthly, Quarterly Notes)
+
+Please see [[note-macros]]
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[Note Templates]: note-templates.md "Note Templates"
+[note-macros]: ../recipes/note-macros.md "Custom Note Macros"
+[//end]: # "Autogenerated link references"

docs/user/features/graph-visualization.md

@@ -0,0 +1,74 @@
+# Graph Visualization
+
+Foam comes with a graph visualization of your notes.
+To see the graph execute the `Foam: Show Graph` command.
+
+## Graph Navigation
+
+With the graph you can:
+
+- highlight a node by hovering on it, to quickly see how it's connected to the rest of your notes
+- select one or more (by keeping `shift` pressed while selecting) nodes by clicking on them, to better understand the structure of your notes
+- navigate to a note by clicking on it while pressing `ctrl` or `cmd`
+- automatically center the graph on the currently edited note, to immediately see its connections
+
+## Custom Graph Styles
+
+The Foam graph will use the current VS Code theme by default, but it's possible to customize it with the `foam.graph.style` setting.
+
+![Graph style demo](../../assets/images/graph-style.gif)
+
+A sample configuration object is provided below, you can provide as many or as little configuration as you wish:
+
+```json
+"foam.graph.style": {
+    "background": "#202020",
+    "fontSize": 12,
+    "highlightedForeground": "#f9c74f",
+    "node": {
+        "note": "#277da1",
+        "placeholder": "#545454",
+        "feature": "green",
+    }
+}
+```
+
+- `note` defines the color for regular nodes
+- `placeholder` defines the color for links that don't match any existing note. This is a [[placeholder]] because no file with such name exists (see [[wikilinks]] for more info).
+- `feature` shows an example of how you can use note types to customize the graph. It defines the color for the notes of type `feature`
+  - see [[note-properties]] for details
+  - you can have as many types as you want
+
+### Style nodes by type
+
+It is possible to customize the style of a node based on the `type` property in the YAML frontmatter of the corresponding document.
+
+For example the following `backlinking.md` note:
+
+```
+---
+type: feature
+---
+# Backlinking
+
+...
+```
+
+And the following `settings.json`:
+
+```json
+"foam.graph.style": {
+    "node": {
+        "feature": "red",
+    }
+}
+```
+
+Will result in the following graph:
+
+![Style node by type](../../assets/images/style-node-by-type.png)
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[wikilinks]: wikilinks.md "Wikilinks"
+[note-properties]: note-properties.md "Note Properties"
+[//end]: # "Autogenerated link references"

docs/user/features/including-notes.md

@@ -16,5 +16,5 @@ Work on this feature is evolving and progressing. See the [[inclusion-of-notes]]
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
 [custom-markdown-preview-styles]: custom-markdown-preview-styles.md "Custom Markdown Preview Styles"
-[inclusion-of-notes]: ../proposals/inclusion-of-notes.md "Inclusion of notes Proposal "
-[//end]: # "Autogenerated link references"
+[inclusion-of-notes]: ../../dev/proposals/inclusion-of-notes.md "Inclusion of notes Proposal "
+[//end]: # "Autogenerated link references"

docs/user/features/link-reference-definitions.md

@@ -1,8 +1,6 @@
 # Link Reference Definitions
 
-## Introduction
-
-When you use `[[wikilinks]]`, the [foam-vscode](https://github.com/foambubble/foam/tree/master/packages/foam-vscode) extension will automatically generate [Markdown Link Reference Definitions](https://spec.commonmark.org/0.29/#link-reference-definitions) at the bottom of the file. This is done to make the content of the file compatible with various Markdown tools (e.g. parsers, static site generators, VS code plugins etc), which don't support `[[wikilinks]]`.
+When you use `[[wikilinks]]`, the [foam-vscode](https://github.com/foambubble/foam/tree/master/packages/foam-vscode) extension can automatically generate [Markdown Link Reference Definitions](https://spec.commonmark.org/0.29/#link-reference-definitions) at the bottom of the file. This is not needed to navigate your workspace with foam-vscode, but is useful for files to remain compatible with various Markdown tools (e.g. parsers, static site generators, VS code plugins etc), which don't support `[[wikilinks]]`.
 
 ## Example
 
@@ -65,14 +63,14 @@ You can ignore the `_site` directory by adding the following to your `.vscode/se
 
 After changing the setting in your workspace, you can run the [[workspace-janitor]] command to convert all existing definitions.
 
-[[todo]] _Implement a `foam.eclude
-
 ## Future improvements
 
+Implement `foam.exclude`. [[todo]]
+
 See [[link-reference-definition-improvements]] for further discussion on current problems and potential solutions.
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[workspace-janitor]: workspace-janitor.md "Janitor"
-[todo]: ../dev/todo.md "Todo"
-[link-reference-definition-improvements]: ../dev/link-reference-definition-improvements.md "Link Reference Definition Improvements"
+[workspace-janitor]: ../tools/workspace-janitor.md "Janitor"
+[todo]: ../../dev/todo.md "Todo"
+[link-reference-definition-improvements]: ../../dev/proposals/link-reference-definition-improvements.md "Link Reference Definition Improvements"
 [//end]: # "Autogenerated link references"

docs/user/features/note-properties.md

@@ -0,0 +1,35 @@
+---
+type: feature
+keywords: hello world
+---
+
+# Note Properties
+
+At the top of the file you can have a section where you define your properties.
+
+> Be aware that this section needs to be at the very top of the file to be valid
+
+For example, for this file, we have:
+
+```text
+---
+type: feature
+keywords: hello world
+---
+```
+
+Those are properties.
+Properties can be used to organize your notes.
+
+## Special Properties
+
+Some properties have special meaning for Foam:
+
+- the `title` property will assign the name to the note that you will see in the graph, regardless of the filename or the first heading (also see how to [[write-notes-in-foam]])
+- the `type` property can be used to style notes differently in the graph (also see [[graph-visualization]])
+- the `tags` property can be used to add tags to a note (see [[tags-and-tag-explorer]])
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[write-notes-in-foam]: ../getting-started/write-notes-in-foam.md "Writing Notes"
+[graph-visualization]: graph-visualization.md "Graph Visualization"
+[//end]: # "Autogenerated link references"

docs/user/features/note-templates.md

@@ -1,8 +1,8 @@
 # Note Templates
 
-Foam supports note templates. Templates are a way to customize the starting content for your notes (instead of always starting from an empty note).
+Foam supports note templates which let you customize the starting content of your notes instead of always starting from an empty note.
 
-Note templates are files located in the special `.foam/templates` directory.
+Note templates are `.md` files located in the special `.foam/templates` directory of your workspace.
 
 ## Quickstart
 
@@ -11,7 +11,7 @@ Create a template:
 * Run the `Foam: Create New Template` command from the command palette
 * OR manually create a regular `.md` file in the `.foam/templates` directory
 
-![Create new template GIF](../assets/images/create-new-template.gif)
+![Create new template GIF](../../assets/images/create-new-template.gif)
 
 _Theme: Ayu Light_
 
@@ -20,7 +20,7 @@ To create a note from a template:
 * Run the `Foam: Create New Note From Template` command and follow the instructions. Don't worry if you've not created a template yet! You'll be prompted to create a new template if none exist.
 * OR run the `Foam: Create New Note` command, which uses the special default template (`.foam/templates/new-note.md`, if it exists)
 
-![Create new note from template GIF](../assets/images/create-new-note-from-template.gif)
+![Create new note from template GIF](../../assets/images/create-new-note-from-template.gif)
 
 _Theme: Ayu Light_
 
@@ -129,7 +129,7 @@ foam_template:
 
 These attributes provide a human readable name and description to be shown in the template picker (e.g. When a user uses the `Foam: Create New Note From Template` command):
 
-![Template Picker annotated with attributes](../assets/images/template-picker-annotated.png)
+![Template Picker annotated with attributes](../../assets/images/template-picker-annotated.png)
 
 ### Adding template metadata to an existing YAML Frontmatter block
 

docs/user/features/paste-images-from-clipboard.md

@@ -0,0 +1,12 @@
+# Paste Images from Clipboard
+
+By installing the [vscode-paste-image](https://github.com/mushanshitiancai/vscode-paste-image) extension, you can paste an image from the clipboard with `cmd+alt+v`.
+
+Images are automatically copied to the `/attachments` folder and a reference is added in the file where you pasted them.
+
+A prompt will ask you to confirm the name of the image, to disable it set `"pasteImage.showFilePathConfirmInputBox": false,` in the settings.
+
+To change the location where the image is created, change the `pasteImage.path` property, e.g.:
+
+- `${currentFileDir}`: save the image next to the file
+- `${currentFileDir}/images`: create an `images` directory next to the file and save the image there

docs/user/features/spell-checking.md

@@ -0,0 +1,15 @@
+# Spell Checking
+
+Foam comes with a spell checker powered by the [Spellright extension](https://marketplace.visualstudio.com/items?itemName=ban.spellright).
+
+Misspelled words are highlighted, like hellow.
+You can place the cursor on top of the word, and press `cmd+.` for suggestions on how to fix the problem.
+
+You can configure the extension in the settings, for example to:
+
+- ignore certain files
+- change the language(s)
+- and much more
+
+You can use any number of alternative spell checking extensions for VS Code. 
+One of our favorites is [LTeX](https://marketplace.visualstudio.com/items?itemName=valentjn.vscode-ltex&ssr=false#overview), which is a bit heavier but offers some extra functionality.

docs/user/features/tags.md

@@ -0,0 +1,30 @@
+---
+tags: my-tag1 my-tag2
+---
+
+# Tags
+
+You can add tags to your notes to categorize or link notes together.
+
+## Creating a tag
+
+There are two ways of creating a tag:
+
+- Adding a `#tag` anywhere in the text of the note, for example: #my-tag1
+- Using the `tags: tag1, tag2` yaml frontmatter [[note property|note-properties]]. Notice `my-tag1` and `my-tag2` tags which are added to this document this way.
+
+Tags can also be hierarchical, so you can have `#parent/child`.
+
+## Using *Tag Explorer*
+
+It's possible to navigate tags via the Tag Explorer panel.
+In the future it will be possible to explore tags via the graph as well.
+
+## Styling tags
+
+Inline tags can be styled using custom CSS with the selector `.foam-tag`.
+
+## Using backlinks in place of tags
+
+Given the power of backlinks, some people prefer to use them as tags.
+For example you can tag your notes about books with [[book]].

docs/user/features/wikilinks.md

@@ -0,0 +1,41 @@
+# Wikilinks
+
+Wikilinks are the internal links that connect the files in your knowledge base. (Also called `[[MediaWiki]]` links).
+
+## Creating and navigating wikilinks
+
+To create a wikilink, type `[[` and then start typing the name of another note in your repo. Once the desired note is selected press the `tab` key to autocomplete it. For example: [[graph-visualization]].
+
+`Cmd` + `Click` ( `Ctrl` + `Click` on Windows ) on wikilink to navigate to that note (`F12` also works while your cursor is on the wikilink). If the file doesn't exist it will be created in your workspace based on your default [[note-template]] settings.
+
+## Placeholders
+
+You can also create a [[placeholder]].
+A placeholder is a wikilink that doesn't have a target file and a link to a placeholder is styled differently so you can easily tell them apart.
+They can still be helpful to highlight connections.
+
+Open the graph with `Foam: Show Graph` command, and look at the placeholder node.
+
+Remember, with `CTRL/CMD+click` on a wikilink you can navigate to the note, or create it (if the link is a placeholder).
+
+## Support for sections
+
+Foam supports autocompletion, navigation, embedding and diagnostics for note sections. Just use the standard wiki syntax of `[[resource#Section Title]]`.
+
+## Markdown compatibility
+
+The [Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode) extension automatically generates [[link-reference-definitions]] at the bottom of the file to make wikilinks compatible with other Markdown tools and parsers.
+
+## Read more
+
+- [[foam-file-format]]
+- [[note-templates]]
+- See [[link-reference-definition-improvements]] for further discussion on current problems and potential solutions.
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[graph-visualization]: graph-visualization.md "Graph Visualization"
+[link-reference-definitions]: link-reference-definitions.md "Link Reference Definitions"
+[foam-file-format]: ../../dev/foam-file-format.md "Foam File Format"
+[note-templates]: note-templates.md "Note Templates"
+[link-reference-definition-improvements]: ../../dev/proposals/link-reference-definition-improvements.md "Link Reference Definition Improvements"
+[//end]: # "Autogenerated link references"

docs/user/frequently-asked-questions.md

@@ -16,7 +16,7 @@
 Any extension you install in Visual Studio Code is enabled by default. Give the philosophy of Foam it works out of the box without doing any configuration upfront. In case you want to disable Foam for a specific workspace, or disable Foam by default and enable it for specific workspaces, it is advised to follow the best practices as [documented by Visual Studio Code](https://code.visualstudio.com/docs/editor/extension-marketplace#_manage-extensions)
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[recommended-extensions]: recommended-extensions.md "Recommended Extensions"
-[foam-file-format]: dev/foam-file-format.md "Foam File Format"
-[wikilinks]: wikilinks.md "Wikilinks"
+[recommended-extensions]: getting-started/recommended-extensions.md "Recommended Extensions"
+[foam-file-format]: ../dev/foam-file-format.md "Foam File Format"
+[wikilinks]: features/wikilinks.md "Wikilinks"
 [//end]: # "Autogenerated link references"

docs/user/getting-started/creating-new-notes.md

@@ -5,10 +5,10 @@
 - `Cmd` + `Shift` + `P` (`Ctrl` + `Shift` + `P` for Windows), execute `Foam: Create New Note` and enter a **Title Case Name** to create `Title Case Name.md`
   - Add a keyboard binding to make creating new notes easier.
   - The [[note-templates]] used by this command can be customized.
-- You shouldn't worry too much about categorizing your notes. You can always [[search-for-notes]], and explore them using the [[graph-visualisation]].
+- You shouldn't worry too much about categorizing your notes. You can always [[search-for-notes]], and explore them using the [[graph-visualization]].
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[note-templates]: note-templates "Note Templates"
-[search-for-notes]: ../recipes/search-for-notes "Search for Notes"
-[graph-visualisation]: graph-visualisation "Graph Visualisation"
+[note-templates]: ../features/note-templates.md "Note Templates"
+[search-for-notes]: ../recipes/search-for-notes.md "Search for Notes"
+[graph-visualization]: ../features/graph-visualization.md "Graph Visualization"
 [//end]: # "Autogenerated link references"

docs/user/getting-started/get-started-with-vscode.md

@@ -0,0 +1,43 @@
+# Getting started with VS Code
+
+VS Code is a powerful text editor, hidden behind a simple interface.
+
+VS Code supports various **keyboard shortcuts**, the most important for us are:
+
+| Shortcut      | Action                       |
+| ------------- | ---------------------------- |
+| `cmd+N`       | create a new file            |
+| `cmd+S`       | save the current file        |
+| `cmd+O`       | open a file                  |
+| `cmd+P`       | use quickpick to open a file |
+| `cmd+shift+P` | invoke a command (see below) |
+
+For more information, see the [VS Code keyboard cheat sheets](https://code.visualstudio.com/docs/getstarted/keybindings#_keyboard-shortcuts-reference), where you can also see how to customize your keybindings.
+
+## Commands
+
+Commands make VS Code extremely powerful.
+
+To invoke a command, press `cmd+shift+P` and select the command you want to execute.
+For example, to see the Foam graph:
+
+- press `cmd+shift+P`
+- start typing `show graph`
+- select the `Foam: Show Graph` command
+
+And watch the magic unfold.
+
+For more information on commands, see [commands on the VS Code site](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette).
+
+If you want to learn more about VS Code, check out their [website](https://code.visualstudio.com/docs#first-steps).
+
+## Panels
+
+You can see a few panels on the left, including:
+
+- `Outline`: this panel shows you the structure of the file based on the headings
+- `Tag Explorer`: This shows you the tags in your workspace, see [[tags-and-tag-explorer]] for more information on tags
+
+## Settings
+
+To view or change the settings in VS Code, press `cmd+,`

docs/user/getting-started/keyboard-shortcuts.md

@@ -0,0 +1,17 @@
+# Keyboard Shortcuts
+
+Here are some keyboard shortcuts you'll love when editing your notes.
+
+This works best if you can see the result in the preview panel, run the `Markdown: Open Preview to the Side` command.
+
+You can use either the name or the id to find each shortcut in the settings (File > Preferences > Keyboard Shortcuts) and find out what it is bound to on your system and change it according to your liking.
+
+| Shortcut       | Name            | ID                                      | Extension           | Use                                 |
+| -------------- | --------------- | --------------------------------------- | ------------------- | ----------------------------------- |
+| `alt+c`        | \-              | markdown.extension.checkTaskList        | Markdown All in One | Toggle TODO items.                  |
+| `cmd+b`        | \-              | markdown.extension.editing.toggleBold   | Markdown All in One | Make selection bold.                |
+| `cmd+i`        | \-              | markdown.extension.editing.toggleItalic | Markdown All in One | Make selection italic.              |
+| `ctrl+shift+f` | Format Document | editor.action.formatDocument            | Base                | Format tables                       |
+| `cmd+shift+f`  | Find files      | workbench.action.findInFiles            | Base                | Search in workspace.                |
+| `cmd+shift+e`  | Show Explorer   | workbench.view.explorer                 | Base                | Show the file explorer.             |
+| `cmd+alt+v`    | Paste Image     | extension.pasteImage                    | Paste Image         | Paste an image from your clipboard. |

docs/user/getting-started/recommended-extensions.md

@@ -2,7 +2,7 @@
 
 These extensions defined in `.vscode/extensions.json` are automatically installed when you accept the workspace's recommended extensions.
 
-This list is subject to change. Especially the Git ones.
+This list is subject to change.
 
 - [Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode) (alpha)
 - [Markdown All In One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one)

docs/user/getting-started/sync-notes-with-soruce-control.md

@@ -1,4 +1,7 @@
-# Git Integration
+# Sync notes with source control
+
+Source control is a way to precicely manage the history and content of a directory of files.
+Often used for program code, this feature is very useful for note taking as well.
 
 There are (too) many ways to commit your changes to source control:
 

docs/user/getting-started/write-notes-in-foam.md

@@ -0,0 +1,74 @@
+# Writing Notes
+
+Notes are simple text files with some extra flavor, in the shape of Markdown syntax and support for extra properties (see [[note-properties]]).
+
+## Foam Syntax
+
+Foam uses standard Markdown, with a few added twists:
+
+- the title of a note (e.g. in the [[graph-visualization]]) is given by precedence based on:
+  - the `title` property (see [[note-properties]])
+  - the first `# heading 1` of the file
+  - the file name
+
+## Markdown Syntax
+
+With Markdown, we can style our notes in a simple way, while keeping the document a simple text file (the best way to future-proof your writings!).
+
+You can see the formatted output by running the `Markdown: Open Preview to the Side` command.
+
+Here is a high level overview of Markdown, for more information on the Markdown syntax [see here](https://commonmark.org/help/).
+
+# Heading 1
+
+## Heading 2
+
+### Heading 3
+
+#### Heading 4
+
+##### Heading 5
+
+###### Heading 6
+
+This is a [link to google](https://www.google.com).
+
+This is a wikilink (aka internal link) to [[note-properties]].
+
+Here is an image:
+![image](../../attachments/foam-icon.png)
+
+> this is a blockquote
+> it can span multiple lines
+
+- list item
+- list item
+- list item
+
+1. One
+2. Two
+3. Three
+
+This text is **in bold** and this is *italic*.
+
+The following is a horizontal rule
+
+---
+
+This is a table:
+| Column 1 | Column 2 |
+| -------- | -------- |
+| R1C1     | R1C2     |
+| R2C1     | R2C2     |
+
+You can `inline code` or
+
+```text
+you can create
+code blocks
+```
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[note-properties]: ../features/note-properties.md "Note Properties"
+[graph-visualization]: ../features/graph-visualization.md "Graph Visualization"
+[//end]: # "Autogenerated link references"

docs/user/index.md

@@ -0,0 +1,82 @@
+# Using Foam
+
+Foam is a collection VS Code extensions and recipes that power up the editor into a full-blown note taking system.
+This folder contains user documentation describing how to get started using Foam, what its main features are, and strategies for getting the most out of Foam.
+The full docs are included in the `foam-template` repo that most users start from.
+
+> See also [[frequently-asked-questions]].
+
+## Getting Started
+
+- [[get-started-with-vscode]]
+- [[recommended-extensions]]
+- [[creating-new-notes]]
+- [[write-notes-in-foam]]
+- [[sync-notes-with-soruce-control]]
+- [[keyboard-shortcuts]]
+
+## Features
+
+- [[wikilinks]]
+- [[tags]]
+- [[backlinking]]
+- [[daily-notes]]
+- [[including-notes]]
+- [[spell-checking]]
+- [[graph-visualization]]
+- [[note-properties]]
+- [[note-templates]]
+- [[paste-images-from-clipboard]]
+- [[custom-markdown-preview-styles]]
+- [[link-reference-definitions]]
+- [[custom-snippets]]
+
+## Recipes
+
+[[recipes]] is a collection of user-contributed patterns that describe different ways you could utilize Foam or integrate it with other tools.
+
+## Publishing
+
+You can publish your Foam notes for consumption in different formats.
+Examples: [[publish-to-github-pages]], [[generate-gatsby-site]], [[publish-to-vercel]]
+
+See [[publishing]] for more details.
+
+## Tools
+
+- [[cli]]
+- [[workspace-janitor]]
+- [[orphans]]
+- [[foam-logging-in-vscode]]
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[frequently-asked-questions]: frequently-asked-questions.md "Frequently Asked Questions"
+[get-started-with-vscode]: getting-started/get-started-with-vscode.md "Getting started with VS Code"
+[recommended-extensions]: getting-started/recommended-extensions.md "Recommended Extensions"
+[creating-new-notes]: getting-started/creating-new-notes.md "Creating New Notes"
+[write-notes-in-foam]: getting-started/write-notes-in-foam.md "Writing Notes"
+[sync-notes-with-soruce-control]: getting-started/sync-notes-with-soruce-control.md "Sync notes with source control"
+[keyboard-shortcuts]: getting-started/keyboard-shortcuts.md "Keyboard Shortcuts"
+[wikilinks]: features/wikilinks.md "Wikilinks"
+[tags]: features/tags.md "Tags"
+[backlinking]: features/backlinking.md "Backlinking"
+[daily-notes]: features/daily-notes.md "Daily Notes"
+[including-notes]: features/including-notes.md "Including notes in a note"
+[spell-checking]: features/spell-checking.md "Spell Checking"
+[graph-visualization]: features/graph-visualization.md "Graph Visualization"
+[note-properties]: features/note-properties.md "Note Properties"
+[note-templates]: features/note-templates.md "Note Templates"
+[paste-images-from-clipboard]: features/paste-images-from-clipboard.md "Paste Images from Clipboard"
+[custom-markdown-preview-styles]: features/custom-markdown-preview-styles.md "Custom Markdown Preview Styles"
+[link-reference-definitions]: features/link-reference-definitions.md "Link Reference Definitions"
+[custom-snippets]: features/custom-snippets.md "Adding Custom Snippets"
+[recipes]: recipes/recipes.md "Recipes"
+[publish-to-github-pages]: publishing/publish-to-github-pages.md "GitHub Pages"
+[generate-gatsby-site]: publishing/generate-gatsby-site.md "Generate a site using Gatsby"
+[publish-to-vercel]: publishing/publish-to-vercel.md "Publish to Vercel"
+[publishing]: publishing/publishing.md "Publishing pages"
+[cli]: tools/cli.md "Command Line Interface"
+[workspace-janitor]: tools/workspace-janitor.md "Janitor"
+[orphans]: tools/orphans.md "Orphaned Notes"
+[foam-logging-in-vscode]: tools/foam-logging-in-vscode.md "Foam logging in VsCode"
+[//end]: # "Autogenerated link references"

docs/user/publishing/publish-to-azure-devops-wiki.md

@@ -26,7 +26,7 @@ readme
 
 A published workspace looks like this:
 
-![Azure DevOps wiki](../assets/images/azure-devops-wiki-demo.png)
+![Azure DevOps wiki](../../assets/images/azure-devops-wiki-demo.png)
 
 There is default table of contents pane to the left of the wiki content. Here, you'll find a list of all directories that are present in your Foam workspace, and all wiki pages. Page names are derived from files names, and they are listed in alphabetical order. You may reorder pages by adding filenames without `.md` extension to `.order` file.
 

docs/user/publishing/publish-to-github-pages.md

@@ -48,6 +48,6 @@ There are many other templates which also support publish your foam workspace to
 [[todo]] [[good-first-task]] Improve this documentation
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: ../dev/todo.md "Todo"
-[good-first-task]: ../dev/good-first-task.md "Good First Task"
+[todo]: ../../dev/todo.md "Todo"
+[good-first-task]: ../../dev/good-first-task.md "Good First Task"
 [//end]: # "Autogenerated link references"

docs/user/publishing/publish-to-gitlab-pages.md

@@ -30,7 +30,7 @@ const siteMetadata = {
   title: "A title",
   shortName: "A short name",
   description: "",
-  imageUrl: "/graph-visualisation.jpg",
+  imageUrl: "/graph-visualization.jpg",
   siteUrl: "https://$USER_NAME.gitlab.io",
 };
 module.exports = {

docs/user/publishing/publish-to-vercel.md

@@ -77,7 +77,7 @@ Next, select the folder to deploy from if prompted. If we are using the default
 
 Finally, if all is successful, Vercel will show the detected framework: Jekyll. Press `Deploy` to proceed on publishing our project.
 
-![](../assets/images/vercel-detect-preset.png)
+![](../../assets/images/vercel-detect-preset.png)
 
 And now, Vercel will take care of building and rendering our foam workspace each time on push. Vercel will publish our site to `xxx.vercel.app`, we can also define a custom domain name for our Vercel website.
 

docs/user/publishing/publishing.md

@@ -2,6 +2,8 @@
 
 Foam pages can be published.
 
+TODO add publishing TOC
+
 ## Foam site generator?
 
 Another case of the [[build-vs-assemble]] dilemma. We could provide a better publishing experience by building a bespoke static site generator (or a gatsby plugin) that's aware of Foam conventions (backlinks etc.)
@@ -21,5 +23,5 @@ Would be cool if Foam pages could be published. Some ideas here.
     - [ ] More granular access control? Email someone a link with a hash? [Testing](testing.md)
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[build-vs-assemble]: ../dev/build-vs-assemble.md "Build vs Assemble"
+[build-vs-assemble]: ../../dev/build-vs-assemble.md "Build vs Assemble"
 [//end]: # "Autogenerated link references"

docs/user/recipes/automatic-git-syncing.md

@@ -19,5 +19,5 @@ __For Foam specific needs, you can add a comment here by following the [[contrib
 - Feedback and issues with the integration of the extension in Foam can be reported in our [issue tracker](https://github.com/foambubble/foam/issues)
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[contribution-guide]: ../contribution-guide.md "Contribution Guide"
+[contribution-guide]: ../../dev/contribution-guide.md "Contribution Guide"
 [//end]: # "Autogenerated link references"

docs/user/recipes/automatically-expand-urls-to-well-titled-links.md

@@ -10,7 +10,7 @@ Markdown Link Expander will scrape your URL's `<title>` tag to create a nice Mar
 
 ## Instructions
 
-![Demo](../assets/images/prettify-links-demo.gif)
+![Demo](../../assets/images/prettify-links-demo.gif)
 
 1. Highlight desired URL
 2. `Cmd` + `Shift` + `P`

docs/user/recipes/diagrams-in-markdown.md

@@ -13,9 +13,9 @@ You can use [Mermaid](https://marketplace.visualstudio.com/items?itemName=bierne
 
 ## Draw.io
 
-[Draw.io](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio) extension allows you to create, edit, and display your diagrams without leaving Visual Studio Code. The `.drawio.svg` or `.drawio.png` files can be automatically embedded and displayed in published Foams, no export needed. FYI, the diagram below was made using Draw.io! You can check the diagram [here](../assets/images/diagram-drawio-demo.drawio.svg).
+[Draw.io](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio) extension allows you to create, edit, and display your diagrams without leaving Visual Studio Code. The `.drawio.svg` or `.drawio.png` files can be automatically embedded and displayed in published Foams, no export needed. FYI, the diagram below was made using Draw.io! You can check the diagram [here](../../assets/images/diagram-drawio-demo.drawio.svg).
 
-![diagram-drawio-demo](../assets/images/diagram-drawio-demo.drawio.svg)
+![diagram-drawio-demo](../../assets/images/diagram-drawio-demo.drawio.svg)
 
 ### Using Draw.io
 
@@ -23,7 +23,3 @@ You can use [Mermaid](https://marketplace.visualstudio.com/items?itemName=bierne
 2. Create a new `*.drawio.svg` or `*.drawio.png` file.
 3. Start drawing your diagram. Once you done, save it.
 4. Embed the diagram file as you embedding the image file, for example: `![My Diagram](my-diagram.drawio.svg)`
-
-[//begin]: # "Autogenerated link references for markdown compatibility"
-[publish-to-github-pages]: ../publishing/publish-to-github-pages.md "GitHub Pages"
-[//end]: # "Autogenerated link references"

docs/user/recipes/how-to-write-recipes.md

@@ -24,7 +24,7 @@ When creating new recipes, if you don't know which extension does what, you can
 
 Here we describe how the extension should be used.
 
-![Demo](../assets/images/foam-navigation-demo.gif)
+![Demo](../../assets/images/foam-navigation-demo.gif)
 
 You may include a screenshot or GIF of the feature in action by uploading an image to the `assets/images` directory. Please try to keep GIFs as small as possible by recording them with a low frame rate.
 
@@ -37,7 +37,7 @@ You can add [[recipes]] by creating a pull request to [foambubble/foam](https://
 Read more in our [[contribution-guide]].
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[recommended-extensions]: ../recommended-extensions.md "Recommended Extensions"
+[recommended-extensions]: ../getting-started/recommended-extensions.md "Recommended Extensions"
 [recipes]: recipes.md "Recipes"
-[contribution-guide]: ../contribution-guide.md "Contribution Guide"
+[contribution-guide]: ../../dev/contribution-guide.md "Contribution Guide"
 [//end]: # "Autogenerated link references"

docs/user/recipes/make-backlinks-more-prominent.md

@@ -6,7 +6,7 @@ This #recipe shows you how to do that.
 
 At the moment, you can drag the explorer pane to your bottom pane, and either show it side by side with another pane, or have take the full width of the editor:
 
-![Demo of dragging and dropping the pane](../assets/images/demo-backlinks-explorer.gif)
+![Demo of dragging and dropping the pane](../../assets/images/demo-backlinks-explorer.gif)
 
 In the future we'll want to improve this feature by
 
@@ -17,5 +17,5 @@ In the future we'll want to improve this feature by
   - [Suggested by @Jash on Discord](https://discordapp.com/channels/729975036148056075/729978910363746315/730999992419876956)
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[materialized-backlinks]: ../dev/materialized-backlinks.md "Materialized Backlinks (stub)"
+[materialized-backlinks]: ../../dev/proposals/materialized-backlinks.md "Materialized Backlinks (stub)"
 [//end]: # "Autogenerated link references"

docs/user/recipes/migrating-from-obsidian.md

@@ -5,6 +5,6 @@
 If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: ../dev/todo.md "Todo"
-[roadmap]: ../dev/roadmap.md "Roadmap"
+[todo]: ../../dev/todo.md "Todo"
+[roadmap]: ../../dev/proposals/roadmap.md "Roadmap"
 [//end]: # "Autogenerated link references"

docs/user/recipes/migrating-from-onenote.md

@@ -22,7 +22,7 @@ The powershell script 'ConvertOneNote2MarkDown-v2.ps1' will utilize the OneNote
 3. For the next sections, it is highly recommended that you use VS Code, and its embedded PowerShell terminal, as this allows you to edit and run the script, as well as check the results of the .md output all in one window.
 4. Whatever you choose, you will need to do the following:
    1. Clone the script to your computer (see [here](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository), if you're unfamiliar with git).
-   2. Once cloned, navigate to the repo folder. In VS Code, use File -> Add Folder to Workspace, right click on the folder in the left side bar and click [Open In Integrated Terminal](../assets/images/migrating-one-note.png).
+   2. Once cloned, navigate to the repo folder. In VS Code, use File -> Add Folder to Workspace, right click on the folder in the left side bar and click [Open In Integrated Terminal](../../assets/images/migrating-one-note.png).
    3. Run the script by executing
 ```.\ConvertOnenote2Markdown-v2```
     * if you receive an error, try running this line to bypass security:

docs/user/recipes/migrating-from-roam.md

@@ -5,6 +5,6 @@
 If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: ../dev/todo.md "Todo"
-[roadmap]: ../dev/roadmap.md "Roadmap"
+[todo]: ../../dev/todo.md "Todo"
+[roadmap]: ../../dev/proposals/roadmap.md "Roadmap"
 [//end]: # "Autogenerated link references"

docs/user/recipes/predefined-user-snippets.md

@@ -24,7 +24,7 @@ This #recipe allows us to introduce Roam style commands to Foam, by using [VS Co
 ```
 
 Which would look like:
-![GIF demonstrating User Snippets](../assets/images/snippets.gif)
+![GIF demonstrating User Snippets](../../assets/images/snippets.gif)
 
 Using snippets enables Foam users to add [[custom-snippets]] themselves so they live alongside the first-class `/commands`.
 
@@ -44,7 +44,7 @@ Some markdown syntax is difficult for users who have never authored markdown bef
 ```
 
 We could provide snippets that expand out into the associated markdown syntax, like in the below GIF:
-![GIF demonstrating markdown snippets](../assets/images/markdown-snippets.gif)
+![GIF demonstrating markdown snippets](../../assets/images/markdown-snippets.gif)
 
 The JSON for these snippets can be found [here](https://github.com/foambubble/foam/pull/192#issuecomment-666736270).
 

docs/user/recipes/recipes.md

@@ -27,7 +27,7 @@ A #recipe is a guide, tip or strategy for getting the most out of your Foam work
 
 ## Discover
 
-- Explore your notes using [[graph-visualisation]]
+- Explore your notes using [[graph-visualization]]
 - Discover relationships with [[backlinking]]
 - Simulating [[unlinked-references]]
 
@@ -106,28 +106,27 @@ Thought of a recipe but don't see a category for them? Add them here and we'll o
 _See [[contribution-guide]] and [[how-to-write-recipes]]._
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[contribution-guide]: ../contribution-guide.md "Contribution Guide"
+[contribution-guide]: ../../dev/contribution-guide.md "Contribution Guide"
 [how-to-write-recipes]: how-to-write-recipes.md "How to Write Recipes"
-[todo]: ../dev/todo.md "Todo"
+[todo]: ../../dev/todo.md "Todo"
 [web-clipper]: web-clipper.md "Web Clipper"
-[graph-visualisation]: ../features/graph-visualisation.md "Graph Visualisation"
+[graph-visualization]: ../features/graph-visualization.md "Graph Visualization"
 [backlinking]: ../features/backlinking.md "Backlinking"
-[unlinked-references]: ../dev/unlinked-references.md "Unlinked references (stub)"
-[wikilinks]: ../wikilinks.md "Wikilinks"
-[creating-new-notes]: ../features/creating-new-notes.md "Creating New Notes"
-[daily-notes]: ../features/daily-notes.md "Daily notes"
+[unlinked-references]: ../../dev/unlinked-references.md "Unlinked references (stub)"
+[wikilinks]: ../features/wikilinks.md "Wikilinks"
+[creating-new-notes]: ../getting-started/creating-new-notes.md "Creating New Notes"
+[daily-notes]: ../features/daily-notes.md "Daily Notes"
 [tags]: ../features/tags.md "Tags"
 [note-templates]: ../features/note-templates.md "Note Templates"
-[orphans]: ../features/orphans.md "Orphans"
+[orphans]: ../tools/orphans.md "Orphaned Notes"
 [note-macros]: note-macros.md "Custom Note Macros"
 [diagrams-in-markdown]: diagrams-in-markdown.md "Diagrams in Markdown"
 [automatically-expand-urls-to-well-titled-links]: automatically-expand-urls-to-well-titled-links.md "Automatically Expand URLs to Well-Titled Links"
 [custom-markdown-preview-styles]: ../features/custom-markdown-preview-styles.md "Custom Markdown Preview Styles"
 [add-images-to-notes]: add-images-to-notes.md "Add images to your notes"
 [shows-image-preview-on-hover]: shows-image-preview-on-hover.md "Shows Image Preview on Hover"
-[good-first-task]: ../dev/good-first-task.md "Good First Task"
+[good-first-task]: ../../dev/good-first-task.md "Good First Task"
 [including-notes]: ../features/including-notes.md "Including notes in a note"
-[git-integration]: ../features/git-integration.md "Git Integration"
 [write-your-notes-in-github-gist]: write-your-notes-in-github-gist.md "Write your notes in GitHub Gist"
 [publish-to-github-pages]: ../publishing/publish-to-github-pages.md "GitHub Pages"
 [publish-to-gitlab-pages]: ../publishing/publish-to-gitlab-pages.md "GitLab Pages"

docs/user/recipes/search-for-notes.md

@@ -9,5 +9,5 @@ Run `Cmd` + `P` ( `Ctrl` +  `P` on Windows ) and type a name (like 'issues') to
 Run `Cmd` + `Shift` + `F` ( `Ctrl` + `Shift` + `F` on Windows ) and type a word (like 'links') to find all the notes that contain that term.
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: ../dev/todo.md "Todo"
+[todo]: ../../dev/todo.md "Todo"
 [//end]: # "Autogenerated link references"

docs/user/recipes/shows-image-preview-on-hover.md

@@ -6,5 +6,5 @@ Use extension: [Image preview](https://marketplace.visualstudio.com/items?itemNa
 
 It looks like this
 
-![picture 1](../assets/images/preview-image-on-hover.png)
-![picture 2](../assets/images/preview-image-in-glutter.png)
+![picture 1](../../assets/images/preview-image-on-hover.png)
+![picture 2](../../assets/images/preview-image-in-glutter.png)

docs/user/recipes/take-notes-from-mobile-phone.md

@@ -59,6 +59,6 @@ If such an app was worth building, it would have to have the following features:
 Given the effort vs reward ratio, it's a low priority for core team, but if someone wants to work on this, we can provide support! Talk to us on the #mobile-apps channel on [Foam Discord](https://foambubble.github.io/join-discord/w).
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[build-vs-assemble]: ../dev/build-vs-assemble.md "Build vs Assemble"
-[workspace-janitor]: ../features/workspace-janitor.md "Janitor"
+[build-vs-assemble]: ../../dev/build-vs-assemble.md "Build vs Assemble"
+[workspace-janitor]: ../tools/workspace-janitor.md "Janitor"
 [//end]: # "Autogenerated link references"

docs/user/tools/foam-logging-in-vscode.md

@@ -1,21 +1,20 @@
 # Foam logging in VsCode
 
-## Find the Foam log
-
-The Foam log can be found in the `Output` tab.
+The Foam extension logs details about what its doing in vscode's `Output` tab.
+Generally this is only useful if you're reporting an issue about Foam.
 
 1. To show the tab, click on `View > Output`.
 2. In the dropdown on the right of the tab, select `Foam`.
 
-![Find the foam log](../assets/images/foam-log.png)
+![Find the foam log](../../assets/images/foam-log.png)
+
+When reporting an issue about Foam, set the log level to `Debug`:
+
+## Change the log level for the session
+
+Execute the command `Foam: Set log level`.
 
 ## Change the default logging level
 
 1. Open workspace settings (`cmd+,`, or execute the `Preferences: Open Workspace Settings` command)
 2. Look for the entry `Foam > Logging: Level`
-
-Set to debug when reporting an issue
-
-## Change the log level for the session
-
-Execute the command `Foam: Set log level`.

docs/user/tools/orphans.md

@@ -1,4 +1,4 @@
-# Orphans
+# Orphaned Notes
 
 Foam helps you to find orphans: notes that have neither forward links nor backlinks.
 

docs/user/tools/workspace-janitor.md

@@ -19,7 +19,7 @@ In the future, Janitor can help you with
 
 Execute the "Foam: Run Janitor" command from the command palette.
 
-![Foam Janitor demo](../assets/images/foam-janitor-demo.gif)
+![Foam Janitor demo](../../assets/images/foam-janitor-demo.gif)
 
 ## Using Janitor from command line (Experimental)
 
@@ -37,6 +37,6 @@ You can run the Janitor as a git hook on every commit to ensure your workspace l
 You can also run the Janitor from a GitHub action to ensure that all changes coming to your workspace are up to date. This can be useful when editing your Foam notes from mobile (i.e. via [GitJournal](https://gitjournal.io)), or your Foam has multiple contributors and you want to ensure that all changes are correctly integrated.
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[link-reference-definitions]: link-reference-definitions.md "Link Reference Definitions"
-[materialized-backlinks]: ../dev/materialized-backlinks.md "Materialized Backlinks (stub)"
+[link-reference-definitions]: ../features/link-reference-definitions.md "Link Reference Definitions"
+[materialized-backlinks]: ../../dev/proposals/materialized-backlinks.md "Materialized Backlinks (stub)"
 [//end]: # "Autogenerated link references"

docs/wikilinks.md

@@ -1,31 +0,0 @@
-# Wikilinks
-
-Foam enables you to Link pages together using `[[file-name]]` annotations (i.e. `[[MediaWiki]]` links).
-
-- Type `[[` and start typing a file name for autocompletion.
-- `Cmd` + `Click` ( `Ctrl` + `Click` on Windows ) on file name to navigate to file (`F12` also works while your cursor is on the file name)
-- `Cmd` + `Click` ( `Ctrl` + `Click` on Windows ) on non-existent file to create that file in the workspace.
-  - The note creation makes use of the special [`new-note.md` note template](features/note-templates)
-
-> If the `F12` shortcut feels unnatural you can rebind it at File > Preferences > Keyboard Shortcuts by searching for `editor.action.revealDefinition`.
-
-## Support for sections
-
-Foam supports autocompletion, navigation, embedding and diagnostics for note sections. Just use the standard wiki syntax of `[[resource#Section Title]]`.
-
-## Markdown compatibility
-
-The [Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode) extension automatically generates [[link-reference-definitions]] at the bottom of the file to make wikilinks compatible with Markdown tools and parsers.
-
-## Read more
-
-- [[foam-file-format]]
-- [[note-templates]]
-- See [[link-reference-definition-improvements]] for further discussion on current problems and potential solutions.
-
-[//begin]: # "Autogenerated link references for markdown compatibility"
-[link-reference-definitions]: features/link-reference-definitions.md "Link Reference Definitions"
-[foam-file-format]: dev/foam-file-format.md "Foam File Format"
-[note-templates]: features/note-templates.md "Note Templates"
-[link-reference-definition-improvements]: dev/link-reference-definition-improvements.md "Link Reference Definition Improvements"
-[//end]: # "Autogenerated link references"

lerna.json

@@ -4,5 +4,5 @@
   ],
   "npmClient": "yarn",
   "useWorkspaces": true,
-  "version": "0.19.1"
+  "version": "0.19.4"
 }

package.json

@@ -9,9 +9,10 @@
     "packages/*"
   ],
   "scripts": {
-    "vscode:package-extension": "yarn workspace foam-vscode package-extension",
-    "vscode:install-extension": "yarn workspace foam-vscode install-extension",
-    "vscode:publish-extension": "yarn workspace foam-vscode publish-extension",
+    "version-extension": "lerna version",
+    "package-extension": "yarn workspace foam-vscode package-extension",
+    "install-extension": "yarn workspace foam-vscode install-extension",
+    "publish-extension": "yarn workspace foam-vscode publish-extension",
     "reset": "yarn && yarn clean && yarn build",
     "clean": "lerna run clean",
     "build": "lerna run build",

packages/foam-vscode/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to the "foam-vscode" extension will be documented in this fi
 
 Check [Keep a Changelog](http://keepachangelog.com/) for recommendations on how to structure this file.
 
+## [0.19.4] - 2022-08-07
+
+Fixes and Improvements:
+- Fixed note embed in preview (#1052)
+
+## [0.19.3] - 2022-08-04
+
+Fixes and Improvements:
+- Image embeds fixed in preview (#1036)
+
+## [0.19.2] - 2022-08-04
+
+Fixes and Improvements:
+- Added support for angle markdown links (#1044)
+- Filter out invalid file name chars when creating note (#1042)
+
+Internal:
+- Reorganized docs (#1031, thanks @infogulch)
+- Fixed documentation links (#1046)
+- Preview code refactoring
+
 ## [0.19.1] - 2022-07-11
 
 Internal:

packages/foam-vscode/README.md

@@ -17,7 +17,7 @@ Foam is also meant to be extensible, so you can integrate with its internals to
 
 ### Graph Visualization
 
-See how your notes are connected via a [graph](https://foambubble.github.io/foam/features/graph-visualisation) with the `Foam: Show Graph` command.
+See how your notes are connected via a [graph](https://foambubble.github.io/foam/user/features/graph-visualization) with the `Foam: Show Graph` command.
 
 ![Graph Visualization](./assets/screenshots/feature-show-graph.gif)
 
@@ -75,7 +75,7 @@ Foam supports link aliasing, so you can have a `[[wikilink]]`, or a `[[wikilink|
 
 ### Templates
 
-Use [custom templates](https://foambubble.github.io/foam/features/note-templates) to have avoid repetitve work on your notes.
+Use [custom templates](https://foambubble.github.io/foam/user/features/note-templates) to have avoid repetitve work on your notes.
 
 ![Templates](./assets/screenshots/feature-templates.gif)
 
@@ -88,7 +88,7 @@ See for each occurrence the context in which it lives, as well as a preview of t
 
 ### Tag Explorer Panel
 
-Tag your notes and navigate them with the [Tag Explorer](https://foambubble.github.io/foam/features/tags).
+Tag your notes and navigate them with the [Tag Explorer](https://foambubble.github.io/foam/user/features/tags).
 Foam also supports hierarchical tags.
 
 ![Tag Explorer Panel](./assets/screenshots/feature-tags-panel.gif)
@@ -109,13 +109,13 @@ Foam highlights wikilinks and placeholder differently, to help you visualize you
 
 ### Daily note
 
-Create a journal with [daily notes](https://foambubble.github.io/foam/features/daily-notes).
+Create a journal with [daily notes](https://foambubble.github.io/foam/user/features/daily-notes).
 
 ![Daily Note](./assets/screenshots/feature-daily-note.gif)
 
 ### Generate references for your wikilinks
 
-Create markdown [references](https://foambubble.github.io/foam/features/link-reference-definitions) for `[[wikilinks]]`, to use your notes in a non-Foam workspace.
+Create markdown [references](https://foambubble.github.io/foam/user/features/link-reference-definitions) for `[[wikilinks]]`, to use your notes in a non-Foam workspace.
 With references you can also make your notes navigable both in GitHub UI as well as GitHub Pages.
 
 ![Generate references](./assets/screenshots/feature-definitions-generation.gif)
@@ -125,12 +125,12 @@ With references you can also make your notes navigable both in GitHub UI as well
 - Explore your knowledge base with the `Foam: Open Random Note` command
 - Access your daily note with the `Foam: Open Daily Note` command
 - Create a new note with the `Foam: Create New Note` command
-  - This becomes very powerful when combined with [note templates](https://foambubble.github.io/foam/features/note-templates) and the `Foam: Create New Note from Template` command
+  - This becomes very powerful when combined with [note templates](https://foambubble.github.io/foam/user/features/note-templates) and the `Foam: Create New Note from Template` command
 - See your workspace as a connected graph with the `Foam: Show Graph` command
 
 ## Recipes
 
-People use Foam in different ways for different use cases, check out the [recipes](https://foambubble.github.io/foam/recipes/recipes) page for inspiration!
+People use Foam in different ways for different use cases, check out the [recipes](https://foambubble.github.io/foam/user/recipes/recipes) page for inspiration!
 
 ## Getting started
 

packages/foam-vscode/package.json

@@ -8,7 +8,7 @@
     "type": "git"
   },
   "homepage": "https://github.com/foambubble/foam",
-  "version": "0.19.1",
+  "version": "0.19.4",
   "license": "MIT",
   "publisher": "foam",
   "engines": {

packages/foam-vscode/src/core/services/markdown-link.test.ts

@@ -131,6 +131,24 @@ describe('MarkdownLink', () => {
       expect(parsed.section).toEqual('');
       expect(parsed.alias).toEqual('');
     });
+    it('should parse links with angles #1039', () => {
+      const link = parser.parse(getRandomURI(), `this is a [](<to/path.md>)`)
+        .links[0];
+      const parsed = MarkdownLink.analyzeLink(link);
+      expect(parsed.target).toEqual('to/path.md');
+      expect(parsed.section).toEqual('');
+      expect(parsed.alias).toEqual('');
+    });
+    it('should parse links with angles and sections #1039', () => {
+      const link = parser.parse(
+        getRandomURI(),
+        `this is a [](<to/path.md#section>)`
+      ).links[0];
+      const parsed = MarkdownLink.analyzeLink(link);
+      expect(parsed.target).toEqual('to/path.md');
+      expect(parsed.section).toEqual('section');
+      expect(parsed.alias).toEqual('');
+    });
   });
 
   describe('rename wikilink', () => {

packages/foam-vscode/src/core/services/markdown-link.ts

@@ -5,7 +5,7 @@ export abstract class MarkdownLink {
     /\[\[([^#|]+)?#?([^|]+)?\|?(.*)?\]\]/
   );
   private static directLinkRegex = new RegExp(
-    /\[(.*)\]\(([^#]*)?#?([^\]]+)?\)/
+    /\[(.*)\]\(<?([^#>]*)?#?([^\]>]+)?>?\)/
   );
 
   public static analyzeLink(link: ResourceLink) {

packages/foam-vscode/src/core/services/markdown-provider.test.ts

@@ -238,6 +238,35 @@ describe('Link resolution', () => {
       ws.set(noteA).set(noteB);
       expect(ws.resolveLink(noteA, noteA.links[0])).toEqual(noteB.uri);
     });
+
+    it('should support angle syntax #1039', () => {
+      const noteA = createNoteFromMarkdown(
+        'Content of note a',
+        '/path/to/note a.md'
+      );
+      const noteB = createNoteFromMarkdown(
+        'Link to [note](<./note a.md>)',
+        '/path/to/note b.md'
+      );
+      const noteC = createNoteFromMarkdown(
+        'Link to [note](./note%20a.md)',
+        '/path/to/note c.md'
+      );
+      const noteD = createNoteFromMarkdown(
+        'Link to [note](./note a.md)',
+        '/path/to/note d.md'
+      );
+
+      const ws = createTestWorkspace();
+      ws.set(noteA)
+        .set(noteB)
+        .set(noteC)
+        .set(noteD);
+
+      expect(ws.resolveLink(noteB, noteB.links[0])).toEqual(noteA.uri);
+      expect(ws.resolveLink(noteC, noteC.links[0])).toEqual(noteA.uri);
+      expect(noteD.links).toEqual([]);
+    });
   });
 });
 

packages/foam-vscode/src/features/index.ts

@@ -6,7 +6,7 @@ import orphans from './orphans';
 import placeholders from './placeholders';
 import backlinks from './backlinks';
 import hoverProvider from './hover-provider';
-import previewNavigation from './preview-navigation';
+import previewNavigation from './preview';
 import completionProvider, { completionCursorMove } from './link-completion';
 import tagCompletionProvider from './tag-completion';
 import linkDecorations from './document-decorator';

packages/foam-vscode/src/features/preview-navigation.ts

@@ -1,205 +0,0 @@
-import markdownItRegex from 'markdown-it-regex';
-import * as vscode from 'vscode';
-import { FoamFeature } from '../types';
-import { isNone, isSome } from '../utils';
-import { Foam } from '../core/model/foam';
-import { FoamWorkspace } from '../core/model/workspace';
-import { Logger } from '../core/utils/log';
-import { toVsCodeUri } from '../utils/vsc-utils';
-import { Resource } from '../core/model/note';
-import { MarkdownLink } from '../core/services/markdown-link';
-import { Range } from '../core/model/range';
-import { isEmpty } from 'lodash';
-import { getFoamVsCodeConfig } from '../services/config';
-// eslint-disable-next-line no-restricted-imports
-import { readFileSync } from 'fs';
-
-const feature: FoamFeature = {
-  activate: async (
-    _context: vscode.ExtensionContext,
-    foamPromise: Promise<Foam>
-  ) => {
-    const foam = await foamPromise;
-
-    return {
-      extendMarkdownIt: (md: markdownit) => {
-        return [
-          markdownItWithFoamTags,
-          markdownItWithNoteInclusion,
-          markdownItWithFoamLinks,
-          markdownItWithRemoveLinkReferences,
-        ].reduce((acc, extension) => extension(acc, foam.workspace), md);
-      },
-    };
-  },
-};
-
-export const CONFIG_EMBED_NOTE_IN_CONTAINER = 'preview.embedNoteInContainer';
-const refsStack: string[] = [];
-export const markdownItWithNoteInclusion = (
-  md: markdownit,
-  workspace: FoamWorkspace
-) => {
-  return md.use(markdownItRegex, {
-    name: 'include-notes',
-    regex: /!\[\[([^[\]]+?)\]\]/,
-    replace: (wikilink: string) => {
-      try {
-        const includedNote = workspace.find(wikilink);
-
-        if (!includedNote) {
-          return `![[${wikilink}]]`;
-        }
-
-        const cyclicLinkDetected = refsStack.includes(
-          includedNote.uri.path.toLocaleLowerCase()
-        );
-
-        if (!cyclicLinkDetected) {
-          refsStack.push(includedNote.uri.path.toLocaleLowerCase());
-        }
-
-        if (cyclicLinkDetected) {
-          return `<div class="foam-cyclic-link-warning">Cyclic link detected for wikilink: ${wikilink}</div>`;
-        }
-        let content = `Embed for [[${wikilink}]]`;
-        switch (includedNote.type) {
-          case 'note': {
-            const noteText = readFileSync(
-              includedNote.uri.toFsPath()
-            ).toString();
-            content = getFoamVsCodeConfig(CONFIG_EMBED_NOTE_IN_CONTAINER)
-              ? `<div class="embed-container-note">${md.render(noteText)}</div>`
-              : noteText;
-            break;
-          }
-          case 'attachment':
-            content = `
-<div class="embed-container-attachment">
-${md.renderInline('[[' + wikilink + ']]')}<br/>
-Embed for attachments is not supported
-</div>`;
-            break;
-          case 'image':
-            content = `<div class="embed-container-image">${md.render(
-              `![](${vscode.workspace.asRelativePath(
-                toVsCodeUri(includedNote.uri)
-              )})`
-            )}</div>`;
-            break;
-        }
-        const section = Resource.findSection(
-          includedNote,
-          includedNote.uri.fragment
-        );
-        if (isSome(section)) {
-          const rows = content.split('\n');
-          content = rows
-            .slice(section.range.start.line, section.range.end.line)
-            .join('\n');
-        }
-        const html = md.render(content);
-        refsStack.pop();
-        return html;
-      } catch (e) {
-        Logger.error(
-          `Error while including [[${wikilink}]] into the current document of the Preview panel`,
-          e
-        );
-        return '';
-      }
-    },
-  });
-};
-
-export const markdownItWithFoamLinks = (
-  md: markdownit,
-  workspace: FoamWorkspace
-) => {
-  return md.use(markdownItRegex, {
-    name: 'connect-wikilinks',
-    regex: /\[\[([^[\]]+?)\]\]/,
-    replace: (wikilink: string) => {
-      try {
-        const { target, alias } = MarkdownLink.analyzeLink({
-          rawText: '[[' + wikilink + ']]',
-          type: 'wikilink',
-          range: Range.create(0, 0),
-        });
-        const label = isEmpty(alias) ? target : alias;
-
-        const resource = workspace.find(target);
-        if (isNone(resource)) {
-          return getPlaceholderLink(label);
-        }
-
-        const link = vscode.workspace.asRelativePath(toVsCodeUri(resource.uri));
-        return `<a class='foam-note-link' title='${resource.title}' href='/${link}' data-href='/${link}'>${label}</a>`;
-      } catch (e) {
-        Logger.error(
-          `Error while creating link for [[${wikilink}]] in Preview panel`,
-          e
-        );
-        return getPlaceholderLink(wikilink);
-      }
-    },
-  });
-};
-
-const getPlaceholderLink = (content: string) =>
-  `<a class='foam-placeholder-link' title="Link to non-existing resource" href="javascript:void(0);">${content}</a>`;
-
-export const markdownItWithFoamTags = (
-  md: markdownit,
-  workspace: FoamWorkspace
-) => {
-  return md.use(markdownItRegex, {
-    name: 'foam-tags',
-    regex: /(?<=^|\s)(#[0-9]*[\p{L}/_-][\p{L}\p{N}/_-]*)/u,
-    replace: (tag: string) => {
-      try {
-        const resource = workspace.find(tag);
-        if (isNone(resource)) {
-          return getFoamTag(tag);
-        }
-      } catch (e) {
-        Logger.error(
-          `Error while creating link for ${tag} in Preview panel`,
-          e
-        );
-        return getFoamTag(tag);
-      }
-    },
-  });
-};
-
-const getFoamTag = (content: string) =>
-  `<span class='foam-tag'>${content}</span>`;
-
-export const markdownItWithRemoveLinkReferences = (
-  md: markdownit,
-  workspace: FoamWorkspace
-) => {
-  md.inline.ruler.before('link', 'clear-references', state => {
-    if (state.env.references) {
-      const src = state.src.toLowerCase();
-      const foamLinkRegEx = /\[\[([^[\]]+?)\]\]/g;
-      const foamLinks = [...src.matchAll(foamLinkRegEx)].map(m =>
-        m[1].toLowerCase()
-      );
-
-      Object.keys(state.env.references).forEach(refKey => {
-        // Remove all references that have corresponding wikilinks.
-        // If the markdown parser sees a reference, it will format it before
-        // we get a chance to create the wikilink.
-        if (foamLinks.includes(refKey.toLowerCase())) {
-          delete state.env.references[refKey];
-        }
-      });
-    }
-    return false;
-  });
-  return md;
-};
-
-export default feature;

packages/foam-vscode/src/features/preview/index.ts

@@ -0,0 +1,28 @@
+import * as vscode from 'vscode';
+import { FoamFeature } from '../../types';
+import { Foam } from '../../core/model/foam';
+import markdownItFoamTags from './tag-highlight';
+import markdownItWikilinkNavigation from './wikilink-navigation';
+import markdownItRemoveLinkReferences from './remove-wikilink-references';
+import markdownItWikilinkEmbed from './wikilink-embed';
+
+const feature: FoamFeature = {
+  activate: async (
+    _context: vscode.ExtensionContext,
+    foamPromise: Promise<Foam>
+  ) => {
+    const foam = await foamPromise;
+
+    return {
+      extendMarkdownIt: (md: markdownit) => {
+        return [
+          markdownItWikilinkEmbed,
+          markdownItFoamTags,
+          markdownItWikilinkNavigation,
+          markdownItRemoveLinkReferences,
+        ].reduce((acc, extension) => extension(acc, foam.workspace), md);
+      },
+    };
+  },
+};
+export default feature;

packages/foam-vscode/src/features/preview/remove-wikilink-references.ts

@@ -0,0 +1,29 @@
+import { FoamWorkspace } from '../../core/model/workspace';
+
+export const markdownItRemoveLinkReferences = (
+  md: markdownit,
+  workspace: FoamWorkspace
+) => {
+  md.inline.ruler.before('link', 'clear-references', state => {
+    if (state.env.references) {
+      const src = state.src.toLowerCase();
+      const foamLinkRegEx = /\[\[([^[\]]+?)\]\]/g;
+      const foamLinks = [...src.matchAll(foamLinkRegEx)].map(m =>
+        m[1].toLowerCase()
+      );
+
+      Object.keys(state.env.references).forEach(refKey => {
+        // Remove all references that have corresponding wikilinks.
+        // If the markdown parser sees a reference, it will format it before
+        // we get a chance to create the wikilink.
+        if (foamLinks.includes(refKey.toLowerCase())) {
+          delete state.env.references[refKey];
+        }
+      });
+    }
+    return false;
+  });
+  return md;
+};
+
+export default markdownItRemoveLinkReferences;

packages/foam-vscode/src/features/preview/tag-highlight.spec.ts

@@ -0,0 +1,19 @@
+import MarkdownIt from 'markdown-it';
+import { FoamWorkspace } from '../../core/model/workspace';
+import markdownItFoamTags from './tag-highlight';
+
+describe('Stylable tag generation in preview', () => {
+  const md = markdownItFoamTags(MarkdownIt(), new FoamWorkspace());
+
+  it('transforms a string containing multiple tags to a stylable html element', () => {
+    expect(md.render(`Lorem #ipsum dolor #sit`)).toMatch(
+      `<p>Lorem <span class='foam-tag'>#ipsum</span> dolor <span class='foam-tag'>#sit</span></p>`
+    );
+  });
+
+  it('transforms a string containing a tag with dash', () => {
+    expect(md.render(`Lorem ipsum dolor #si-t`)).toMatch(
+      `<p>Lorem ipsum dolor <span class='foam-tag'>#si-t</span></p>`
+    );
+  });
+});

packages/foam-vscode/src/features/preview/tag-highlight.ts

@@ -0,0 +1,33 @@
+import markdownItRegex from 'markdown-it-regex';
+import { isNone } from '../../utils';
+import { FoamWorkspace } from '../../core/model/workspace';
+import { Logger } from '../../core/utils/log';
+
+export const markdownItFoamTags = (
+  md: markdownit,
+  workspace: FoamWorkspace
+) => {
+  return md.use(markdownItRegex, {
+    name: 'foam-tags',
+    regex: /(?<=^|\s)(#[0-9]*[\p{L}/_-][\p{L}\p{N}/_-]*)/u,
+    replace: (tag: string) => {
+      try {
+        const resource = workspace.find(tag);
+        if (isNone(resource)) {
+          return getFoamTag(tag);
+        }
+      } catch (e) {
+        Logger.error(
+          `Error while creating link for ${tag} in Preview panel`,
+          e
+        );
+        return getFoamTag(tag);
+      }
+    },
+  });
+};
+
+const getFoamTag = (content: string) =>
+  `<span class='foam-tag'>${content}</span>`;
+
+export default markdownItFoamTags;

packages/foam-vscode/src/features/preview/wikilink-embed.spec.ts

@@ -1,81 +1,17 @@
 import MarkdownIt from 'markdown-it';
-import { createMarkdownParser } from '../core/services/markdown-parser';
-import { FoamWorkspace } from '../core/model/workspace';
-import { createTestNote } from '../test/test-utils';
+import { FoamWorkspace } from '../../core/model/workspace';
+import { createMarkdownParser } from '../../core/services/markdown-parser';
 import {
   createFile,
   deleteFile,
-  getUriInWorkspace,
   withModifiedFoamConfiguration,
-} from '../test/test-utils-vscode';
-import {
+} from '../../test/test-utils-vscode';
+import markdownItWikilinkEmbed, {
   CONFIG_EMBED_NOTE_IN_CONTAINER,
-  markdownItWithFoamLinks,
-  markdownItWithFoamTags,
-  markdownItWithNoteInclusion,
-  markdownItWithRemoveLinkReferences,
-} from './preview-navigation';
+} from './wikilink-embed';
 
 const parser = createMarkdownParser();
 
-describe('Link generation in preview', () => {
-  const noteA = createTestNote({
-    uri: './path/to/note-a.md',
-    // TODO: this should really just be the workspace folder, use that once #806 is fixed
-    root: getUriInWorkspace('just-a-ref.md'),
-    title: 'My note title',
-    links: [{ slug: 'placeholder' }],
-  });
-  const ws = new FoamWorkspace().set(noteA);
-
-  const md = [
-    markdownItWithFoamLinks,
-    markdownItWithRemoveLinkReferences,
-  ].reduce((acc, extension) => extension(acc, ws), MarkdownIt());
-
-  it('generates a link to a note', () => {
-    expect(md.render(`[[note-a]]`)).toEqual(
-      `<p><a class='foam-note-link' title='${noteA.title}' href='/path/to/note-a.md' data-href='/path/to/note-a.md'>note-a</a></p>\n`
-    );
-  });
-
-  it('generates a link to a placeholder resource', () => {
-    expect(md.render(`[[placeholder]]`)).toEqual(
-      `<p><a class='foam-placeholder-link' title="Link to non-existing resource" href="javascript:void(0);">placeholder</a></p>\n`
-    );
-  });
-
-  it('generates a placeholder link to an unknown slug', () => {
-    expect(md.render(`[[random-text]]`)).toEqual(
-      `<p><a class='foam-placeholder-link' title="Link to non-existing resource" href="javascript:void(0);">random-text</a></p>\n`
-    );
-  });
-
-  it('generates a wikilink even when there is a link reference', () => {
-    const note = `[[note-a]]
-    [note-a]: <note-a.md> "Note A"`;
-    expect(md.render(note)).toEqual(
-      `<p><a class='foam-note-link' title='${noteA.title}' href='/path/to/note-a.md' data-href='/path/to/note-a.md'>note-a</a>\n[note-a]: &lt;note-a.md&gt; &quot;Note A&quot;</p>\n`
-    );
-  });
-});
-
-describe('Stylable tag generation in preview', () => {
-  const md = markdownItWithFoamTags(MarkdownIt(), new FoamWorkspace());
-
-  it('transforms a string containing multiple tags to a stylable html element', () => {
-    expect(md.render(`Lorem #ipsum dolor #sit`)).toMatch(
-      `<p>Lorem <span class='foam-tag'>#ipsum</span> dolor <span class='foam-tag'>#sit</span></p>`
-    );
-  });
-
-  it('transforms a string containing a tag with dash', () => {
-    expect(md.render(`Lorem ipsum dolor #si-t`)).toMatch(
-      `<p>Lorem ipsum dolor <span class='foam-tag'>#si-t</span></p>`
-    );
-  });
-});
-
 describe('Displaying included notes in preview', () => {
   it('should render an included note in flat mode', async () => {
     const note = await createFile('This is the text of note A', [
@@ -87,7 +23,7 @@ describe('Displaying included notes in preview', () => {
       CONFIG_EMBED_NOTE_IN_CONTAINER,
       false,
       () => {
-        const md = markdownItWithNoteInclusion(MarkdownIt(), ws);
+        const md = markdownItWikilinkEmbed(MarkdownIt(), ws);
 
         expect(
           md.render(`This is the root node. 
@@ -114,7 +50,7 @@ describe('Displaying included notes in preview', () => {
       CONFIG_EMBED_NOTE_IN_CONTAINER,
       true,
       () => {
-        const md = markdownItWithNoteInclusion(MarkdownIt(), ws);
+        const md = markdownItWikilinkEmbed(MarkdownIt(), ws);
 
         const res = md.render(`This is the root node. ![[note-a]]`);
         expect(res).toContain('This is the root node');
@@ -143,7 +79,7 @@ This is the third section of note D
     );
     const parser = createMarkdownParser([]);
     const ws = new FoamWorkspace().set(parser.parse(note.uri, note.content));
-    const md = markdownItWithNoteInclusion(MarkdownIt(), ws);
+    const md = markdownItWikilinkEmbed(MarkdownIt(), ws);
 
     await withModifiedFoamConfiguration(
       CONFIG_EMBED_NOTE_IN_CONTAINER,
@@ -166,7 +102,7 @@ This is the third section of note D
   });
 
   it('should fallback to the bare text when the note is not found', () => {
-    const md = markdownItWithNoteInclusion(MarkdownIt(), new FoamWorkspace());
+    const md = markdownItWikilinkEmbed(MarkdownIt(), new FoamWorkspace());
 
     expect(md.render(`This is the root node. ![[non-existing-note]]`)).toMatch(
       `<p>This is the root node. ![[non-existing-note]]</p>`
@@ -185,7 +121,7 @@ This is the third section of note D
     const ws = new FoamWorkspace()
       .set(parser.parse(noteA.uri, noteA.content))
       .set(parser.parse(noteB.uri, noteB.content));
-    const md = markdownItWithNoteInclusion(MarkdownIt(), ws);
+    const md = markdownItWikilinkEmbed(MarkdownIt(), ws);
     const res = md.render(noteBText);
 
     expect(res).toContain('This is the text of note B which includes');

packages/foam-vscode/src/features/preview/wikilink-embed.ts

@@ -0,0 +1,89 @@
+import markdownItRegex from 'markdown-it-regex';
+import * as vscode from 'vscode';
+import { isSome } from '../../utils';
+import { FoamWorkspace } from '../../core/model/workspace';
+import { Logger } from '../../core/utils/log';
+import { toVsCodeUri } from '../../utils/vsc-utils';
+import { Resource } from '../../core/model/note';
+import { getFoamVsCodeConfig } from '../../services/config';
+// eslint-disable-next-line no-restricted-imports
+import { readFileSync } from 'fs';
+
+export const CONFIG_EMBED_NOTE_IN_CONTAINER = 'preview.embedNoteInContainer';
+const refsStack: string[] = [];
+
+export const markdownItWikilinkEmbed = (
+  md: markdownit,
+  workspace: FoamWorkspace
+) => {
+  return md.use(markdownItRegex, {
+    name: 'embed-wikilinks',
+    regex: /!\[\[([^[\]]+?)\]\]/,
+    replace: (wikilink: string) => {
+      try {
+        const includedNote = workspace.find(wikilink);
+
+        if (!includedNote) {
+          return `![[${wikilink}]]`;
+        }
+
+        const cyclicLinkDetected = refsStack.includes(
+          includedNote.uri.path.toLocaleLowerCase()
+        );
+
+        if (!cyclicLinkDetected) {
+          refsStack.push(includedNote.uri.path.toLocaleLowerCase());
+        }
+
+        if (cyclicLinkDetected) {
+          return `<div class="foam-cyclic-link-warning">Cyclic link detected for wikilink: ${wikilink}</div>`;
+        }
+        let content = `Embed for [[${wikilink}]]`;
+        switch (includedNote.type) {
+          case 'note': {
+            const noteText = readFileSync(
+              includedNote.uri.toFsPath()
+            ).toString();
+            content = getFoamVsCodeConfig(CONFIG_EMBED_NOTE_IN_CONTAINER)
+              ? `<div class="embed-container-note">${md.render(noteText)}</div>`
+              : noteText;
+            break;
+          }
+          case 'attachment':
+            content = `
+<div class="embed-container-attachment">
+${md.renderInline('[[' + wikilink + ']]')}<br/>
+Embed for attachments is not supported
+</div>`;
+            break;
+          case 'image':
+            content = `<div class="embed-container-image">${md.render(
+              `![](${md.normalizeLink(includedNote.uri.path)})`
+            )}</div>`;
+            break;
+        }
+        const section = Resource.findSection(
+          includedNote,
+          includedNote.uri.fragment
+        );
+        if (isSome(section)) {
+          const rows = content.split('\n');
+          content = rows
+            .slice(section.range.start.line, section.range.end.line)
+            .join('\n');
+        }
+        const html = md.render(content);
+        refsStack.pop();
+        return html;
+      } catch (e) {
+        Logger.error(
+          `Error while including [[${wikilink}]] into the current document of the Preview panel`,
+          e
+        );
+        return '';
+      }
+    },
+  });
+};
+
+export default markdownItWikilinkEmbed;

packages/foam-vscode/src/features/preview/wikilink-navigation.spec.ts

@@ -0,0 +1,51 @@
+import MarkdownIt from 'markdown-it';
+import { createMarkdownParser } from '../../core/services/markdown-parser';
+import { FoamWorkspace } from '../../core/model/workspace';
+import { createTestNote } from '../../test/test-utils';
+import { getUriInWorkspace } from '../../test/test-utils-vscode';
+import markdownItWikilinkNavigation from './wikilink-navigation';
+import markdownItRemoveLinkReferences from './remove-wikilink-references';
+
+const parser = createMarkdownParser();
+
+describe('Link generation in preview', () => {
+  const noteA = createTestNote({
+    uri: './path/to/note-a.md',
+    // TODO: this should really just be the workspace folder, use that once #806 is fixed
+    root: getUriInWorkspace('just-a-ref.md'),
+    title: 'My note title',
+    links: [{ slug: 'placeholder' }],
+  });
+  const ws = new FoamWorkspace().set(noteA);
+
+  const md = [
+    markdownItWikilinkNavigation,
+    markdownItRemoveLinkReferences,
+  ].reduce((acc, extension) => extension(acc, ws), MarkdownIt());
+
+  it('generates a link to a note', () => {
+    expect(md.render(`[[note-a]]`)).toEqual(
+      `<p><a class='foam-note-link' title='${noteA.title}' href='/path/to/note-a.md' data-href='/path/to/note-a.md'>note-a</a></p>\n`
+    );
+  });
+
+  it('generates a link to a placeholder resource', () => {
+    expect(md.render(`[[placeholder]]`)).toEqual(
+      `<p><a class='foam-placeholder-link' title="Link to non-existing resource" href="javascript:void(0);">placeholder</a></p>\n`
+    );
+  });
+
+  it('generates a placeholder link to an unknown slug', () => {
+    expect(md.render(`[[random-text]]`)).toEqual(
+      `<p><a class='foam-placeholder-link' title="Link to non-existing resource" href="javascript:void(0);">random-text</a></p>\n`
+    );
+  });
+
+  it('generates a wikilink even when there is a link reference', () => {
+    const note = `[[note-a]]
+    [note-a]: <note-a.md> "Note A"`;
+    expect(md.render(note)).toEqual(
+      `<p><a class='foam-note-link' title='${noteA.title}' href='/path/to/note-a.md' data-href='/path/to/note-a.md'>note-a</a>\n[note-a]: &lt;note-a.md&gt; &quot;Note A&quot;</p>\n`
+    );
+  });
+});