v0.20.0

* Added create-note command and refactored some template code

* Added tests

* Added uri resolution logic across multiple folders

* Deprecating create-note-from-default-template command, it is now replaced by the new and more flexible create-note command (which still has the same defaults)

.all-contributorsrc

@@ -598,6 +598,349 @@
       "contributions": [
         "code"
       ]
+    },
+    {
+      "login": "joeltjames",
+      "name": "Joel James",
+      "avatar_url": "https://avatars.githubusercontent.com/u/3732400?v=4",
+      "profile": "https://github.com/joeltjames",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "ryo33",
+      "name": "Hashiguchi Ryo",
+      "avatar_url": "https://avatars.githubusercontent.com/u/8780513?v=4",
+      "profile": "https://www.ryo33.com",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "movermeyer",
+      "name": "Michael Overmeyer",
+      "avatar_url": "https://avatars.githubusercontent.com/u/1459385?v=4",
+      "profile": "https://movermeyer.com",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "derrickqin",
+      "name": "Derrick Qin",
+      "avatar_url": "https://avatars.githubusercontent.com/u/3038111?v=4",
+      "profile": "https://github.com/derrickqin",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "zomars",
+      "name": "Omar López",
+      "avatar_url": "https://avatars.githubusercontent.com/u/3504472?v=4",
+      "profile": "https://www.linkedin.com/in/zomars/",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "RobinKing",
+      "name": "Robin King",
+      "avatar_url": "https://avatars.githubusercontent.com/u/1583193?v=4",
+      "profile": "http://robincn.com",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "dheepakg",
+      "name": "Dheepak ",
+      "avatar_url": "https://avatars.githubusercontent.com/u/4730170?v=4",
+      "profile": "http://twitter.com/deegovee",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "daniel-vera-g",
+      "name": "Daniel VG",
+      "avatar_url": "https://avatars.githubusercontent.com/u/28257108?v=4",
+      "profile": "https://github.com/daniel-vera-g",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "Barabazs",
+      "name": "Barabas",
+      "avatar_url": "https://avatars.githubusercontent.com/u/31799121?v=4",
+      "profile": "https://github.com/Barabazs",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "EngincanV",
+      "name": "Engincan VESKE",
+      "avatar_url": "https://avatars.githubusercontent.com/u/43685404?v=4",
+      "profile": "http://enginveske@gmail.com",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "pderaaij",
+      "name": "Paul de Raaij",
+      "avatar_url": "https://avatars.githubusercontent.com/u/495374?v=4",
+      "profile": "http://www.paulderaaij.nl",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "bronson",
+      "name": "Scott Bronson",
+      "avatar_url": "https://avatars.githubusercontent.com/u/1776?v=4",
+      "profile": "https://github.com/bronson",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "rafo",
+      "name": "Rafael Riedel",
+      "avatar_url": "https://avatars.githubusercontent.com/u/41793?v=4",
+      "profile": "http://rafaelriedel.de",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "Pearcekieser",
+      "name": "Pearcekieser",
+      "avatar_url": "https://avatars.githubusercontent.com/u/5055971?v=4",
+      "profile": "https://github.com/Pearcekieser",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "theowenyoung",
+      "name": "Owen Young",
+      "avatar_url": "https://avatars.githubusercontent.com/u/62473795?v=4",
+      "profile": "https://github.com/theowenyoung",
+      "contributions": [
+        "doc",
+        "content"
+      ]
+    },
+    {
+      "login": "ksprashu",
+      "name": "Prashanth Subrahmanyam",
+      "avatar_url": "https://avatars.githubusercontent.com/u/476729?v=4",
+      "profile": "http://www.prashu.com",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "JonasSprenger",
+      "name": "Jonas SPRENGER",
+      "avatar_url": "https://avatars.githubusercontent.com/u/25108895?v=4",
+      "profile": "https://github.com/JonasSprenger",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "Laptop765",
+      "name": "Paul",
+      "avatar_url": "https://avatars.githubusercontent.com/u/1468359?v=4",
+      "profile": "https://github.com/Laptop765",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "eltociear",
+      "name": "Ikko Ashimine",
+      "avatar_url": "https://avatars.githubusercontent.com/u/22633385?v=4",
+      "profile": "https://bandism.net/",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "memeplex",
+      "name": "memeplex",
+      "avatar_url": "https://avatars.githubusercontent.com/u/2845433?v=4",
+      "profile": "https://github.com/memeplex",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "AndreiD049",
+      "name": "AndreiD049",
+      "avatar_url": "https://avatars.githubusercontent.com/u/52671223?v=4",
+      "profile": "https://github.com/AndreiD049",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "iam-yan",
+      "name": "Yan",
+      "avatar_url": "https://avatars.githubusercontent.com/u/48427014?v=4",
+      "profile": "https://github.com/iam-yan",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "jimt",
+      "name": "Jim Tittsler",
+      "avatar_url": "https://avatars.githubusercontent.com/u/180326?v=4",
+      "profile": "https://WikiEducator.org/User:JimTittsler",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "MalcolmMielle",
+      "name": "Malcolm Mielle",
+      "avatar_url": "https://avatars.githubusercontent.com/u/4457840?v=4",
+      "profile": "http://malcolmmielle.wordpress.com/",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "veesar",
+      "name": "Veesar",
+      "avatar_url": "https://avatars.githubusercontent.com/u/74916913?v=4",
+      "profile": "https://snippets.page/",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "bentongxyz",
+      "name": "bentongxyz",
+      "avatar_url": "https://avatars.githubusercontent.com/u/60358804?v=4",
+      "profile": "https://github.com/bentongxyz",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "techCarpenter",
+      "name": "Brian DeVries",
+      "avatar_url": "https://avatars.githubusercontent.com/u/42778030?v=4",
+      "profile": "https://brianjdevries.com",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "cliffordfajardo",
+      "name": "Clifford Fajardo ",
+      "avatar_url": "https://avatars.githubusercontent.com/u/6743796?v=4",
+      "profile": "http://Cliffordfajardo.com",
+      "contributions": [
+        "tool"
+      ]
+    },
+    {
+      "login": "chrisUsick",
+      "name": "Chris Usick",
+      "avatar_url": "https://avatars.githubusercontent.com/u/6589365?v=4",
+      "profile": "http://cu-dev.ca",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "josephdecock",
+      "name": "Joe DeCock",
+      "avatar_url": "https://avatars.githubusercontent.com/u/1145533?v=4",
+      "profile": "https://github.com/josephdecock",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "drewtyler",
+      "name": "Drew Tyler",
+      "avatar_url": "https://avatars.githubusercontent.com/u/5640816?v=4",
+      "profile": "http://www.drewtyler.com",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "Lauviah0622",
+      "name": "Lauviah0622",
+      "avatar_url": "https://avatars.githubusercontent.com/u/43416399?v=4",
+      "profile": "https://github.com/Lauviah0622",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "joshdover",
+      "name": "Josh Dover",
+      "avatar_url": "https://avatars.githubusercontent.com/u/1813008?v=4",
+      "profile": "https://www.elastic.co/elastic-agent",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "phelma",
+      "name": "Phil Helm",
+      "avatar_url": "https://avatars.githubusercontent.com/u/4057948?v=4",
+      "profile": "http://phelm.co.uk",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "lingyv-li",
+      "name": "Larry Li",
+      "avatar_url": "https://avatars.githubusercontent.com/u/8937944?v=4",
+      "profile": "https://github.com/lingyv-li",
+      "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"
+      ]
+    },
+    {
+      "login": "dmurph",
+      "name": "Daniel Murphy",
+      "avatar_url": "https://avatars.githubusercontent.com/u/294026?v=4",
+      "profile": "http://www.dmurph.com",
+      "contributions": [
+        "code"
+      ]
     }
   ],
   "contributorsPerLine": 7,

.eslintrc.json

@@ -1,20 +1,60 @@
 {
-    "root": true,
-    "parser": "@typescript-eslint/parser",
-    "parserOptions": {
-        "ecmaVersion": 6,
-        "sourceType": "module"
-    },
-    "plugins": [
-        "@typescript-eslint"
-    ],
-    "rules": {
-        "@typescript-eslint/class-name-casing": "warn",
-        "@typescript-eslint/semi": "warn",
-        "curly": "warn",
-        "eqeqeq": "warn",
-        "no-throw-literal": "warn",
-        "semi": "off",
-        "require-await": "warn"
+  "root": true,
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": 6,
+    "sourceType": "module"
+  },
+  "env": { "node": true, "es6": true },
+  "plugins": ["@typescript-eslint", "import", "jest"],
+  "extends": [
+    "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
+    "plugin:import/recommended",
+    "plugin:import/typescript",
+    "plugin:jest/recommended"
+  ],
+  "rules": {
+    "no-use-before-define": "off",
+    "@typescript-eslint/no-use-before-define": "off",
+    "@typescript-eslint/no-explicit-any": "off",
+    "@typescript-eslint/no-non-null-assertion": "off",
+    "@typescript-eslint/explicit-function-return-type": "off",
+    "@typescript-eslint/interface-name-prefix": "off",
+    "import/no-extraneous-dependencies": [
+      "error",
+      {
+        "devDependencies": ["**/src/test/**", "**/src/**/*{test,spec}.ts"]
+      }
+    ]
+  },
+  "overrides": [
+    {
+      // Restrict usage of fs module outside tests to keep foam compatible with the browser
+      "files": ["**/src/**"],
+      "excludedFiles": ["**/src/test/**", "**/src/**/*{test,spec}.ts"],
+      "rules": {
+        "no-restricted-imports": [
+          "error",
+          {
+            "name": "fs",
+            "message": "Extension code must not rely Node.js filesystem, use vscode.workspace.fs instead."
+          }
+        ]
+      }
     }
+  ],
+  "settings": {
+    "import/core-modules": ["vscode"],
+    "import/parsers": {
+      "@typescript-eslint/parser": [".ts", ".tsx"]
+    },
+    "import/resolver": {
+      "typescript": {
+        "alwaysTryTypes": true
+      }
+    }
+  },
+  "ignorePatterns": ["**/core/common/**", "*.js"],
+  "reportUnusedDisableDirectives": true
 }

.github/ISSUE_TEMPLATE/bug.md

@@ -1,23 +0,0 @@
----
-name: Bug report
-about: Create a report to help us be foamier
-labels: bug
----
-
-- Foam version: <!-- Check in the VSCode extension tab. -->
-- Platform: Windows | Mac | Linux
-- Issue occur on the [foam template](https://github.com/foambubble/foam-template) repo: Yes | No
-
-**Summary**
-<!-- A clear and concise description of what the bug is.-->
-
-**Steps to reproduce**
-1.
-2.
-
-**Additional information**
-<!-- Add any other context about the problem here. -->
-Feel free to attach any of the following that might help with debugging the issue:
-- screenshots
-- a zip with a minimal repo to reproduce the issue
-- the Foam log in VsCode (see [instructions](https://github.com/foambubble/foam/blob/master/docs/foam-logging-in-vscode.md))

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,97 @@
+name: 'Bug report'
+description: Create a report to help us improve
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for reporting an issue :pray:.
+
+        This issue tracker is for reporting bugs found in `foam` (https://github.com/foambubble).
+        If you have a question about how to achieve something and are struggling, please post a question
+        inside of either of the following places:
+          - Foam's Discussion's tab: https://github.com/foambubble/foam/discussions
+          - Foam's Discord channel: https://foambubble.github.io/join-discord/g
+          
+
+        Before submitting a new bug/issue, please check the links below to see if there is a solution or question posted there already:
+         - Foam's Issue's tab: https://github.com/foambubble/foam/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc
+         - Foam's closed issues tab: https://github.com/foambubble/foam/issues?q=is%3Aissue+sort%3Aupdated-desc+is%3Aclosed
+         - Foam's Discussions tab: https://github.com/foambubble/foam/discussions
+
+        The more information you fill in, the better the community can help you.
+  - type: textarea
+    id: description
+    attributes:
+      label: Describe the bug
+      description: Provide a clear and concise description of the challenge you are running into.
+    validations:
+      required: true
+  - type: input
+    id: reproducible_example
+    attributes:
+      label: Small Reproducible Example
+      description: |
+        Note:
+        - Your bug will may get fixed much faster if there is a way we can somehow run your example or code.
+        - To create a shareable example, consider cloning the following Foam Github template: https://github.com/foambubble/foam-template
+        - Please read these tips for providing a minimal example: https://stackoverflow.com/help/mcve.
+      placeholder: |
+        e.g. Link to your github repository containing a small reproducible example that the team can run.
+    validations:
+      required: false
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to Reproduce the Bug or Issue
+      description: Describe the steps we have to take to reproduce the behavior.
+      placeholder: |
+        1. Go to '...'
+        2. Click on '....'
+        3. Scroll down to '....'
+        4. See error
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: Provide a clear and concise description of what you expected to happen.
+      placeholder: |
+        As a user, I expected ___ behavior but i am seeing ___
+    validations:
+      required: true
+  - type: textarea
+    id: screenshots_or_videos
+    attributes:
+      label: Screenshots or Videos
+      description: |
+        If applicable, add screenshots or a video to help explain your problem.
+        For more information on the supported file image/file types and the file size limits, please refer
+        to the following link: https://docs.github.com/en/github/writing-on-github/working-with-advanced-formatting/attaching-files
+      placeholder: |
+        You can drag your video or image files inside of this editor ↓
+  - type: input
+    id: os
+    attributes:
+      label: Operating System Version
+      description: What opearting system are you using?
+      placeholder: |
+        - OS: [e.g. macOS, Windows, Linux]
+    validations:
+      required: true
+  - type: input
+    id: vscode_version 
+    attributes:
+      label: Visual Studio Code Version
+      description: |
+        What version of Visual Studio Code are you using?
+        How to find Visual Studio Code Version: https://code.visualstudio.com/docs/supporting/FAQ#_how-do-i-find-the-version
+    validations:
+      required: true
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: | 
+        Add any other context about the problem here.
+        The Foam log output for VSCode can be found here: https://github.com/foambubble/foam/blob/master/docs/features/foam-logging-in-vscode.md

.github/ISSUE_TEMPLATE/feature.md

@@ -1,6 +0,0 @@
----
-name: Feature request
-about: Suggest an idea to help us be foamier
----
-
-<!-- Describe the feature you'd like. -->

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,42 @@
+name: Feature request
+description: Suggest an idea for the `Foam` project
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This issue form is for requesting features only!
+        If you want to report a bug, please use the [bug report](https://github.com/foambubble/foam/issues/new?assignees=&labels=&template=bug_report.yml) form.
+  - type: textarea
+    validations:
+      required: true
+    attributes:
+      label: Is your feature request related to a problem? Please describe.
+      description: A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+  - type: textarea
+    validations:
+      required: true
+    attributes:
+      label: Describe the solution you'd like
+      description: A clear and concise description of what you want to happen.
+      placeholder: |
+        As a user, I expected ___ behavior but ___ ...
+        
+        Ideal Steps I would like to see:
+        1. Go to '...'
+        2. Click on '....'
+        3. ....
+  - type: textarea
+    validations:
+      required: true
+    attributes:
+      label: Describe alternatives you've considered
+      description: A clear and concise description of any alternative solutions or features you've considered.
+  - type: textarea
+    attributes:
+      label: Screenshots or Videos
+      description: |
+        If applicable, add screenshots or a video to help explain your problem.
+        For more information on the supported file image/file types and the file size limits, please refer
+        to the following link: https://docs.github.com/en/github/writing-on-github/working-with-advanced-formatting/attaching-files
+      placeholder: |
+        You can drag your video or image files inside of this editor ↓

.github/workflows/ci.yml

@@ -3,30 +3,30 @@ name: CI
 on:
   push:
     branches:
-      - '**'
-  # The following will also make the workflow run on all PRs, internal and external.
-  # This would create duplicate runs, that we are skipping by adding the "if" to the jobs below.
-  # See https://github.community/t/duplicate-checks-on-push-and-pull-request-simultaneous-event/18012
+      - master
   pull_request:
+    branches:
+      - master
 
 jobs:
   lint:
     name: Lint
     runs-on: ubuntu-18.04
-    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != 'foambubble/foam'
+    timeout-minutes: 10
     steps:
       - uses: actions/checkout@v1
       - name: Setup Node
         uses: actions/setup-node@v1
         with:
           node-version: '12'
-      - name: Restore Dependencies
+      - name: Restore Dependencies and VS Code test instance
         uses: actions/cache@v2
         with:
           path: |
             node_modules
             */*/node_modules
-          key: ${{ runner.os }}-${{ hashFiles('**/yarn.lock') }}
+            packages/foam-vscode/.vscode-test
+          key: ${{ runner.os }}-${{ hashFiles('**/yarn.lock', 'packages/foam-vscode/src/test/run-tests.ts') }}-${{ secrets.CACHE_VERSION }}
       - name: Install Dependencies
         run: yarn
       - name: Check Lint Rules
@@ -38,27 +38,28 @@ jobs:
       matrix:
         os: [macos-10.15, ubuntu-18.04, windows-2019]
     runs-on: ${{ matrix.os }}
-    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != 'foambubble/foam'
     env:
       OS: ${{ matrix.os }}
+    timeout-minutes: 15
     steps:
       - uses: actions/checkout@v1
       - name: Setup Node
         uses: actions/setup-node@v1
         with:
           node-version: '12'
-      - name: Restore Dependencies
+      - name: Restore Dependencies and VS Code test instance
         uses: actions/cache@v2
         with:
           path: |
             node_modules
             */*/node_modules
-          key: ${{ runner.os }}-${{ hashFiles('**/yarn.lock') }}
+            packages/foam-vscode/.vscode-test
+          key: ${{ runner.os }}-${{ hashFiles('**/yarn.lock', 'packages/foam-vscode/src/test/run-tests.ts') }}-${{ secrets.CACHE_VERSION }}
       - name: Install Dependencies
         run: yarn
       - name: Build Packages
         run: yarn build
       - name: Run Tests
-        uses: GabrielBB/xvfb-action@v1.0
+        uses: GabrielBB/xvfb-action@v1.4
         with:
-          run: yarn test
+          run: yarn test --stream

.gitignore

@@ -9,3 +9,4 @@ dist
 docs/_site
 docs/.sass-cache
 docs/.jekyll-metadata
+.test-workspace

.vscode/launch.json

@@ -3,74 +3,51 @@
 // Hover to view descriptions of existing attributes.
 // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
 {
-	"version": "0.2.0",
-	"configurations": [
-		{
-			"type": "node",
-			"name": "vscode-jest-tests",
-			"request": "launch",
-			"runtimeArgs": ["workspace", "foam-core", "run", "test"], // ${yarnWorkspaceName} is what we're missing
-			"args": [
-					"--runInBand"
-			],
-			"runtimeExecutable": "yarn",
-			"console": "integratedTerminal",
-			"internalConsoleOptions": "neverOpen",
-			"disableOptimisticBPs": true,
-	},
-		{
-			"name": "Debug Jest Tests",
-			"type": "node",
-			"request": "launch",
-			"runtimeArgs": [
-				"--inspect-brk",
-				"${workspaceRoot}/node_modules/.bin/tsdx",
-				"test",
-			],
-			"console": "integratedTerminal",
-			"cwd": "${workspaceFolder}/packages/foam-core",
-			"internalConsoleOptions": "neverOpen"
-	},
-		{
-			"name": "Run VSCode Extension",
-			"type": "extensionHost",
-			"request": "launch",
-			"runtimeExecutable": "${execPath}",
-			"args": [
-				"--extensionDevelopmentPath=${workspaceFolder}/packages/foam-vscode"
-			],
-			"outFiles": [
-				"${workspaceFolder}/packages/foam-vscode/out/**/*.js"
-			],
-			"preLaunchTask": "${defaultBuildTask}"
-		},
-
-		// @NOTE: This task is broken. VSCode e2e tests are currently disabled
-		// due to incompability of jest and mocha inside a typescript monorepo
-		// Contributions to fix this are welcome!
-		{
-			"name": "Test VSCode Extension",
-			"type": "extensionHost",
-			"request": "launch",
-			"runtimeExecutable": "${execPath}",
-			"args": [
-				"--extensionDevelopmentPath=${workspaceFolder}/packages/foam-vscode",
-				"--extensionTestsPath=${workspaceFolder}/packages/foam-vscode/out/test/suite/index"
-			],
-			"outFiles": [
-				"${workspaceFolder}/packages/foam-vscode/out/test/**/*.js"
-			],
-			"preLaunchTask": "${defaultBuildTask}"
-		},
-		{
-			"name": "Test Core",
-			"type": "node",
-			"request": "launch",
-			"program": "${workspaceFolder}/node_modules/tsdx/dist/index.js",
-			"args": ["test"],
-			"cwd": "${workspaceFolder}/packages/foam-core",
-			"internalConsoleOptions": "openOnSessionStart",
-			"preLaunchTask": "${defaultBuildTask}"
-		}
-	]
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug Jest Tests",
+      "type": "extensionHost",
+      "request": "launch",
+      "args": [
+        "${workspaceFolder}/packages/foam-vscode/.test-workspace",
+        "--disable-extensions",
+        "--disable-workspace-trust",
+        "--extensionDevelopmentPath=${workspaceFolder}/packages/foam-vscode",
+        "--extensionTestsPath=${workspaceFolder}/packages/foam-vscode/out/test/suite"
+      ],
+      "outFiles": [
+        "${workspaceFolder}/packages/foam-vscode/out/**/*.js"
+      ],
+      "preLaunchTask": "${defaultBuildTask}"
+    },
+    {
+      "name": "Run VSCode Extension",
+      "type": "extensionHost",
+      "request": "launch",
+      "runtimeExecutable": "${execPath}",
+      "args": [
+        "--extensionDevelopmentPath=${workspaceFolder}/packages/foam-vscode"
+      ],
+      "outFiles": [
+        "${workspaceFolder}/packages/foam-vscode/out/**/*.js"
+      ],
+      "preLaunchTask": "${defaultBuildTask}"
+    },
+    {
+      "type": "node",
+      "name": "vscode-jest-tests",
+      "request": "launch",
+      "console": "integratedTerminal",
+      "internalConsoleOptions": "neverOpen",
+      "disableOptimisticBPs": true,
+      "cwd": "${workspaceFolder}/packages/foam-vscode",
+      "runtimeExecutable": "yarn",
+      "args": [
+        "jest",
+        "--runInBand",
+        "--watchAll=false"
+      ]
+    }
+  ]
 }

.vscode/settings.json

@@ -12,15 +12,21 @@
   },
   // Turn off tsc task auto detection since we have the necessary tasks as npm scripts
   "typescript.tsc.autoDetect": "off",
+  "foam.edit.linkReferenceDefinitions": "withExtensions",
   "foam.files.ignore": [
     "**/.vscode/**/*",
     "**/_layouts/**/*",
     "**/_site/**/*",
-    "**/node_modules/**/*"
+    "**/node_modules/**/*",
+    "packages/**/*"
   ],
-  "editor.defaultFormatter": "esbenp.prettier-vscode",
-  "prettier.requireConfig": true,
-  "editor.formatOnSave": true,
   "editor.tabSize": 2,
-  "jest.debugCodeLens.showWhenTestStateIn": ["fail", "unknown", "pass"]
+  "editor.formatOnSave": true,
+  "editor.formatOnSaveMode": "file",
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "jest.autoRun": "off",
+  "jest.rootPath": "packages/foam-vscode",
+  "jest.jestCommandLine": "yarn jest",
+  "gitdoc.enabled": false,
+  "search.mode": "reuseEditor"
 }

.vscode/tasks.json

@@ -1,31 +1,31 @@
 // See https://go.microsoft.com/fwlink/?LinkId=733558
 // for the documentation about the tasks.json format
 {
-	"version": "2.0.0",
-	"tasks": [
-		{
-			"label": "watch: foam-vscode",
-			"type": "npm",
-			"script": "start:vscode",
-			"problemMatcher": "$tsc-watch",
-			"isBackground": true,
-			"presentation": {
-				"reveal": "always"
-			},
-			"group": {
-				"kind": "build",
-				"isDefault": true
-			}
-		},
-		{
-			"label": "test: all packages",
-			"type": "npm",
-			"script": "test",
-			"problemMatcher": [],
-			"group": {
-				"kind": "test",
-				"isDefault": true
-			},
-		}
-	]
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "watch: foam-vscode",
+      "type": "npm",
+      "script": "watch",
+      "problemMatcher": "$tsc-watch",
+      "isBackground": true,
+      "presentation": {
+        "reveal": "always"
+      },
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      }
+    },
+    {
+      "label": "test: all packages",
+      "type": "npm",
+      "script": "test",
+      "problemMatcher": [],
+      "group": {
+        "kind": "test",
+        "isDefault": true
+      }
+    }
+  ]
 }

.yarnrc

@@ -0,0 +1 @@
+--ignore-engines true

LICENSE

@@ -1,6 +1,6 @@
 The MIT Licence (MIT)
 
-Copyright 2020 Jani Eväkallio <jani.evakallio@gmail.com>
+Copyright 2020 - present Jani Eväkallio <jani.evakallio@gmail.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in
@@ -17,4 +17,17 @@ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
 FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
 IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
-CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Where noted, some code uses the following license:
+
+MIT License
+
+Copyright (c) 2015 - present Microsoft Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:

docs/.vscode/extensions.json

@@ -14,9 +14,6 @@
     // Tons of markdown goodies (lists, tables of content, so much more)
     "yzhang.markdown-all-in-one",
 
-    // [[wiki-links]], backlinking etc
-    "kortina.vscode-markdown-notes",
-
     // Graph visualizer
     "tchayen.markdown-links",
 

docs/.vscode/settings.json

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

docs/404.md

@@ -3,9 +3,10 @@
 Well, that shouldn't have happened!
 
 If you got here via a link from another document, please file an [issue](https://github.com/foambubble/foam/issues) on our GitHub repo including:
+
 - the page you came from
 - the link you followed
 
 Thanks!
 
--The Foam Team
+-The Foam Team

docs/Gemfile

@@ -35,4 +35,3 @@ gem "wdm", "~> 0.1.0", :install_if => Gem.win_platform?
 # kramdown v2 ships without the gfm parser by default. If you're using
 # kramdown v1, comment out this line.
 gem "kramdown-parser-gfm"
-

docs/Gemfile.lock

@@ -203,14 +203,14 @@ GEM
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     mercenary (0.3.6)
-    mini_portile2 (2.5.0)
+    mini_portile2 (2.5.1)
     minima (2.5.1)
       jekyll (>= 3.5, < 5.0)
       jekyll-feed (~> 0.9)
       jekyll-seo-tag (~> 2.1)
     minitest (5.14.2)
     multipart-post (2.1.1)
-    nokogiri (1.11.1)
+    nokogiri (1.11.5)
       mini_portile2 (~> 2.5.0)
       racc (~> 1.4)
     octokit (4.19.0)
@@ -223,7 +223,7 @@ GEM
     rb-fsevent (0.10.4)
     rb-inotify (0.10.1)
       ffi (~> 1.0)
-    rexml (3.2.4)
+    rexml (3.2.5)
     rouge (3.23.0)
     ruby-enum (0.8.0)
       i18n

docs/LICENSE.txt

@@ -0,0 +1,33 @@
+The MIT Licence (MIT)
+
+Copyright 2020 - present Jani Eväkallio <jani.evakallio@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicence, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Where noted, some code uses the following license:
+
+MIT License
+
+Copyright (c) 2015 - present Microsoft Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:

docs/_layouts/foam.html

@@ -19,21 +19,21 @@ window.addEventListener('DOMContentLoaded', (event) => {
   document
     .querySelectorAll(".markdown-body a[title]:not([href^=http])")
     .forEach((a) => {
-      // filter to only wiki-links
+      // filter to only wikilinks
       var prev = a.previousSibling;
       var next = a.nextSibling;
       if (
-        prev instanceof Text && prev.textContent.endsWith('[') && 
+        prev instanceof Text && prev.textContent.endsWith('[') &&
         next instanceof Text && next.textContent.startsWith(']')
       ) {
-        
+
         // remove surrounding brackets
         prev.textContent = prev.textContent.slice(0, -1);
         next.textContent = next.textContent.slice(1);
 
         // add CSS list for styling
         a.classList.add('wikilink');
-        
+
         // replace page-link with "Page Title"...
         a.innerText = a.title;
 

docs/big-vision.md

@@ -12,7 +12,6 @@
 - What use cases are we working towards?
   -[[todo]] User round table
 
-
 [//begin]: # "Autogenerated link references for markdown compatibility"
 [todo]: dev/todo.md "Todo"
-[//end]: # "Autogenerated link references"
+[//end]: # "Autogenerated link references"

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/architecture.md

@@ -1,21 +0,0 @@
----
-tags: architecture
----
-# Architecture
-
-This document aims to provide a quick overview of the Foam architecture!
-
-Foam code and documentation live in the monorepo at [foambubble/foam](https://github.com/foambubble/foam/).
-- [/docs](https://github.com/foambubble/foam/tree/master/docs): documentation and [[recipes]].
-- [/packages/foam-core](https://github.com/foambubble/foam/tree/master/packages/foam-core) - Powers the core functionality in Foam across all platforms.
-- [/packages/foam-vscode](https://github.com/foambubble/foam/tree/master/packages/foam-vscode) - The core VSCode plugin.
-- [/packages/foam-cli](https://github.com/foambubble/foam/tree/master/packages/foam-cli) - The Foam CLI tool.
-
-Exceptions to the monorepo are:
-- The starter template at [foambubble/foam-template](https://github.com/foambubble/)
-- All other [[recommended-extensions]] live in their respective GitHub repos.
-
-[//begin]: # "Autogenerated link references for markdown compatibility"
-[recipes]: ../recipes/recipes.md "Recipes"
-[recommended-extensions]: ../recommended-extensions.md "Recommended Extensions"
-[//end]: # "Autogenerated link references"

docs/dev/build-vs-assemble.md

@@ -10,5 +10,3 @@ But there's also a bunch of roadmap items that are hard to implement this way, a
 Overall, we should strive to build big things from small things. Focused, interoperable modules are better, because they allow users to pick and mix which features work for them. A good example of why this matters is the Markdown All In One extension we rely on: While it provides many of the things we need, a few of its features are incompatible with how I would like to work, and therefore it becomes a limiter of how well I can improve my own workflow.
 
 However, there becomes a point where we may benefit from implementing a centralised solution, e.g. a syntax, an extension or perhaps a VSCode language server. As much as possible, we should allow users to operate in a decentralised manner.
-
-

docs/dev/code-of-conduct.md

@@ -118,7 +118,7 @@ the community.
 
 This Code of Conduct is adapted from the [Contributor Covenant][homepage],
 version 2.0, available at
-https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+<https://www.contributor-covenant.org/version/2/0/code_of_conduct.html>.
 
 Community Impact Guidelines were inspired by [Mozilla's code of conduct
 enforcement ladder](https://github.com/mozilla/diversity).
@@ -126,7 +126,5 @@ enforcement ladder](https://github.com/mozilla/diversity).
 [homepage]: https://www.contributor-covenant.org
 
 For answers to common questions about this code of conduct, see the FAQ at
-https://www.contributor-covenant.org/faq. Translations are available at
-https://www.contributor-covenant.org/translations.
-
-
+<https://www.contributor-covenant.org/faq>. Translations are available at
+<https://www.contributor-covenant.org/translations>.

docs/dev/contribution-guide.md

@@ -2,19 +2,21 @@
 tags: todo, good-first-task
 ---
 # Contribution Guide
+
 Foam is open to contributions of any kind, including but not limited to code, documentation, ideas, and feedback.
 This guide aims to help guide new and seasoned contributors getting around the Foam codebase.
 
 ## Getting Up To Speed
+
 Before you start contributing we recommend that you read the following links:
 
 - [[principles]] - This document describes the guiding principles behind Foam.
 - [[code-of-conduct]] - Rules we hope every contributor aims to follow, allowing everyone to participate in our community!
 
 ## Diving In
+
 We understand that diving in an unfamiliar codebase may seem scary,
 to make it easier for new contributors we provide some resources:
-- [[architecture]] - This document describes the architecture of Foam and how the repository is structured.
 
 You can also see [existing issues](https://github.com/foambubble/foam/issues) and help out!
 Finally, the easiest way to help, is to use it and provide feedback by [submitting issues](https://github.com/foambubble/foam/issues/new/choose) or participating in the [Foam Community Discord](https://foambubble.github.io/join-discord/g)!
@@ -31,36 +33,59 @@ If you're interested in contributing, this short guide will help you get things
 
    `yarn install`
 
-3. This project uses [Yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/). `foam-vscode` relies on `foam-core`. This means we need to compile it before we do any extension development. From the root, run the command:
+3. From the root, run the command:
 
    `yarn build`
 
 You should now be ready to start working!
 
+### Structure of the project
+
+Foam code and documentation live in the monorepo at [foambubble/foam](https://github.com/foambubble/foam/).
+
+- [/docs](https://github.com/foambubble/foam/tree/master/docs): documentation and [[recipes]].
+
+Exceptions to the monorepo are:
+
+- The starter template at [foambubble/foam-template](https://github.com/foambubble/)
+- All other [[recommended-extensions]] live in their respective GitHub repos
+
+This project uses [Yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/). 
+
+Originally Foam had:
+
+- [/packages/foam-core](https://github.com/foambubble/foam/tree/master/packages/foam-core) - Powers the core functionality in Foam across all platforms.
+- [/packages/foam-vscode](https://github.com/foambubble/foam/tree/master/packages/foam-vscode) - The core VS Code plugin.
+
+To improve DX we have moved the `foam-core` module into `packages/foam-vscode/src/core`, but from a development point of view it's useful to think of the `foam-vscode/src/core` "submodule" as something that might be extracted in the future.
+
+For all intents and purposes this means two things:
+
+1. nothing in `foam-vscode/src/core` should depend on files outside of this directory
+2. code in `foam-vscode/src/core` should NOT depend on `vscode` library
+
+We have kept the yarn workspace for the time being as we might use it to pull out `foam-core` in the future, or we might need it for other packages that the VS Code plugin could depend upon (e.g. currently the graph visualization is inside the module, but it might be pulled out if its complexity increases).
+
 ### Testing
 
 Code needs to come with tests.
 We use the following convention in Foam:
-- *.test.ts are unit tests
-- *.spec.ts are integration tests
 
-Also, note that tests in `foam-core` and `foam-cli` live in the `test` directory.
-Tests in `foam-vscode` live alongside the code in `src`.
+- `*.test.ts` are unit tests
+- `*.spec.ts` are integration tests
+
+Tests live alongside the code in `src`.
 
 ### The VS Code Extension
 
 This guide assumes you read the previous instructions and you're set up to work on Foam.
 
-1. Now we'll use the launch configuration defined at [`.vscode/launch.json`](https://github.com/foambubble/foam/blob/master/.vscode/launch.json) to start a new extension host of VS Code. From the root, or the `foam-vscode` workspace, press f5.
+1. Now we'll use the launch configuration defined at [`.vscode/launch.json`](https://github.com/foambubble/foam/blob/master/.vscode/launch.json) to start a new extension host of VS Code. Open the "Run and Debug" Activity (the icon with the bug on the far left) and select "Run VSCode Extension" in the pop-up menu. Now hit F5 or click the green arrow "play" button to fire up a new copy of VS Code with your extension installed.
 
 2. In the new extension host of VS Code that launched, open a Foam workspace (e.g. your personal one, or a test-specific one created from [foam-template](https://github.com/foambubble/foam-template)). This is strictly not necessary, but the extension won't auto-run unless it's in a workspace with a `.vscode/foam.json` file.
 
 3. Test a command to make sure it's working as expected. Open the Command Palette (Ctrl/Cmd + Shift + P) and select "Foam: Update Markdown Reference List". If you see no errors, it's good to go!
 
-For more resources related to the VS Code Extension, check out the links below:
-
-- [[tutorial-adding-a-new-command-to-the-vs-code-extension]]
-
 ---
 
 Feel free to modify and submit a PR if this guide is out-of-date or contains errors!
@@ -68,7 +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"
-[architecture]: dev/architecture.md "Architecture"
+[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

@@ -1,16 +1,16 @@
 # Foam File Format
 
-This file is an example of a valid Foam file. Essentially it's just a markdown file with a bit of additional support for mediawiki-style `[[wiki-links]]`.
+This file is an example of a valid Foam file. Essentially it's just a markdown file with a bit of additional support for MediaWiki-style `[[wikilinks]]`.
 
-Here are a few specific constraints, mainly because our tooling is a bit fragmented. Most of these should be eventually lifted, and our requirement should just be "Markdown with `[[wiki-links]]`:
+Here are a few specific constraints, mainly because our tooling is a bit fragmented. Most of these should be eventually lifted, and our requirement should just be "Markdown with `[[wikilinks]]`:
 
 - **The first top level `# Heading` will be used as title for the note.**
   - If not available, we will use the file name
 - **File name should have extension `.md`**
   - This is a temporary limitation and will be lifted in future versions.
   - At least `.mdx` will be supported, but ideally we'll support any file that you can map to `Markdown` language mode in VS Code
-- **In addition to normal Markdown Links syntax you can use `[[media-wiki]]` links.** See [[wiki-links]] for more details.
+- **In addition to normal Markdown Links syntax you can use `[[MediaWiki]]` links.** See [[wikilinks]] for more details.
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[wiki-links]: ../wiki-links.md "Wiki Links"
+[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

@@ -13,6 +13,7 @@ Present: @jevakallio, @riccardoferretti
 
 - Land work to master
   - Create a foam-core package
+
   -
 
 ### Open questions
@@ -122,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)
@@ -17,7 +17,7 @@
 `foam-core`'s primary responsibility is to build an API on top of a workspace of markdown files, which allows us to:
 
 - Treat files as a graph, based on links
-  - Can be either [[wiki-links]] or relative `[markdown](links.md)` style
+  - Can be either [[wikilinks]] or relative `[markdown](links.md)` style
   - We need to know about the edges (connections) as well as nodes
     - What link points to what other file, etc.
     - Needs to have the exact link text, e.g. even if `[[some-page]]` or `[[some-page.md]]` or `[[Some Page]]` point to the same document (`./some-page.md`), we need to know which format was used, so [[link-reference-definitions]] can be generated correctly
@@ -61,11 +61,11 @@ Here are some example use cases that the core should support. They don't need to
 
 - Adding and editing page content
   - [[materialized-backlinks]]
-  - [[link-reference-definitions]] for [[wiki-links]]
+  - [[link-reference-definitions]] for [[wikilinks]]
   - [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"
-[wiki-links]: ../wiki-links.md "Wiki Links"
-[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/inclusion-of-notes.md

@@ -0,0 +1,48 @@
+# Inclusion of notes Proposal <!-- omit in TOC -->
+
+Currently it is not possible within Foam to include other notes into a note. Next to including a full note it could be interesting to add functionalities that allow for greater flexibility. This proposal discusses some functionalities around inclusion of notes.
+
+**IMPORTANT: This design is merely a proposal of a design that could be implemented. It DOES NOT represent a commitment by `Foam` developers to implement the features outlined in this document. This document is merely a mechanism to facilitate discussion of a possible future direction for `Foam`.**
+
+- [Introduction](#introduction)
+- [New features](#new-features)
+  - [Including a note](#including-a-note)
+  - [Include a section of a note](#include-a-section-of-a-note)
+  - [Include an attribute of a file (note property or frontmatter)](#include-an-attribute-of-a-file-note-property-or-frontmatter)
+
+## Introduction
+
+Initial work and thought on including a note was ignited by issue [#652](https://github.com/foambubble/foam/issues/652). Requested by a user was a likewise functionality as offered in Obsidian. This was simply the ability to include a note.
+
+Whilst researching digital gardening for my own setup, I came across an in-depth overview by [Maggie Appleton](https://maggieappleton.com/roam-garden). Showing examples of her personal Roam Research I see valuable possibilites to connect more information, if we would add additional functionalities to the possibility of including a note. This proposal displays these possible functionalities and markup.
+
+## New features
+
+### Including a note
+
+The minimal functionality is the ability to fully include a note. Markup used in Obsidian for this is `![[wikilink]]`. For Foam I would suggest to follow this syntax. Benefits being:
+
+- Adds minimal amount of knowledge required as syntax is based on the syntax of creating a wikilink.
+- Makes the auto-complete work ouf-of-the-box, without any additional code and listeners required.
+
+**Important**. A risk exists that a loop of including the same notes arises. E.g. Note A includes note B which includes note A. This needs to be prevented by the implementation and made visible to the user.
+
+### Include a section of a note
+
+It could be interesting to only include a section of a note instead of the entire note. In order to do so thse user should be able to use the following syntax:
+
+`![[wikilink#section-b]]`
+
+As a result it will include the section title + section content until the next section *or* end of file.
+
+### Include an attribute of a file (note property or frontmatter)
+
+As a user I could be interested in collecting the value of any given proeprty for a note. For example, I might want to include the tags as defined in the frontmatter of note A. This should be possible via the syntax:
+
+`![[wikilink:<property>]]`
+
+The property value should be lookedup by foam defined properties, e.g. title, **or** any property defined in the frontmatter of a note.
+
+So, the example of including the tags of a note should be:
+
+`![[wikilink:tags]]`

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

@@ -4,13 +4,13 @@
 
 ### File-by-file Insertion
 
-For the time being, if you want to get [[wiki-links]] into all files within the workspace, you'll need to generate the link reference definitions yourself file-by-file (with the assistance of Foam).
+For the time being, if you want to get [[wikilinks]] into all files within the workspace, you'll need to generate the link reference definitions yourself file-by-file (with the assistance of Foam).
 
 ### Wikilinks don't work on GitHub
 
 > **TL;DR;** [workaround](#workaround) in the end of the chapter.
 
-If you click any of the wiki-links on GitHub web UI (such as the `README.md` of a project), you'll notice that the links break with a 404 error.
+If you click any of the wikilinks on GitHub web UI (such as the `README.md` of a project), you'll notice that the links break with a 404 error.
 
 At the time of writing (June 28 2020) this is a known, but unsolved error. To understand why this is the case, we need to understand what we are trading off.
 
@@ -59,7 +59,7 @@ Problem space in essence:
     - may clutter the search results
 - During build-time (when converting markdown to html for publishing purposes)
   - link reference definitions are needed, if the files are published via such tools (or to such platforms) that don't understand wikilinks
-  - link reference definitions might have to be in different formats depending on the publish target (e.g. Github pages vs Github UI)
+  - link reference definitions might have to be in different formats depending on the publish target (e.g. GitHub pages vs GitHub UI)
 
 The potential solution:
 
@@ -72,6 +72,7 @@ The potential solution:
     - This would be a GitHub action (or a local script, ran via foam-cli) that outputs publish-friendly markdown format for static site generators and other publishing tools
     - This build step should be pluggable, so that other transformations could be ran during it
   - Have publish targets defined in settings, that support both turning the link reference definitions on/off and defining their format (.md or not). Example draft (including also edit-time aspect):
+
     ```typescript
     // settings json
     // see enumerations below for explanations on values
@@ -120,8 +121,9 @@ The potential solution:
     }
 
     ```
-  - With Foam repo, just use edit-time link reference definitions with '.md' extension - this makes the links work in the Github UI
-  - Have publish target defined for Github pages, that doesn't use '.md' extension, but still has the link reference definitions. Generate the output into gh-pages branch (or separate repo) with automation.
+
+  - With Foam repo, just use edit-time link reference definitions with '.md' extension - this makes the links work in the GitHub UI
+  - Have publish target defined for GitHub pages, that doesn't use '.md' extension, but still has the link reference definitions. Generate the output into gh-pages branch (or separate repo) with automation.
     - This naturally requires first removing the existing link reference definitions during the build
 - Other
   - To clean up the search results, remove link reference definition section guards (assuming that these are not defined by the markdown spec). Use unifiedjs parse trees to identify if there's missing (or surplus) definitions (check if they are identified properly by the library), and just add the needed definitions to the bottom of the file (without guards) AND remove them if they are not needed (anywhere from the file).
@@ -135,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"
-[wiki-links]: ../wiki-links.md "Wiki Links"
-[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

@@ -11,8 +11,7 @@ The idea would be to automatically generate lists of backlinks (and optionally,
 - Make every link two-way navigable in published sites
 - 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"
+[//end]: # "Autogenerated link references"

docs/dev/proposals/roadmap.md

@@ -25,7 +25,7 @@ If a roadmap item is a stub, **consider** opening a [GitHub issue](https://githu
 - [[improve-default-workspace-settings]]
   - Discussion: [foam#270](https://github.com/foambubble/foam/issues/270)
 - Improve [[git-integration]]
-- Fix [[wiki-links]] compatibility issues
+- Fix [[wikilinks]] compatibility issues
 - Simplify [[foam-file-format]]
 
 ### Core features
@@ -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"
-[wiki-links]: ../wiki-links.md "Wiki Links"
-[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/proposals/templates-v2.md

@@ -0,0 +1,329 @@
+# Templates v2 Proposal <!-- omit in TOC -->
+
+The current capabilities of templates is limited in some important ways. This document aims to propose a design that addresses these shortcomings.
+
+**IMPORTANT: This design is merely a proposal of a design that could be implemented. It DOES NOT represent a commitment by `Foam` developers to implement the features outlined in this document. This document is merely a mechanism to facilitate discussion of a possible future direction for `Foam`.**
+
+- [Introduction](#introduction)
+- [Limitations of current templating](#limitations-of-current-templating)
+  - [Too much friction to create a new note](#too-much-friction-to-create-a-new-note)
+    - [Manual note creation (Mouse + Keyboard)](#manual-note-creation-mouse--keyboard)
+    - [Manual note creation (Keyboard)](#manual-note-creation-keyboard)
+    - [Foam missing note creation](#foam-missing-note-creation)
+    - [`Markdown Notes: New Note` (Keyboard)](#markdown-notes-new-note-keyboard)
+    - [Foam template note creation (Keyboard)](#foam-template-note-creation-keyboard)
+  - [Templating of daily notes](#templating-of-daily-notes)
+  - [Templating of filepaths](#templating-of-filepaths)
+- [Goal / Philosophy](#goal--philosophy)
+- [Proposal](#proposal)
+  - [Summary](#summary)
+  - [Add a `${title}` and `${titleSlug}` template variables](#add-a-title-and-titleslug-template-variables)
+  - [Add a `Foam: Create New Note` command and hotkey](#add-a-foam-create-new-note-command-and-hotkey)
+    - [Case 1: `.foam/templates/new-note.md` doesn't exist](#case-1-foamtemplatesnew-notemd-doesnt-exist)
+    - [Case 2: `.foam/templates/new-note.md` exists](#case-2-foamtemplatesnew-notemd-exists)
+  - [Change missing wikilinks to use the default template](#change-missing-wikilinks-to-use-the-default-template)
+  - [Add a metadata section to templates](#add-a-metadata-section-to-templates)
+    - [Example](#example)
+  - [Add a replacement for `dateFormat`](#add-a-replacement-for-dateformat)
+  - [Add support for daily note templates](#add-support-for-daily-note-templates)
+  - [Eliminate all `foam.openDailyNote` settings](#eliminate-all-foamopendailynote-settings)
+- [Summary: resulting behaviour](#summary-resulting-behaviour)
+  - [`Foam: Create New Note`](#foam-create-new-note)
+  - [`Foam: Open Daily Note`](#foam-open-daily-note)
+  - [Navigating to missing wikilinks](#navigating-to-missing-wikilinks)
+  - [`Foam: Create Note From Template`](#foam-create-note-from-template)
+- [Extensions](#extensions)
+  - [More variables in templates](#more-variables-in-templates)
+  - [`defaultFilepath`](#defaultfilepath)
+  - [Arbitrary hotkey -> template mappings?](#arbitrary-hotkey---template-mappings)
+
+## Introduction
+
+Creating of new notes in Foam is too cumbersome and slow. Despite their power, Foam templates can currently only be used in very limited scenarios.
+
+This proposal aims to address these issues by streamlining note creation and by allowing templates to be used everywhere.
+
+## Limitations of current templating
+
+### Too much friction to create a new note
+
+Creating new notes should an incredibly streamlined operation. There should be no friction to creating new notes.
+
+Unfortunately, all of the current methods for creating notes are cumbersome.
+
+#### Manual note creation (Mouse + Keyboard)
+
+1. Navigate to the directory where you want the note
+2. Click the new file button
+3. Provide a filename
+4. Manually enter the template contents you want
+
+#### Manual note creation (Keyboard)
+
+1. Navigate to the directory where you want the note
+2. `⌘N` to create a new file
+3. `⌘S` to save the file and give it a filename
+4. Manually enter the template contents you want
+
+#### Foam missing note creation
+
+1. Open an existing note in the directory where you want the note
+2. Use the wikilinks syntax to create a link to the title of the note you want to have
+3. Use `Ctrl+Click`/`F12` to create the new file
+4. Manually enter the template contents you want
+
+#### `Markdown Notes: New Note` (Keyboard)
+
+1. Navigate to the directory where you want the note
+2. `Shift+⌘P` to open the command pallette
+3. Type `New Note` until it appears in the list. Press `Enter/Return` to select it.
+4. Enter a title for the note
+5. Manually enter the template contents you want
+
+#### Foam template note creation (Keyboard)
+
+1. `Shift+⌘P` to open the command pallette
+2. Type `Create New Note From Template` until it appears in the list. Press `Enter/Return` to select it.
+3. Use the arrow keys (or type the template name) to select the template. Press `Enter/Return` to select it.
+4. Modify the filepath to match the desired directory + filename. Press `Enter/Return` to select it.
+
+All of these steps are far too cumbersome. And only the last one allows the use of templates.
+
+### Templating of daily notes
+
+Currently `Open Daily Note` opens an otherwise empty note, with a title defined by the `foam.openDailyNote.titleFormat` setting.
+Daily notes should be able to be fully templated as well.
+
+### Templating of filepaths
+
+As discussed in ["Template the filepath in `openDailyNote`"](https://github.com/foambubble/foam/issues/523), it would be useful to be able to specify the default filepaths of templates. For example, many people include timestamps in their filepaths.
+
+## Goal / Philosophy
+
+In a sentence: **Creating a new note should be a single button press and should use templates.**
+
+## Proposal
+
+1. Add a new `Foam: Create New Note` that is the streamlined counterpart to the more flexible `Foam: Create New Note From Template`
+2. Use templates everywhere
+3. Add metadata into the actual templates themselves in order to template the filepaths themselves.
+
+### Summary
+
+This can be done through a series of changes to the way that templates are implemented:
+
+1. Add a `${title}` and `${titleSlug}` template variables
+2. Add a `Foam: Create New Note` command and hotkey
+3. Change missing wikilinks to use the default template
+4. Add a metadata section to templates
+5. Add a replacement for `dateFormat`
+6. Add support for daily note templates
+7. Eliminate all `foam.openDailyNote` settings
+
+I've broken it out into these steps to show that the overall proposal can be implemented piecemeal in independent PRs that build on one another.
+
+### Add a `${title}` and `${titleSlug}` template variables
+
+When you use `Markdown Notes: New Note`, and give it a title, the title is formatted as a filename and also used as the title in the resulting note.
+
+**Example:**
+
+Given the title `Living in a dream world` to `Markdown Notes: New Note`, the filename is `living-in-a-dream-world.md` and the file contents are:
+
+```markdown
+# Living in a dream world
+```
+
+When creating a note from a template in Foam, you should be able to use a `${title}` variable. If the template uses the `${title}` variable, the user will be prompted for a title when they create a note from a template.
+
+Example:
+
+Given this `.foam/templates/my_template.md` template that uses the `${title}` variable:
+
+```markdown
+# ${title}
+```
+
+When a user asks for a new note using this template (eg. `Foam: Create New Note From Template`), VSCode will first ask the user for a title then provide it to the template, producing:
+
+```markdown
+# Living in a dream world
+```
+
+There will also be a `${titleSlug}` variable made available, which will be the "slugified" version of the title (eg. `living-in-a-dream-world`). This will be useful in later steps where we want to template the filepath of a template.
+
+### Add a `Foam: Create New Note` command and hotkey
+
+Instead of using `Markdown Notes: New Note`, Foam itself will have a `Create New Note` command that creates notes using templates.
+
+This would open use the template found at `.foam/templates/new-note.md` to create the new note.
+
+`Foam: Create New Note` will offer the fastest workflow for creating a note when you don't need customization, while `Foam: Create New Note From Template` will remain to serve a fully customizable (but slower) workflow.
+
+#### Case 1: `.foam/templates/new-note.md` doesn't exist
+
+If `.foam/templates/new-note.md` doesn't exist, it behaves the same as `Markdown Notes: New Note`:
+
+* it would ask for a title and create the note in the current directory. It would open a note with the note containing the title.
+
+**Note:** this would use an implicit default template, making use of the `${title}` variable.
+
+#### Case 2: `.foam/templates/new-note.md` exists
+
+If `.foam/templates/new-note.md` exists:
+
+* it asks for the note title and creates the note in the current directory
+
+**Progress:** At this point, we have a faster way to create new notes from templates.
+
+### Change missing wikilinks to use the default template
+
+Clicking on a dangling/missing wikilink should be equivalent to calling `Foam: Create New Note` with the contents of the link as the title.
+That way, creating a note by navigating to a missing note uses the default template.
+
+### Add a metadata section to templates
+
+* The `Foam: New Note` command creates a new note in the current directory. This is a sensible default that makes it quick, but lacks flexibility.
+* The `Foam: Create New Note From Template` asks the user to confirm/customize the filepath. This is more flexible but slower since there are more steps involved.
+
+Both commands use templates. It would be nice if we could template the filepaths as well as the template contents (See ["Template the filepath in `openDailyNote`"](https://github.com/foambubble/foam/issues/523) for a more in-depth discussion the benefits of filepath templating).
+
+In order to template the filepath, there needs to be a place where metadata like this can be specified.
+I think this metadata should be stored alongside the templates themselves. That way, it can make use of all the same template variable available to the templates themselves.
+
+Conceptually, adding metadata to the templates is similar to Markdown frontmatter, though the choice of exact syntax for adding this metadata will have to be done with care since the templates can contain arbitrary contents including frontmatter.
+
+#### Example
+
+A workable syntax is still to be determined.
+While this syntax probably doesn't work as a solution, for this example I will demonstrate the concept using a second frontmatter block:
+
+```markdown
+<!-- The below front-matter block is for foam-specific template settings -->
+<!-- It is removed when the user creates a new note using this template -->
+---
+<!-- The default filepath to use when using this template -->
+<!-- Relative paths are relative to the workspace, absolute paths are absolute -->
+<!-- Note that you can include VSCode snippet variables to template the path -->
+filepath: `journal/${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE}_${titleSlug}.md`
+---
+
+<!-- The actual contents of the template begin after the `---` thematic break immediately below this line-->
+---
+---
+created: ${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE}T${CURRENT_HOUR}:${CURRENT_MINUTE}:${CURRENT_SECOND}
+tags: []
+---
+
+# ${title}
+```
+
+In this example, using this template improves the UX:
+
+In `Foam: Create New Note` workflow, having `filepath` metadata within `.foam/templates/new-note.md` allows for control over the filepath without having to introduce any more UX steps to create a new note. It's still just a hotkey away and a title.
+
+As we'll see, when it comes to allowing daily notes to be templated, we don't even need to use `${title}` in our template, in which case we don't we don't even need to prompt for a title.
+
+In the `Create New Note From Template` workflow, during the step where we allow the user to customize the filepath, it will already templated according to the `filepath` in the template's metadata. This means that the user has to make fewer changes to the path, especially in cases where they want to include things like datetimes in the filenames. This makes it faster (eg. don't have to remember what day it is, and don't have to type it) and less error-prone (eg. when they accidentally type the wrong date).
+
+### Add a replacement for `dateFormat`
+
+`foam.openDailyNote.filenameFormat` uses `dateFormat()` to put the current timestamp into the daily notes filename. This is much more flexible than what is available in VSCode Snippet variables. Before daily notes are switched over to use templates, we will have to come up with another mechanism/syntax to allow for calls to `dateFormat()` within template files.
+
+This would be especially useful in the migration of users to the new daily notes templates. For example, if `.foam/templates/daily-note.md` is unset, then we could generate an implicit template for use by `Foam: Open Daily Note`. Very roughly something like:
+
+```markdown
+<!-- The below front-matter block is for foam-specific template settings -->
+<!-- It is removed when the user creates a new note using this template -->
+---
+<!-- The default filepath to use when using this template -->
+<!-- Relative paths are relative to the workspace, absolute paths are absolute -->
+<!-- Note that you can include VSCode snippet variables to template the path -->
+filepath: `${foam.openDailyNote.directory}/${foam.openDailyNote.filenameFormat}.${foam.openDailyNote.fileExtension}`
+---
+
+<!-- The actual contents of the template begin after the `---` thematic break immediately below this line-->
+---
+# ${foam.openDailyNote.titleFormat}
+```
+
+### Add support for daily note templates
+
+With the above features implemented, making daily notes use templates is simple.
+
+We define a `.foam/templates/daily-note.md` filepath that the `Foam: Open Daily Note` command will always use to find its daily note template.
+If `.foam/templates/daily-note.md` does not exist, it falls back to a default, implicitly defined daily notes template (which follows the default behaviour of the current `foam.openDailyNote` settings).
+
+Both `Foam: Open Daily Note` and `Foam: Create New Note` can share all of the implementation code, with the only differences being the hotkeys used and the template filepath used.
+
+Example daily note template (again using the example syntax of the foam-specific frontmatter block):
+
+```markdown
+<!-- The below front-matter block is for foam-specific template settings -->
+<!-- It is removed when the user creates a new note using this template -->
+---
+<!-- The default filepath to use when using this template -->
+<!-- Relative paths are relative to the workspace, absolute paths are absolute -->
+<!-- Note that you can include VSCode snippet variables to template the path -->
+filepath: `journal/${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE}.md`
+---
+
+<!-- The actual contents of the template begin after the `---` thematic break immediately below this line-->
+---
+# ${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE}
+```
+
+Since there is no use of the `${title}` variable, opening the daily note behaves exactly as it does today and automatically opens the note with no further user interaction.
+
+### Eliminate all `foam.openDailyNote` settings
+
+Now that all of the functionality of the `foam.openDailyNote` settings have been obviated, these settings can be removed:
+
+* `foam.openDailyNote.directory`, `foam.openDailyNote.filenameFormat`, and `foam.openDailyNote.fileExtension` can be specified in the `filepath` metadata of the daily note template.
+* `foam.openDailyNote.titleFormat` has been replaced by the ability to fully template the daily note, including the title.
+
+## Summary: resulting behaviour
+
+### `Foam: Create New Note`
+
+A new command optimized for speedy creation of new notes. This will become the default way to create new notes. In its fastest form, it simply opens the new note with no further user interaction.
+
+### `Foam: Open Daily Note`
+
+Simplified since it no longer has its custom settings, and re-uses all the same implementation code as `Foam: Create New Note`.
+Templates can now be used with daily notes.
+
+### Navigating to missing wikilinks
+
+Now creates the new notes using the default template. Re-uses all the same implementation code as `Foam: Create New Note`
+Now uses the contents of the wikilink as the `${title}` parameter for the template.
+
+### `Foam: Create Note From Template`
+
+Almost the exact same as it is today. However, with `${title}` and `filepath` templating, users will have less changes to make in the filepath confirmation step.
+It's the slower but more powerful version of `Foam: Create New Note`, allowing you to pick any template, as well as customize the filepath.
+
+## Extensions
+
+In addition to the ideas of this proposal, there are ways we could imagine extending it. These are all "out of scope" for this design, but thinking about them could be useful to guide our thinking about this design.
+
+### More variables in templates
+
+`${title}` is necessary in this case to replace the functionality of `Markdown Notes: New Note`.
+However, one could imagine that this pattern of "Ask the user for a value for missing variable values" could be useful in other situations too.
+Perhaps users could even define their own (namespaced) template variables, and Foam would ask them for values to use for each when creating a note using a template that used those variables.
+
+### `defaultFilepath`
+
+By using `defaultFilepath` instead of `filepath` in the metadata section, you could have more control over the note creation without having to fall back to the full `Create New Note From Template` workflow.
+
+* `filepath` will not ask the user for the file path, simply use the value provided (as described above)
+* `defaultFilepath` will ask the user for the file path, pre-populating the file path using `defaultFilepath`
+
+The first allows "one-click" note creation, the second more customization.
+This might not be necessary, or this might not be the right way to solve the problem. We'll see.
+
+### Arbitrary hotkey -> template mappings?
+
+`Foam: Open Daily Note` and `Foam: Create New Note` only differ by their hotkey and their default template setting.
+Is there a reason/opportunity to abstract this further and allow for users to define custom `hotkey -> template` mappings?

docs/dev/proposals/wikilinks-in-foam.md

@@ -0,0 +1,93 @@
+# Wikilinks in Foam
+
+Foam supports standard wikilinks in the format `[[wikilink]]`.
+
+Wikilinks can refer to any note or attachment in the repo: `[[note.md]]`, `[[doc.pdf]]`, `[[image.jpg]]`.
+
+The usual wikilink syntax without extension refers to notes: `[[wikilink]]` and `[[wikilink.md]]` are equivalent.
+
+The goal of wikilinks is to uniquely identify a file in a repo, no matter in which directory it lives.
+
+Sometimes in a repo you can have files with the same name in different directories.
+Foam allows you to identify those files using the minimum effort needed to disambiguate them.
+
+This is achieved by adding as many directories above the file needed to uniquely identify the link, e.g. `[[house/todo]]`.
+
+See below for more details.
+
+## Goals for wikilinks in Foam
+
+Wikilinks in Foam are meant to satisfy the following:
+- make it easy for users to identify a resource
+- make it interoperable with other similar note taking systems (Obsidian, Dendron, ...)
+- be easy to get started with, but satisfy growing needs
+
+## Types of wikilinks supported in Foam
+
+Foam supports two types of keys inside a wikilink: a **path** reference and an **identifier** reference:
+
+- `[[./file]]` and `[[../to/another/file]]` are **path** links to a resource, relative _from the source_
+- `[[/path/to/file]]` is a **path** link to a resource, relative _from the repo root_
+- `[[file]]` is an **identifier** of a resource (based on the filename)
+- `[[path/to/file]]` is an **identifier** of a resource (based on the path), the same is true for `[[to/file]]`
+
+It's important to note that sometimes identifier keys can't uniquely locale a resource.
+
+A more concrete example will help:
+
+```
+/
+  projects/
+    house/
+      todo.md
+    buy-car/
+      todo.md
+      cars.md
+  work/
+    todo.md
+    notes.md
+```
+
+In the above repo:
+
+- `[[cars]]` is a unique identifier of a resource - it can be used anywhere in the repo
+- `[[todo]]` is an non-unique identifier as it can refer to multiple resources
+- `[[house/todo]]` is a unique identifier of a resource - it can be used anywhere in the repo
+- `[[projects/house/todo]]` is a unique identifier of a resource - it can be used anywhere in the repo
+- `[[/projects/house/todo]]` is a path reference to a resource
+- `[[./todo]]` is a path reference to a resource (e.g. from `/projects/buy-car/cars.md`)
+
+Basically we could say as a rule:
+
+- if the link starts with `/` or `.` we consider it a **path** reference, in the first case from the repo root, otherwise from the source note
+- if a link doesn't start with `/` or `.` it is an **identifier**
+  - generally speaking we use the shortest identifier available to identify a resource, **but all are valid**
+    - `[[projects/buy-car/cars]]`, `[[buy-car/cars]]`, `[[cars]]` are all unique identifier to the same resource, and are all valid in a document
+    - the same can be said for `[[projects/house/todo]]` and `[[house/todo]]` - but not for `[[todo]]`, because it can refer to more than one resource
+
+## Compatibility with other apps
+
+| Scenario                    | Obsidian                        | Foam                            |
+| --------------------------- | ------------------------------- | ------------------------------- |
+| 1 `[[notes]]`               | ✔ unique identifier in repo     | ✔ unique identifier in repo     |
+| 2 `[[/work/notes]]`         | ✔ valid path from repo root     | ✔ valid path from repo root     |
+| 3 `[[work/notes]]`          | ✔ valid path from repo root     | ✔ valid identifier in repo      |
+| 4 `[[project/house/todo]]`  | ✔ valid path from repo root     | ✔ valid unique identifier       |
+| 5 `[[/project/house/todo]]` | ✔ valid path from repo root     | ✔ valid path from repo root     |
+| 6 `[[house/todo]]`          | ✔ valid unique identifier       | ✔ valid unique identifier       |
+| 7 `[[todo]]`                | ✘ ambiguous identifier          | ✘ ambiguous identifier          |
+| 8 `[[/house/todo]]`         | ✘ incorrect path from repo root | ✘ incorrect path from repo root |
+
+## Non-unique identifiers
+
+We can't prevent non-unique identifiers from occurring in Foam (first and foremost because a file could be edited with another editor) but we can flag them. 
+
+Therefore Foam follows the following strategy instead:
+
+1. there is a clear resolution mechanism (alphabetic) so that if nothing changes a non-unique identifier will always return the same note. Resolution has to be deterministic
+2. a diagnostic entry (warning or error) is showed to the user for non-unique identifiers, so she knows that she's using a "risky" identifier
+   1. The quick resolution for this item will show the available unique identifiers matching the non-unique one
+
+## Thanks 
+
+Thanks to [@memplex](https://github.com/memeplex) for helping with the thinking around this proposal.

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

@@ -0,0 +1,25 @@
+# Releasing Foam
+
+1. Get to the latest code
+   - `git checkout master && git fetch && git rebase`
+2. Sanity checks
+   - `yarn reset`
+   - `yarn test`
+3. Update change log 
+   - `./packages/foam-vscode/CHANGELOG.md`
+   - `git add *`
+   - `git commit -m"Preparation for next release"`
+4. Update version
+   - `$ yarn version-extension <version>` (where `version` is `patch/minor/major`) 
+5. Package extension
+   - `$ yarn package-extension`
+6. Publish extension
+   - `$ yarn publish-extension`
+7. Update the release notes in GitHub
+   - in GitHub, top right, click on "releases"
+   - select "tags" in top left
+   - select the tag that was just released, click "edit" and copy release information from changelog
+   - publish (no need to attach artifacts)
+8. Annouce on Discord
+
+Steps 1 to 6 should really be replaced by a GitHub action...

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

@@ -11,10 +11,10 @@ One of Foam's big features is the ability to find all instances of a reference,
 Implementing this is on the [[roadmap]], but for the time being you can achieve similar things by:
 
 - `Cmd` + `Shift` + `F` ( `Ctrl` + `Shift` + `F` on Windows ) to find all the references, e.g. "Cat food"
-- `Cmd` + `Shift` + `H` ( `Ctrl` + `Shift` + `F` on Windows ) to replace them with [[cat-food]].
+- `Cmd` + `Shift` + `H` ( `Ctrl` + `Shift` + `H` on Windows ) to replace them with [[cat-food]].
 - Click any of the references to create a new note.
 
 [//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/creating-new-notes.md

@@ -1,12 +0,0 @@
-# Creating New Notes
-
-- Write out a new `[[wiki-link]]` and `Cmd` + `Click` to create a new file and enter it.
-  - For keyboard navigation, use the 'Follow Definition' key `F12` (or [remap key binding](https://code.visualstudio.com/docs/getstarted/keybindings) to something more ergonomic)
-- `Cmd` + `Shift` + `P` (`Ctrl` + `Shift` + `P` for Windows), execute `New Note` from [VS Code Markdown Notes](https://marketplace.visualstudio.com/items?itemName=kortina.vscode-markdown-notes) and enter a **Title Case Name** to create `title-case-name.md`
-  - Add a keyboard binding to make creating new notes easier.
-- You shouldn't worry too much about categorizing your notes. You can always [[search-for-notes]], and explore them using the [[graph-visualisation]].
-
-[//begin]: # "Autogenerated link references for markdown compatibility"
-[search-for-notes]: ../recipes/search-for-notes.md "Search for Notes"
-[graph-visualisation]: graph-visualisation.md "Graph Visualisation"
-[//end]: # "Autogenerated link references"

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

@@ -1,15 +0,0 @@
-# Custom Markdown Preview Styles
-
-Visual Studio Code allows you to use your own CSS in the Markdown preview tab.
-
-## Instructions
-
-Custom CSS for the Markdown preview can be implemented by using the `"markdown.styles": []` setting in `settings.json`. The stylesheets can either be https URLs or relative paths to local files in the current workspace.
-
-For example, to load a stylesheet called `Style.css`, we can update `settings.json` with the following line:
-
-```
-{
-  "markdown.styles": ["Style.css"]
-}
-```

docs/features/daily-notes.md

@@ -1,54 +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):
-
-```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/note-2020-07-25.mdx`, with the heading `Journal Entry, Sunday, July 25`.
-
-## Daily Note Templates
-
-In the future, Foam may provide a functionality for specifying a template for new Daily Notes and other types of documents.
-
-In the meantime, you can use [VS Code Snippets](https://code.visualstudio.com/docs/editor/userdefinedsnippets) for defining your own Daily Note template.
-
-## Roam-style Automatic Daily Notes
-
-In the future, Foam may provide an option for automatically opening your Daily Note when you open your Foam workspace.
-
-If you want this behavior now, you can use the excellent [Auto Run Command](https://marketplace.visualstudio.com/items?itemName=gabrielgrinberg.auto-run-command#review-details) extension to run the "Open Daily Note" command upon entering a Foam workspace by specifying the following configuration in your `.vscode/settings.json`:
-
-```json
-  "auto-run-command.rules": [
-    {
-      "condition": "hasFile: .vscode/foam.json",
-      "command": "foam-vscode.open-daily-note",
-      "message": "Have a nice day!"
-    }
-  ],
-```
-
-## 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/foam-local-plugins.md

@@ -1,60 +0,0 @@
-# Foam Local Plugins
-
-Foam can use workspace plugins to provide customization for users.
-
-## ATTENTION
-
-This feature is experimental and its API subject to change.
-**Local plugins can execute arbitrary code on your machine** - ensure you trust the content of the repo.
-
-## Goal
-
-Here are some of the things that we could enable with local plugins in Foam:
-
-- extend the document syntax to support roam style attributes (e.g. `stage:: seedling`)
-- automatically add tags to my notes based on the location in the repo (e.g. notes in `/areas/finance` will automatically get the `#finance` tag)
-- add a new CLI command to support some internal use case or automate import/export
-- extend the VSCode experience to support one's own workflow, e.g. weekly note, templates, extra panels, foam model derived TOC, ... all without having to write/deploy a VSCode extension
-
-## How to enable local plugins
-
-Plugins can execute arbitrary code on the client's machine.
-For this reason this feature is disabled by default, and needs to be explicitly enabled.
-
-To enable the feature:
-
-- create a `~/.foam/config.json` file
-- add the following content to the file
-
-```
-{
-	"experimental": {
-		"localPlugins": {
-			"enabled": true
-		}
-	}
-}
-```
-
-For security reasons this setting can only be defined in the user settings file.
-(otherwise a malicious repo could set it via its `./foam/config.json`)
-
-- [[todo]] an additional security mechanism would involve having an explicit list of whitelisted repo paths where plugins are allowed. This would provide finer grain control over when to enable or disable the feature.
-
-## Technical approach
-
-When Foam is loaded it will check whether the experimental local plugin feature is enabled, and in such case it will:
-
-- check `.foam/plugins` directory.
-  - each directory in there is considered a plugin
-  - the layout of each directory is
-    - `index.js` contains the main info about the plugin, specifically it exports:
-      - `name: string` the name of the plugin
-      - `description?: string` the description of the plugin
-      - `parser?: ParserPlugin` an object that interacts with the markdown parsing phase
-
-Currently for simplicity we keep everything in one file. We might in the future split the plugin by domain (e.g. vscode, cli, core, ...)
-
-[//begin]: # 'Autogenerated link references for markdown compatibility'
-[todo]: ../dev/todo.md 'Todo'
-[//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/note-templates.md

@@ -1,17 +0,0 @@
-# Note Templates
-
-Foam supports note templates.
-
-Note templates live in `.foam/templates`. Run the `Foam: Create New Template` command from the command palette or create a regular `.md` file there to add a template.
-
-![Create new template GIF](../assets/images/create-new-template.gif)
-
-_Theme: Ayu Light_
-
-To create a note from a template, execute 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.
-
-![Create new note from template GIF](../assets/images/create-new-note-from-template.gif)
-
-_Theme: Ayu Light_
-
-Templates can use all the variables available in [VS Code Snippets](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_variables).

docs/features/tags.md

@@ -1,18 +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
-
-## 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.
-
-## 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/frequently-asked-questions.md

@@ -1,18 +0,0 @@
-# Frequently Asked Questions
-
-> ⚠️ Foam is still in preview. Expect the experience to be a little rough.
-
-- [Frequently Asked Questions](#frequently-asked-questions)
-  - [Links/Graphs/BackLinks don't work. How do I enable them?](#linksgraphsbacklinks-dont-work-how-do-i-enable-them)
-
-## Links/Graphs/BackLinks don't work. How do I enable them?
-
-- Ensure that you have all the [[recommended-extensions]] installed in Visual Studio Code
-- Reload Visual Studio Code by running `Cmd` + `Shift` + `P` (`Ctrl` + `Shift` + `P` for Windows), type "reload" and run the **Developer: Reload Window** command to for the updated extensions take effect
-- Check the formatting rules for links on [[foam-file-format]], [[wiki-links]] and [[link-formatting-and-autocompletion]]
-
-[//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"
-[wiki-links]: wiki-links.md "Wiki Links"
-[//end]: # "Autogenerated link references"

docs/inbox.md

@@ -5,7 +5,7 @@ Uncategorised thoughts, to be added
 - Release notes
 - Markdown Preview
   - It's possible to customise the markdown preview styling. **Maybe make it use local foam workspace styles for live preview of the site??**
-    - See: https://marketplace.visualstudio.com/items?itemName=bierner.markdown-preview-github-styles
+    - See: <https://marketplace.visualstudio.com/items?itemName=bierner.markdown-preview-github-styles>
 - Use VS Code [CodeTour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) for onboarding
 - Investigate other similar extensions:
   - [Unotes](https://marketplace.visualstudio.com/items?itemName=ryanmcalister.Unotes)
@@ -16,10 +16,10 @@ Uncategorised thoughts, to be added
   - Every Foam could have a different theme even in the editor, so you'll see it like they see it
     - UI and layout design of your workspace can become a thing
 - VS Code Notebooks API
-  - https://code.visualstudio.com/api/extension-guides/notebook
+  - <https://code.visualstudio.com/api/extension-guides/notebook>
 - Future architecture
   - Could we do publish-related settings as a pre-push git hook, e.g. generating footnote labels
-  - Running them on Github Actions to edit stuff as it comes in
+  - Running them on GitHub Actions to edit stuff as it comes in
     - Ideally, we shouldn't have to touch files, should be just markdown
 - Looking at the errors/warnings/output panes makes me think, what kind of automated quality tools could we write.
   - Deduplication, finding similarities...
@@ -29,8 +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

@@ -31,14 +31,12 @@ You can use **Foam** for organising your research, keeping re-discoverable notes
 
 **Foam** is a tool that supports creating relationships between thoughts and information to help you think better.
 
-![Foam kitchen sink, showing a few of the key features](assets/images/foam-features-dark-mode-demo.png)
-
 Whether you want to build a [Second Brain](https://www.buildingasecondbrain.com/) or a [Zettelkasten](https://zettelkasten.de/posts/overview/), write a book, or just get better at long-term learning, **Foam** can help you organise your thoughts if you follow these simple rules:
 
 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 `[[wiki-links]]`, 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]].
+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-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._
 
@@ -48,7 +46,7 @@ Like the soapy suds it's named after, **Foam** is mostly air.
 
 1. The editing experience of **Foam** is powered by VS Code, enhanced by workspace settings that glue together [[recommended-extensions]] and preferences optimised for writing and navigating information.
 2. To back up, collaborate on and share your content between devices, Foam pairs well with [GitHub](http://github.com/).
-3. To publish your content, you can set it up to publish to [GitHub Pages](https://pages.github.com/) with zero code and zero config, or to any website hosting platform like [Netlify](http://netlify.com/) or [Vercel](https://vercel.com).
+3. To publish your content, you can set it up to publish to [GitHub Pages](https://pages.github.com/), or to any website hosting platform like [Netlify](http://netlify.com/) or [Vercel](https://vercel.com).
 
 > **Fun fact**: This documentation was researched, written and published using **Foam**.
 
@@ -66,12 +64,14 @@ These instructions assume you have a GitHub account, and you have Visual Studio
 
 2. [Clone the repository locally](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) and open it in VS Code.
 
-    *Open the repository as a folder using the `File > Open...` menu item. In VS Code, "open workspace" refers to [multi-root workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces).*
+   *Open the repository as a folder using the `File > Open...` menu item. In VS Code, "open workspace" refers to [multi-root workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces).*
 
 3. When prompted to install recommended extensions, click **Install all** (or **Show Recommendations** if you want to review and install them one by one)
 
 After setting up the repository, open `.vscode/settings.json` and edit, add or remove any settings you'd like for your Foam workspace.
 
+* *If using a [multi-root workspace](https://code.visualstudio.com/docs/editor/multi-root-workspaces) as noted above, make sure that your **Foam** directory is first in the list. There are some settings that will need to be migrated from `.vscode/settings.json` to your `.code-workspace` file.*
+
 To learn more about how to use **Foam**, read the [[recipes]].
 
 Getting stuck in the setup? Read the [[frequently-asked-questions]].
@@ -189,6 +189,54 @@ If that sounds like something you're interested in, I'd love to have you along o
   </tr>
   <tr>
     <td align="center"><a href="http://www.nitwit.se"><img src="https://avatars.githubusercontent.com/u/1382124?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Mark Dixon</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=nitwit-se" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/joeltjames"><img src="https://avatars.githubusercontent.com/u/3732400?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Joel James</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=joeltjames" title="Code">💻</a></td>
+    <td align="center"><a href="https://www.ryo33.com"><img src="https://avatars.githubusercontent.com/u/8780513?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Hashiguchi Ryo</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=ryo33" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://movermeyer.com"><img src="https://avatars.githubusercontent.com/u/1459385?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Michael Overmeyer</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=movermeyer" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/derrickqin"><img src="https://avatars.githubusercontent.com/u/3038111?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Derrick Qin</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=derrickqin" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://www.linkedin.com/in/zomars/"><img src="https://avatars.githubusercontent.com/u/3504472?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Omar López</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=zomars" title="Documentation">📖</a></td>
+    <td align="center"><a href="http://robincn.com"><img src="https://avatars.githubusercontent.com/u/1583193?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Robin King</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=RobinKing" title="Code">💻</a></td>
+  </tr>
+  <tr>
+    <td align="center"><a href="http://twitter.com/deegovee"><img src="https://avatars.githubusercontent.com/u/4730170?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Dheepak </b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=dheepakg" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/daniel-vera-g"><img src="https://avatars.githubusercontent.com/u/28257108?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Daniel VG</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=daniel-vera-g" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/Barabazs"><img src="https://avatars.githubusercontent.com/u/31799121?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Barabas</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=Barabazs" title="Code">💻</a></td>
+    <td align="center"><a href="http://enginveske@gmail.com"><img src="https://avatars.githubusercontent.com/u/43685404?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Engincan VESKE</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=EngincanV" title="Documentation">📖</a></td>
+    <td align="center"><a href="http://www.paulderaaij.nl"><img src="https://avatars.githubusercontent.com/u/495374?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Paul de Raaij</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=pderaaij" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/bronson"><img src="https://avatars.githubusercontent.com/u/1776?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Scott Bronson</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=bronson" title="Documentation">📖</a></td>
+    <td align="center"><a href="http://rafaelriedel.de"><img src="https://avatars.githubusercontent.com/u/41793?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Rafael Riedel</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=rafo" title="Documentation">📖</a></td>
+  </tr>
+  <tr>
+    <td align="center"><a href="https://github.com/Pearcekieser"><img src="https://avatars.githubusercontent.com/u/5055971?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Pearcekieser</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=Pearcekieser" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/theowenyoung"><img src="https://avatars.githubusercontent.com/u/62473795?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Owen Young</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=theowenyoung" title="Documentation">📖</a> <a href="#content-theowenyoung" title="Content">🖋</a></td>
+    <td align="center"><a href="http://www.prashu.com"><img src="https://avatars.githubusercontent.com/u/476729?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Prashanth Subrahmanyam</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=ksprashu" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/JonasSprenger"><img src="https://avatars.githubusercontent.com/u/25108895?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Jonas SPRENGER</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=JonasSprenger" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/Laptop765"><img src="https://avatars.githubusercontent.com/u/1468359?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Paul</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=Laptop765" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://bandism.net/"><img src="https://avatars.githubusercontent.com/u/22633385?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Ikko Ashimine</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=eltociear" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/memeplex"><img src="https://avatars.githubusercontent.com/u/2845433?v=4?s=60" width="60px;" alt=""/><br /><sub><b>memeplex</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=memeplex" title="Code">💻</a></td>
+  </tr>
+  <tr>
+    <td align="center"><a href="https://github.com/AndreiD049"><img src="https://avatars.githubusercontent.com/u/52671223?v=4?s=60" width="60px;" alt=""/><br /><sub><b>AndreiD049</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=AndreiD049" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/iam-yan"><img src="https://avatars.githubusercontent.com/u/48427014?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Yan</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=iam-yan" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://WikiEducator.org/User:JimTittsler"><img src="https://avatars.githubusercontent.com/u/180326?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Jim Tittsler</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=jimt" title="Documentation">📖</a></td>
+    <td align="center"><a href="http://malcolmmielle.wordpress.com/"><img src="https://avatars.githubusercontent.com/u/4457840?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Malcolm Mielle</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=MalcolmMielle" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://snippets.page/"><img src="https://avatars.githubusercontent.com/u/74916913?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Veesar</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=veesar" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/bentongxyz"><img src="https://avatars.githubusercontent.com/u/60358804?v=4?s=60" width="60px;" alt=""/><br /><sub><b>bentongxyz</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=bentongxyz" title="Code">💻</a></td>
+    <td align="center"><a href="https://brianjdevries.com"><img src="https://avatars.githubusercontent.com/u/42778030?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Brian DeVries</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=techCarpenter" title="Code">💻</a></td>
+  </tr>
+  <tr>
+    <td align="center"><a href="http://Cliffordfajardo.com"><img src="https://avatars.githubusercontent.com/u/6743796?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Clifford Fajardo </b></sub></a><br /><a href="#tool-cliffordfajardo" title="Tools">🔧</a></td>
+    <td align="center"><a href="http://cu-dev.ca"><img src="https://avatars.githubusercontent.com/u/6589365?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Chris Usick</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=chrisUsick" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/josephdecock"><img src="https://avatars.githubusercontent.com/u/1145533?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Joe DeCock</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=josephdecock" title="Code">💻</a></td>
+    <td align="center"><a href="http://www.drewtyler.com"><img src="https://avatars.githubusercontent.com/u/5640816?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Drew Tyler</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=drewtyler" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/Lauviah0622"><img src="https://avatars.githubusercontent.com/u/43416399?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Lauviah0622</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=Lauviah0622" title="Code">💻</a></td>
+    <td align="center"><a href="https://www.elastic.co/elastic-agent"><img src="https://avatars.githubusercontent.com/u/1813008?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Josh Dover</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=joshdover" title="Code">💻</a></td>
+    <td align="center"><a href="http://phelm.co.uk"><img src="https://avatars.githubusercontent.com/u/4057948?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Phil Helm</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=phelma" title="Documentation">📖</a></td>
+  </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>
+    <td align="center"><a href="http://www.dmurph.com"><img src="https://avatars.githubusercontent.com/u/294026?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Daniel Murphy</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=dmurph" title="Code">💻</a></td>
   </tr>
 </table>
 
@@ -203,14 +251,14 @@ If that sounds like something you're interested in, I'd love to have you along o
 
 ## License
 
-Foam is licensed under the [MIT license](license).
+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

@@ -37,7 +37,7 @@ This principle may seem like it contradicts [Foam wants you to own your thoughts
 
 - **Foam is a collection of ideas.** Foam was released to the public not to share the few good ideas in it, but to learn many good ideas from others. As you improve your own workflow, share your work on your own Foam blog.
 - **Foam is open for contributions.** If you use a tool or workflow that you like that fits these principles, please contribute them back to the Foam template as [[recipes]], [[recommended-extensions]] or documentation in [this workspace](https://github.com/foambubble/foam). See also: [[contribution-guide]].
-- **Foam is open source.** Feel free to fork it, improve it and remix it. Just don't sell it, as per our [license](license).
+- **Foam is open source.** Feel free to fork it, improve it and remix it. Just don't sell it, as per our [license](LICENSE.txt).
 - **Foam is not Roam.** This project was inspired by Roam Research, but we're not limited by what Roam does. No idea is too big (though if it doesn't fit with Foam's core workflow, we might make it a [[recipes]] page instead).
 
 ## Foam is for hackers, not only for programmers
@@ -48,10 +48,9 @@ While Foam uses tools popular among computer programmers, Foam should be inclusi
 - **Foam is not just for programmers.** If you're a programmer, feel free to write scripts and extensions to support your own workflow, and publish them for others to use, but the out of the box Foam experience should not require you to know how to do so. You should, however, be curious and open to adopting new tools that are unfamiliar to you, and evaluate whether they could work for you.
 - **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/publishing/publish-to-github-pages.md

@@ -1,46 +0,0 @@
-# Github Pages
-
-- The [Foam template](https://github.com/foambubble/foam-template) is **GitHub Pages** ready, all you have to do is [turn it on in your repository settings](https://guides.github.com/features/pages/).
-- The default GitHub Pages template is called [Primer](https://github.com/pages-themes/primer). See Primer docs for how to customise html layouts and templates.
-- GitHub Pages is built on [Jekyll](https://jekyllrb.com/), so it supports things like permalinks, front matter metadata etc.
-
-## How to publish locally
-
-If you want to test your published foam, follow the instructions:
-- https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/creating-a-github-pages-site-with-jekyll
-- https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/testing-your-github-pages-site-locally-with-jekyll
-
-Assuming you have installed ruby/jekyll and the rest:
-- `touch Gemfile`
-  - open the file and paste the following:
-```
-source 'https://rubygems.org'
-
-gem "github-pages", "VERSION"
-```
-replacing `VERSION` with the latest from https://rubygems.org/gems/github-pages (e.g. `gem "github-pages", "209"`)
-- `bundle`
-- `bundle exec jekyll 3.9.0 new .`
-- edit the `Gemfile` according to the instructions at [Creating Your Site](https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/creating-a-github-pages-site-with-jekyll#creating-your-site) Point n.8
-- `bundle exec jekyll serve`
-
-
-## Other templates
-There are many other templates which also support publish your foam workspace to github pages
-
-* gatsby-digital-garden
-    * [repo](https://github.com/mathieudutour/gatsby-digital-garden)
-    * [demo-website](https://mathieudutour.github.io/gatsby-digital-garden/)
-* foam-mkdocs-template
-    * [repo](https://github.com/Jackiexiao/foam-mkdocs-template)
-    * [demo-website](https://jackiexiao.github.io/foam/)
-* foam-jekyll-template
-    * [repo](https://github.com/hikerpig/foam-jekyll-template)
-    * [demo-website](https://hikerpig.github.io/foam-jekyll-template/)
-
-[[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"
-[//end]: # "Autogenerated link references"

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

@@ -1,61 +0,0 @@
-# GitLab Pages
-
-You don't have to use GitHub to serve Foam pages. You can also use GitLab.
-
-## Setup a project
-
-### Generate the directory from GitHub
-
-Generate a solution using the [Foam template].
-
-Change the remote to GitLab, or copy all the files into a new GitLab repo.
-
-### Add a _config.yaml
-Add another file to the root directory (the one with `readme.md` in it) called `_config.yaml` (no extension)
-
-```yaml
-title: My Awesome Foam Project
-baseurl: "" # the subpath of your site, e.g. /blog
-url: "/" # the base hostname & protocol for your site
-theme: jekyll-theme-minimal
-plugins:
-  - jekyll-optional-front-matter
-optional_front_matter:
-  remove_originals: true
-defaults:
-  -
-    scope:
-      path: "" # we need to add this to properly render layouts
-    values:
-      layout: "default"
-```
-
-You can choose a theme if you want from places like [Jekyll Themes](https://jekyllthemes.io/)
-
-### Add a Gemlock file
-
-Add another file to the root directory (the one with `readme.md` in it) called `Gemfile` (no extension)
-
-```ruby
-source "https://rubygems.org"
-
-gem "jekyll"
-gem "jekyll-theme-minimal"
-gem "jekyll-optional-front-matter"
-```
-
-Commit the file and push it to gitlab.
-
-## Setup CI/CD
-
-1. From the project home in GitLab click `Set up CI/CD`
-2. Choose `Jekyll` as your template from the template dropdown
-3. Click `commit`
-4. Now when you go to CI / CD > Pipelines, you should see the code running
-
-## Troubleshooting
-
-- *Could not locate Gemfile* - You didn't follow the steps above to [#Add a Gemlock file]
-- *Conversion error: Jekyll::Converters::Scss encountered an error while converting* You need to reference a theme.
-- *Pages are running in CI/CD, but I only ever see `test`, and never deploy* - Perhaps you've renamed the main branch (from master) - check the settings in `.gitlab-ci.yml` and ensure the deploy command is running to the branch you expect it to.
-- *I deployed, but my .msd files don't seem to be being converted into .html files* - You need a gem that GitHub installs by default - check `gem "jekyll-optional-front-matter"` appears in the `Gemfile`

docs/reading-list.md

@@ -5,8 +5,6 @@
 - [VSCode Extensions Packs](https://code.visualstudio.com/blogs/2017/03/07/extension-pack-roundup) [[todo]] Evaluate for deployment
 - [Dark mode](https://css-tricks.com/dark-modes-with-css/)
 
-
-
 [//begin]: # "Autogenerated link references for markdown compatibility"
 [todo]: dev/todo.md "Todo"
 [//end]: # "Autogenerated link references"

docs/terminology.md

@@ -17,4 +17,3 @@ Also happens to sound quite a lot like Home. Funny, that.
 ## Bubble
 
 Individual Foam note, written in Markdown.
-

docs/user/features/backlinking.md

@@ -1,6 +1,6 @@
 # Backlinking
 
-When using [[wiki-links]], you can find all notes that link to a specific note in the [VS Code Markdown Notes](https://marketplace.visualstudio.com/items?itemName=kortina.vscode-markdown-notes) **Backlinks Explorer**
+When using [[wikilinks]], you can find all notes that link to a specific note in the **Backlinks Explorer**
 
 - Run `Cmd` + `Shift` + `P` (`Ctrl` + `Shift` + `P` for Windows), type "backlinks" and run the **Explorer: Focus on Backlinks** view.
 - Keep this pane always visible to discover relationships between your thoughts
@@ -8,8 +8,8 @@ When using [[wiki-links]], you can find all notes that link to a specific note i
 - Finding backlinks in published Foam workspaces via [[materialized-backlinks]] is on the [[roadmap]] but not yet implemented.
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[wiki-links]: ../wiki-links.md "Wiki Links"
+[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/commands.md

@@ -0,0 +1,45 @@
+# Foam Commands
+
+Foam has various commands that you can explore by calling the command palette and typing "Foam".
+
+In particular, some commands can be very customizible and can help with custom workflows and use cases.
+
+## foam-vscode.create-note command
+
+This command creates a note.
+Although it works fine on its own, it can be customized to achieve various use cases.
+Here are the settings available for the command:
+-  notePath: The path of the note to create. If relative it will be resolved against the workspace root.
+- templatePath: The path of the template to use. If relative it will be resolved against the workspace root.
+- text: The text to use for the note. If also a template is provided, the template has precedence
+- variables: Variables to use in the text or template (e.g. `FOAM_TITLE`)
+- date: The date used to resolve the FOAM_DATE_* variables. in `YYYY-MM-DD` format
+- onFileExists?: 'overwrite' | 'open' | 'ask' | 'cancel': What to do in case the target file already exists
+
+To customize a command and associate a key binding to it, open the key binding settings and add the appropriate configuration, here are some examples:
+
+- Create a note called `test note.md` with some text. If the note already exists, ask for a new name
+```
+{
+  "key": "alt+f",
+  "command": "foam-vscode.create-note",
+  "args": {
+    "text": "test note ${FOAM_DATE_YEAR}",
+    "notePath": "test note.md",
+    "onFileExists": "ask"
+  }
+}
+```
+
+- Create a note following the `weekly-note.md` template. If the note already exists, open it
+```
+{
+  "key": "alt+g",
+  "command": "foam-vscode.create-note",
+  "args": {
+    "templatePath": ".foam/templates/weekly-note.md",
+    "onFileExists": "open"
+  }
+}
+```
+

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

@@ -0,0 +1,31 @@
+# Custom Markdown Preview Styles
+
+Visual Studio Code allows you to use your own CSS in the Markdown preview tab.
+
+## Instructions
+
+Custom CSS for the Markdown preview can be implemented by using the `"markdown.styles": []` setting in `settings.json`. The stylesheets can either be https URLs or relative paths to local files in the current workspace.
+
+For example, to load a stylesheet called `Style.css`, we can update `settings.json` with the following line:
+
+```
+{
+  "markdown.styles": ["Style.css"]
+}
+```
+
+## Foam elements
+
+### Foam note & placeholder links
+
+It is possible to custom style the links to a note or placeholder. The links are an `<a>` tag. For notes use the class `foam-note-link`, for placeholders use `foam-placeholder-link`.
+
+### Cyclic inclusion warnings
+
+Foams offers the functionality to include other notes in your note. This will be displayed in the preview tab. Foam recognises a cyclic inclusion of notes and will display a warning when detected. The following html is used and can be custom styled using the class `foam-cyclic-link-warning`.
+
+```html
+<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

@@ -0,0 +1,20 @@
+# Including notes in a note
+
+In some situations it might be useful to include the content of another note in your current note. Foam supports this displaying within the vscode environment. Note, this does not work out-of-the-box for your publishing solutions.
+
+## Including a note
+
+Including a note can be done by adding an `!` before a wikilink defintion. For example `![[wikilink]]`.
+
+## Custom styling
+
+Displaying the inclusion of notes allows for some custom styling, see [[custom-markdown-preview-styles]]
+
+## Future possibilities
+
+Work on this feature is evolving and progressing. See the [[inclusion-of-notes]] proposal for the current discussion.
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[custom-markdown-preview-styles]: custom-markdown-preview-styles.md "Custom Markdown Preview Styles"
+[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,28 +1,30 @@
 # Link Reference Definitions
 
-## Introduction
-
-When you use `[[wiki-links]]`, 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 `[[wiki-links]]`.
+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
 
 The following example:
+
   ```md
-  - [[wiki-links]]
+  - [[wikilinks]]
   - [[github-pages]]
   ```
+
 ...generates the following link reference definitions to the bottom of the file:
+
   ```md
-  [wiki-links]: wiki-links "Wiki Links"
-  [github-pages]: github-pages "Github Pages"
+  [wikilinks]: wikilinks "Wikilinks"
+  [github-pages]: github-pages "GitHub Pages"
   ```
+
 You can open the [raw markdown](https://foambubble.github.io/foam/features/link-reference-definitions.md) to see them at the bottom of this file
 
 ## Specification
 
 The three components of a link reference definition are `[link-label]: link-target "Link Title"`
 
-- **link label:** The link text to match in the surrounding markdown document. This matches the inner bracket of the double-bracketed `[[wiki-link]]` notation
+- **link label:** The link text to match in the surrounding markdown document. This matches the inner bracket of the double-bracketed `[[wikilink]]` notation
 - **link destination** The target of the matched link
   - By default we generate links without extension. This can be overridden, see [Configuration](#configuration) below
 - **"Link Title"** Optional title for link (The Foam template has a snippet of JavaScript to replace this on the website at runtime)
@@ -61,15 +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

@@ -0,0 +1,187 @@
+# Note Templates
+
+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 `.md` files located in the special `.foam/templates` directory of your workspace.
+
+## Quickstart
+
+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)
+
+_Theme: Ayu Light_
+
+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)
+
+_Theme: Ayu Light_
+
+## Special templates
+### Default template
+
+The `.foam/templates/new-note.md` template is special in that it is the template that will be used by the `Foam: Create New Note` command.
+Customize this template to contain content that you want included every time you create a note.
+
+### Default daily note template
+
+The `.foam/templates/daily-note.md` template is special in that it is the template that will be used when creating daily notes (e.g. by using `Foam: Open Daily Note`).
+Customize this template to contain content that you want included every time you create a daily note.
+
+## Variables
+
+Templates can use all the variables available in [VS Code Snippets](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_variables).
+
+In addition, you can also use variables provided by Foam:
+
+| Name                 | Description                                                                                                                                                                                                                 |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `FOAM_SELECTED_TEXT` | Foam will fill it with selected text when creating a new note, if any text is selected. Selected text will be replaced with a wikilink to the new note.                                                                     |
+| `FOAM_TITLE`         | The title of the note. If used, Foam will prompt you to enter a title for the note.                                                                                                                                         |
+| `FOAM_SLUG`          | The sluggified title of the note (using the default github slug method). If used, Foam will prompt you to enter a title for the note unless `FOAM_TITLE` has already caused the prompt.                                     |
+| `FOAM_DATE_*`        | `FOAM_DATE_YEAR`, `FOAM_DATE_MONTH`, etc. Foam-specific versions of [VS Code's datetime snippet variables](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_variables). Prefer these versions over VS Code's. |
+
+### `FOAM_DATE_*` variables
+
+Foam defines its own set of datetime variables that have a similar behaviour as [VS Code's datetime snippet variables](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_variables).
+
+For example, `FOAM_DATE_YEAR` has the same behaviour as VS Code's `CURRENT_YEAR`, `FOAM_DATE_SECONDS_UNIX` has the same behaviour as `CURRENT_SECONDS_UNIX`, etc.
+
+By default, prefer using the `FOAM_DATE_` versions. The datetime used to compute the values will be the same for both `FOAM_DATE_` and VS Code's variables, with the exception of the creation notes using the daily note template.
+
+#### Relative daily notes
+
+When referring to daily notes, you can use the relative snippets (`/+1d`, `/tomorrow`, etc.). In these cases, the new notes will be created with the daily note template, but the datetime used should be the relative datetime, not the current datetime.
+By using the `FOAM_DATE_` versions of the variables, the correct relative date will populate the variables, instead of the current datetime.
+
+For example, given this daily note template (`.foam/templates/daily-note.md`):
+
+```markdown
+# $FOAM_DATE_YEAR-$FOAM_DATE_MONTH-$FOAM_DATE_DATE
+
+## Here's what I'm going to do today
+
+* Thing 1
+* Thing 2
+```
+
+When the `/tomorrow` snippet is used, `FOAM_DATE_` variables will be populated with tomorrow's date, as expected.
+If instead you were to use the VS Code versions of these variables, they would be populated with today's date, not tomorrow's, causing unexpected behaviour.
+
+When creating notes in any other scenario, the `FOAM_DATE_` values are computed using the same datetime as the VS Code ones, so the `FOAM_DATE_` versions can be used in all scenarios by default.
+
+## Metadata
+
+Templates can also contain metadata about the templates themselves. The metadata is defined in YAML "Frontmatter" blocks within the templates.
+
+| Name          | Description                                                                                                                      |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `filepath`    | The filepath to use when creating the new note. If the filepath is a relative filepath, it is relative to the current workspace. |
+| `name`        | A human readable name to show in the template picker.                                                                            |
+| `description` | A human readable description to show in the template picker.                                                                     |
+
+Foam-specific variables (e.g. `$FOAM_TITLE`) can be used within template metadata. However, VS Code snippet variables are ([currently](https://github.com/foambubble/foam/pull/655)) not supported.
+
+### `filepath` attribute
+
+The `filepath` metadata attribute allows you to define a relative or absolute filepath to use when creating a note using the template.
+If the filepath is a relative filepath, it is relative to the current workspace.
+
+**Note:** While you can make use of the `filepath` attribute in [daily note](daily-notes.md) templates (`.foam/templates/daily-note.md`), there is currently no way to have `filepath` vary based on the date. This will be improved in the future. For now, you can customize the location of daily notes using the [`foam.openDailyNote` settings](daily-notes.md).
+
+#### Example of relative `filepath`
+
+For example, `filepath` can be used to customize `.foam/templates/new-note.md`, overriding the default `Foam: Create New Note` behaviour of opening the file in the same directory as the active file:
+
+```yaml
+---
+# This will create the note in the "journal" subdirectory of the current workspace,
+# regardless of which file is the active file.
+foam_template:
+  filepath: 'journal/$FOAM_TITLE.md'
+---
+```
+
+#### Example of absolute `filepath`
+
+`filepath` can be an absolute filepath, so that the notes get created in the same location, regardless of which file or workspace the editor currently has open.
+The format of an absolute filepath may vary depending on the filesystem used.
+
+```yaml
+---
+foam_template:
+  # Unix / MacOS filesystems
+  filepath: '/Users/john.smith/foam/journal/$FOAM_TITLE.md'
+
+  # Windows filesystems
+  filepath: 'C:\Users\john.smith\Documents\foam\journal\$FOAM_TITLE.md'
+---
+```
+
+### `name` and `description` attributes
+
+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)
+
+### Adding template metadata to an existing YAML Frontmatter block
+
+If your template already has a YAML Frontmatter block, you can add the Foam template metadata to it.
+
+#### Limitations
+
+Foam only supports adding the template metadata to *YAML* Frontmatter blocks. If the existing Frontmatter block uses some other format (e.g. JSON), you will have to add the template metadata to its own YAML Frontmatter block.
+
+Further, the template metadata must be provided as a [YAML block mapping](https://yaml.org/spec/1.2/spec.html#id2798057), with the attributes placed on the lines immediately following the `foam_template` line:
+
+```yaml
+---
+existing_frontmatter: "Existing Frontmatter block"
+foam_template: # this is a YAML "Block" mapping ("Flow" mappings aren't supported)
+  name: My Note Template # Attributes must be on the lines immediately following `foam_template`
+  description: This is my note template
+  filepath: `journal/$FOAM_TITLE.md`
+---
+This is the rest of the template
+```
+
+Due to the technical limitations of parsing the complex YAML format, unless the metadata is provided this specific form, Foam is unable to correctly remove the template metadata before creating the resulting note.
+
+If this limitation proves inconvenient to you, please let us know. We may be able to extend our parsing capabilities to cover your use case. In the meantime, you can add the template metadata without this limitation by providing it in its own YAML Frontmatter block.
+
+### Adding template metadata to its own YAML Frontmatter block
+
+You can add the template metadata to its own YAML Frontmatter block at the start of the template:
+
+```yaml
+---
+foam_template:
+  name: My Note Template
+  description: This is my note template
+  filepath: `journal/$FOAM_TITLE.md`
+---
+This is the rest of the template
+```
+
+If the note already has a Frontmatter block, a Foam-specific Frontmatter block can be added to the start of the template. The Foam-specific Frontmatter block must always be placed at the very beginning of the file, and only whitespace can separate the two Frontmatter blocks.
+
+```yaml
+---
+foam_template:
+  name: My Note Template
+  description: This is my note template
+  filepath: `journal/$FOAM_TITLE.md`
+---
+
+---
+existing_frontmatter: "Existing Frontmatter block"
+---
+This is the rest of the template
+```

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,9 @@
+# Spell Checking
+
+There are many spell checking extensions for VS Code.
+
+The most popular spell checker for VS Code is [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker).
+
+Another 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.
+
+Another popular one is [Spellright](https://marketplace.visualstudio.com/items?itemName=ban.spellright), but be mindful that there have been reports of incompatibility with the `vscode-markdown` extension (see https://github.com/foambubble/foam/issues/1068).

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

@@ -0,0 +1,22 @@
+# Frequently Asked Questions
+
+> ⚠️ Foam is still in preview. Expect the experience to be a little rough.
+
+- [Frequently Asked Questions](#frequently-asked-questions)
+  - [Links/Graphs/BackLinks don't work. How do I enable them?](#linksgraphsbacklinks-dont-work-how-do-i-enable-them)
+  - [I don't want Foam enabled for all my workspaces](#i-dont-want-foam-enabled-for-all-my-workspaces)
+
+## Links/Graphs/BackLinks don't work. How do I enable them?
+
+- Ensure that you have all the [[recommended-extensions]] installed in Visual Studio Code
+- Reload Visual Studio Code by running `Cmd` + `Shift` + `P` (`Ctrl` + `Shift` + `P` for Windows), type "reload" and run the **Developer: Reload Window** command to for the updated extensions take effect
+- Check the formatting rules for links on [[foam-file-format]] and [[wikilinks]]
+
+## I don't want Foam enabled for all my workspaces
+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]: 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

@@ -0,0 +1,15 @@
+# Creating New Notes
+
+- Write out a new `[[wikilink]]` and `Cmd` + `Click` to create a new file and enter it.
+  - For keyboard navigation, use the 'Follow Definition' key `F12` (or [remap the 'editor.action.revealDefinition' key binding](https://code.visualstudio.com/docs/getstarted/keybindings) to something more ergonomic)
+- `Cmd` + `Shift` + `P` (`Ctrl` + `Shift` + `P` for Windows), execute `Foam: Create Note` and enter a **Title Case Name** to create `Title Case Name.md`
+  - Add a keyboard binding to make creating new notes easier. See [[commands]] for more info on this.
+  - 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-visualization]].
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[commands]: ../features/commands.md "Foam Commands"
+[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,13 +2,11 @@
 
 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 Notes](https://marketplace.visualstudio.com/items?itemName=kortina.vscode-markdown-notes)
-- [Markdown Links](https://marketplace.visualstudio.com/items?itemName=tchayen.markdown-links)
 - [Markdown All In One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one)
-
+- [Paste Image](https://marketplace.visualstudio.com/items?itemName=mushan.vscode-paste-image)
 
 ## Extensions For Additional Features
 
@@ -16,9 +14,11 @@ These extensions are not (yet?) defined in `.vscode/extensions.json`, but have b
 
 - [Emojisense](https://marketplace.visualstudio.com/items?itemName=bierner.emojisense)
 - [Markdown Emoji](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-emoji) (adds `:smile:` syntax, works with emojisense to provide autocomplete for this syntax)
-- [Mermaid Support for Preview](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid)
+- [Markdown Preview Mermaid Support](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid)
 - [Mermaid Markdown Syntax Highlighting](https://marketplace.visualstudio.com/items?itemName=bpruitt-goddard.mermaid-markdown-syntax-highlighting)
 - [VSCode PDF Viewing](https://marketplace.visualstudio.com/items?itemName=tomoki1207.pdf)
-- [Git Lens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens)
-- [Markdown Extended](https://marketplace.visualstudio.com/items?itemName=jebbs.markdown-extended) (with `kbd` option disabled, `kbd` turns wiki-links into non-clickable buttons)
+- [Project Manager](https://marketplace.visualstudio.com/items?itemName=alefragnani.project-manager) (to quickly switch between projects)
+- [Markdown Extended](https://marketplace.visualstudio.com/items?itemName=jebbs.markdown-extended) (with `kbd` option disabled, `kbd` turns wikilinks into non-clickable buttons)
 - [GitDoc](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.gitdoc) (easy version management via git auto commits)
+- [Markdown Footnotes](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-footnotes) (Adds [^footnote] syntax support to VS Code's built-in markdown preview)
+- [Todo Tree](https://marketplace.visualstudio.com/items?itemName=Gruntfuggly.todo-tree) (Searches workspace for TODO and related comments and summarizes those lines in vs-code gutter)

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/generate-gatsby-site.md

@@ -2,20 +2,22 @@
 
 ## Using foam-gatsby-template
 
-You can use [foam-gatsby-template](https://github.com/mathieudutour/foam-gatsby-template) to generate a static site to host it online on Github or [Vercel](https://vercel.com).
+You can use [foam-gatsby-template](https://github.com/mathieudutour/foam-gatsby-template) to generate a static site to host it online on GitHub or [Vercel](https://vercel.com).
 
 ### Publishing your foam to GitHub pages
-It comes configured with Github actions to auto deploy to Github pages when changes are pushed to your main branch.
+
+It comes configured with GitHub actions to auto deploy to GitHub pages when changes are pushed to your main branch.
 
 ### Publishing your foam to Vercel
 
 When you're ready to publish, run a local build.
+
 ```bash
 cd _layouts
 npm run build
 ```
 
-Remove `public` from your .gitignore file then commit and push your public folder in `_layouts` to Github.
+Remove `public` from your .gitignore file then commit and push your public folder in `_layouts` to GitHub.
 
 Log into your Vercel account. (Create one if you don't have it already.)
 
@@ -26,3 +28,7 @@ That's it!
 ## Using foam-template-gatsby-kb
 
 You can use another template [foam-template-gatsby-kb](https://github.com/hikerpig/foam-template-gatsby-kb), and host it on [Vercel](https://vercel.com) or [Netlify](https://www.netlify.com/).
+
+## Using foam-template-gatsby-theme-primer-wiki
+
+You can use another template [foam-template-gatsby-theme-primer-wiki](https://github.com/theowenyoung/foam-template-gatsby-theme-primer-wiki), ([Demo](https://demo-wiki.owenyoung.com/)), and host it on Github Pages, [Vercel](https://vercel.com) or [Netlify](https://www.netlify.com/).