Setup Language Server boilerplate (#258 )

docs: Fix typo in Diagrams recipes (#256 )
docs: add spencerwooo as a contributor (#255 )
2026-01-11 15:08:01 -05:00 · 2020-09-10 10:49:02 +01:00 · 2020-09-08 18:04:13 +01:00 · 2020-09-08 16:28:44 +01:00 · 2020-09-08 16:27:06 +01:00 · 2020-09-08 15:55:23 +01:00
138 changed files with 6901 additions and 1179 deletions
--- a/.all-contributorsrc
+++ b/.all-contributorsrc
@@ -175,7 +175,8 @@
      "profile": "https://anku.netlify.com/",
      "contributions": [
        "doc",
-        "test"
+        "test",
+        "code"
      ]
    },
    {
@@ -186,7 +187,227 @@
      "contributions": [
        "doc"
      ]
+    },
+    {
+      "login": "TaiChi-IO",
+      "name": "TaiChi-IO",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/65092992?v=4",
+      "profile": "https://github.com/TaiChi-IO",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "juanfrank77",
+      "name": "Juan F Gonzalez ",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/12146882?v=4",
+      "profile": "https://github.com/juanfrank77",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "SanketDG",
+      "name": "Sanket Dasgupta",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/8980971?v=4",
+      "profile": "https://sanketdg.github.io",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "nstafie",
+      "name": "Nicholas Stafie",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/10801854?v=4",
+      "profile": "https://github.com/nstafie",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "francishamel",
+      "name": "Francis Hamel",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/36383308?v=4",
+      "profile": "https://github.com/francishamel",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "digiguru",
+      "name": "digiguru",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/619436?v=4",
+      "profile": "http://digiguru.co.uk",
+      "contributions": [
+        "code",
+        "doc"
+      ]
+    },
+    {
+      "login": "chirag-singhal",
+      "name": "CHIRAG SINGHAL",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/42653703?v=4",
+      "profile": "https://github.com/chirag-singhal",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "lostintangent",
+      "name": "Jonathan Carter",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/116461?v=4",
+      "profile": "https://github.com/lostintangent",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "synesthesia",
+      "name": "Julian Elve",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/181399?v=4",
+      "profile": "https://www.synesthesia.co.uk",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "thomaskoppelaar",
+      "name": "Thomas Koppelaar",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/36331365?v=4",
+      "profile": "https://github.com/thomaskoppelaar",
+      "contributions": [
+        "question",
+        "code",
+        "userTesting"
+      ]
+    },
+    {
+      "login": "MehraAkshay",
+      "name": "Akshay",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/8671497?v=4",
+      "profile": "http://www.akshaymehra.com",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "johnlindquist",
+      "name": "John Lindquist",
+      "avatar_url": "https://avatars0.githubusercontent.com/u/36073?v=4",
+      "profile": "http://johnlindquist.com",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "epicfaace",
+      "name": "Ashwin Ramaswami",
+      "avatar_url": "https://avatars2.githubusercontent.com/u/1689183?v=4",
+      "profile": "https://ashwin.run/",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "Klaudioz",
+      "name": "Claudio Canales",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/632625?v=4",
+      "profile": "https://github.com/Klaudioz",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "vitaly-pevgonen",
+      "name": "vitaly-pevgonen",
+      "avatar_url": "https://avatars0.githubusercontent.com/u/6272738?v=4",
+      "profile": "https://github.com/vitaly-pevgonen",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "dshemetov",
+      "name": "Dmitry Shemetov",
+      "avatar_url": "https://avatars0.githubusercontent.com/u/1810426?v=4",
+      "profile": "https://dshemetov.github.io",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "hooncp",
+      "name": "hooncp",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/48883554?v=4",
+      "profile": "https://github.com/hooncp",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "martinlaws",
+      "name": "Martin Laws",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/13721239?v=4",
+      "profile": "http://rt-canada.ca",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "sksmith",
+      "name": "Sean K Smith",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/2085441?v=4",
+      "profile": "http://seanksmith.me",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "kneely",
+      "name": "Kevin Neely",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/37545028?v=4",
+      "profile": "https://www.linkedin.com/in/kevin-neely/",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "ariefrahmansyah",
+      "name": "Arief Rahmansyah",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/8122852?v=4",
+      "profile": "https://ariefrahmansyah.dev",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "vHanda",
+      "name": "Vishesh Handa",
+      "avatar_url": "https://avatars2.githubusercontent.com/u/426467?v=4",
+      "profile": "http://vhanda.in",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "HeroicHitesh",
+      "name": "Hitesh Kumar",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/37622734?v=4",
+      "profile": "http://www.linkedin.com/in/heroichitesh",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "spencerwooo",
+      "name": "Spencer Woo",
+      "avatar_url": "https://avatars2.githubusercontent.com/u/32114380?v=4",
+      "profile": "https://spencerwoo.com",
+      "contributions": [
+        "doc"
+      ]
    }
  ],
-  "contributorsPerLine": 7
+  "contributorsPerLine": 7,
+  "skipCi": true
 }
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
--- a/.github/workflows/foam-cli.yml
+++ b/.github/workflows/foam-cli.yml
@@ -0,0 +1,25 @@
+name: Test foam-cli
+
+on:
+  pull_request:
+    paths:
+      - 'packages/foam-cli/**'
+  push:
+    paths:
+      - 'packages/foam-cli/**'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+      - uses: actions/setup-node@v1
+
+      - name: Install dependencies
+        run: yarn
+
+      # - name: Lint foam-lint
+      #   run: yarn workspace foam-cli lint
+
+      - name: Test foam-cli
+        run: yarn workspace foam-cli test
--- a/.github/workflows/foam-core.yml
+++ b/.github/workflows/foam-core.yml
@@ -0,0 +1,25 @@
+name: Test foam-core
+
+on:
+  pull_request:
+    paths:
+      - 'packages/foam-core/**'
+  push:
+    paths:
+      - 'packages/foam-core/**'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+      - uses: actions/setup-node@v1
+
+      - name: Install dependencies
+        run: yarn
+
+      - name: Lint foam-core
+        run: yarn workspace foam-core lint
+
+      - name: Test foam-core
+        run: yarn workspace foam-core test
--- a/.github/workflows/foam-vscode.yml
+++ b/.github/workflows/foam-vscode.yml
@@ -0,0 +1,29 @@
+name: Test foam-vscode
+
+on:
+  pull_request:
+    paths:
+      - 'packages/foam-vscode/**'
+  push:
+    paths:
+      - 'packages/foam-vscode/**'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+      - uses: actions/setup-node@v1
+
+      - name: Install dependencies
+        run: yarn
+
+      - name: Lint foam-vscode
+        run: yarn workspace foam-vscode lint
+      - name: Test foam-vscode
+        run: yarn workspace foam-vscode test
+      # - name: Publish foam-vscode
+      #   if: github.ref == 'refs/heads/master'
+      #   run: yarn workspace foam-vscode publish-extension
+      #   with:
+      #     vsce_token: ${{ secrets.VSCE_TOKEN }}
--- a/.vscode/launch.json
+++ b/.vscode/launch.json
@@ -6,10 +6,34 @@
 	"version": "0.2.0",
 	"configurations": [
 		{
-             // This task is also defined in packages/foam-vscode/.vscode/launch.json
-             // for when running separately outside of the monorepo environment
-			"name": "Run Extension",
-            "type": "extensionHost",
+			"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": [
@@ -18,12 +42,14 @@
 			"outFiles": [
 				"${workspaceFolder}/packages/foam-vscode/out/**/*.js"
 			],
-			"preLaunchTask": "Build foam-vscode"
+			"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!
 		{
-            // This task is also defined in packages/foam-vscode/.vscode/launch.json
-            // for when running separately outside of the monorepo environment
-			"name": "Extension Tests",
+			"name": "Test VSCode Extension",
 			"type": "extensionHost",
 			"request": "launch",
 			"runtimeExecutable": "${execPath}",
@@ -34,16 +60,36 @@
 			"outFiles": [
 				"${workspaceFolder}/packages/foam-vscode/out/test/**/*.js"
 			],
-			"preLaunchTask": "Build foam-vscode"
+			"preLaunchTask": "${defaultBuildTask}"
 		},
 		{
+			"name": "Test Core",
 			"type": "node",
 			"request": "launch",
-			"name": "Workspace Manager tests",
 			"program": "${workspaceFolder}/node_modules/tsdx/dist/index.js",
 			"args": ["test"],
 			"cwd": "${workspaceFolder}/packages/foam-core",
-			"internalConsoleOptions": "openOnSessionStart"
+			"internalConsoleOptions": "openOnSessionStart",
+			"preLaunchTask": "${defaultBuildTask}"
+		},
+		{
+			"name": "Debug Language Server",
+			"type": "node",
+			"request": "attach",
+			"port": 6009,
+			// large timeout to account for typescript watch startup time
+			"timeout": 30000,
+			"restart": true,
+			"trace": true,
+			"localRoot": "${workspaceFolder}/packages/foam-language-server/src/",
+			"remoteRoot": "${workspaceFolder}/packages/foam-language-server/dist/",
+			"outFiles": ["${workspaceFolder}/packages/foam-language-server/dist/**/*.js"]
+		},
+	],
+	"compounds": [
+		{
+			"name": "Run Extension & Debug LSP",
+			"configurations": ["Run VSCode Extension", "Debug Language Server"]
 		}
 	]
 }
--- a/.vscode/tasks.json
+++ b/.vscode/tasks.json
@@ -4,19 +4,28 @@
 	"version": "2.0.0",
 	"tasks": [
 		{
-            // This task is also defined in packages/foam-vscode/.vscode/tasks.json
-            // for when running separately outside of the monorepo environment
-            "type": "npm",
-            "script": "watch",
-            "label": "Build foam-vscode",
-            "path": "packages/foam-vscode",
-            "problemMatcher": "$tsc-watch",
+			"label": "watch: foam-vscode",
+			"type": "npm",
+			"script": "start:vscode",
+			"problemMatcher": "$tsc-watch",
 			"isBackground": true,
 			"presentation": {
-				"reveal": "silent",
-				"revealProblems": "onProblem",
-				"focus": true
+				"reveal": "always"
+			},
+			"group": {
+				"kind": "build",
+				"isDefault": true
 			}
+		},
+		{
+			"label": "test: all packages",
+			"type": "npm",
+			"script": "test",
+			"problemMatcher": [],
+			"group": {
+				"kind": "test",
+				"isDefault": true
+			},
 		}
 	]
 }
--- a/docs/.vscode/settings.json
+++ b/docs/.vscode/settings.json
@@ -5,6 +5,7 @@
  "editor.overviewRulerBorder": false,
  "editor.lineHeight": 24,
  "workbench.colorTheme": "Gray Matter Light",
+  "vscodeMarkdownNotes.noteCompletionConvention": "noExtension",
  "[markdown]": {
    "editor.quickSuggestions": {
      "other": true,
--- a/docs/_layouts/foam.html
+++ b/docs/_layouts/foam.html
@@ -0,0 +1,52 @@
+---
+layout: default
+---
+
+<script type="text/javascript">
+// NOTE: this should be in sync with the settings/usage in the vscode extension
+// atm it's just a wide superset of md extensions to cover a wide range of cases
+var MD_EXT = ['.md', '.markdown', '.mdx', '.mdown', '.mkdn', '.mkd', '.mdwn', '.mdtxt', '.mdtext', '.text', '.Rmd'];
+function normalizeMdLink(link) {
+  var url = new URL(link);
+  var mdFileExt = MD_EXT.find(ext => url.pathname.endsWith(ext));
+  if (mdFileExt) {
+    url.pathname = url.pathname.slice(0, mdFileExt.length * -1);
+  }
+  return url.toString();
+}
+
+window.addEventListener('DOMContentLoaded', (event) => {
+  document
+    .querySelectorAll(".markdown-body a[title]:not([href^=http])")
+    .forEach((a) => {
+      // filter to only wiki-links
+      var prev = a.previousSibling;
+      var next = a.nextSibling;
+      if (
+        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;
+
+        // ...and normalize the links to allow html pages navigation
+        a.href = normalizeMdLink(a.href);
+      }
+    });
+
+  document.querySelectorAll(".github-only").forEach((el) => {
+    el.remove();
+  });
+});
+</script>
+
+
+{{ content }}
--- a/docs/_layouts/home.html
+++ b/docs/_layouts/home.html
@@ -1,25 +1,16 @@
 ---
-layout: default
+layout: foam
 ---

 <script async defer src="https://buttons.github.io/buttons.js"></script>

 {{ content }}

-<script type="text/javascript">
-  // Hack: Replace page-link with "Page Title"
-  document
-    .querySelectorAll(".markdown-body a[title]:not([href^=http])")
-    .forEach((a) => {
-      a.innerText = a.title;
-    });
-
-  document.querySelectorAll(".github-only").forEach((el) => {
-    el.remove();
-  });
-
+<script>
+window.addEventListener('DOMContentLoaded', (event) => {
  var duplicateHeading = document.querySelector("h1:not(#foam)");
  if (duplicateHeading && duplicateHeading.remove) {
    duplicateHeading.remove();
  }
+});
 </script>
--- a/docs/_layouts/mathjax.html
+++ b/docs/_layouts/mathjax.html
@@ -0,0 +1,15 @@
+---
+layout: foam
+---
+
+{{ content }}
+
+<script src="https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML" type="text/javascript"></script>
+<script type="text/x-mathjax-config">
+    MathJax.Hub.Config({
+        tex2jax: {
+            skipTags: ['script', 'noscript', 'style', 'textarea', 'pre'],
+            inlineMath: [['$','$']]
+        }
+    });
+</script>
--- a/docs/_layouts/page.html
+++ b/docs/_layouts/page.html
@@ -1,18 +1,5 @@
 ---
-layout: default
+layout: foam
 ---

 {{ content }}
-
-<script type="text/javascript">
-  // Hack: Replace page-link with "Page Title"
-  document
-    .querySelectorAll(".markdown-body a[title]:not([href^=http])")
-    .forEach((a) => {
-      a.innerText = a.title;
-    });
-
-  document.querySelectorAll(".github-only").forEach((el) => {
-    el.remove();
-  });
-</script>
--- a/docs/assets/css/style.scss
+++ b/docs/assets/css/style.scss
@@ -52,6 +52,16 @@ blockquote {
    "DejaVu Serif", "Bitstream Vera Serif", "Liberation Serif", Georgia, serif;
 }

+.wikilink:before {
+  content: "[[";
+  opacity: 0.5;
+}
+
+.wikilink:after {
+  content: "]]";
+  opacity: 0.5;
+}
+
 .github-only {
  display: none;
 }
--- a/docs/assets/images/azure-devops-wiki-demo.png
+++ b/docs/assets/images/azure-devops-wiki-demo.png
--- a/docs/assets/images/custom-snippet.gif
+++ b/docs/assets/images/custom-snippet.gif
--- a/docs/assets/images/daily-note.gif
+++ b/docs/assets/images/daily-note.gif
--- a/docs/assets/images/diagram-drawio-demo.drawio.svg
+++ b/docs/assets/images/diagram-drawio-demo.drawio.svg
@@ -0,0 +1,68 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="281px" height="181px" viewBox="-0.5 -0.5 281 181" content="&lt;mxfile host=&quot;dd26700e-36c4-4a92-a6df-21c7be0d8350&quot; modified=&quot;2020-08-31T10:44:14.509Z&quot; agent=&quot;5.0 (Macintosh; Intel Mac OS X 10_15_4) AppleWebKit/537.36 (KHTML, like Gecko) Code/1.48.2 Chrome/78.0.3904.130 Electron/7.3.2 Safari/537.36&quot; etag=&quot;ygaBEVmOlivkHZFzXaxy&quot; version=&quot;13.1.3&quot;&gt;&lt;diagram id=&quot;6hGFLwfOUW9BJ-s0fimq&quot; name=&quot;Page-1&quot;&gt;1ZVNT4NAEIZ/DVdT2NrWq7XqQU89aI+bMsKahSHboYC/3qXMAhvUmJi08QTzzMcy72yGQKyz+sHIIn3GGHQQzeI6EHdBFIXLcGUfLWmYhMvrjiRGxcwGsFUfwHDGtFQxHLxAQtSkCh/uMc9hTx6TxmDlh72h9k8tZAITsN1LPaUvKqa0o6toOfBHUEnqTg4XN50nky6YOzmkMsZqhMQmEGuDSN1bVq9Bt+o5Xbq8+2+8/YcZyOk3Caz7gRrXG8S2VTbRUIoJ5lJvBnprsMxjaAvMrDXEPCEWFoYWvgNRw3OTJaFFKWWavVArem3Tr+z5nbkbue5qLn0yGmfkZJou69qZu7FvSDtZLq9rsO3qW4kYHbA0e46K+FZJkwBHiX489mIDZmBPsSEGtCR19KtLvmBJHzfMwL7wGL4eyeKyI1n+o5HMzzQSPvoodekXHQ3JH0GVKoJtIU8fX9k16MvN9cAQ1D9rMO2OE6I5rxC3RN1KqYaN1LN0tI0Ws78LIiaCRBcXJFz4gvQCnUOQ+UQQcXFBRHQ+Qaw5/LROvtG/X2w+AQ==&lt;/diagram&gt;&lt;/mxfile&gt;">
+    <defs/>
+    <g>
+        <path d="M 110 60 L 110 90 L 60 90 L 60 113.63" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/>
+        <path d="M 60 118.88 L 56.5 111.88 L 60 113.63 L 63.5 111.88 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/>
+        <path d="M 170 60 L 170 90 L 220 90 L 220 113.63" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/>
+        <path d="M 220 118.88 L 216.5 111.88 L 220 113.63 L 223.5 111.88 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/>
+        <rect x="80" y="0" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 30px; margin-left: 81px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">
+                                1
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="140" y="34" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    1
+                </text>
+            </switch>
+        </g>
+        <rect x="0" y="120" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 150px; margin-left: 1px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">
+                                2
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="60" y="154" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    2
+                </text>
+            </switch>
+        </g>
+        <rect x="160" y="120" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 150px; margin-left: 161px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">
+                                3
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="220" y="154" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    3
+                </text>
+            </switch>
+        </g>
+    </g>
+    <switch>
+        <g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/>
+        <a transform="translate(0,-5)" xlink:href="https://desk.draw.io/support/solutions/articles/16000042487" target="_blank">
+            <text text-anchor="middle" font-size="10px" x="50%" y="100%">
+                Viewer does not support full SVG 1.1
+            </text>
+        </a>
+    </switch>
+</svg>
--- a/docs/assets/images/foam-janitor-demo.gif
+++ b/docs/assets/images/foam-janitor-demo.gif
--- a/docs/assets/images/markdown-snippets.gif
+++ b/docs/assets/images/markdown-snippets.gif
--- a/docs/assets/images/md-notes-autocomplete-no-extension.png
+++ b/docs/assets/images/md-notes-autocomplete-no-extension.png
--- a/docs/assets/images/md-notes-autocomplete-with-extension.png
+++ b/docs/assets/images/md-notes-autocomplete-with-extension.png
--- a/docs/assets/images/migrating-one-note.png
+++ b/docs/assets/images/migrating-one-note.png
--- a/docs/assets/images/snippets.gif
+++ b/docs/assets/images/snippets.gif
--- a/docs/assets/images/vercel-detect-preset.png
+++ b/docs/assets/images/vercel-detect-preset.png
--- a/docs/azure-devops-wiki.md
+++ b/docs/azure-devops-wiki.md
@@ -0,0 +1,63 @@
+# Azure DevOps Wiki
+
+Publish your Foam workspace as an Azure DevOps wiki.
+
+[Azure DevOps](https://azure.microsoft.com/en-us/services/devops/) is Microsoft's collaboration software for software development teams, formerly known as Team Foundation Server (TFS) and Visual Studio Team Services. It is available as an on-premise or SaaS version. The following recipe was tested with the SaaS version, but should work the same way for the on-premise.
+
+The following recipe is written with the assumption that you already have an [Azure DevOps](https://azure.microsoft.com/en-us/services/devops/) project.
+
+## Setup a Foam workspace
+
+1. Generate a Foam workspace using the [foam-template project](https://github.com/foambubble/foam-template). 
+2. Change the remote to a git repository in Azure DevOps (Repos -> Import a Repository -> Add Clone URL with Authentication), or copy all the files into a new Azure DevOps git repository.
+3. Define which document will be the wiki home page. To do that, create a file called `.order` in the Foam workspace root folder, with first line being the document filename without `.md` extension. For a project created from the Foam template, the file would look like this:
+```
+readme
+```
+4. Push the repository to remote in Azure DevOps.
+
+## Publish repository to a wiki
+
+
+1. Navigate to your Azure DevOps project in a web browser.
+2. Choose **Overview** > **Wiki**. If you don't have wikis for your project, choose **Publish code as a wiki** on welcome page. 
+3. Choose repository with your Foam workspace, branch (usually `master` or `main`), folder (for workspace created from foam-template it is `/`), and wiki name, and press **Publish**.
+
+A published workspace looks like this:
+
+![Azure DevOps wiki](assets/images/azure-devops-wiki-demo.png)
+
+There is default table of contents pane to the left of the wiki content. Here, you'll find a list of all directories that are present in your Foam workspace, and all wiki pages. Page names are derived from files names, and they are listed in alphabetical order. You may reorder pages by adding filenames without `.md` extension to `.order` file. 
+
+_Note that first entry in `.order` file defines wiki's home page._
+
+## Update wiki
+
+While you are pushing changes to GitHub, you won't see the wiki updated if you don't add Azure as a remote. You can push to multiple repositories simultaneously.
+ 
+ 1. First open a terminal and check if Azure is added running: `git remote show origin`. If you don't see Azure add it in the output then follow these steps.
+ 2. Rename your current remote (most likely named origin) to a different name by running: `git remote rename origin main`
+ 3. You can then add the remote for your second remote repository, in this case, Azure. e.g `git remote add azure https://<YOUR_ID>@dev.azure.com/<YOUR_ID>/foam-notes/_git/foam-notes`. You can get it from: Repos->Files->Clone and copy the URL.
+ 4. Now, you need to set up your origin remote to push to both of these. So run: `git config -e` and edit it.
+ 5. Add the `remote origin` section to the bottom of the file with the URLs from each remote repository you'd like to push to. You'll see something like that:
+ ```bash
+ [core]
+  ... 
+   (ignore this part)
+   ... 
+[branch "master"]
+  remote = github
+  merge = refs/heads/master
+[remote "github"]
+  url = git@github.com:username/repo.git
+  fetch = +refs/heads/*:refs/remotes/github/*
+[remote "azure"]
+  url = https://<YOUR_ID>@dev.azure.com/<YOUR_ID>/foam-notes/_git/foam-notes
+  fetch = +refs/heads/*:refs/remotes/azure/*
+[remote "origin"]
+  url = git@github.com:username/repo.git
+  url = https://<YOUR_ID>@dev.azure.com/<YOUR_ID>/foam-notes/_git/foam-notes
+ ```
+ 6. You can then push to both repositories by: `git push origin master` or a single one using: `git push github master` or `git push azure master`
+  
+For more information, read the [Azure DevOps documentation](https://docs.microsoft.com/en-us/azure/devops/project/wiki/publish-repo-to-wiki). 
--- a/docs/backlinking.md
+++ b/docs/backlinking.md
@@ -9,6 +9,7 @@ When using [[wiki-links]], you can find all notes that link to a specific note i

 [//begin]: # "Autogenerated link references for markdown compatibility"
 [wiki-links]: wiki-links "Wiki Links"
+[make-backlinks-more-prominent]: make-backlinks-more-prominent "Make Backlinks More Prominent"
 [materialized-backlinks]: materialized-backlinks "Materialized Backlinks (stub)"
 [roadmap]: roadmap "Roadmap"
 [//end]: # "Autogenerated link references"
--- a/docs/capture-notes-with-drafts-pro.md
+++ b/docs/capture-notes-with-drafts-pro.md
@@ -0,0 +1,142 @@
+# Capture Notes With Drafts Pro
+
+## Context
+
+* You use [Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode) to manage your notes
+* You wish to adopt a practice such as [A writing inbox for transient and incomplete notes](https://notes.andymatuschak.org/A%20writing%20inbox%20for%20transient%20and%20incomplete%20notes)
+* You wish to use [Drafts Pro](https://docs.getdrafts.com/) to capture quick notes into your Foam notes from your iOS device
+
+## Required Extensions
+
+* [Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode)
+
+## Other tools
+
+* We assume you are familiar with how to use GitHub (if you are using Foam this is implicit)
+* You have an iOS device with [Drafts](https://getdrafts.com/)
+* You have upgraded to [Drafts Pro](https://docs.getdrafts.com/draftspro) (needed to edit actions).
+
+## Instructions
+
+1. [Create a new action in Drafts](https://docs.getdrafts.com/docs/actions/editing-actions)
+2. Add a single [step](https://docs.getdrafts.com/actions/steps/) of type Script
+3. Edit the script adding the code from the block below
+4. Edit settings at the top of the script to suit your preferences
+5. Set other Action options in Drafts as you wish
+6. Save the Action
+7. In GitHub [create a Personal Access Token](https://github.com/settings/tokens) and give it `repo` scope - make a note of the token
+8. In Drafts create a note
+9. Select the action you created in steps 1-6
+10. On the first run you will need to add the following information:
+    1. your GitHub username
+    2. the repository name of your Foam repo
+    3. the GitHub access token from step 7
+    4. An author name
+11. Check your Github repo for a commit
+12. If you are publishing your Foam to the web you may want to edit your publishing configuration to exclude inbox files - as publishing (and method) is a user choice that is beyond the scope of this recipe
+
+## Code for Drafts Action
+
+```javascript
+// adapted from https://forums.getdrafts.com/t/script-step-post-to-github-without-working-copy/3594
+// post to writing inbox in Foam digital garden
+
+/*
+ * edit these lines to suit your preferences
+ */
+const inboxFolder = "inbox/";   // the folder in your Foam repo where notes are saved. MUST have trailing slash, except for root of repo use ''
+const requiredTags = ['inbox']; // all documents will have these added in addition to tags from the Drafts app
+const addLinkToInbox = true;    // true = created note will have link to [[index]], false = no link
+const addTimeStamp = true;      // true = add a note of capture date/time at foot of note
+
+/*
+ * stop editing
+ */
+
+const credential = Credential.create("GitHub garden repo", "The repo name, and its credentials, hosting your Foam notes");
+credential.addTextField("username", "GitHub Username");
+credential.addTextField('repo', 'Repo name');
+credential.addPasswordField("key", "GitHub personal access token");
+credential.addTextField('author', 'Author');
+credential.authorize();
+
+const githubKey = credential.getValue('key');
+const githubUser = credential.getValue('username');
+const repo = credential.getValue('repo');
+const author = credential.getValue('author');
+
+const http = HTTP.create(); // create HTTP object
+const base = 'https://api.github.com';
+
+
+const posttime = new Date();
+const title = draft.title;  
+const txt = draft.processTemplate("[[line|3..]]");
+const mergedTags = [...draft.tags, ...requiredTags];
+const slugbase = title.toLowerCase().replace(/\s/g, "-");
+
+const datestr = `${posttime.getFullYear()}-${pad(posttime.getMonth() + 1)}-${pad(posttime.getDate())}`;
+const timestr = `${pad(posttime.getHours())}:${pad(posttime.getMinutes())}:00`;
+const yr = `${posttime.getFullYear()}`;
+const pdOffset = posttime.getTimezoneOffset();
+const offsetChar = pdOffset >= 0 ? '-' : '+';
+var pdHours = Math.floor(pdOffset/60);
+console.log(pdHours);
+pdHours = pdHours >= 0 ? pdHours : pdHours * -1;
+console.log(pdHours);
+const tzString = `${offsetChar}${pad(pdHours)}:00`;
+const postdate = `${datestr}T${timestr}${tzString}`;
+
+
+const slug = `${slugbase}`
+const fn = `${slug}.md`;
+let preamble = `# ${title} \n\n`;
+
+mergedTags.forEach(function(item,index){
+   preamble += `#${item} `;
+  }
+);
+
+if (addLinkToInbox) {
+    preamble += "\n\n[[inbox]]\n";
+}
+
+preamble += "\n\n";
+
+var doc = `${preamble}${txt}`;
+
+if (addTimeStamp){
+
+    doc += `\n\nCaptured: ${postdate}\n`
+}
+
+const options = {
+    url: `https://api.github.com/repos/${githubUser}/${repo}/contents/${inboxFolder}${fn}`,
+    method: 'PUT',
+    data: {
+        message: `Inbox from Drafts ${datestr}`,
+        content: Base64.encode(doc)
+    },
+    headers: {
+        'Authorization': `token ${githubKey}`
+    }
+};
+
+var response = http.request(options);
+
+if (response.success) {
+    // yay
+} else {
+    console.log(response.statusCode);
+    console.log(response.error);
+}
+
+function pad(n) {
+    let str = String(n);
+    while (str.length < 2) {
+        str = `0${str}`;
+    }
+    return str;
+}
+
+```
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -9,7 +9,5 @@ Create a CLI tool to allow running common Foam commands. These may include:
 More commands to be added.

 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[roadmap]: roadmap "Roadmap"
-[workspace-janitor]: workspace-janitor "Workspace Janitor (stub)"
+[workspace-janitor]: workspace-janitor "Janitor"
 [//end]: # "Autogenerated link references"
--- a/docs/code-of-conduct.md
+++ b/docs/code-of-conduct.md
@@ -129,6 +129,4 @@ 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.

-[//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[//end]: # "Autogenerated link references"
+
--- a/docs/contribution-guide.md
+++ b/docs/contribution-guide.md
@@ -2,12 +2,12 @@

 > [[todo]] [[good-first-task]] This contribution guide itself could be improved 😅

-Foam is open to contributions of any kind, including but not limited to code, documentation, ideas and feedback. Here are some general tips on how to get started on contributing to Foam:
+Foam is open to contributions of any kind, including but not limited to code, documentation, ideas, and feedback. Here are some general tips on how to get started on contributing to Foam:

 - Use Foam for yourself, figure out what could be improved.
 - Check out [[roadmap]] to see what's already in the plans. I have thoughts about how to implement some of these, but open to ideas and code contributions!
 - Read about our [[principles]] to understand Foam's philosophy and direction
- Read and act in accordance of our [[code-of-conduct]].
+- Read and act in accordance with our [[code-of-conduct]].
 - Feel free to open [GitHub issues](https://github.com/foambubble/foam/issues) to give me feedback and ideas for new features.
 - Foam code and documentation live in the monorepo at [foambubble/foam](https://github.com/foambubble/foam/)
  - [/docs](https://github.com/foambubble/foam/docs): documentation and [[recipes]]
--- a/docs/creating-a-new-language.md
+++ b/docs/creating-a-new-language.md
@@ -1,3 +1,5 @@
+# Creating a New Language
+
 ## Creating a new language

 What if we created a new language that made it more ergonomic to use VS Code as a Foam workspace
--- a/docs/creating-new-notes.md
+++ b/docs/creating-new-notes.md
@@ -1,7 +1,8 @@
 # Creating New Notes

- Write out a new `[[wiki-link]]` and `Cmd` + `Click` to create a new file.
- `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`
+- 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 categorising your notes. You can always [[search-for-notes]], and explore them using the [[graph-visualisation]].

--- a/docs/custom-snippets.md
+++ b/docs/custom-snippets.md
@@ -0,0 +1,10 @@
+# Adding Custom Snippets
+
+You can add custom snippets whilst the default set of snippets are decided by following the below steps:
+
+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)
+
+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).
--- a/docs/daily-notes.md
+++ b/docs/daily-notes.md
@@ -1,36 +1,54 @@
 # Daily notes

-The idea is to make it easier for people to be able to create 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.

-This feature is open for discussion at [foambubble/foam#54](https://github.com/foambubble/foam/issues/54).
+![Daily note feature in action](assets/images/daily-note.gif)

-## Must have
+## Keyboard shortcut

- Should exist as part of [foam-vscode](https://github.com/foambubble/foam/tree/master/packages/foam-vscode) extension 
- A new command "Foam: Open Daily Note", which creates new file and focuses into it, or opens the existing file for today if it exists already.
-  - File should have a Level 1 `# Heading`
- Extension should define a hotkey for it (TBD? What do other apps do?)
+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).

-## Should have
+## Configuration

- Settings to customise:
-  - Format of file name, default to `yyyy-mm-dd`
-  - Format of title
-    - Default to same as file name
-    - Allow override e.g. `MMMMM D, YYYY`, to July 8. 2020 (locale specific)
-  - Extension of file, default to `.md`
-  - Directory into which file should be created, default to `./` (workspace root)
-    - Should create directory if needed
+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`.

-## Could have
- Automatically update a "daily notes" index file, newest first. Format TBD
-  - A custom note template .md file that could be stored in `.vscode/` directory (would supercede having to format the title)
-    - This could be useful for people who e.g. want there to be a format for every day's notes with fixed questions and stuff.
-  - Maybe we could do it with just back links or tags, by putting e.g. `[[daily]]` into the note template
-  - If files were named in alphabetic sortable order, and back links would display in reverse order, newest would always come on top
+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"
-[todo]: todo "Todo"
-[roadmap]: roadmap "Roadmap"
-[//end]: # "Autogenerated link references"
-
+[note-macros]: note-macros "Custom Note Macros"
+[//end]: # "Autogenerated link references"
--- a/docs/diagrams-in-markdown.md
+++ b/docs/diagrams-in-markdown.md
@@ -1,18 +1,31 @@
 # Diagrams in Markdown

-You can use VS Code plugins such as [Mermaid](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid) to draw and preview diagrams in your content.
+We have two alternative recipes for displaying diagrams in markdown:
+
+- [Mermaid](#mermaid)
+- [Draw.io](#drawio)
+
+
+## Mermaid
+
+You can use [Mermaid](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid) plugin to draw and preview diagrams in your content.

 ⚠️ Be aware that Mermaid diagrams don't automatically get rendered in published Foams in [[github-pages]], and would require you to eject to another static site generation approach that supports Mermaid plugins.

---
+## Draw.io

-[[todo]] [[good-first-task]] **Help improve this recipe!** 
+[Draw.io](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio) extension allows you to create, edit, and display your diagrams without leaving Visual Studio Code. The `.drawio.svg` or `.drawio.png` files can be automatically embedded and displayed in published Foams, no export needed. FYI, the diagram below was made using Draw.io! You can check the diagram [here](./assets/images/diagram-drawio-demo.drawio.svg).
+
+![diagram-drawio-demo](./assets/images/diagram-drawio-demo.drawio.svg)
+
+### Using Draw.io
+
+1. Install [Draw.io](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio) VS Code extension.
+2. Create a new `*.drawio.svg` or `*.drawio.png` file.
+3. Start drawing your diagram. Once you done, save it.
+4. Embed the diagram file as you embedding the image file, for example: `![My Diagram](my-diagram.drawio.svg)`

-[[todo]] [[good-first-task]] Suggestions for alternative diagramming approaches welcome

 [//begin]: # "Autogenerated link references for markdown compatibility"
 [github-pages]: github-pages "Github Pages"
-[good-first-task]: good-first-task "Good First Task"
-[todo]: todo "Todo"
-[contribution-guide]: contribution-guide "Contribution Guide"
-[//end]: # "Autogenerated link references"
+[//end]: # "Autogenerated link references"
--- a/docs/eleventy-and-netlify.md
+++ b/docs/eleventy-and-netlify.md
@@ -0,0 +1,19 @@
+# Eleventy and Netlify
+
+You can use [foam-eleventy-template](https://github.com/juanfrank77/foam-eleventy-template) to generate a static site with [Eleventy](https://www.11ty.dev/), and host it online on [Netlify](https://www.netlify.com/). 
+
+With this template you can
+- Have control over what to publish and what to keep private 
+- Customize the styling of the site to your own liking
+
+## Publishing your foam
+
+When you're ready to publish, import the GitHub repository you created with **foam-eleventy-template** into your Netlify account. (Create one if you don't have it already.)
+
+Once that's done, all you have to do is make changes to your workspace in VS Code and push them to the main branch on GitHub. Netlify will recognize the changes, deploy them automatically and give you a link where your Foam is published.
+
+
+That's it!
+
+You can now see it online and use that link to share it with your friends, so that they can see it too.
+
--- a/docs/foam-core.md
+++ b/docs/foam-core.md
@@ -20,7 +20,7 @@
  - Can be either [[wiki-links]] 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
+    - 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
 - Treat each file as semi-structured data
  - Title, headings, lists, paragraphs, images, links, data, code
  - Also, possible Foam-specific meta stuff, like "backlinks" or "block references".
@@ -61,7 +61,7 @@ Here are some example use cases that the core should support. They don't need to

 - Adding and editing page content
  - [[materialized-backlinks]]
-  - [[wiki-links]] reference definitions
+  - [[link-reference-definitions]] for [[wiki-links]]
  - [Frontmatter](https://jekyllrb.com/docs/front-matter/)
 - Finding all documents with `#tag`
 - Finding all documents with instances of `[[link]]`
@@ -96,10 +96,11 @@ 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]: workspace-janitor "Workspace Janitor"
+[workspace-janitor]: workspace-janitor "Janitor"
 [cli]: cli "Command Line Interface"
 [build-vs-assemble]: build-vs-assemble "Build vs Assemble"
 [wiki-links]: wiki-links "Wiki Links"
+[link-reference-definitions]: link-reference-definitions "Link Reference Definitions"
 [materialized-backlinks]: materialized-backlinks "Materialized Backlinks (stub)"
 [todo]: todo "Todo"
 [feature-comparison]: feature-comparison "Feature comparison"
--- a/docs/foam-file-format.md
+++ b/docs/foam-file-format.md
@@ -14,29 +14,9 @@ Here are a few specific constraints, mainly because our tooling is a bit fragmen
 - **File name should have extension `.md` or `.markdown`**
  - 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.**
-  - When you do, 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.
-    - Here's an example:
-      - [[wiki-links]]
-      - [[github-pages]]
-    - This will generate the following references:
-      ```md
-      [wiki-links]: wiki-links "Wiki Links"
-      [github-pages]: github-pages "Github Pages"
-      ```
-    - The three components 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 destination** The target of the matched link
-        - Right now we generate link destinations without file extension. This is a choice, see [discussion here](https://foambubble.github.io/foam/wiki-links#why-dont-wiki-links-work-on-github).
-      - **"Link Title"** Optional title for link (The Foam template has a snippet of JavaScript to replace this on the website at runtime)
-    - Open the [raw markdown](https://raw.githubusercontent.com/foambubble/foam/master/foam-file-format.md) to see them at the bottom of this file
-    - In the near future, these can be batch generated for all workspace files (WIP)
-      - For the time being, if you want to get [[wiki-links]] support across all files, you'll need to generate the link reference definitions yourself.
-      - If you end up writing a batch job for this, please share your solution, as this is something we'll need to implement soon!
+- **In addition to normal Markdown Links syntax you can use `[[media-wiki]]` links.** See [[wiki-links]] for more details.

 [//begin]: # "Autogenerated link references for markdown compatibility"
-[wiki-links]: wiki-links "Wiki Links"
-[github-pages]: github-pages "Github Pages"
 [decision-needed]: decision-needed "Decision Needed"
-[daily-notes]: daily-notes "Daily notes"
+[wiki-links]: wiki-links "Wiki Links"
 [//end]: # "Autogenerated link references"
--- a/docs/frequently-asked-questions.md
+++ b/docs/frequently-asked-questions.md
@@ -0,0 +1,19 @@
+# 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 "Recommended Extensions"
+[foam-file-format]: foam-file-format "Foam File Format"
+[wiki-links]: wiki-links "Wiki Links"
+[link-formatting-and-autocompletion]: link-formatting-and-autocompletion "Link Formatting and Autocompletion"
+[//end]: # "Autogenerated link references"
--- a/docs/gistpad.md
+++ b/docs/gistpad.md
@@ -0,0 +1,51 @@
+# GistPad
+
+[GistPad](https://aka.ms/gistpad) is a Visual Studio Code extension that allows you to edit your GitHub gists and repos, without needing to clone anything locally. It provides support for editing Foam workspaces, complete with `[[link]]` [completion/navigation](https://github.com/vsls-contrib/gistpad#links), [daily pages](https://github.com/vsls-contrib/gistpad#daily-pages), [pasting images](https://github.com/vsls-contrib/gistpad#pasting-images-1) and [backlinks](https://github.com/vsls-contrib/gistpad#backlinks). If you'd like to persist your notes in a GitHub repository, and automatically sync changes without needing to manually commit/push/pull, then GistPad might be an option worth exploring.
+
+<img width="700px" src="https://user-images.githubusercontent.com/116461/87234714-96ba9400-c388-11ea-92c3-544d9a3bb633.png" />
+
+## Getting started
+
+To start using GistPad for your Foam-based knowledge base, simply perform the following steps:
+
+1. Download the [GistPad extension](https://aka.ms/gistpad) and then re-start Visual Studio Code
+
+1. Run the `GistPad: Sign In` command, and provide a [GitHub token](https://github.com/settings/tokens/new) that includes the `repo` scope (and optionally `gist` and `delete_repo` scope, if you'd like to use GistPad for managing your GitHub content more holistically)
+
+1. Run the `GistPad: Manage Repository` command and select the `Create repo from template...` or `Create private repo from template...` depending on your preference
+
+1. Select the `Foam-style wiki` template, and then specify a name for your Foam workspace (e.g. `my-foam-notes`, `johns-knowledge-base`)
+
+Your new repo will be created in your GitHub account, and the `Foam` welcome page will be automatically opened. If you already have an existing Foam workspace in GitHub, then when you run step #3 above, simply select or specify the name of the GitHub repository instead.
+
+> Note: If you have any and all feedback on how GistPad can be improved to support your Foam workflow, please don't hesitate to [let us know](https://github.com/vsls-contrib/gistpad)! 👍
+
+<img width="700px" src="https://user-images.githubusercontent.com/116461/87863222-c1b76180-c90d-11ea-87d9-04bee1c58a0d.png" />
+
+## Managing your workspace
+
+Once you've opened/created the Foam repository, it will appear in the `Repositories` view of the `GistPad` tab (the one with the little notebook icon). From this tree view, you can add/edit/delete/rename new pages, upload local files, as well as view the backlinks for each page (they appear as child notes of a page).
+
+<img width="250px" src="https://user-images.githubusercontent.com/116461/87234704-83a7c400-c388-11ea-90a8-2a660bef4dc5.png" />
+
+## Editing your workspace
+
+When you create or open a page, you can edit the markdown content as usual, as well as [paste images](https://github.com/vsls-contrib/gistpad#pasting-images-1), and create [`[[links]]` to other pages](https://github.com/vsls-contrib/gistpad#links). When you type `[[`, you'll recieve auto-completion for the existing pages in your workspace, and you can also automatically create new pages by simply creating a link to it.
+
+Since you're using the Visual Studio Code markdown editor, you can benefit from all of the rich language services (e.g. syntax highlighting, header collapsing), as well as the extension ecosystem (e.g. [Emojisense](https://marketplace.visualstudio.com/items?itemName=bierner.emojisense)).
+
+## Navigating your workspace
+
+When editing a file, you can easily navigate `[[links]]` by hovering over them to see a preview of their contents and/or `cmd+clicking` on them in order to jump to the respective page. Furthermore, when you add a link to a page, a [backlink](https://github.com/vsls-contrib/gistpad#backlinks) is automatically added to it.
+
+You can view a page's backlinks using either of the following techniques:
+
+1. Expanding the file's node in the `Repositories` tree, since it's child nodes will represent backlinks. This makes it easy to browse your pages and their backlinks in a single hierachical view.
+
+1. Opening a file, and then viewing it's backlinks list at the bottom of the editor view. This makes it easy to read a page and then see its backlinks in a contextually rich way.
+
+## Daily Pages
+
+In addition to create arbitrary pages, you can also use GistPad for journaling or capturing [daily notes](https://github.com/vsls-contrib/gistpad#daily-pages). Simply click the calendar icon in the `Repositories` tree, which will open up the page that represents today. If the page doesn't already exist, then it will be created in the workspace before being opened.
+
+<img width="700px" src="https://user-images.githubusercontent.com/116461/87234721-b356cc00-c388-11ea-946a-e7f9c92258a6.png" />
--- a/docs/gitlab-pages.md
+++ b/docs/gitlab-pages.md
@@ -0,0 +1,51 @@
+# 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
+```
+
+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`
--- a/docs/good-first-task.md
+++ b/docs/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 "Materialized Backlinks"
+[materialized-backlinks]: materialized-backlinks "Materialized Backlinks (stub)"
 [//end]: # "Autogenerated link references"
--- a/docs/graph-visualisation.md
+++ b/docs/graph-visualisation.md
@@ -6,7 +6,4 @@

 ![Demo of graph visualiser](assets/images/foam-navigation-demo.gif)

-[//begin]: # "Autogenerated link references for markdown compatibility"
-[wiki-links]: wiki-links "Wiki Links"
-[todo]: todo "Todo"
-[//end]: # "Autogenerated link references"
+
--- a/docs/images-from-your-clipboard.md
+++ b/docs/images-from-your-clipboard.md
@@ -0,0 +1,5 @@
+# Images from your Clipboard
+
+You can directly link and paste images that are copied to the clipboard using either the [Paste
+Image](https://marketplace.visualstudio.com/items?itemName=mushan.vscode-paste-image)
+extension, or the [Markdown Image](https://marketplace.visualstudio.com/items?itemName=hancel.markdown-image) extension. The former does not have MDX support (yet), the latter does.
--- a/docs/inbox.md
+++ b/docs/inbox.md
@@ -3,7 +3,6 @@
 Uncategorised thoughts, to be added

 - Release notes
- Automatic updates
 - 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
@@ -11,10 +10,18 @@ Uncategorised thoughts, to be added
 - Investigate other similar extensions:
  - [Unotes](https://marketplace.visualstudio.com/items?itemName=ryanmcalister.Unotes)
  - [vscode-memo](https://github.com/svsool/vscode-memo)
+  - [gistpad wiki](https://github.com/jevakallio/gistpad/tree/master/src/repos/wiki)
+- Open in Foam
+  - When you want to open a Foam published website in your own VS Code, we could have a "Open in Foam" link that opens the link in VS Code via a url binding (if possible), downloads the github repo locally, and opens it as a Foam workspace.
+  - 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
+- Developer documentation
+  - GistPad has a good vs code contrib primer: https://github.com/jevakallio/gistpad/blob/master/CONTRIBUTING.md  
+- VS Code Notebooks API
+  - https://code.visualstudio.com/api/extension-guides/notebook
+- Snippets in template
 - Foam as a (VS Code) language
  - Syntax highlighting
-  - Autocompletion
-    - Get rid of mediawiki links in favor of write time tooling
  - Snippets
 - Future architecture
  - Could we do publish-related settings as a pre-push git hook, e.g. generating footnote labels
--- a/docs/index.md
+++ b/docs/index.md
@@ -62,16 +62,20 @@ These instructions assume you have a GitHub account, and you have Visual Studio

   <a class="github-button" href="https://github.com/foambubble/foam-template/generate" data-icon="octicon-repo-template" data-size="large" aria-label="Use this template foambubble/foam-template on GitHub">Use this template</a>

-   (If you want to keep your thoughts to yourself, remember to set the repository private, or if you don't want to use GitHub to host your workspace at all, choose **Download as ZIP** instead of **Use this template**.)
+   *If you want to keep your thoughts to yourself, remember to set the repository private, or if you don't want to use GitHub to host your workspace at all, choose [**Download as ZIP**](https://github.com/foambubble/foam-template/archive/master.zip) instead of **Use this template**.*

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

 To learn more about how to use **Foam**, read the [[recipes]].

+Getting stuck in the setup? Read the [[frequently-asked-questions]].
+
 There are [[known-issues]], and I'm sure, many unknown issues! Please [report them on GitHub](http://github.com/foambubble/foam/issues)!

 ## Features
@@ -106,29 +110,61 @@ If that sounds like something you're interested in, I'd love to have you along o
 <!-- markdownlint-disable -->
 <table>
  <tr>
-    <td align="center"><a href="https://jevakallio.dev/"><img src="https://avatars1.githubusercontent.com/u/1203949?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Jani Eväkallio</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=jevakallio" title="Code">💻</a> <a href="https://github.com/foambubble/foam/commits?author=jevakallio" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://joeprevite.com/"><img src="https://avatars3.githubusercontent.com/u/3806031?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Joe Previte</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=jsjoeio" title="Code">💻</a> <a href="https://github.com/foambubble/foam/commits?author=jsjoeio" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://github.com/riccardoferretti"><img src="https://avatars3.githubusercontent.com/u/457005?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Riccardo</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=riccardoferretti" title="Code">💻</a> <a href="https://github.com/foambubble/foam/commits?author=riccardoferretti" title="Documentation">📖</a></td>
-    <td align="center"><a href="http://ojanaho.com/"><img src="https://avatars0.githubusercontent.com/u/2180090?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Janne Ojanaho</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=jojanaho" title="Code">💻</a> <a href="https://github.com/foambubble/foam/commits?author=jojanaho" title="Documentation">📖</a></td>
-    <td align="center"><a href="http://bypaulshen.com/"><img src="https://avatars3.githubusercontent.com/u/2266187?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Paul Shen</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=paulshen" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://github.com/coffenbacher"><img src="https://avatars0.githubusercontent.com/u/245867?v=4?s=60" width="60px;" alt=""/><br /><sub><b>coffenbacher</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=coffenbacher" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://mathieu.dutour.me/"><img src="https://avatars2.githubusercontent.com/u/3254314?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Mathieu Dutour</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=mathieudutour" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://jevakallio.dev/"><img src="https://avatars1.githubusercontent.com/u/1203949?v=4" width="60px;" alt=""/><br /><sub><b>Jani Eväkallio</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=jevakallio" title="Code">💻</a> <a href="https://github.com/foambubble/foam/commits?author=jevakallio" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://joeprevite.com/"><img src="https://avatars3.githubusercontent.com/u/3806031?v=4" width="60px;" alt=""/><br /><sub><b>Joe Previte</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=jsjoeio" title="Code">💻</a> <a href="https://github.com/foambubble/foam/commits?author=jsjoeio" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/riccardoferretti"><img src="https://avatars3.githubusercontent.com/u/457005?v=4" width="60px;" alt=""/><br /><sub><b>Riccardo</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=riccardoferretti" title="Code">💻</a> <a href="https://github.com/foambubble/foam/commits?author=riccardoferretti" title="Documentation">📖</a></td>
+    <td align="center"><a href="http://ojanaho.com/"><img src="https://avatars0.githubusercontent.com/u/2180090?v=4" width="60px;" alt=""/><br /><sub><b>Janne Ojanaho</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=jojanaho" title="Code">💻</a> <a href="https://github.com/foambubble/foam/commits?author=jojanaho" title="Documentation">📖</a></td>
+    <td align="center"><a href="http://bypaulshen.com/"><img src="https://avatars3.githubusercontent.com/u/2266187?v=4" width="60px;" alt=""/><br /><sub><b>Paul Shen</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=paulshen" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/coffenbacher"><img src="https://avatars0.githubusercontent.com/u/245867?v=4" width="60px;" alt=""/><br /><sub><b>coffenbacher</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=coffenbacher" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://mathieu.dutour.me/"><img src="https://avatars2.githubusercontent.com/u/3254314?v=4" width="60px;" alt=""/><br /><sub><b>Mathieu Dutour</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=mathieudutour" title="Documentation">📖</a></td>
  </tr>
  <tr>
-    <td align="center"><a href="https://github.com/presidentelect"><img src="https://avatars2.githubusercontent.com/u/1242300?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Michael Hansen</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=presidentelect" title="Documentation">📖</a></td>
-    <td align="center"><a href="http://klickverbot.at/"><img src="https://avatars1.githubusercontent.com/u/19335?v=4?s=60" width="60px;" alt=""/><br /><sub><b>David Nadlinger</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=dnadlinger" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://pluckd.co/"><img src="https://avatars2.githubusercontent.com/u/20598571?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Fernando</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=MrCordeiro" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://github.com/jfgonzalez7"><img src="https://avatars3.githubusercontent.com/u/58857736?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Juan Gonzalez</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=jfgonzalez7" title="Documentation">📖</a></td>
-    <td align="center"><a href="http://www.louiechristie.com/"><img src="https://avatars1.githubusercontent.com/u/6807448?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Louie Christie</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=louiechristie" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://supersandro.de/"><img src="https://avatars2.githubusercontent.com/u/7258858?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Sandro</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=SuperSandro2000" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://github.com/Skn0tt"><img src="https://avatars1.githubusercontent.com/u/14912729?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Simon Knott</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=Skn0tt" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/presidentelect"><img src="https://avatars2.githubusercontent.com/u/1242300?v=4" width="60px;" alt=""/><br /><sub><b>Michael Hansen</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=presidentelect" title="Documentation">📖</a></td>
+    <td align="center"><a href="http://klickverbot.at/"><img src="https://avatars1.githubusercontent.com/u/19335?v=4" width="60px;" alt=""/><br /><sub><b>David Nadlinger</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=dnadlinger" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://pluckd.co/"><img src="https://avatars2.githubusercontent.com/u/20598571?v=4" width="60px;" alt=""/><br /><sub><b>Fernando</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=MrCordeiro" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/jfgonzalez7"><img src="https://avatars3.githubusercontent.com/u/58857736?v=4" width="60px;" alt=""/><br /><sub><b>Juan Gonzalez</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=jfgonzalez7" title="Documentation">📖</a></td>
+    <td align="center"><a href="http://www.louiechristie.com/"><img src="https://avatars1.githubusercontent.com/u/6807448?v=4" width="60px;" alt=""/><br /><sub><b>Louie Christie</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=louiechristie" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://supersandro.de/"><img src="https://avatars2.githubusercontent.com/u/7258858?v=4" width="60px;" alt=""/><br /><sub><b>Sandro</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=SuperSandro2000" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/Skn0tt"><img src="https://avatars1.githubusercontent.com/u/14912729?v=4" width="60px;" alt=""/><br /><sub><b>Simon Knott</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=Skn0tt" title="Documentation">📖</a></td>
  </tr>
  <tr>
-    <td align="center"><a href="https://styfle.dev/"><img src="https://avatars1.githubusercontent.com/u/229881?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Steven</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=styfle" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://github.com/Georift"><img src="https://avatars2.githubusercontent.com/u/859430?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Tim</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=Georift" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://github.com/sauravkhdoolia"><img src="https://avatars1.githubusercontent.com/u/34188267?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Saurav Khdoolia</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=sauravkhdoolia" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://anku.netlify.com/"><img src="https://avatars1.githubusercontent.com/u/22813027?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Ankit Tiwari</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=anku255" title="Documentation">📖</a> <a href="https://github.com/foambubble/foam/commits?author=anku255" title="Tests">⚠️</a></td>
-    <td align="center"><a href="https://github.com/ayushbaweja"><img src="https://avatars1.githubusercontent.com/u/44344063?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Ayush Baweja</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=ayushbaweja" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://styfle.dev/"><img src="https://avatars1.githubusercontent.com/u/229881?v=4" width="60px;" alt=""/><br /><sub><b>Steven</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=styfle" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/Georift"><img src="https://avatars2.githubusercontent.com/u/859430?v=4" width="60px;" alt=""/><br /><sub><b>Tim</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=Georift" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/sauravkhdoolia"><img src="https://avatars1.githubusercontent.com/u/34188267?v=4" width="60px;" alt=""/><br /><sub><b>Saurav Khdoolia</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=sauravkhdoolia" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://anku.netlify.com/"><img src="https://avatars1.githubusercontent.com/u/22813027?v=4" width="60px;" alt=""/><br /><sub><b>Ankit Tiwari</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=anku255" title="Documentation">📖</a> <a href="https://github.com/foambubble/foam/commits?author=anku255" title="Tests">⚠️</a> <a href="https://github.com/foambubble/foam/commits?author=anku255" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/ayushbaweja"><img src="https://avatars1.githubusercontent.com/u/44344063?v=4" width="60px;" alt=""/><br /><sub><b>Ayush Baweja</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=ayushbaweja" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/TaiChi-IO"><img src="https://avatars3.githubusercontent.com/u/65092992?v=4" width="60px;" alt=""/><br /><sub><b>TaiChi-IO</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=TaiChi-IO" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/juanfrank77"><img src="https://avatars1.githubusercontent.com/u/12146882?v=4" width="60px;" alt=""/><br /><sub><b>Juan F Gonzalez </b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=juanfrank77" title="Documentation">📖</a></td>
+  </tr>
+  <tr>
+    <td align="center"><a href="https://sanketdg.github.io"><img src="https://avatars3.githubusercontent.com/u/8980971?v=4" width="60px;" alt=""/><br /><sub><b>Sanket Dasgupta</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=SanketDG" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/nstafie"><img src="https://avatars1.githubusercontent.com/u/10801854?v=4" width="60px;" alt=""/><br /><sub><b>Nicholas Stafie</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=nstafie" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/francishamel"><img src="https://avatars3.githubusercontent.com/u/36383308?v=4" width="60px;" alt=""/><br /><sub><b>Francis Hamel</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=francishamel" title="Code">💻</a></td>
+    <td align="center"><a href="http://digiguru.co.uk"><img src="https://avatars1.githubusercontent.com/u/619436?v=4" width="60px;" alt=""/><br /><sub><b>digiguru</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=digiguru" title="Code">💻</a> <a href="https://github.com/foambubble/foam/commits?author=digiguru" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/chirag-singhal"><img src="https://avatars3.githubusercontent.com/u/42653703?v=4" width="60px;" alt=""/><br /><sub><b>CHIRAG SINGHAL</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=chirag-singhal" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/lostintangent"><img src="https://avatars3.githubusercontent.com/u/116461?v=4" width="60px;" alt=""/><br /><sub><b>Jonathan Carter</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=lostintangent" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://www.synesthesia.co.uk"><img src="https://avatars3.githubusercontent.com/u/181399?v=4" width="60px;" alt=""/><br /><sub><b>Julian Elve</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=synesthesia" title="Documentation">📖</a></td>
+  </tr>
+  <tr>
+    <td align="center"><a href="https://github.com/thomaskoppelaar"><img src="https://avatars3.githubusercontent.com/u/36331365?v=4" width="60px;" alt=""/><br /><sub><b>Thomas Koppelaar</b></sub></a><br /><a href="#question-thomaskoppelaar" title="Answering Questions">💬</a> <a href="https://github.com/foambubble/foam/commits?author=thomaskoppelaar" title="Code">💻</a> <a href="#userTesting-thomaskoppelaar" title="User Testing">📓</a></td>
+    <td align="center"><a href="http://www.akshaymehra.com"><img src="https://avatars1.githubusercontent.com/u/8671497?v=4" width="60px;" alt=""/><br /><sub><b>Akshay</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=MehraAkshay" title="Code">💻</a></td>
+    <td align="center"><a href="http://johnlindquist.com"><img src="https://avatars0.githubusercontent.com/u/36073?v=4" width="60px;" alt=""/><br /><sub><b>John Lindquist</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=johnlindquist" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://ashwin.run/"><img src="https://avatars2.githubusercontent.com/u/1689183?v=4" width="60px;" alt=""/><br /><sub><b>Ashwin Ramaswami</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=epicfaace" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/Klaudioz"><img src="https://avatars1.githubusercontent.com/u/632625?v=4" width="60px;" alt=""/><br /><sub><b>Claudio Canales</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=Klaudioz" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/vitaly-pevgonen"><img src="https://avatars0.githubusercontent.com/u/6272738?v=4" width="60px;" alt=""/><br /><sub><b>vitaly-pevgonen</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=vitaly-pevgonen" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://dshemetov.github.io"><img src="https://avatars0.githubusercontent.com/u/1810426?v=4" width="60px;" alt=""/><br /><sub><b>Dmitry Shemetov</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=dshemetov" title="Documentation">📖</a></td>
+  </tr>
+  <tr>
+    <td align="center"><a href="https://github.com/hooncp"><img src="https://avatars1.githubusercontent.com/u/48883554?v=4" width="60px;" alt=""/><br /><sub><b>hooncp</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=hooncp" title="Documentation">📖</a></td>
+    <td align="center"><a href="http://rt-canada.ca"><img src="https://avatars1.githubusercontent.com/u/13721239?v=4" width="60px;" alt=""/><br /><sub><b>Martin Laws</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=martinlaws" title="Documentation">📖</a></td>
+    <td align="center"><a href="http://seanksmith.me"><img src="https://avatars3.githubusercontent.com/u/2085441?v=4" width="60px;" alt=""/><br /><sub><b>Sean K Smith</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=sksmith" title="Code">💻</a></td>
+    <td align="center"><a href="https://www.linkedin.com/in/kevin-neely/"><img src="https://avatars1.githubusercontent.com/u/37545028?v=4" width="60px;" alt=""/><br /><sub><b>Kevin Neely</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=kneely" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://ariefrahmansyah.dev"><img src="https://avatars3.githubusercontent.com/u/8122852?v=4" width="60px;" alt=""/><br /><sub><b>Arief Rahmansyah</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=ariefrahmansyah" title="Documentation">📖</a></td>
+    <td align="center"><a href="http://vhanda.in"><img src="https://avatars2.githubusercontent.com/u/426467?v=4" width="60px;" alt=""/><br /><sub><b>Vishesh Handa</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=vHanda" title="Documentation">📖</a></td>
+    <td align="center"><a href="http://www.linkedin.com/in/heroichitesh"><img src="https://avatars3.githubusercontent.com/u/37622734?v=4" width="60px;" alt=""/><br /><sub><b>Hitesh Kumar</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=HeroicHitesh" title="Documentation">📖</a></td>
+  </tr>
+  <tr>
+    <td align="center"><a href="https://spencerwoo.com"><img src="https://avatars2.githubusercontent.com/u/32114380?v=4" width="60px;" alt=""/><br /><sub><b>Spencer Woo</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=spencerwooo" title="Documentation">📖</a></td>
  </tr>
 </table>

@@ -145,11 +181,11 @@ If that sounds like something you're interested in, I'd love to have you along o
 Foam is licensed under the [MIT license](license).

 [//begin]: # "Autogenerated link references for markdown compatibility"
-[wiki-links]: wiki-links "Wiki Links"
 [graph-visualisation]: graph-visualisation "Graph visualisation"
 [backlinking]: backlinking "Backlinking"
 [recommended-extensions]: recommended-extensions "Recommended Extensions"
 [recipes]: recipes "Recipes"
+[frequently-asked-questions]: frequently-asked-questions "Frequently Asked Questions"
 [known-issues]: known-issues "Known Issues"
 [roadmap]: roadmap "Roadmap"
 [principles]: principles "Principles"
--- a/docs/katex-math-rendering.md
+++ b/docs/katex-math-rendering.md
@@ -0,0 +1,58 @@
+# Katex Math Rendering
+
+Apart from using the method mentioned in [[math-support]], we can also use KaTeX to render our math equations in Foam. The caveat is: we can't rely on GitHub Pages to host and deploy our website anymore, because the plugin we'll be using to let Jekyll support KaTeX doesn't play well together with GitHub Pages.
+
+The alternative solution is to using [[vercel]] for building and publishing our website, so before you start integrating KaTeX into your Foam project, please follow the instructions to host your Foam workspace on [[vercel]] first.
+
+## Adding required plugins
+
+Add the plugin `jekyll-katex` to your Foam workspace's `_config.yml` and `Gemfile` if you haven't done so already. For detailed instructions, please refer to the `#Adding a _config.yml` and `#Adding a Gemfile` in [[vercel]].
+
+## Loading KaTeX JS and CSS
+
+Because we are using KaTeX to render math, we will also need to import KaTeX's JS and CSS files from CDN. The official method to load these files is documented at: [KaTeX/KaTeX#starter-template](https://github.com/KaTeX/KaTeX#starter-template). In our case, we will need to add the following code snippet to our `_layouts/page.html`:
+
+```html
+<!-- _layouts/page.html -->
+---
+layout: default
+---
+
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/katex.min.css" integrity="sha384-AfEj0r4/OFrOo5t7NnNe46zW/tFgW6x/bCJG8FqQCEo3+Aro6EYUG4+cU+KJWu/X" crossorigin="anonymous">
+
+<!-- The loading of KaTeX is deferred to speed up page rendering -->
+<script defer src="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/katex.min.js" integrity="sha384-g7c+Jr9ZivxKLnZTDUhnkOnsh30B4H0rpLUpJ4jAIKs4fnJI+sEnkvrMWph2EDg4" crossorigin="anonymous"></script>
+
+<!-- To automatically render math in text elements, include the auto-render extension: -->
+<script defer src="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/contrib/auto-render.min.js" integrity="sha384-mll67QQFJfxn0IYznZYonOWZ644AWYC+Pt2cHqMaRhXVrursRwvLnLaebdGIlYNa" crossorigin="anonymous" onload="renderMathInElement(document.body);"></script>
+
+<!-- ... -->
+```
+
+## Adding liquid tags to wrap page content
+
+The plugin `jekyll-katex` focuses on rendering:
+
+- Single math equations wrapped inside `katex` liquid tags like {% raw %}`{% katex %} ... {% endkatex %}`{% endraw %}.
+- Or multiple math equations in paragraphs wrapped inside {% raw %}`{% katexmm %} ... {% endkatexmm %}`{% endraw %}.
+
+In our case, we'll be using the latter tag to wrap our {% raw %}`{{ content }}`{% endraw %}. Wrap {% raw %}`{{ content }}`{% endraw %} in the liquid tags inside `_layouts/page.html` like so:
+
+```html
+<!-- _layouts/page.html -->
+
+<!-- ... -->
+{% raw %}{% katexmm %} {{ content }} {% endkatexmm %}{% endraw %}
+<!-- ... -->
+```
+
+## Render equations in Foam's homepage as well
+
+You may have noticed that we only made modifications to the template `_layouts/page.html`, which means that `_layouts/home.html` won't have KaTeX support. If you wan't to render math in Foam's home page, you'll need to make the same modifications to `_layouts/home.html` as well.
+
+Finally, if all goes well, then our site hosted on Vercel will support rendering math equations with KaTeX after commiting these changes to GitHub. Here's a demo of the default template with KaTeX support: [Foam Template with KaTeX support](https://foam-template.vercel.app/).
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[math-support]: math-support "Math Support"
+[vercel]: vercel "Vercel"
+[//end]: # "Autogenerated link references"
--- a/docs/link-formatting-and-autocompletion.md
+++ b/docs/link-formatting-and-autocompletion.md
@@ -0,0 +1,75 @@
+# Link Formatting and Autocompletion
+
+When coming from Roam, Obsidian and such tools, you may be used to writing [[wiki-links]] in `[[Title Case Format]]`. Foam will eventually support this syntax (see: [foambubble/rfcs#3](https://github.com/foambubble/rfcs/pull/3)), but for the time being, we do not.
+
+Foam relies heavily on our [[recommended-extensions]], and each extension has slightly different semantics and edge cases. This is a short guide on how to name your files, format your links, and configure your editor so that you can enjoy Foam until our implementation catches up with our aspirations.
+
+## Short version
+
+- Name your files in `lower-dash-case.md`. 
+  - Read on: [How to name your files](#how-to-name-your-files)
+- Use [[wiki-links]] that match the file name exactly, without file extension: `[[lower-dash-case]]`
+  - Read on: [How to format your links](#how-to-format-your-links)
+  - Read on: [How to autocomplete your links correctly](#how-to-autocomplete-your-links-correctly)
+- Ensure every file has a `# Heading` element
+  - This will be used as your document title.
+  
+## How to name your files
+
+As described in [[foam-file-format]], **Foam file names should not contain spaces.** Because of the [Markdown Notes](https://marketplace.visualstudio.com/items?itemName=kortina.vscode-markdown-notes) extension's default behaviour, we recommend naming your files in lower-dash-case: `foam-file-format.md`.
+
+ℹ️ This means:
+- All lowercase
+- No spaces, punctuation or special characters
+- Using dashes as word separators
+- Ending with a `.md` extension
+
+✅ Valid lower-dash-case file names include:
+- `roadmap.md`
+- `foam-file-format.md`
+- `f-f-f-f-falling.md`
+
+❌ Some invalid names include:
+
+- `Roadmap.md` (Name should not be capitalised)
+- `foam file format.md` (Name should not have spaces)
+- `f-f-f-f-falling!.md` (Name should not have special characters)
+
+Some of these file names may work for a subset of use cases (for example, if you don't publish your Foam site), but we'd still recommend following these rules.
+
+As per [[foam-file-format]], we eventually want to make Foam a lot more lenient. As per our [[principles]], you should be able to focus on your work and not fight against Foam. We're not there yet, but we'll get there.
+
+## How to format your links
+
+Use [[wiki-links]] to link between files. Each link:
+- **Should match file name exactly**: `[[foam-file-format]]`, not `[[Foam File Format]]`
+  - If you're reading this document on the Foam website, you might think: "That's not right!" What about links like [[foam-file-format]]! That uses spaces, capitalised letters, and everything!
+  - But if you look at the <a href="link-formatting-and-autocompletion.md">raw version of this document</a>, you'll see that the link is actually written as `[[foam-file-format]]`: we make it look nicer with a bit of web magic and a sprinkle of JavaScript.
+- **Not include a file extension**: `[[foam-file-format]]`, not `[[foam-file-format.md]]`.
+  - You might ask: If I can't use the `.md` extension, why does Foam autocomplete it for me?
+  - The answer is: It's a setting. See [How to autocomplete your links correctly](#how-to-autocomplete-your-links-correctly) below.
+
+## How to autocomplete your links correctly
+
+Foam autocompletion is provided by [Markdown Notes](https://marketplace.visualstudio.com/items?itemName=kortina.vscode-markdown-notes). The default behaviour of Markdown Notes Autocomplete is to suffix `.md` to the end of suggestion, such as in the below screenshot:
+
+![Autocomplete from Markdown Notes with file extension](./assets/images/md-notes-autocomplete-with-extension.png)
+
+To change this behaviour, add the below to your `.vscode/settings.json` file:
+
+```json
+"vscodeMarkdownNotes.noteCompletionConvention": "noExtension"
+```
+
+Now your autocomplete will look like the below screenshot:
+
+![Autocomplete from Markdown Notes without file extension](./assets/images/md-notes-autocomplete-no-extension.png)
+
+If you created your Foam from the official [foam-template](https://github.com/foambubble/foam-template) project after 27th July 2020, this setting should be already correctly set.
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[wiki-links]: wiki-links "Wiki Links"
+[recommended-extensions]: recommended-extensions "Recommended Extensions"
+[foam-file-format]: foam-file-format "Foam File Format"
+[principles]: principles "Principles"
+[//end]: # "Autogenerated link references"
--- a/docs/link-reference-definition-improvements.md
+++ b/docs/link-reference-definition-improvements.md
@@ -0,0 +1,141 @@
+# Link Reference Definition Improvements
+
+## Current Problems
+
+### 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).
+
+### 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.
+
+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.
+
+So, why don't they work on GitHub?
+
+The three components of [[link-reference-definitions]] are link label, link destination and Link Title.
+
+The issue is the middle **link destination** component. It's configured to point to the file name **without file extension**, i.e. "file-name" instead of "file-name.md". This is to make the GitHub Pages rendering work, because if we generated the links to `file-name.md`, the links would point to the raw markdown files instead of their generated HTML versions.
+
+| Environment      | `file-name` | `file-name.md` |
+| ---------------- | ----------- | -------------- |
+| **VS Code**      | Works       | Works          |
+| **GitHub pages** | Works       | Breaks         |
+| **GitHub UI**    | Breaks      | Works          |
+
+So as you can see, we've prioritised GitHub Pages over GitHub Web UI for the time being.
+
+Ideally, we'd like a solution that works with both, but it's not defined yet (see [[link-reference-definitions]] for more details)
+
+#### Workaround
+
+For the time being, you can use relative `[markdown links](markdown-link.md)` syntax.
+
+**Pros:**
+
+- This will work on all platforms.
+
+**Cons:**
+
+- It will break the Markdown Notes [[backlinking]] support
+- Less convenient to write
+
+### Finding certain words clutter the VS Code search results
+
+Since link reference definitions have `[//begin]` and `[//end]` guards with explanatory text that use certain words, these words (like "generate") appear in VS Code search results if you happen to search matching strings from the workspace.
+
+## Improvement Proposal
+
+Problem space in essence:
+
+- During edit-time (when modifying the markdown files in an editor)
+  - link reference definitions are needed if user uses editor extensions that don't understand wikilinks
+  - link reference definitions may be annoying since they 
+    - add content to files that the user hasn't typed in by themselves
+    - get out of date if user uses a tool that doesn't autogenerate them
+    - 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)
+
+The potential solution:
+
+- For edit-time
+  - Make edit-time link reference definition generation optional via user settings. They should be on by default, and generating valid markdown links with a relative path to a `.md` file.
+  - Make format of the link reference definition configurable (whether to include '.md' or not)
+  - Out of recommended extensions, currently only "markdown links" doesn't support them (?). However even its [code](https://github.com/tchayen/markdown-links/blob/master/src/parsing.ts#L25) seems to include wikilink parser, so it might just be a bug?
+- For build-time
+  - To satisfy mutually incompatible constraints between GitHub UI, VSCode UI, and GitHub Pages, we should add a pre-processing/build step for pushing to GitHub Pages. 
+    - 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
+    {
+      "foam": {
+        "publish": [
+          {
+            "name": "Gitlab Mirror",     // name of the publish target
+            "linkTranspilation": "Off",
+            "linkReferenceDefinitions": "withExtensions"
+          },
+          {
+            "name": "GitHub Pages",
+            "linkTranspilation": "Off",
+            "linkReferenceDefinitions": "withoutExtensions"
+          },
+          {
+            "name": "Blog",
+            "linkTranspilation": "Off",
+            "linkReferenceDefinitions": "Off"
+          },
+          {
+            "name": "My Amazing PDF book",
+            "linkTranspilation": "WikiLinksToMarkdown"
+          }
+        ],
+        "edit": {
+          "linkReferenceDefinitions": "Off"
+        }
+      }
+    }
+
+    // Defines if and how links in markdown files are somehow converted (in-place) during build time
+    // Note that this enumeration is not valid edit-time, since we (probably) don't want to change text like this while user is editing it
+    enum LinkTranspilation {
+      Off,                   // links are not transpiled
+      WikiLinksToMarkdown,   // links using wiki-format [[link]] are converted to normal md links: [link](./some/file.md)
+                             // if this is set, not link reference definitions are generated (not needed)
+    }
+    
+    // Defines if and how link reference definition section is generated
+    enum LinkReferenceDefinitions {
+      Off,               // link reference definitions are not generated
+      WithExtensions,    // link reference definitions contain .md (or similar) file extensions
+      WithoutExtensions  // link reference definitions do not contain file extenions
+    }
+
+    ```
+  - 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).
+
+Note that the proposal above supports both (build-time) inline transpilation of wikilinks as well as creation reference definitions. Depending on the direction of Foam, also only one of them could be selected. In that case the other could be implemented at later point of time.
+
+UI-wise, the publish targets could be picked in some similar fashion as the run/debug targets in vscode by implementing a separate panel, or maybe through command execution (CTRL+SHIFT+P) - not yet defined at this point.
+
+## Links
+
+- [tracking issue on GitHub](https://github.com/foambubble/foam/issues/16)
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[wiki-links]: wiki-links "Wiki Links"
+[link-reference-definitions]: link-reference-definitions "Link Reference Definitions"
+[backlinking]: backlinking "Backlinking"
+[//end]: # "Autogenerated link references"
--- a/docs/link-reference-definitions.md
+++ b/docs/link-reference-definitions.md
@@ -0,0 +1,73 @@
+# 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]]`.
+
+## Example
+
+The following example:
+  ```md
+  - [[wiki-links]]
+  - [[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"
+  ```
+You can open the [raw markdown](https://raw.githubusercontent.com/foambubble/foam/master/foam-file-format.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 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)
+
+## Configuration
+
+You can choose to generate link reference definitions with or without file extensions, depending on the target. As a rule of thumb:
+
+- Links with file extensions work better with standard markdown-based tools, such as GitHub web UI.
+- Links without file extensions work better with certain web publishing tools that treat links as literal urls and don't transform them automatically, such as the standard GitHub pages installation.
+
+By default, Foam generates links without file extensions for legacy reasons, but this may change in future versions. 
+
+You can override this setting in your Foam workspace's `settings.json`:
+
+- `"foam.edit.linkReferenceDefinitions": "withoutExtensions"` (default)
+- `"foam.edit.linkReferenceDefinitions": "withExtensions"`
+
+### Ignoring files
+
+Sometimes, you may want to ignore certain files or folders, so that Foam doesn't generate link reference definitions to them. 
+
+For instance, if you're using a local instance of [Jekyll](https://jekyllrb.com/), you may find that it writes copies of each `.md` file into a `_site` directory, which may lead to Foam generating references to them instead of the original source notes.
+
+You can ignore the `_site` directory by adding the following to your `.vscode/settings.json`:
+
+```json
+  "files.exclude": {
+    "**/_site": true
+  },
+  "files.watcherExclude": {
+    "**/_site": true
+  },
+```
+
+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
+
+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 "Janitor"
+[link-reference-definition-improvements]: link-reference-definition-improvements "Link Reference Definition Improvements"
+[//end]: # "Autogenerated link references"
--- a/docs/math-support.md
+++ b/docs/math-support.md
@@ -0,0 +1,51 @@
+---
+layout: mathjax
+---
+
+# Math Support
+
+Published Foam pages don't support math formulas by default. To enable this feature, you can add the following code snippet to the end of `_layouts/page.html`:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML" type="text/javascript"></script>
+<script type="text/x-mathjax-config">
+    MathJax.Hub.Config({
+        tex2jax: {
+            skipTags: ['script', 'noscript', 'style', 'textarea', 'pre'],
+            inlineMath: [['$','$']]
+        }
+    });
+</script>
+```
+
+This approach uses the [MathJax](https://www.mathjax.org/) library to render anything delimited by ```$``` (customizable in the snippet above) pairs to inline math and ```$$``` to blocks of math (like a html div tag) using with the AMS-LaTeX dialect embedded within MathJax. 
+
+Example of inline math using `$...$`: 
+
+`$e^{i \pi}+1=0$`, becomes $e^{i \pi}+1=0$
+
+Example of a math block using `$$...$$`:
+
+`$$ f_{\mathbf{X}}\left(x_{1}, \ldots, x_{k}\right)=\frac{\exp \left(-\frac{1}{2}(\mathbf{x}-\boldsymbol{\mu})^{\mathrm{T}} \mathbf{\Sigma}^{-1}(\mathbf{x}-\boldsymbol{\mu})\right)}{\sqrt{(2 \pi)^{k}|\mathbf{\Sigma}|}} $$`
+
+Becomes:
+
+$$ f_{\mathbf{X}}\left(x_{1}, \ldots, x_{k}\right)=\frac{\exp \left(-\frac{1}{2}(\mathbf{x}-\boldsymbol{\mu})^{\mathrm{T}} \mathbf{\Sigma}^{-1}(\mathbf{x}-\boldsymbol{\mu})\right)}{\sqrt{(2 \pi)^{k}|\mathbf{\Sigma}|}} $$  
+
+## Alternative approaches
+
+There are other dialects of LaTeX (instead of AMS), and other JavaScript rendering libraries you may want to use. In a future version of Foam, we may support KaTeX syntax out of the box, but at this time, these integrations are left as an exercise to the user.
+
+## Why don't my Math expressions work on my Foam's home page?
+
+If you want the index page of your Foam site to render maths, you'll need to add that to `_layouts/home.html` as well, or change the layout of the index page to be "page" instead of "home" by putting this Front Matter on the top of your `readme.md/index.md`:
+
+```
+---
+layout: page
+---
+
+# Your normal title here
+```
+
+Reference: [How to support latex in github-pages](https://stackoverflow.com/questions/26275645/how-to-support-latex-in-github-pages)
--- a/docs/meeting-notes/foam-core-2020-07-11.md
+++ b/docs/meeting-notes/foam-core-2020-07-11.md
@@ -123,4 +123,5 @@ How others solve this:

 [//begin]: # "Autogenerated link references for markdown compatibility"
 [todo]: ../todo "Todo"
+[Index]: ../index "Foam"
 [//end]: # "Autogenerated link references"
--- a/docs/migrating-from-onenote.md
+++ b/docs/migrating-from-onenote.md
@@ -0,0 +1,36 @@
+# Migrating from OneNote
+
+This guide mostly duplicates the instructions at the repo for the PowerShell [script](https://github.com/nixsee/ConvertOneNote2MarkDown).
+
+## Summary
+
+The powershell script 'ConvertOneNote2MarkDown-v2.ps1' will utilize the OneNote Object Model on your workstation to convert all OneNote pages to Word documents and then utilizes PanDoc to convert the Word documents to Markdown (.md) format. It will also:
+
+* Create a folder structure for your Notebooks and Sections.
+* Process pages that are in sections at the Notebook, Section Group and 1st Nested Section Group levels.
+* Allow you you choose between putting all Images in a central '/media' folder for each notebook, or in a separate '/media' folder in each folder of the hierarchy.
+* Fix image references in the resulting .md files, generating relative references to the image files within the markdown document.
+* A title, description, and date header will be added to each file as well.
+* And more (see details at repo)!
+
+## Usage
+
+1. Start the OneNote application. All notebooks currently loaded in [OneNote](https://getonetastic.com/download) will be converted.
+2. It is advised that you install [Onetastic](https://getonetastic.com/download) and the attached macro, which will automatically expand any collapsed paragraphs in the notebook. They won't be exported otherwise.
+    * To install the macro, click the New Macro Button within the Onetastic Toolbar and then select File -> Import and select the .xml macro included in the release.
+    * Run the macro for each Notebook that is open
+3. For the next sections, it is highly recommended that you use VS Code, and its embedded PowerShell terminal, as this allows you to edit and run the script, as well as check the results of the .md output all in one window.
+4. Whatever you choose, you will need to do the following:
+   1. Clone the script to your computer (see [here](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository), if you're unfamiliar with git).
+   2. Once cloned, navigate to the repo folder. In VS Code, use File -> Add Folder to Workspace, right click on the folder in the left side bar and click [Open In Integrated Terminal](assets/images/migrating-one-note.png).
+   3. Run the script by executing
+```.\ConvertOnenote2Markdown-v2```
+    * if you receive an error, try running this line to bypass security:
+     ```Set-ExecutionPolicy Bypass -Scope Process```
+    * if you still have trouble, try running both Onenote and Powershell as an administrator.
+5. It will ask you for the path to store the markdown folder structure. Please use an empty folder. If using VS Code, you might not be able to paste the filepath - right click on the blinking cursor and it will paste from clipboard. **Attention:** use a full absolute path for the destination.
+6. Read the prompts carefully to select your desired options. If you aren't actively editing your pages in Onenote, it is HIGHLY recommended that you don't delete the intermediate word docs, as they take 80+% of the time to generate. They are stored in their own folder, out of the way. You can then quickly re-run the script with different parameters until you find what you like.
+7. Sit back and wait until the process completes.
+8. To stop the process at any time, press Ctrl+C.
+9. If you like, you can inspect some of the .md files prior to completion. If you're not happy with the results, stop the process, delete the .md and re-run with different parameters.
+10. At this point, you should be ready to load the new directory into Foam!
--- a/docs/mobile-apps.md
+++ b/docs/mobile-apps.md
@@ -14,9 +14,11 @@ This Roadmap item discusses existing assembled solutions, and some thoughts on f
 - Provides functionality to edit, create, and browser markdown files.
 - Support journal mode, todo lists, and free writing
 - Syncs to GitHub repo
+- Supports Wiki Links
+- Supports Backlinks
+- Developer is happy to prioritize Foam compatibility

 #### Cons
- Doesn't support [[wiki-links]] **(deal breaker, but support [coming soon](https://twitter.com/GitJournal_io/status/1280194357296062466))**
 - Doesn't generate link reference lists (but this is ok, since [[workspace-janitor]] as a GitHub action can solve this)
 - Not as sleek as Apple/Google notes, some keyboard state glitching on Android, etc.
 - Lack of control over roadmap. Established product with a paid plan, so may not be open to Foam-supportive changes and additions that don't benefit most users.
@@ -41,9 +43,7 @@ Given the effort vs reward ratio, it's a low priority for core team, but if some


 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[roadmap]: roadmap "Roadmap"
 [build-vs-assemble]: build-vs-assemble "Build vs Assemble"
 [wiki-links]: wiki-links "Wiki Links"
-[workspace-janitor]: workspace-janitor "Workspace Janitor (stub)"
-[//end]: # "Autogenerated link references"
+[workspace-janitor]: workspace-janitor "Janitor"
+[//end]: # "Autogenerated link references"
--- a/docs/new-note-for-testing.md
+++ b/docs/new-note-for-testing.md
@@ -1,4 +0,0 @@
-
-[//begin]: # "Autogenerated link references for markdown compatibility"
-[unrelated]: unrelated "Unrelated"
-[//end]: # "Autogenerated link references"
--- a/docs/note-macros.md
+++ b/docs/note-macros.md
@@ -0,0 +1,63 @@
+# Custom Note Macros
+
+This extension gives you the ability to create custom note macros. It was heavily inspired by Foam's [[daily-notes]] functionality.
+
+## Installation
+
+**This extension is not included in the template**
+
+To install search note-macros in vscode or head to [note-macros - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=NeelyInnovations.note-macros)
+
+## Instructions
+
+### Run macro From command pallette
+
+Simply use `Ctrl+P` or `Alt+P` depend on your os, and type `Note Macros: Run A Macro` then chose the macro you want to execute.
+
+### Create Custom Note Macros
+
+Create your own custom macros by adding them to your `settings.json` (Code|File > Preferences > User Settings). A full example can be found at [settings.json](https://github.com/kneely/note-macros/blob/master/settings.json)
+
+For example:
+
+This macro creates a Weekly note in the Weekly note Directory.
+
+```json
+{
+  "note-macros": {
+    "Weekly": [
+      {
+        "type": "note",
+        "directory": "Weekly",
+        "extension": ".md",
+        "name": "weekly-note",
+        "date": "yyyy-W"
+      }
+    ]
+  }
+}
+```
+
+For an explanation of the fields please go to [note-macros - Explanation of Fields](https://github.com/kneely/note-macros#explanation-of-fields)
+
+### Add Keybindings to Run your Macros
+
+in `keybindings.json` (Code|File > Preferences > Keyboard Shortcuts) add bindings to your macros:
+
+```json
+{
+  "key": "ctrl+cmd+/",
+  "command": "note-macros.Weekly"
+}
+```
+
+## Issues and Feedback
+
+If you have any issues or questions please look at the [README.md](https://github.com/kneely/note-macros#note-macros) on the [note-macros](https://github.com/kneely/note-macros) GitHub.
+
+If you run into any issues that are not fixed by referring to the README or feature requests please open an [issue](https://github.com/kneely/note-macros/issues).
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[daily-notes]: daily-notes "Daily notes"
+[//end]: # "Autogenerated link references"
+
--- a/docs/predefined-user-snippets.md
+++ b/docs/predefined-user-snippets.md
@@ -0,0 +1,59 @@
+# Pre-defined User Snippets
+
+Having pre-defined user snippets would enable us to introduce Roam style commands to Foam. Consider the below snippets:
+
+```json
+{
+  "Zettelkasten Id": {
+    "scope": "markdown",
+    "prefix": "/id",
+    "description": "Zettelkasten Id",
+    "body": [
+      "${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE} ${CURRENT_HOUR}:${CURRENT_MINUTE}:${CURRENT_SECOND}"
+    ]
+  },
+  "Current date": {
+    "scope": "markdown",
+    "prefix": "/date",
+    "description": "Current date",
+    "body": [
+      "${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE} ${CURRENT_HOUR}:${CURRENT_MINUTE}:${CURRENT_SECOND}"
+    ]
+  }
+}
+```
+
+Which would look like:
+![GIF demonstrating User Snippets](./assets/images/snippets.gif)
+
+Using snippets enables Foam users to add [[custom-snippets]] themselves so they live alongside the first-class `/commands`.
+
+## Notes & Considerations
+
+- VS Code supplies "commands" already via the command palette
+  - Consider the UX around this. Users less familiar with VS Code are more likely to be familiar with `/` to trigger a command menu. Experienced VS Code users may be more likely to favour the command palette.
+- We can use `TabCompletionProvider` and `snippets` and mix them (maybe) via the following VS Code setting: `"editor.snippetSuggestions": "inline" | "top" | "bottom" | "none"`
+- For more discussion, consult the PR [here](https://github.com/foambubble/foam/pull/192).
+
+## Simplifying Markdown Syntax
+
+Some markdown syntax is difficult for users who have never authored markdown before. Take for example a checkbox/todo. The following syntax is required:
+
+```
+- [ ] Something todo...
+```
+
+We could provide snippets that expand out into the associated markdown syntax, like in the below GIF:
+![GIF demonstrating markdown snippets](./assets/images/markdown-snippets.gif)
+
+The JSON for these snippets can be found [here](https://github.com/foambubble/foam/pull/192#issuecomment-666736270).
+
+[//begin]: # 'Autogenerated link references for markdown compatibility'
+[custom-snippets]: custom-snippets 'Adding Custom Snippets'
+[//end]: # 'Autogenerated link references'
+[//begin]: # 'Autogenerated link references for markdown compatibility'
+[custom-snippets]: custom-snippets 'Adding Custom Snippets'
+[//end]: # 'Autogenerated link references'
+[//begin]: # 'Autogenerated link references for markdown compatibility'
+[custom-snippets]: custom-snippets 'Adding Custom Snippets'
+[//end]: # 'Autogenerated link references'
--- a/docs/principles.md
+++ b/docs/principles.md
@@ -36,7 +36,7 @@ This principle may seem like it contradicts [Foam wants you to own your thoughts
 ## Foam allows people to collaborate in discovering better ways to work, together.

 - **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](httpsL//github,com/foambubble/foam). See also: [[roadmap]] and [[contribution-guide]].
+- **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: [[roadmap]] and [[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 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).

--- a/docs/reading-list.md
+++ b/docs/reading-list.md
@@ -6,3 +6,7 @@
 - [Dark mode](https://css-tricks.com/dark-modes-with-css/)


+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[Todo]: todo "Todo"
+[//end]: # "Autogenerated link references"
--- a/docs/recipes.md
+++ b/docs/recipes.md
@@ -14,7 +14,7 @@ Guides, tips and strategies for getting the most out of your Foam workspace!
 - [Workflow](#workflow)
 - [Creative ideas](#creative-ideas)
 - [Other](#other)
-  
+
 ## Contribute

 - Start by reading [[contribution-guide]]
@@ -23,7 +23,7 @@ Guides, tips and strategies for getting the most out of your Foam workspace!
 ## Take smart notes

 - Introduction to Zettelkasten [[todo]]
-  
+
 ## Discover
 - Explore your notes using [[graph-visualisation]]
 - Discover relationships with [[backlinking]]
@@ -31,15 +31,18 @@ Guides, tips and strategies for getting the most out of your Foam workspace!

 ## Organise
 - Using [[backlinking]] for [[reference-lists]].
-  
+
 ## Write
- Link documents with [[wiki-links]]
+- Link documents with [[wiki-links]], using Foam's [[link-formatting-and-autocompletion]].
 - Use shortcuts for [[creating-new-notes]]
+- Instantly create and access your [[daily-notes]]
+- Use custom [[note-macros]] to create weekly, monthly etc. notes
 - Draw [[diagrams-in-markdown]]
 - Prettify your links, [[automatically-expand-urls-to-well-titled-links]]
 - Style your environment with [[custom-markdown-preview-styles]]
+- Paste and link [[images-from-your-clipboard]]
 - [Markdown All-in-One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one) features [[todo]] [[good-first-task]]
-  - Manage checklists 
+  - Manage checklists
  - Automatic Table of Contents
  - Live preview markdown
  - _More..._
@@ -48,30 +51,35 @@ Guides, tips and strategies for getting the most out of your Foam workspace!

 ## Version control

- Quick commits with [[git-integration]]
+- Quick commits with VS Code's built in [[git-integration]]
+- Store your workspace in an auto-synced GitHub repo with [[gistpad]]
 - Sync your GitHub repo automatically [[todo]].

 ## Publish

 - Publish to [[github-pages]]
+- Publish to [[gitlab-pages]]
+- Publish your site with [[eleventy-and-netlify]]
+- Publish to [[azure-devops-wiki]]
+- Publish to [[vercel]]
 - Make the site your own by [[customising-styles]].
- Host your own website [[todo]]
+- Render math symbols, by either
+  - adding client-side [[math-support]] to the default [[github-pages]] site
+  - adding a custom Jekyll plugin to support [[katex-math-rendering]]

 ## Collaborate

 - Give your team push access to your GitHub repo [[todo]]
 - Real-time collaboration via VS Code Live Share [[todo]]
 - Accept patches via GitHub PRs [[todo]]
- 
+
 ## Workflow

-Workflow recipes wanted!
-
-_See [[contribution-guide]] and [[how-to-write-recipes]]._
+- Capture notes from Drafts app on iOS [[capture-notes-with-drafts-pro]]

 ## Creative ideas

-Creative ideas welcome! 
+Creative ideas welcome!

 - Support [Anki](https://apps.ankiweb.net/) cards from notes like [Remnote](https://www.remnote.io/) [[todo]]

@@ -79,7 +87,7 @@ _See [[contribution-guide]] and [[how-to-write-recipes]]._

 ## Other

-Thought of a recipe but don't see a category for them? Add them here and we'll organise them once we detect a theme. 
+Thought of a recipe but don't see a category for them? Add them here and we'll organise them once we detect a theme.

 _See [[contribution-guide]] and [[how-to-write-recipes]]._

@@ -92,12 +100,24 @@ _See [[contribution-guide]] and [[how-to-write-recipes]]._
 [unlinked-references]: unlinked-references "Unlinked references (stub)"
 [reference-lists]: reference-lists "Reference Lists"
 [wiki-links]: wiki-links "Wiki Links"
+[link-formatting-and-autocompletion]: link-formatting-and-autocompletion "Link Formatting and Autocompletion"
 [creating-new-notes]: creating-new-notes "Creating New Notes"
+[daily-notes]: daily-notes "Daily notes"
 [diagrams-in-markdown]: diagrams-in-markdown "Diagrams in Markdown"
 [automatically-expand-urls-to-well-titled-links]: automatically-expand-urls-to-well-titled-links "Automatically Expand URLs to Well-Titled Links"
 [custom-markdown-preview-styles]: custom-markdown-preview-styles "Custom Markdown Preview Styles"
+[images-from-your-clipboard]: images-from-your-clipboard "Images from your Clipboard"
 [good-first-task]: good-first-task "Good First Task"
+[note-macros]: note-macros "Custom Note Macros"
 [git-integration]: git-integration "Git integration"
+[gistpad]: gistpad "GistPad"
 [github-pages]: github-pages "Github Pages"
+[gitlab-pages]: gitlab-pages "GitLab Pages"
+[eleventy-and-netlify]: eleventy-and-netlify "Eleventy and Netlify"
+[azure-devops-wiki]: azure-devops-wiki "Azure DevOps Wiki"
+[vercel]: vercel "Vercel"
 [customising-styles]: customising-styles "Customising Styles"
+[math-support]: math-support "Math Support"
+[katex-math-rendering]: katex-math-rendering "Katex Math Rendering"
+[capture-notes-with-drafts-pro]: capture-notes-with-drafts-pro "Capture Notes With Drafts Pro"
 [//end]: # "Autogenerated link references"
--- a/docs/reference-lists.md
+++ b/docs/reference-lists.md
@@ -12,5 +12,5 @@ Use [[backlinking]] for handy reference lists:
 [//begin]: # "Autogenerated link references for markdown compatibility"
 [backlinking]: backlinking "Backlinking"
 [todo]: todo "Todo"
-[materialized-backlinks]: materialized-backlinks "Materialized Backlinks"
+[materialized-backlinks]: materialized-backlinks "Materialized Backlinks (stub)"
 [//end]: # "Autogenerated link references"
--- a/docs/referencing-notes-by-title.md
+++ b/docs/referencing-notes-by-title.md
@@ -29,6 +29,6 @@
 - Can [MDX](https://github.com/mdx-js/mdx) help us here?

 [//begin]: # "Autogenerated link references for markdown compatibility"
-[unlinked-references]: unlinked-references "Unlinked references"
-[renaming-files]: renaming-files "Renaming files"
+[unlinked-references]: unlinked-references "Unlinked references (stub)"
+[renaming-files]: renaming-files "Renaming files (stub)"
 [//end]: # "Autogenerated link references"
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -35,13 +35,15 @@ If a roadmap item is a stub, **consider** opening a [GitHub issue](https://githu

 - [[renaming-files]]
 - [[unlinked-references]]
- [[daily-notes]]
 - [[block-references]]
 - [[improved-backlinking]]
  - UX: [[make-backlinks-more-prominent]]
 - [[materialized-backlinks]]
 - [[automatic-git-syncing]]
 - [[git-flows-for-teams]]
+- [[user-settings]]
+- [[link-reference-definitions]]
+- [[predefined-user-snippets]]

 ### Publishing

@@ -64,13 +66,18 @@ If a roadmap item is a stub, **consider** opening a [GitHub issue](https://githu

 ### Migration

+The community is working on a number of automated scripts to help you migrate to Foam. The main work of developing such a method involves exporting your notes, converting them to the Markdown format, and then making sure that the links between notes (if you had those) still work.
+
 - [[migrating-from-roam]]
  - Discussion: [foam#55](https://github.com/foambubble/foam/issues/55)
 - [[migrating-from-obsidian]]
  - Discussion: [foam#46](https://github.com/foambubble/foam/issues/46)
+- [[migrating-from-onenote]]
+  - Discussion: [foam#151](https://github.com/foambubble/foam/issues/151)
 - _Migration from other tools..._

-### integration
+### Integration
+
 - _Integrations to third party tools_...
  
 ### Wild ideas
@@ -82,7 +89,7 @@ If a roadmap item is a stub, **consider** opening a [GitHub issue](https://githu
 [build-vs-assemble]: build-vs-assemble "Build vs Assemble"
 [recipes]: recipes "Recipes"
 [cli]: cli "Command Line Interface"
-[workspace-janitor]: workspace-janitor "Workspace Janitor"
+[workspace-janitor]: workspace-janitor "Janitor"
 [contribution-guide]: contribution-guide "Contribution Guide"
 [improve-default-workspace-settings]: improve-default-workspace-settings "Improve Default Workspace Settings (stub)"
 [git-integration]: git-integration "Git integration"
@@ -90,12 +97,15 @@ If a roadmap item is a stub, **consider** opening a [GitHub issue](https://githu
 [foam-file-format]: foam-file-format "Foam File Format"
 [renaming-files]: renaming-files "Renaming files (stub)"
 [unlinked-references]: unlinked-references "Unlinked references (stub)"
-[daily-notes]: daily-notes "Daily notes"
 [block-references]: block-references "Block References (stub)"
 [improved-backlinking]: improved-backlinking "Improved Backlinking (stub)"
+[make-backlinks-more-prominent]: make-backlinks-more-prominent "Make Backlinks More Prominent"
 [materialized-backlinks]: materialized-backlinks "Materialized Backlinks (stub)"
 [automatic-git-syncing]: automatic-git-syncing "Automatic Git Syncing (stub)"
 [git-flows-for-teams]: git-flows-for-teams "Git Flows for Teams (stub)"
+[user-settings]: user-settings "User Settings (stub)"
+[link-reference-definitions]: link-reference-definitions "Link Reference Definitions"
+[predefined-user-snippets]: predefined-user-snippets "Pre-defined User Snippets"
 [officially-support-alternative-templates]: officially-support-alternative-templates "Officially Support Alternative Templates (stub)"
 [improved-static-site-generation]: improved-static-site-generation "Improved Static Site Generation (stub)"
 [mdx-by-default]: mdx-by-default "MDX by Default(stub)"
@@ -108,7 +118,7 @@ If a roadmap item is a stub, **consider** opening a [GitHub issue](https://githu
 [web-editor]: web-editor "Web Editor (stub)"
 [migrating-from-roam]: migrating-from-roam "Migrating from Roam (stub)"
 [migrating-from-obsidian]: migrating-from-obsidian "Migrating from Obsidian (stub)"
+[migrating-from-onenote]: migrating-from-onenote "Migrating from OneNote"
 [foam-linter]: foam-linter "Foam Linter (stub)"
 [refactoring-via-language-server-protocol]: refactoring-via-language-server-protocol "Refactoring via Language Server Protocol (stub)"
-[make-backlinks-more-prominent]: make-backlinks-more-prominent "Make Backlinks More Prominent"
-[//end]: # "Autogenerated link references"
+[//end]: # "Autogenerated link references"
--- a/docs/terminology.md
+++ b/docs/terminology.md
@@ -4,20 +4,17 @@ It would be good to have some shared terminology to talk about Foam concepts. So

 Here's some ideas, these are open for discussion.

-## Foam (project)
+## Foam, the software project

 The set of tools and ideas collected in this organisation.

-## Foam workspace
+## (Your) Foam

-The directory/repository where you keep all your documents.
+The directory/repository where you keep all your notes.
+
+Also happens to sound quite a lot like Home. Funny, that.

 ## Bubble

-Individual Foam document, written in Markdown.
+Individual Foam note, written in Markdown.

-## Foam blog
-
-When you use Foam to publish content to an audience.
-
-_Better ideas welcome._
--- a/docs/user-settings.md
+++ b/docs/user-settings.md
@@ -0,0 +1,9 @@
+# User Settings (stub)
+
+**[[todo]] This [[roadmap]] item needs more specification work.** 
+
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[todo]: todo "Todo"
+[roadmap]: roadmap "Roadmap"
+[//end]: # "Autogenerated link references"
--- a/docs/vercel.md
+++ b/docs/vercel.md
@@ -0,0 +1,85 @@
+# Vercel
+
+[Vercel](https://vercel.com/) is a static website hosting solution similar to [[github-pages]]. This recipe shows you how to deploy the default Foam website template to Vercel.
+
+## Setting up the project
+
+### Using Foam's template
+
+Generate a GitHub repository using the default [Foam template](https://github.com/foambubble/foam-template), this will be the workspace that we will be deploying with Vercel. This workspace is a barebone Jekyll source website, which means we can customize and install plugins just like any other Jekyll websites.
+
+As we won't be using GitHub Pages, we will be adding a few configuration files in order to help Vercel pick up on how to build our site.
+
+### Adding a `_config.yml`
+
+First, we'll need to add a `_config.yml` at the root directory. This is the Jekyll configuration file. In here, we will set the site's title, theme, repository and permalink options, and also tell Jekyll what plugins to use:
+
+```yaml
+# _config.yml
+title: Foam
+# All the plugins we will be installing now that we won't be using GitHub Pages
+plugins:
+  - jekyll-katex  # optional
+  - jekyll-default-layout
+  - jekyll-relative-links
+  - jekyll-readme-index
+  - jekyll-titles-from-headings
+  - jekyll-optional-front-matter
+# The default Jekyll theme we will be using
+theme: jekyll-theme-primer
+# The GitHub repository that we are hosting our foam workspace from
+repository: user/repo
+# Generate permalinks in format specified in: https://jekyllrb.com/docs/permalinks/#built-in-formats
+permalink: pretty
+```
+
+The `theme` specifies a theme for our deployed Jekyll website. 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. We can also choose a theme if you want from places like [Jekyll Themes](https://jekyllthemes.io/).
+
+The `plugins` specifies a list of Jekyll plugins that we will be installing in the next section. As we won't be using GitHub Pages, we'll need to install these plugins that GitHub Pages installs for us under the hood.
+
+_If you want to use LaTeX rendered with KaTeX (which is what the plugin `jekyll-katex` does), you can specify it here. And yes, one of the benefits of deploying with Vercel is that we can use KaTeX to render LaTeX! More on: [[katex-math-rendering]]_
+
+### Adding a `Gemfile`
+
+Next up, we'll create another new file called `Gemfile` in the root directory. This is where we will let Vercel know what plugins to install when building our website.
+
+In our `Gemfile`, we need to specify our Ruby packages:
+
+```ruby
+# Gemfile
+source "https://rubygems.org"
+gem "jekyll"
+gem "kramdown-parser-gfm"
+gem "jekyll-theme-primer"
+gem "jekyll-optional-front-matter"
+gem "jekyll-default-layout"
+gem "jekyll-relative-links"
+gem "jekyll-readme-index"
+gem "jekyll-titles-from-headings"
+gem "jekyll-katex"  # Optional, the package that enables KaTeX math rendering
+```
+
+### Enable math rendering with KaTeX (optional)
+
+Besides adding the plugin `jekyll-katex` in `_config.yml` and `Gemfile`, we'll also have to follow the guides in [[katex-math-rendering]] to let our site fully support using KaTeX to render math equations.
+
+### Commiting changes to GitHub repo
+
+Finally, commit the newly created files to GitHub.
+
+## Importing project to Vercel
+
+First, import our foam workspace (GitHub repository) to Vercel with [Vercel's _Import Git Repository_](https://vercel.com/import/git). Paste our GitHub repo's url and Vercel will automatically pull and analyze the tool we use to deploy our website. (In our case: Jekyll.)
+
+Next, select the folder to deploy from if prompted. If we are using the default template, then Vercel will default to the root directory of our Foam workspace.
+
+Finally, if all is successful, Vercel will show the detected framework: Jekyll. Press `Deploy` to proceed on publishing our project.
+
+![](assets/images/vercel-detect-preset.png)
+
+And now, Vercel will take care of building and rendering our foam workspace each time on push. Vercel will publish our site to `xxx.vercel.app`, we can also define a custom domain name for our Vercel website.
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[github-pages]: github-pages "GitHub Pages"
+[katex-math-rendering]: katex-math-rendering "Katex Math Rendering"
+[//end]: # "Autogenerated link references"
--- a/docs/wiki-links.md
+++ b/docs/wiki-links.md
@@ -1,9 +1,10 @@
 # Wiki Links

-Foam enables you to Link pages together using `[[file-name]]` annotations.
+Foam enables you to Link pages together using `[[file-name]]` annotations (i.e. `[[media-wiki]]` links).

- Both `[[file-name]]` and `[[file-name.md]]` work
 - Type `[[` and start typing a file name for autocompletion.
+  - Note that your file names should be in `lower-dash-case.md`, and your wiki links should reference file names exactly: `[[lower-dash-case]]`, not `[[Lower Dash Case]]`. 
+  - See [[link-formatting-and-autocompletion]] for more information, and how to setup your link autocompletions to make this easier.
 - `Cmd` + `Click` ( `Ctrl` + `Click` on Windows ) on file name to navigate to file (`F12` also works while your cursor is on the file name)
 - `Cmd` + `Click` ( `Ctrl` + `Click` on Windows ) on non-existent file to create that file in the workspace.

@@ -16,72 +17,17 @@ Foam enables you to Link pages together using `[[file-name]]` annotations.

 ## Markdown compatibility

-The [Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode) extension automatically generates [markdown link reference definitions](https://spec.commonmark.org/0.29/#link-reference-definitions) at the bottom of the file to make wiki-links compatible with Markdown tools and parsers.
-
-If you look at link references the bottom of any Foam workspace file that uses wiki-links, you should see an automatically generated list of references that look as follows:
-
-```markdown
-[wiki-links]: wiki-links "Wiki Links"
-[other-page]: other-page "Other Page"
-```
-
-These exist to make `[[wiki-links]]` compatible with Markdown-consuming tools such as static site generators, VS Code plugins etc. 
-
-## Why don't `[[wiki-links]]` work on GitHub
-
-> **TL;DR;** [workaround](#workaround) in the end.
-
-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.
-
-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.
-
-So, why don't they work on GitHub?
-
-The three components of a [link reference definitions](https://spec.commonmark.org/0.29/#link-reference-definitions) are:
-
- **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 destination** The target of the matched link
- **"Link Title"** Optional title for link (The Foam template has a snippet of JavaScript to replace this on the website at runtime)
-
-The issue is the middle **link destination** component. It's configured to point to the file name **without file extension**, i.e. "file-name" instead of "file-name.md". This is to make the GitHub Pages rendering work, because if we generated the links to `file-name.md`, the links would point to the raw markdown files instead of their generated HTML versions.
-
-| Environment      | `file-name` | `file-name.md` |
-| ---------------- | ----------- | -------------- |
-| **VS Code**      | Works       | Works          |
-| **GitHub pages** | Works       | Breaks         |
-| **GitHub UI**    | Breaks      | Works          |
-
-So as you can see, we've prioritised GitHub Pages over GitHub Web U for the time being.
-
-Ideally, we'd like a solution that works with both, but I haven't thought of it yet. Ideas include:
-
- **Writing a better static side generator that works with `file-name.md` link targets.** This is on the [[roadmap]], but for the time being GitHub Pages support is as must-have.
- **Adding a configuration setting to generate `file-name.md` link targets.** This is fine and I would accept this contribution to [foam-vscode](https://github.com/foambubble/foam/tree/master/packages/foam-vscode), but it doesn't solve the core problem.
-
-An acceptable solution may include one where we don't generate link reference definitions at all, but if we do, ideally, we'd like to generate `file-name.md` links since those are more standards compatible for different markdown tools.
-
-I'm sure there's an elegant-ish solution out there. Ideas and suggestions welcome that the [tracking issue on GitHub](https://github.com/foambubble/foam/issues/16)
-
-### Workaround
-
-For the time being, you can use relative `[markdown links](markdown-link.md)` syntax.
-
-**Pros:**
-
- This will work on all platforms.
-
-**Cons:**
-
- It will break the Markdown Notes [[backlinking]] support
- Less convenient to write
+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 wiki-links compatible with Markdown tools and parsers.

 ## Read more

 - [[foam-file-format]]
+- [[link-formatting-and-autocompletion]]
+- See [[link-reference-definition-improvements]] for further discussion on current problems and potential solutions.

 [//begin]: # "Autogenerated link references for markdown compatibility"
-[wiki-links]: wiki-links "Wiki Links"
-[roadmap]: roadmap "Roadmap"
-[backlinking]: backlinking "Backlinking"
+[link-formatting-and-autocompletion]: link-formatting-and-autocompletion "Link Formatting and Autocompletion"
+[link-reference-definitions]: link-reference-definitions "Link Reference Definitions"
 [foam-file-format]: foam-file-format "Foam File Format"
+[link-reference-definition-improvements]: link-reference-definition-improvements "Link Reference Definition Improvements"
 [//end]: # "Autogenerated link references"
--- a/docs/workspace-janitor.md
+++ b/docs/workspace-janitor.md
@@ -1,69 +1,40 @@
-# Workspace Janitor
+# Janitor

-## What is it?
+To store your personal knowledge graph in markdown files instead of a database, we need some additional tooling to create and maintain relationships with notes.

-To store your personal knowledge graph in markdown files instead of a database, we need some additional tooling to create and maintain:
+**Foam Janitor** (inspired by Andy Matuschak's [note-link-janitor](https://github.com/andymatuschak/note-link-janitor)) helps you migrate existing notes to Foam, and maintain your Foam's health over time.

- Relationships between notes
-  - link references for [[wiki-links]]/markdown compatibility
-  - [[materialized-backlinks]]
-  - etc.
- Format and structure of each note (e.g. title)
- Renaming and refactoring files and directories
- Linting related functionality
-  - File names
-  - Note links
-  - Zettelkasten linking
- Visibility for orphaned notes
+Currently, Foam's Janitor helps you to:
+- Ensure your [[link-reference-definitions]] are up to date
+- Ensure every document has a well-formatted title (required for Markdown Links, Markdown Notes, and Foam Gatsby Template compatibility)

-This is necessary:
+In the future, Janitor can help you with
+- Updating [[materialized-backlinks]]
+- Lint, format and structure notes
+- Rename and move notes around while keeping their references up to date.

- When migrating to Foam
- To maintain your workspace health over long period of time
+## Using Janitor from VS Code (Experimental)

-## Problem
+Execute the "Foam: Run Janitor" command from the command palette.

-Currently, the VS Code extension is very naive, and only updates the currently active editor. This isn't sufficient, because:
+![Foam Janitor demo](assets/images/foam-janitor-demo.gif)

- For e.g. [[materialized-backlinks]] to work, files need to update in the background.
-  - Separation of clean vs generated workspace for publishing?
-  - Support for standard markdown tools
-    - Output to a /build directory
-    - Would have to implement a custom previewer
-    - [[todo]] **Janne Ojanaho! Write a short proposal for this.**
- If VS Code extension bugs our or is not ran, the workspace can lead in an inconsistent state
- In collaboration scenarios, two people may change the same file, causing incomplete updates
- If someone pushes changes from outside VS Code (Obsidian, Git Journal, etc.) links aren't updated
+## Using Janitor from command line (Experimental)

-## Proposal
+> ⚠️ Improvements to this documentation are welcome!

-Implement a note janitor (working title, named after Andy Matuschak's [note-link-janitor](https://github.com/andymatuschak/note-link-janitor)), which ensures all files are correctly linked and updated, no matter how changes happen.
+The Janitor can be installed from [NPM](https://www.npmjs.com/) and executed as a standalone CLI tool:

-Janitor should be runnable:
+```sh
+> npm install -g foam-cli
+> foam janitor path/to/workspace
+```

- From VS Code
-  - Replaces the existing logic in extension.ts
-  - In theory, we could do this using the [VS Code Tasks](https://code.visualstudio.com/docs/editor/tasks), exposing it from foam-vscode with a [TaskProvider](https://code.visualstudio.com/api/extension-guides/task-provider)
-  - It's not clear to me whether modifying the file in the active VS Code buffer from a background task is problematic for e.g. focus/selection management. I think this is how e.g. Prettier works, but not sure if there's some special case for the active editor.
-  - VS Code provides its own workspace watching functionality. Not sure it would be beneficial to use this over just chokidar-style file watching in the background
- As a pre-push Git Hook (is this a good idea?) to ensure we send fully formed note graphs, even if you had to do some editing outside vs code
- As a GitHub Action (for incoming changes via PRs and other apps like GitJournal)
-  - Run the "build" and push back to master/gh-pages
- As a NPM script/dependency for any other purpose
+You can run the Janitor as a git hook on every commit to ensure your workspace links are up to date. This can be especially helpful if you edit your markdown documents from other apps. 

-## Software architecture
-
- It's not really clear to me whether the workspace janitor should be its own package, or if the Janitor should just be the [[cli]] package, or the [[foam-core]] package.
- Ideally the janitor should be lightweight so installing it on CI is quick
- It would be cool if it didn't have many weird node-specific dependencies, maybe it could be even ran INSIDE a mobile application?
- We don't want to pollute foam-core, but janitor might actually get quite diverse in use cases.
-
-Decoupling things like the core janitor API from the CLI API would help potentially with situations where we might want to have a separate file watcher strategy for CLI and active VS Code workspaces (see above).
+You can also run the Janitor from a GitHub action to ensure that all changes coming to your workspace are up to date. This can be useful when editing your Foam notes from mobile (i.e. via [GitJournal](https://gitjournal.io)), or your Foam has multiple contributors and you want to ensure that all changes are correctly integrated.

 [//begin]: # "Autogenerated link references for markdown compatibility"
-[wiki-links]: wiki-links "Wiki Links"
+[link-reference-definitions]: link-reference-definitions "Link Reference Definitions"
 [materialized-backlinks]: materialized-backlinks "Materialized Backlinks (stub)"
-[cli]: cli "Command Line Interface"
-[foam-core]: foam-core "Foam Core"
-[todo]: todo "Todo"
 [//end]: # "Autogenerated link references"
--- a/lerna.json
+++ b/lerna.json
@@ -4,5 +4,5 @@
  ],
  "npmClient": "yarn",
  "useWorkspaces": true,
-  "version": "0.2.0"
+  "version": "0.3.1"
 }
--- a/package.json
+++ b/package.json
@@ -10,7 +10,15 @@
    "packages/*"
  ],
  "scripts": {
-    "watch": "yarn workspace foam-vscode watch"
+    "start:vscode": "yarn workspace foam-vscode vscode:start-debugging",
+    "build:core": "yarn workspace foam-core build",
+    "watch:core": "yarn workspace foam-core start",
+    "test:core": "yarn workspace foam-core test",
+    "clean": "lerna run clean",
+    "build": "lerna run build",
+    "test": "lerna run test",
+    "lint": "lerna run lint",
+    "watch": "lerna run watch --concurrency 20 --stream"
  },
  "devDependencies": {
    "all-contributors-cli": "^6.16.1",
--- a/packages/foam-cli/README.md
+++ b/packages/foam-cli/README.md
@@ -19,7 +19,7 @@ $ npm install -g foam-cli
 $ foam COMMAND
 running command...
 $ foam (-v|--version|version)
-foam-cli/0.2.0 darwin-x64 node-v12.18.0
+foam-cli/0.3.0 darwin-x64 node-v12.18.0
 $ foam --help [COMMAND]
 USAGE
  $ foam COMMAND
@@ -28,28 +28,9 @@ USAGE
 <!-- usagestop -->
 # Commands
 <!-- commands -->
-* [`foam hello [FILE]`](#foam-hello-file)
 * [`foam help [COMMAND]`](#foam-help-command)
-
-## `foam hello [FILE]`
-
-describe the command here
-
-```
-USAGE
-  $ foam hello [FILE]
-
-OPTIONS
-  -f, --force
-  -h, --help       show CLI help
-  -n, --name=name  name to print
-
-EXAMPLE
-  $ foam hello
-  hello world from ./src/hello.ts!
-```
-
-_See code: [src/commands/hello.ts](https://github.com/foambubble/foam/blob/v0.2.0/src/commands/hello.ts)_
+* [`foam janitor [WORKSPACEPATH]`](#foam-janitor-workspacepath)
+* [`foam migrate [WORKSPACEPATH]`](#foam-migrate-workspacepath)

 ## `foam help [COMMAND]`

@@ -67,6 +48,43 @@ OPTIONS
 ```

 _See code: [@oclif/plugin-help](https://github.com/oclif/plugin-help/blob/v3.1.0/src/commands/help.ts)_
+
+## `foam janitor [WORKSPACEPATH]`
+
+Updates link references and heading across all the markdown files in the given workspaces
+
+```
+USAGE
+  $ foam janitor [WORKSPACEPATH]
+
+OPTIONS
+  -h, --help                show CLI help
+  -w, --without-extensions  generate link reference definitions without extensions (for legacy support)
+
+EXAMPLE
+  $ foam-cli janitor path-to-foam-workspace
+```
+
+_See code: [src/commands/janitor.ts](https://github.com/foambubble/foam/blob/v0.3.0/src/commands/janitor.ts)_
+
+## `foam migrate [WORKSPACEPATH]`
+
+Updates file names, link references and heading across all the markdown files in the given workspaces
+
+```
+USAGE
+  $ foam migrate [WORKSPACEPATH]
+
+OPTIONS
+  -h, --help                show CLI help
+  -w, --without-extensions  generate link reference definitions without extensions (for legacy support)
+
+EXAMPLE
+  $ foam-cli migrate path-to-foam-workspace
+  Successfully generated link references and heading!
+```
+
+_See code: [src/commands/migrate.ts](https://github.com/foambubble/foam/blob/v0.3.0/src/commands/migrate.ts)_
 <!-- commandsstop -->

 ## Development
--- a/packages/foam-cli/babel.config.js
+++ b/packages/foam-cli/babel.config.js
@@ -0,0 +1,6 @@
+module.exports = {
+  presets: [
+    ['@babel/preset-env', {targets: {node: 'current'}}],
+   '@babel/preset-typescript',
+  ],
+};
--- a/packages/foam-cli/jest.config.js
+++ b/packages/foam-cli/jest.config.js
@@ -0,0 +1,188 @@
+// For a detailed explanation regarding each configuration property, visit:
+// https://jestjs.io/docs/en/configuration.html
+
+module.exports = {
+  // All imported modules in your tests should be mocked automatically
+  // automock: false,
+
+  // Stop running tests after `n` failures
+  // bail: 0,
+
+  // The directory where Jest should store its cached dependency information
+  // cacheDirectory: "/private/var/folders/p6/5y5l8tbs1d32pq9b596lk48h0000gn/T/jest_dx",
+
+  // Automatically clear mock calls and instances between every test
+  clearMocks: true,
+
+  // Indicates whether the coverage information should be collected while executing the test
+  // collectCoverage: false,
+
+  // An array of glob patterns indicating a set of files for which coverage information should be collected
+  // collectCoverageFrom: undefined,
+
+  // The directory where Jest should output its coverage files
+  // coverageDirectory: undefined,
+
+  // An array of regexp pattern strings used to skip coverage collection
+  // coveragePathIgnorePatterns: [
+  //   "/node_modules/"
+  // ],
+
+  // Indicates which provider should be used to instrument code for coverage
+  // coverageProvider: "babel",
+
+  // A list of reporter names that Jest uses when writing coverage reports
+  // coverageReporters: [
+  //   "json",
+  //   "text",
+  //   "lcov",
+  //   "clover"
+  // ],
+
+  // An object that configures minimum threshold enforcement for coverage results
+  // coverageThreshold: undefined,
+
+  // A path to a custom dependency extractor
+  // dependencyExtractor: undefined,
+
+  // Make calling deprecated APIs throw helpful error messages
+  // errorOnDeprecated: false,
+
+  // Force coverage collection from ignored files using an array of glob patterns
+  // forceCoverageMatch: [],
+
+  // A path to a module which exports an async function that is triggered once before all test suites
+  // globalSetup: undefined,
+
+  // A path to a module which exports an async function that is triggered once after all test suites
+  // globalTeardown: undefined,
+
+  // A set of global variables that need to be available in all test environments
+  // globals: {},
+
+  // The maximum amount of workers used to run your tests. Can be specified as % or a number. E.g. maxWorkers: 10% will use 10% of your CPU amount + 1 as the maximum worker number. maxWorkers: 2 will use a maximum of 2 workers.
+  // maxWorkers: "50%",
+
+  // An array of directory names to be searched recursively up from the requiring module's location
+  // moduleDirectories: [
+  //   "node_modules"
+  // ],
+
+  // An array of file extensions your modules use
+  // moduleFileExtensions: [
+  //   "js",
+  //   "json",
+  //   "jsx",
+  //   "ts",
+  //   "tsx",
+  //   "node"
+  // ],
+
+  // A map from regular expressions to module names or to arrays of module names that allow to stub out resources with a single module
+  // moduleNameMapper: {},
+
+  // An array of regexp pattern strings, matched against all module paths before considered 'visible' to the module loader
+  // modulePathIgnorePatterns: [],
+
+  // Activates notifications for test results
+  // notify: false,
+
+  // An enum that specifies notification mode. Requires { notify: true }
+  // notifyMode: "failure-change",
+
+  // A preset that is used as a base for Jest's configuration
+  // preset: undefined,
+
+  // Run tests from one or more projects
+  // projects: undefined,
+
+  // Use this configuration option to add custom reporters to Jest
+  // reporters: undefined,
+
+  // Automatically reset mock state between every test
+  // resetMocks: false,
+
+  // Reset the module registry before running each individual test
+  // resetModules: false,
+
+  // A path to a custom resolver
+  // resolver: undefined,
+
+  // Automatically restore mock state between every test
+  // restoreMocks: false,
+
+  // The root directory that Jest should scan for tests and modules within
+  // rootDir: undefined,
+
+  // A list of paths to directories that Jest should use to search for files in
+  // roots: [
+  //   "<rootDir>"
+  // ],
+
+  // Allows you to use a custom runner instead of Jest's default test runner
+  // runner: "jest-runner",
+
+  // The paths to modules that run some code to configure or set up the testing environment before each test
+  // setupFiles: [],
+
+  // A list of paths to modules that run some code to configure or set up the testing framework before each test
+  // setupFilesAfterEnv: [],
+
+  // A list of paths to snapshot serializer modules Jest should use for snapshot testing
+  // snapshotSerializers: [],
+
+  // The test environment that will be used for testing
+  testEnvironment: "node",
+
+  // Options that will be passed to the testEnvironment
+  // testEnvironmentOptions: {},
+
+  // Adds a location field to test results
+  // testLocationInResults: false,
+
+  // The glob patterns Jest uses to detect test files
+  // testMatch: [
+  //   "**/__tests__/**/*.[jt]s?(x)",
+  //   "**/?(*.)+(spec|test).[tj]s?(x)"
+  // ],
+
+  // An array of regexp pattern strings that are matched against all test paths, matched tests are skipped
+  // testPathIgnorePatterns: [
+  //   "/node_modules/"
+  // ],
+
+  // The regexp pattern or array of patterns that Jest uses to detect test files
+  // testRegex: [],
+
+  // This option allows the use of a custom results processor
+  // testResultsProcessor: undefined,
+
+  // This option allows use of a custom test runner
+  // testRunner: "jasmine2",
+
+  // This option sets the URL for the jsdom environment. It is reflected in properties such as location.href
+  // testURL: "http://localhost",
+
+  // Setting this value to "fake" allows the use of fake timers for functions such as "setTimeout"
+  // timers: "real",
+
+  // A map from regular expressions to paths to transformers
+  // transform: undefined,
+
+  // An array of regexp pattern strings that are matched against all source file paths, matched files will skip transformation
+  // transformIgnorePatterns: [
+  //   "/node_modules/"
+  // ],
+
+  // An array of regexp pattern strings that are matched against all modules before the module loader will automatically return a mock for them
+  // unmockedModulePathPatterns: undefined,
+
+  // Indicates whether each individual test should be reported during the run
+  // verbose: undefined,
+
+  // An array of regexp patterns that are matched against all source file paths before re-running tests in watch mode
+  // watchPathIgnorePatterns: [],
+
+  // Whether to use watchman for file crawling
+  // watchman: true,
+};
--- a/packages/foam-cli/package.json
+++ b/packages/foam-cli/package.json
@@ -1,7 +1,7 @@
 {
  "name": "foam-cli",
  "description": "Foam CLI",
-  "version": "0.2.0",
+  "version": "0.3.0",
  "author": "Jani Eväkallio @jevakallio",
  "bin": {
    "foam": "./bin/run"
@@ -11,17 +11,24 @@
    "@oclif/command": "^1",
    "@oclif/config": "^1",
    "@oclif/plugin-help": "^3",
+    "foam-core": "^0.3.0",
+    "ora": "^4.0.4",
    "tslib": "^1"
  },
  "devDependencies": {
+    "@babel/core": "^7.10.4",
+    "@babel/preset-env": "^7.10.4",
+    "@babel/preset-typescript": "^7.10.4",
    "@oclif/dev-cli": "^1",
    "@types/node": "^10",
+    "babel-jest": "^26.1.0",
    "chai": "^4",
    "eslint": "^5.13",
    "eslint-config-oclif": "^3.1",
    "eslint-config-oclif-typescript": "^0.1",
-    "foam-core": "^0.2.0",
    "globby": "^10",
+    "jest": "^26.1.0",
+    "mock-fs": "^4.12.0",
    "ts-node": "^8",
    "typescript": "^3.3"
  },
@@ -52,11 +59,13 @@
  },
  "repository": "foambubble/foam",
  "scripts": {
-    "cli": "./bin/run",
+    "clean": "rimraf tmp",
+    "build": "tsc -b",
+    "test": "jest",
+    "lint": "echo Missing lint task in CLI package",
+    "cli": "yarn build && ./bin/run",
    "postpack": "rm -f oclif.manifest.json",
-    "posttest": "eslint . --ext .ts --config .eslintrc",
    "prepack": "rm -rf lib && tsc -b && oclif-dev manifest && oclif-dev readme",
-    "test": "nyc --extension .ts mocha --forbid-only \"test/**/*.test.ts\"",
    "version": "oclif-dev readme && git add README.md"
  },
  "types": "lib/index.d.ts"
--- a/packages/foam-cli/src/commands/hello.ts
+++ b/packages/foam-cli/src/commands/hello.ts
@@ -1,44 +0,0 @@
-import {Command, flags} from '@oclif/command'
-import { NoteGraph } from 'foam-core';
-export default class Hello extends Command {
-  static description = 'describe the command here'
-
-  static examples = [
-    `$ foam hello
-hello world from ./src/hello.ts!
-`,
-  ]
-
-  static flags = {
-    help: flags.help({char: 'h'}),
-    // flag with a value (-n, --name=VALUE)
-    name: flags.string({char: 'n', description: 'name to print'}),
-    // flag with no value (-f, --force)
-    force: flags.boolean({char: 'f'}),
-  }
-
-  static args = [{name: 'file'}]
-
-  async run() {
-    const {args, flags} = this.parse(Hello)
-    const name = flags.name ?? 'world'
-
-//     const wm = new NoteGraph();
-//     wm.addNoteFromMarkdown('page-a.md', `
-// # Page A
-// ## Section
-// - [[page-b]]
-// - [[page-c]];
-//     `);
-
-//     wm.addNoteFromMarkdown('page-a.md', `
-// # Page B
-// This references [[page-a]]`);
-
-//     console.log(wm.getNoteWithLinks('page-a'));
-
-
-
-
-  }
-}
--- a/packages/foam-cli/src/commands/janitor.ts
+++ b/packages/foam-cli/src/commands/janitor.ts
@@ -0,0 +1,79 @@
+import { Command, flags } from '@oclif/command';
+import * as ora from 'ora';
+import {
+  initializeNoteGraph,
+  generateLinkReferences,
+  generateHeading,
+  applyTextEdit
+} from 'foam-core';
+import { writeFileToDisk } from '../utils/write-file-to-disk';
+import { isValidDirectory } from '../utils';
+
+export default class Janitor extends Command {
+  static description =
+    'Updates link references and heading across all the markdown files in the given workspaces';
+
+  static examples = [
+    `$ foam-cli janitor path-to-foam-workspace
+`,
+  ];
+
+  static flags = {
+    'without-extensions': flags.boolean({
+      char: 'w',
+      description: 'generate link reference definitions without extensions (for legacy support)'
+    }),
+    help: flags.help({ char: 'h' }),
+  };
+
+  static args = [{ name: 'workspacePath' }];
+
+  async run() {
+    const spinner = ora('Reading Files').start();
+
+    const { args, flags } = this.parse(Janitor);
+
+    const { workspacePath = './' } = args;
+
+    if (isValidDirectory(workspacePath)) {
+      const graph = await initializeNoteGraph(workspacePath);
+
+      const notes = graph.getNotes().filter(Boolean); // removes undefined notes
+
+      spinner.succeed();
+      spinner.text = `${notes.length} files found`;
+      spinner.succeed();
+
+      // exit early if no files found.
+      if (notes.length === 0) {
+        this.exit();
+      }
+
+      spinner.text = 'Generating link definitions';
+
+      const fileWritePromises = notes.map(note => {
+        // Get edits
+        const heading = generateHeading(note);
+        const definitions = generateLinkReferences(note, graph, !flags['without-extensions']);
+
+        // apply Edits
+        let file = note.source.text;
+        file = heading ? applyTextEdit(file, heading) : file;
+        file = definitions ? applyTextEdit(file, definitions) : file;
+
+        if (heading || definitions) {
+          return writeFileToDisk(note.source.uri, file);
+        }
+
+        return Promise.resolve(null);
+      });
+
+      await Promise.all(fileWritePromises);
+
+      spinner.succeed();
+      spinner.succeed('Done!');
+    } else {
+      spinner.fail('Directory does not exist!');
+    }
+  }
+}
--- a/packages/foam-cli/src/commands/migrate.ts
+++ b/packages/foam-cli/src/commands/migrate.ts
@@ -0,0 +1,106 @@
+import { Command, flags } from '@oclif/command';
+import * as ora from 'ora';
+import {
+  initializeNoteGraph,
+  generateLinkReferences,
+  generateHeading,
+  getKebabCaseFileName,
+  applyTextEdit
+} from 'foam-core';
+import { writeFileToDisk } from '../utils/write-file-to-disk';
+import { renameFile } from '../utils/rename-file';
+import { isValidDirectory } from '../utils';
+
+// @todo: Refactor 'migrate' and 'janitor' commands and avoid repeatition
+export default class Migrate extends Command {
+  static description =
+    'Updates file names, link references and heading across all the markdown files in the given workspaces';
+
+  static examples = [
+    `$ foam-cli migrate path-to-foam-workspace
+Successfully generated link references and heading!
+`,
+  ];
+
+  static flags = {
+    'without-extensions': flags.boolean({
+      char: 'w',
+      description: 'generate link reference definitions without extensions (for legacy support)'
+    }),
+    help: flags.help({ char: 'h' }),
+  };
+
+  static args = [{ name: 'workspacePath' }];
+
+  async run() {
+    const spinner = ora('Reading Files').start();
+
+    const { args, flags } = this.parse(Migrate);
+
+    const { workspacePath = './' } = args;
+
+    if (isValidDirectory(workspacePath)) {
+      let graph = await initializeNoteGraph(workspacePath);
+
+      let notes = graph.getNotes().filter(Boolean); // removes undefined notes
+
+      spinner.succeed();
+      spinner.text = `${notes.length} files found`;
+      spinner.succeed();
+
+      // exit early if no files found.
+      if (notes.length === 0) {
+        this.exit();
+      }
+
+      // Kebab case file names
+      const fileRename = notes.map(note => {
+        if (note.title != null) {
+          const kebabCasedFileName = getKebabCaseFileName(note.title);
+          if (kebabCasedFileName) {
+            return renameFile(note.source.uri, kebabCasedFileName);
+          }
+        }
+        return Promise.resolve(null);
+      });
+
+      await Promise.all(fileRename);
+
+      spinner.text = 'Renaming files';
+
+      // Reinitialize the graph after renaming files
+      graph = await initializeNoteGraph(workspacePath);
+
+      notes = graph.getNotes().filter(Boolean); // remove undefined notes
+
+      spinner.succeed();
+      spinner.text = 'Generating link definitions';
+
+      const fileWritePromises = await Promise.all(
+        notes.map(note => {
+          // Get edits
+          const heading = generateHeading(note);
+          const definitions = generateLinkReferences(note, graph, !flags['without-extensions']);
+
+          // apply Edits
+          let file = note.source.text;
+          file = heading ? applyTextEdit(file, heading) : file;
+          file = definitions ? applyTextEdit(file, definitions) : file;
+
+          if (heading || definitions) {
+            return writeFileToDisk(note.source.uri, file);
+          }
+
+          return Promise.resolve(null);
+        })
+      );
+
+      await Promise.all(fileWritePromises);
+
+      spinner.succeed();
+      spinner.succeed('Done!');
+    } else {
+      spinner.fail('Directory does not exist!');
+    }
+  }
+}
--- a/packages/foam-cli/src/utils/index.ts
+++ b/packages/foam-cli/src/utils/index.ts
@@ -0,0 +1,4 @@
+import * as fs from 'fs';
+
+export const isValidDirectory = (path: string) =>
+  fs.existsSync(path) && fs.lstatSync(path).isDirectory();
--- a/packages/foam-cli/src/utils/rename-file.ts
+++ b/packages/foam-cli/src/utils/rename-file.ts
@@ -0,0 +1,15 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ *
+ * @param fileUri absolute path for the file that needs to renamed
+ * @param newFileName  "new file name" without the extension
+ */
+export const renameFile = async (fileUri: string, newFileName: string) => {
+  const dirName = path.dirname(fileUri);
+  const extension = path.extname(fileUri);
+  const newFileUri = path.join(dirName, `${newFileName}${extension}`);
+
+  return fs.promises.rename(fileUri, newFileUri);
+};
--- a/packages/foam-cli/src/utils/write-file-to-disk.ts
+++ b/packages/foam-cli/src/utils/write-file-to-disk.ts
@@ -0,0 +1,5 @@
+import * as fs from 'fs';
+
+export const writeFileToDisk = async (fileUri: string, data: string) => {
+  return fs.promises.writeFile(fileUri, data);
+};
--- a/packages/foam-cli/test/rename-file.test.ts
+++ b/packages/foam-cli/test/rename-file.test.ts
@@ -0,0 +1,30 @@
+import { renameFile } from '../src/utils/rename-file';
+import * as fs from 'fs';
+import mockFS from 'mock-fs';
+
+const doesFileExist = path =>
+  fs.promises
+    .access(path)
+    .then(() => true)
+    .catch(() => false);
+
+describe('renameFile', () => {
+  const fileUri = './test/oldFileName.md';
+
+  beforeAll(() => {
+    mockFS({ [fileUri]: '' });
+  });
+
+  afterAll(() => {
+    mockFS.restore();
+  });
+
+  it('should rename existing file', async () => {
+    expect(await doesFileExist(fileUri)).toBe(true);
+
+    renameFile(fileUri, 'new-file-name');
+
+    expect(await doesFileExist(fileUri)).toBe(false);
+    expect(await doesFileExist('./test/new-file-name.md')).toBe(true);
+  });
+});
--- a/packages/foam-cli/test/write-file-to-disk.test.ts
+++ b/packages/foam-cli/test/write-file-to-disk.test.ts
@@ -0,0 +1,23 @@
+import { writeFileToDisk } from '../src/utils/write-file-to-disk';
+import * as fs from 'fs';
+import mockFS from 'mock-fs';
+
+describe('writeFileToDisk', () => {
+  const fileUri = './test-file.md';
+
+  beforeAll(() => {
+    mockFS({ [fileUri]: 'content in the existing file' });
+  });
+
+  afterAll(() => {
+    fs.unlinkSync(fileUri);
+    mockFS.restore();
+  });
+
+  it('should overrwrite existing file in the disk with the new data', async () => {
+    const expected = `content in the new file`;
+    await writeFileToDisk(fileUri, expected);
+    const actual = await fs.promises.readFile(fileUri, { encoding: 'utf8' });
+    expect(actual).toBe(expected);
+  });
+});
--- a/packages/foam-core/package.json
+++ b/packages/foam-core/package.json
@@ -2,19 +2,21 @@
  "name": "foam-core",
  "author": "Jani Eväkallio",
  "repository": "https://github.com/foambubble/foam",
-  "version": "0.2.0",
+  "version": "0.3.0",
  "license": "MIT",
  "files": [
    "dist"
  ],
  "scripts": {
-    "start": "tsdx watch",
-    "build": "tsdx build",
+    "clean": "rimraf dist",
+    "build": "tsdx build --tsconfig ./tsconfig.build.json",
    "test": "tsdx test",
-    "lint": "tsdx lint",
+    "lint": "tsdx lint src test",
+    "watch": "tsdx watch",
    "prepare": "tsdx build"
  },
  "devDependencies": {
+    "@types/github-slugger": "^1.3.0",
    "@types/graphlib": "^2.1.6",
    "@types/lodash": "^4.14.157",
    "husky": "^4.2.5",
@@ -23,12 +25,18 @@
    "typescript": "^3.9.5"
  },
  "dependencies": {
+    "detect-newline": "^3.1.0",
+    "github-slugger": "^1.3.0",
+    "glob": "^7.1.6",
    "graphlib": "^2.1.8",
-    "lodash": "^4.17.15",
+    "lodash": "^4.17.19",
+    "remark-frontmatter": "^2.0.0",
    "remark-parse": "^8.0.2",
    "remark-wiki-link": "^0.0.4",
+    "title-case": "^3.0.2",
    "unified": "^9.0.0",
-    "unist-util-visit": "^2.0.2"
+    "unist-util-visit": "^2.0.2",
+    "yaml": "^1.10.0"
  },
  "main": "dist/index.js",
  "types": "dist/index.d.ts"
--- a/packages/foam-core/src/definitions.ts
+++ b/packages/foam-core/src/definitions.ts
@@ -0,0 +1,2 @@
+export const LINK_REFERENCE_DEFINITION_HEADER = `[//begin]: # "Autogenerated link references for markdown compatibility"`;
+export const LINK_REFERENCE_DEFINITION_FOOTER = `[//end]: # "Autogenerated link references"`;
--- a/packages/foam-core/src/index.ts
+++ b/packages/foam-core/src/index.ts
@@ -1,5 +1,39 @@
-export { NoteGraph, Note, NoteLink } from './note-graph';
+import { NoteGraph, Note, NoteLink } from './note-graph';
+
 export {
  createNoteFromMarkdown,
  createMarkdownReferences,
+  stringifyMarkdownLinkReferenceDefinition,
 } from './markdown-provider';
+
+export {
+  TextEdit,
+  generateHeading,
+  generateLinkReferences,
+  getKebabCaseFileName,
+} from './janitor';
+
+export { applyTextEdit } from './janitor/apply-text-edit';
+
+export { initializeNoteGraph } from './initialize-note-graph';
+
+export { NoteGraph, Note, NoteLink };
+
+export {
+  LINK_REFERENCE_DEFINITION_HEADER,
+  LINK_REFERENCE_DEFINITION_FOOTER,
+} from './definitions';
+
+export interface FoamConfig {
+  // TODO
+}
+
+export interface Foam {
+  notes: NoteGraph;
+  // config: FoamConfig
+}
+
+export const createFoam = (config: FoamConfig) => ({
+  notes: new NoteGraph(),
+  config: config,
+});
--- a/packages/foam-core/src/initialize-note-graph.ts
+++ b/packages/foam-core/src/initialize-note-graph.ts
@@ -0,0 +1,30 @@
+import glob from 'glob';
+import { promisify } from 'util';
+import fs from 'fs';
+import os from 'os';
+import detectNewline from 'detect-newline';
+import { NoteGraph } from './note-graph';
+import { createNoteFromMarkdown } from './markdown-provider';
+
+const findAllFiles = promisify(glob);
+
+export const initializeNoteGraph = async (workspacePath: string) => {
+  // remove trailing slash from workspacePath if exists
+  if (workspacePath.substr(-1) === '/')
+    workspacePath = workspacePath.slice(0, -1);
+
+  const files = await findAllFiles(`${workspacePath}/**/*.md`, {});
+
+  const graph = new NoteGraph();
+  await Promise.all(
+    (await files).map(f => {
+      return fs.promises.readFile(f).then(data => {
+        const markdown = (data || '').toString();
+        const eol = detectNewline(markdown) || os.EOL;
+        graph.setNote(createNoteFromMarkdown(f, markdown, eol));
+      });
+    })
+  );
+
+  return graph;
+};
--- a/packages/foam-core/src/janitor/apply-text-edit.ts
+++ b/packages/foam-core/src/janitor/apply-text-edit.ts
@@ -0,0 +1,18 @@
+import { TextEdit } from '../index';
+
+/**
+ *
+ * @param text text on which the textEdit will be applied
+ * @param textEdit
+ * @returns {string} text with the applied textEdit
+ */
+export const applyTextEdit = (text: string, textEdit: TextEdit): string => {
+  const characters = text.split('');
+  const startOffset = textEdit.range.start.offset || 0;
+  const endOffset = textEdit.range.end.offset || 0;
+  const deleteCount = endOffset - startOffset;
+
+  const textToAppend = `${textEdit.newText}`;
+  characters.splice(startOffset, deleteCount, textToAppend);
+  return characters.join('');
+};
--- a/packages/foam-core/src/janitor/index.ts
+++ b/packages/foam-core/src/janitor/index.ts
@@ -0,0 +1,127 @@
+import { Position } from 'unist';
+import GithubSlugger from 'github-slugger';
+import { Note, GraphNote, NoteGraph } from '../note-graph';
+import {
+  LINK_REFERENCE_DEFINITION_HEADER,
+  LINK_REFERENCE_DEFINITION_FOOTER,
+} from '../definitions';
+import {
+  createMarkdownReferences,
+  stringifyMarkdownLinkReferenceDefinition,
+} from '../markdown-provider';
+import { getHeadingFromFileName } from '../utils';
+
+const slugger = new GithubSlugger();
+
+export interface TextEdit {
+  range: Position;
+  newText: string;
+}
+
+export const generateLinkReferences = (
+  note: GraphNote,
+  ng: NoteGraph,
+  includeExtensions: boolean
+): TextEdit | null => {
+  if (!note) {
+    return null;
+  }
+
+  const markdownReferences = createMarkdownReferences(
+    ng,
+    note.id,
+    includeExtensions
+  );
+
+  const newReferences =
+    markdownReferences.length === 0
+      ? ''
+      : [
+          LINK_REFERENCE_DEFINITION_HEADER,
+          ...markdownReferences.map(stringifyMarkdownLinkReferenceDefinition),
+          LINK_REFERENCE_DEFINITION_FOOTER,
+        ].join(note.source.eol);
+
+  if (note.definitions.length === 0) {
+    if (newReferences.length === 0) {
+      return null;
+    }
+
+    const padding =
+      note.source.end.column === 1
+        ? note.source.eol
+        : `${note.source.eol}${note.source.eol}`;
+    return {
+      newText: `${padding}${newReferences}`,
+      range: {
+        start: note.source.end,
+        end: note.source.end,
+      },
+    };
+  } else {
+    const first = note.definitions[0];
+    const last = note.definitions[note.definitions.length - 1];
+    const oldReferences = note.definitions
+      .map(stringifyMarkdownLinkReferenceDefinition)
+      .join(note.source.eol);
+
+    if (oldReferences === newReferences) {
+      return null;
+    }
+
+    return {
+      // @todo: do we need to ensure new lines?
+      newText: `${newReferences}`,
+      range: {
+        start: first.position!.start,
+        end: last.position!.end,
+      },
+    };
+  }
+};
+
+export const generateHeading = (note: Note): TextEdit | null => {
+  if (!note) {
+    return null;
+  }
+
+  if (note.title) {
+    return null;
+  }
+
+  const frontmatterExists = note.source.contentStart.line !== 1;
+
+  let newLineExistsAfterFrontmatter = false;
+  if (frontmatterExists) {
+    const lines = note.source.text.split(note.source.eol);
+    const index = note.source.contentStart.line - 1;
+    const line = lines[index];
+    newLineExistsAfterFrontmatter = line === '';
+  }
+
+  const paddingStart = frontmatterExists ? note.source.eol : '';
+  const paddingEnd = newLineExistsAfterFrontmatter
+    ? note.source.eol
+    : `${note.source.eol}${note.source.eol}`;
+
+  return {
+    newText: `${paddingStart}# ${getHeadingFromFileName(
+      note.slug
+    )}${paddingEnd}`,
+    range: {
+      start: note.source.contentStart,
+      end: note.source.contentStart,
+    },
+  };
+};
+
+/**
+ *
+ * @param fileName
+ * @returns null if file name is already in kebab case otherise returns
+ * the kebab cased file name
+ */
+export const getKebabCaseFileName = (fileName: string) => {
+  const kebabCasedFileName = slugger.slug(fileName);
+  return kebabCasedFileName === fileName ? null : kebabCasedFileName;
+};
--- a/packages/foam-core/src/markdown-provider.ts
+++ b/packages/foam-core/src/markdown-provider.ts
@@ -1,11 +1,14 @@
 import unified from 'unified';
 import markdownParse from 'remark-parse';
 import wikiLinkPlugin from 'remark-wiki-link';
+import frontmatterPlugin from 'remark-frontmatter';
+import { parse as parseYAML } from 'yaml';
 import visit, { CONTINUE, EXIT } from 'unist-util-visit';
-import { Node, Parent } from 'unist';
+import { Node, Parent, Point } from 'unist';
 import * as path from 'path';
-import { Link, Note, NoteGraph } from './note-graph';
-import { dropExtension } from './utils';
+import { NoteLink, NoteLinkDefinition, NoteGraph, Note } from './note-graph';
+import { dropExtension, uriToSlug } from './utils';
+import { ID } from './types';

 let processor: unified.Processor | null = null;

@@ -14,44 +17,121 @@ function parse(markdown: string): Node {
    processor ||
    unified()
      .use(markdownParse, { gfm: true })
+      .use(frontmatterPlugin, ['yaml'])
      .use(wikiLinkPlugin);
  return processor.parse(markdown);
 }

-export function createNoteFromMarkdown(uri: string, markdown: string): Note {
-  const filename = path.basename(uri);
-  const id = path.parse(filename).name;
+export function createNoteFromMarkdown(
+  uri: string,
+  markdown: string,
+  eol: string
+): Note {
  const tree = parse(markdown);
-  let title = id;
+  let title: string | null = null;
+
  visit(tree, node => {
    if (node.type === 'heading' && node.depth === 1) {
      title = ((node as Parent)!.children[0].value as string) || title;
    }
-    return title === id ? CONTINUE : EXIT;
+    return title === null ? CONTINUE : EXIT;
  });
-  const links: Link[] = [];
+
+  const links: NoteLink[] = [];
+  const linkDefinitions: NoteLinkDefinition[] = [];
+  let frontmatter: any = {};
+  let start: Point = { line: 1, column: 1, offset: 0 }; // start position of the note
  visit(tree, node => {
+    if (node.type === 'yaml') {
+      frontmatter = parseYAML(node.value as string) ?? {}; // parseYAML returns null if the frontmatter is empty
+      // Update the start position of the note by exluding the metadata
+      start = {
+        line: node.position!.end.line! + 1,
+        column: 1,
+        offset: node.position!.end.offset! + 1,
+      };
+    }
+
    if (node.type === 'wikiLink') {
      links.push({
-        from: id,
-        to: node.value as string,
-        text: node.value as string,
+        type: 'wikilink',
+        slug: node.value as string,
+        position: node.position!,
+      });
+    }
+
+    if (node.type === 'definition') {
+      linkDefinitions.push({
+        label: node.label as string,
+        url: node.url as string,
+        title: node.title as string,
+        position: node.position,
      });
    }
  });
-  return new Note(id, title, links, uri, markdown);
+
+  // Give precendence to the title from the frontmatter if it exists
+  title = frontmatter.title ?? title;
+
+  const end = tree.position!.end;
+  const definitions = getFoamDefinitions(linkDefinitions, end);
+
+  return {
+    properties: frontmatter,
+    slug: uriToSlug(uri),
+    title: title,
+    links: links,
+    definitions: definitions,
+    source: {
+      uri: uri,
+      text: markdown,
+      contentStart: start,
+      end: end,
+      eol: eol,
+    },
+  };
 }

-interface MarkdownReference {
-  linkText: string;
-  wikiLink: string;
-  pageTitle: string;
+function getFoamDefinitions(
+  defs: NoteLinkDefinition[],
+  fileEndPoint: Point
+): NoteLinkDefinition[] {
+  let previousLine = fileEndPoint.line;
+  let foamDefinitions = [];
+
+  // walk through each definition in reverse order
+  // (last one first)
+  for (const def of defs.reverse()) {
+    // if this definition is more than 2 lines above the
+    // previous one below it (or file end), that means we
+    // have exited the trailing definition block, and should bail
+    const start = def.position!.start.line;
+    if (start < previousLine - 2) {
+      break;
+    }
+
+    foamDefinitions.unshift(def);
+    previousLine = def.position!.end.line;
+  }
+
+  return foamDefinitions;
 }

+export function stringifyMarkdownLinkReferenceDefinition(
+  definition: NoteLinkDefinition
+) {
+  let text = `[${definition.label}]: ${definition.url}`;
+  if (definition.title) {
+    text = `${text} "${definition.title}"`;
+  }
+
+  return text;
+}
 export function createMarkdownReferences(
  graph: NoteGraph,
-  noteId: string
-): MarkdownReference[] {
+  noteId: ID,
+  includeExtension: boolean
+): NoteLinkDefinition[] {
  const source = graph.getNote(noteId);

  // Should never occur since we're already in a file,
@@ -66,30 +146,42 @@ export function createMarkdownReferences(
  return graph
    .getForwardLinks(noteId)
    .map(link => {
-      const target = graph.getNote(link.to);
-
+      let target = graph.getNote(link.to);
+      // if we don't find the target by ID we search the graph by slug
+      if (!target) {
+        const candidates = graph.getNotes({ slug: link.link.slug });
+        if (candidates.length > 1) {
+          console.log(
+            `Warning: Slug ${link.link.slug} matches ${candidates.length} documents. Picking one.`
+          );
+        }
+        target = candidates.length > 0 ? candidates[0] : null;
+      }
      // We are dropping links to non-existent notes here,
      // but int the future we may want to surface these too
      if (!target) {
        console.log(
-          `Link '${link.to}' in '${noteId}' points to a non-existing note.`
+          `Warning: Link '${link.to}' in '${noteId}' points to a non-existing note.`
        );
        return null;
      }

      const relativePath = path.relative(
-        path.dirname(source.path),
-        target.path
+        path.dirname(source.source.uri),
+        target.source.uri
      );
-      const relativePathWithoutExtension = dropExtension(relativePath);

-      // [wiki-link-text]: wiki-link "Page title"
+      const pathToNote = includeExtension
+        ? relativePath
+        : dropExtension(relativePath);
+
+      // [wiki-link-text]: path/to/file.md "Page title"
      return {
-        linkText: link.to,
-        wikiLink: relativePathWithoutExtension,
-        pageTitle: target.title,
+        label: link.link.slug,
+        url: pathToNote,
+        title: target.title || target.slug,
      };
    })
    .filter(Boolean)
-    .sort() as MarkdownReference[];
+    .sort() as NoteLinkDefinition[];
 }
--- a/packages/foam-core/src/note-graph.ts
+++ b/packages/foam-core/src/note-graph.ts
@@ -1,91 +1,151 @@
-import { Graph, Edge } from 'graphlib';
+import { Graph } from 'graphlib';
+import { EventEmitter } from 'events';
+import { Position, Point, URI, ID } from './types';
+import { hashURI, computeRelativeURI } from './utils';

-type ID = string;
+export interface NoteSource {
+  uri: URI;
+  text: string;
+  contentStart: Point;
+  end: Point;
+  eol: string;
+}

-export interface Link {
+export interface WikiLink {
+  type: 'wikilink';
+  slug: string;
+  position: Position;
+}
+
+// at the moment we only model wikilink
+export type NoteLink = WikiLink;
+
+export interface NoteLinkDefinition {
+  label: string;
+  url: string;
+  title?: string;
+  position?: Position;
+}
+
+export interface Note {
+  title: string | null;
+  slug: string; // note: this slug is not necessarily unique
+  properties: object;
+  // sections: NoteSection[]
+  // tags: NoteTag[]
+  links: NoteLink[];
+  definitions: NoteLinkDefinition[];
+  source: NoteSource;
+}
+
+export type GraphNote = Note & {
+  id: ID;
+};
+
+export interface GraphConnection {
  from: ID;
  to: ID;
-  text: string;
+  link: NoteLink;
 }

-export interface NoteLink {
-  to: ID;
-  text: string;
-}
+export type NoteGraphEventHandler = (e: { note: GraphNote }) => void;

-export class Note {
-  public id: ID;
-  public title: string;
-  public source: string;
-  public path: string;
-  public links: NoteLink[];
-
-  constructor(
-    id: ID,
-    title: string,
-    links: NoteLink[],
-    path: string,
-    source: string
-  ) {
-    this.id = id;
-    this.title = title;
-    this.source = source;
-    this.path = path;
-    this.links = links;
-  }
-}
+export type NotesQuery = { slug: string } | { title: string };

 export class NoteGraph {
  private graph: Graph;
+  private events: EventEmitter;
+  private createIdFromURI: (uri: URI) => ID;

  constructor() {
    this.graph = new Graph();
+    this.events = new EventEmitter();
+    this.createIdFromURI = hashURI;
  }

-  public setNote(note: Note) {
-    if (this.graph.hasNode(note.id)) {
-      (this.graph.outEdges(note.id) || []).forEach(edge => {
+  public setNote(note: Note): GraphNote {
+    const id = this.createIdFromURI(note.source.uri);
+    const noteExists = this.graph.hasNode(id);
+    if (noteExists) {
+      (this.graph.outEdges(id) || []).forEach(edge => {
        this.graph.removeEdge(edge);
      });
    }
-    this.graph.setNode(note.id, note);
+    const graphNote: GraphNote = {
+      ...note,
+      id: id,
+    };
+    this.graph.setNode(id, graphNote);
    note.links.forEach(link => {
-      this.graph.setEdge(note.id, link.to, link.text);
+      const relativePath =
+        note.definitions.find(def => def.label === link.slug)?.url ?? link.slug;
+      const targetPath = computeRelativeURI(note.source.uri, relativePath);
+      const targetId = this.createIdFromURI(targetPath);
+      const connection: GraphConnection = {
+        from: graphNote.id,
+        to: targetId,
+        link: link,
+      };
+      this.graph.setEdge(graphNote.id, targetId, connection);
    });
+    this.events.emit(noteExists ? 'update' : 'add', { note: graphNote });
+    return graphNote;
  }

-  public getNotes(): Note[] {
-    return this.graph.nodes().map(id => this.graph.node(id));
+  public getNotes(query?: NotesQuery): GraphNote[] {
+    // prettier-ignore
+    const filterFn =
+      query == null ? (note: Note | null) => note != null
+        : 'slug' in query ? (note: Note | null) => note?.slug === query.slug
+        : 'title' in query ? (note: Note | null) => note?.title === query.title
+        : (note: Note | null) => note != null;
+
+    return this.graph
+      .nodes()
+      .map(id => this.graph.node(id))
+      .filter(filterFn);
  }

-  public getNote(noteId: ID): Note | void {
-    if (this.graph.hasNode(noteId)) {
-      return this.graph.node(noteId);
-    }
-    throw new Error(`Note with ID [${noteId}] not found`);
+  public getNote(noteId: ID): GraphNote | null {
+    return this.graph.node(noteId) ?? null;
  }

-  public getAllLinks(noteId: ID): Link[] {
+  public getNoteByURI(uri: URI): GraphNote | null {
+    return this.getNote(this.createIdFromURI(uri));
+  }
+
+  public getAllLinks(noteId: ID): GraphConnection[] {
    return (this.graph.nodeEdges(noteId) || []).map(edge =>
-      convertEdgeToLink(edge)
+      this.graph.edge(edge.v, edge.w)
    );
  }

-  public getForwardLinks(noteId: ID): Link[] {
+  public getForwardLinks(noteId: ID): GraphConnection[] {
    return (this.graph.outEdges(noteId) || []).map(edge =>
-      convertEdgeToLink(edge)
+      this.graph.edge(edge.v, edge.w)
    );
  }

-  public getBacklinks(noteId: ID): Link[] {
+  public getBacklinks(noteId: ID): GraphConnection[] {
    return (this.graph.inEdges(noteId) || []).map(edge =>
-      convertEdgeToLink(edge)
+      this.graph.edge(edge.v, edge.w)
    );
  }
+
+  public unstable_onNoteAdded(callback: NoteGraphEventHandler) {
+    this.events.addListener('add', callback);
+  }
+
+  public unstable_onNoteUpdated(callback: NoteGraphEventHandler) {
+    this.events.addListener('update', callback);
+  }
+
+  public unstable_removeEventListener(callback: NoteGraphEventHandler) {
+    this.events.removeListener('add', callback);
+    this.events.removeListener('update', callback);
+  }
+
+  public dispose() {
+    this.events.removeAllListeners();
+  }
 }
-
-const convertEdgeToLink = (edge: Edge): Link => ({
-  from: edge.v,
-  to: edge.w,
-  text: edge.name || edge.w,
-});
--- a/packages/foam-core/src/types.d.ts
+++ b/packages/foam-core/src/types.d.ts
@@ -0,0 +1,4 @@
+export { Position, Point } from 'unist';
+
+export type URI = string;
+export type ID = string;
--- a/packages/foam-core/src/utils.ts
+++ b/packages/foam-core/src/utils.ts
@@ -1,5 +1,46 @@
+import path from 'path';
+import crypto from 'crypto';
+import { titleCase } from 'title-case';
+import GithubSlugger from 'github-slugger';
+import { URI, ID } from 'types';
+
+export const hash = (text: string) =>
+  crypto
+    .createHash('sha1')
+    .update(text)
+    .digest('hex');
+
+export const uriToSlug = (noteUri: URI): string => {
+  return GithubSlugger.slug(path.parse(noteUri).name);
+};
+
+export const hashURI = (uri: URI): ID => {
+  return hash(path.normalize(uri));
+};
+
+export const computeRelativeURI = (
+  reference: URI,
+  relativeSlug: string
+): URI => {
+  // if no extension is provided, use the same extension as the source file
+  const slug =
+    path.extname(relativeSlug) !== ''
+      ? relativeSlug
+      : `${relativeSlug}${path.extname(reference)}`;
+  return path.normalize(path.join(path.dirname(reference), slug));
+};
+
 export function dropExtension(path: string): string {
  const parts = path.split('.');
  parts.pop();
  return parts.join('.');
 }
+
+/**
+ *
+ * @param filename
+ * @returns title cased heading after removing special characters
+ */
+export const getHeadingFromFileName = (filename: string): string => {
+  return titleCase(filename.replace(/[^\w\s]/gi, ' '));
+};
--- a/packages/foam-core/test/migration/Roam
+++ b/packages/foam-core/test/migration/Roam
@@ -0,0 +1,3 @@
+# Roam Document
+
+[[Second Roam Document]]
--- a/packages/foam-core/test/migration/Second
+++ b/packages/foam-core/test/migration/Second
@@ -0,0 +1 @@
+# Second Roam Document
--- a/packages/foam-core/test/scaffold/file-with-only-frontmatter.md
+++ b/packages/foam-core/test/scaffold/file-with-only-frontmatter.md
@@ -0,0 +1,3 @@
+---
+noTitle: This frontmatter doesn't contain any title
+---
--- a/packages/foam-core/test/scaffold/file-without-title.md
+++ b/packages/foam-core/test/scaffold/file-without-title.md
@@ -0,0 +1 @@
+This file is missing a title
--- a/packages/foam-core/test/scaffold/first-document.md
+++ b/packages/foam-core/test/scaffold/first-document.md
@@ -0,0 +1,11 @@
+# First Document
+
+Here's some [unrelated] content.
+
+[unrelated]: http://unrelated.com 'This link should not be changed'
+
+[[file-without-title]]
+
+[//begin]: # 'Autogenerated link references for markdown compatibility'
+[second-document]: second-document 'Second Document'
+[//end]: # 'Autogenerated link references'
--- a/packages/foam-core/test/scaffold/index.md
+++ b/packages/foam-core/test/scaffold/index.md
@@ -0,0 +1,9 @@
+# Index
+
+This file is intentionally missing the link reference definitions
+
+[[first-document]]
+
+[[second-document]]
+
+[[file-without-title]]
--- a/packages/foam-core/test/scaffold/second-document.md
+++ b/packages/foam-core/test/scaffold/second-document.md
@@ -0,0 +1,9 @@
+# Second Document
+
+This is just a link target for now.
+
+We can use it for other things later if needed.
+
+[//begin]: # 'Autogenerated link references for markdown compatibility'
+[first-document]: first-document 'First Document'
+[//end]: # 'Autogenerated link references'
--- a/packages/foam-core/test/scaffold/third-document.md
+++ b/packages/foam-core/test/scaffold/third-document.md
@@ -0,0 +1,12 @@
+# Third Document
+
+All the link references are correct in this file.
+
+[[first-document]]
+
+[[second-document]]
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[first-document]: first-document "First Document"
+[second-document]: second-document "Second Document"
+[//end]: # "Autogenerated link references"
--- a/Show More
+++ b/Show More