v0.7.2

Added API and events around note deletion

Improved github workflows, added logic to avoid duplicate runs in CI and merged build + test jobs

Added support for running workflows in multiple environments, commented window-2019 as test don't pass, but they will be fixed in another PR to avoid scope creep here.

.all-contributorsrc

@@ -175,7 +175,8 @@
       "profile": "https://anku.netlify.com/",
       "contributions": [
         "doc",
-        "test"
+        "test",
+        "code"
       ]
     },
     {
@@ -211,7 +212,8 @@
       "avatar_url": "https://avatars3.githubusercontent.com/u/8980971?v=4",
       "profile": "https://sanketdg.github.io",
       "contributions": [
-        "doc"
+        "doc",
+        "code"
       ]
     },
     {
@@ -241,6 +243,289 @@
         "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"
+      ]
+    },
+    {
+      "login": "ingalless",
+      "name": "ingalless",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/22981941?v=4",
+      "profile": "https://ingalless.com",
+      "contributions": [
+        "code",
+        "doc"
+      ]
+    },
+    {
+      "login": "jmg-duarte",
+      "name": "José Duarte",
+      "avatar_url": "https://avatars2.githubusercontent.com/u/15343819?v=4",
+      "profile": "http://jmg-duarte.github.io",
+      "contributions": [
+        "code",
+        "doc"
+      ]
+    },
+    {
+      "login": "yenly",
+      "name": "Yenly",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/6759658?v=4",
+      "profile": "https://www.yenly.wtf",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "hikerpig",
+      "name": "hikerpig",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/2259688?v=4",
+      "profile": "https://www.hikerpig.cn",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "Sigfried",
+      "name": "Sigfried Gold",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/1586931?v=4",
+      "profile": "http://sigfried.org",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "tristansokol",
+      "name": "Tristan Sokol",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/867661?v=4",
+      "profile": "http://www.tristansokol.com",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "umbrellait-danil-rodin",
+      "name": "Danil Rodin",
+      "avatar_url": "https://avatars0.githubusercontent.com/u/49779373?v=4",
+      "profile": "https://umbrellait.com",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "scott-joe",
+      "name": "Scott Williams",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/2026866?v=4",
+      "profile": "https://www.linkedin.com/in/scottjoewilliams/",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "Jackiexiao",
+      "name": "jackiexiao",
+      "avatar_url": "https://avatars2.githubusercontent.com/u/18050469?v=4",
+      "profile": "https://jackiexiao.github.io/blog",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "jbn",
+      "name": "John B Nelson",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/78835?v=4",
+      "profile": "https://generativist.substack.com/",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "asifm",
+      "name": "Asif Mehedi",
+      "avatar_url": "https://avatars2.githubusercontent.com/u/3958387?v=4",
+      "profile": "https://github.com/asifm",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "litanlitudan",
+      "name": "Tan Li",
+      "avatar_url": "https://avatars2.githubusercontent.com/u/4970420?v=4",
+      "profile": "https://github.com/litanlitudan",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "ShaunaGordon",
+      "name": "Shauna Gordon",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/579361?v=4",
+      "profile": "http://shaunagordon.com",
+      "contributions": [
+        "doc"
+      ]
     }
   ],
   "contributorsPerLine": 7,

.github/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,21 @@
+---
+name: Bug report
+about: Create a report to help us be foamier
+labels: bug
+---
+
+<!-- Check in the VSCode extension tab. -->
+- Foam version:
+
+**Summary**
+<!-- A clear and concise description of what the bug is.-->
+
+**Steps to reproduce**
+1.
+2.
+
+Does this issue occur on the [foam template](https://github.com/foambubble/foam-template) repo? Yes/No
+
+**Additional information**
+<!-- Add any other context about the problem here. -->
+*Feel free to attach a screenshot and/or include a zip with a minimal repo to reproduce the issue*

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Question
+    url: https://discord.gg/8c4BChMfSu
+    about: Please ask and answer questions here.

.github/ISSUE_TEMPLATE/feature.md

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

.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - '**'
+  # The following will also make the workflow run on all PRs, internal and external.
+  # This would create duplicate runs, that we are skipping by adding the "if" to the jobs below.
+  # See https://github.community/t/duplicate-checks-on-push-and-pull-request-simultaneous-event/18012
+  pull_request:
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-18.04
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != 'foambubble/foam'
+    steps:
+      - uses: actions/checkout@v1
+      - name: Setup Node
+        uses: actions/setup-node@v1
+        with:
+          node-version: '12'
+      - name: Install Dependencies
+        run: yarn
+      - name: Check Lint Rules
+        run: yarn lint
+
+  test:
+    name: Build and Test
+    strategy:
+      matrix:
+        os: [macos-10.15, ubuntu-18.04] # add windows-2019 after fixing tests for it
+    runs-on: ${{ matrix.os }}
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != 'foambubble/foam'
+    env:
+      OS: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v1
+      - name: Setup Node
+        uses: actions/setup-node@v1
+        with:
+          node-version: '12'
+      - name: Install Dependencies
+        run: yarn
+      - name: Build Packages
+        run: yarn build
+      - name: Run Tests
+        run: yarn test

.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,17 @@
 			"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}"
 		}
 	]
 }

.vscode/settings.json

@@ -7,9 +7,15 @@
     },
     "search.exclude": {
         // set this to false to include compiled JS folders in search results
-        "packages/**/out": true, 
+        "packages/**/out": true,
         "packages/**/dist": true
     },
     // Turn off tsc task auto detection since we have the necessary tasks as npm scripts
-    "typescript.tsc.autoDetect": "off"
+    "typescript.tsc.autoDetect": "off",
+    "foam.files.ignore": [
+        "**/.vscode/**/*",
+        "**/_layouts/**/*",
+        "**/_site/**/*",
+        "**/node_modules/**/*"
+    ]
 }

.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
+			},
 		}
 	]
 }

CONTRIBUTING.md

@@ -1,14 +0,0 @@
-# Contributing
-
-Hello, friend.
-
-This repository is a [monorepo](https://en.wikipedia.org/wiki/Monorepo) managed by [Yarn Workspaces](https://classic.yarnpkg.com/en/docs/workspaces/).
-
-- The [packages](packages/) directory contains all Foam core code packages
-- The [docs](docs/) directory contains a Foam workspace that hosts the official [documentation site](https://foambubble.github.io/foam)
-
-The foam starter template lives outside of this repository at [foambubble/foam-template](https://github.com/foambubble/foam-template).
-
-See [Foam Contribution Guide](https://foambubble.github.io/foam/contribution-guide) on the rendered Foam workspace for more information on how to contribute to Foam.
-
-Thank you for your interest!

docs/.vscode/settings.json

@@ -5,6 +5,8 @@
   "editor.overviewRulerBorder": false,
   "editor.lineHeight": 24,
   "workbench.colorTheme": "Gray Matter Light",
+  "foam.edit.linkReferenceDefinitions": "withExtensions",
+  "vscodeMarkdownNotes.noteCompletionConvention": "noExtension",
   "[markdown]": {
     "editor.quickSuggestions": {
       "other": true,

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 }}

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>

docs/_layouts/mathjax.html

@@ -1,22 +1,9 @@
 ---
-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>
-
 <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({

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>

docs/architecture.md

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

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;
 }

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>

docs/automatic-git-syncing.md

@@ -1,11 +1,11 @@
 # Automatic Git Syncing (stub)
 
-**[[todo]] This [[roadmap]] item needs more specification work.** 
+**[[todo]] This [[roadmap]] item needs more specification work.**
 
 If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
 
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[roadmap]: roadmap "Roadmap"
-[//end]: # "Autogenerated link references"
+[todo]: todo.md "Todo"
+[roadmap]: roadmap.md "Roadmap"
+[//end]: # "Autogenerated link references"

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

docs/backlinking.md

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

docs/big-vision.md

@@ -14,5 +14,5 @@
 
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
+[todo]: todo.md "Todo"
 [//end]: # "Autogenerated link references"

docs/block-references.md

@@ -1,10 +1,10 @@
 # Block References (stub)
 
-**[[todo]] This [[roadmap]] item needs more specification work.** 
+**[[todo]] This [[roadmap]] item needs more specification work.**
 
 If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[roadmap]: roadmap "Roadmap"
-[//end]: # "Autogenerated link references"
+[todo]: todo.md "Todo"
+[roadmap]: roadmap.md "Roadmap"
+[//end]: # "Autogenerated link references"

docs/blog.md

@@ -3,5 +3,5 @@
 - [[2020-07-11-three-weeks-in]]
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[2020-07-11-three-weeks-in]: blog/2020-07-11-three-weeks-in "Three Weeks In"
+[2020-07-11-three-weeks-in]: blog/2020-07-11-three-weeks-in.md "Three Weeks In"
 [//end]: # "Autogenerated link references"

docs/build-vs-assemble.md

@@ -12,5 +12,5 @@ Overall, we should strive to build big things from small things. Focused, intero
 However, there becomes a point where we may benefit from implementing a centralised solution, e.g. a syntax, an extension or perhaps a VSCode language server. As much as possible, we should allow users to operate in a decentralised manner.
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[referencing-notes-by-title]: referencing-notes-by-title "Referencing notes by title"
+[referencing-notes-by-title]: referencing-notes-by-title.md "Referencing notes by title"
 [//end]: # "Autogenerated link references"

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

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)"
-[//end]: # "Autogenerated link references"
+[workspace-janitor]: workspace-janitor.md "Janitor"
+[//end]: # "Autogenerated link references"

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

docs/contributing.md

@@ -1,7 +0,0 @@
-# Contributing
-
-Head over to the [[contribution-guide]]. `CONTRIBUTING.md` file name is blocklisted on GitHub pages, and doesn't appear in the [rendered output](https://foambubble.github.io/foam).
-
-[//begin]: # "Autogenerated link references for markdown compatibility"
-[contribution-guide]: contribution-guide "Contribution Guide"
-[//end]: # "Autogenerated link references"

docs/contribution-guide.md

@@ -1,25 +1,28 @@
+---
+tags: todo, good-first-task
+---
 # Contribution Guide
+Foam is open to contributions of any kind, including but not limited to code, documentation, ideas, and feedback.
+This guide aims to help guide new and seasoned contributors getting around the Foam codebase.
 
-> [[todo]] [[good-first-task]] This contribution guide itself could be improved 😅
+## Getting Up To Speed
+Before you start contributing we recommend that you read the following links:
 
-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:
+- [[principles]] - This document describes the guiding principles behind Foam.
+- [[code-of-conduct]] - Rules we hope every contributor aims to follow, allowing everyone to participate in our community!
 
-- 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]].
-- 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]]
-  - [/packages/foam-vscode](https://github.com/foambubble/foam/tree/master/packages/foam-vscode): the core VSCode plugin
-  - [/packages/foam-core](https://github.com/foambubble/foam/tree/master/packages/foam-core): powers the core functionality in Foam across all platforms
-- Exceptions to the monorepo are:
-  - The starter template at [foambubble/foam-template](https://github.com/foambubble/)
-  - All other [[recommended-extensions]] live in their respective GitHub repos.
+## Diving In
+We understand that diving in an unfamiliar codebase may seem scary,
+to make it easier for new contributors we provide some resources:
+- [[roadmap]] - You can read our roadmap to see what is coming to Foam, many of these are open to suggestions!
+- [[architecture]] - This document describes the architecture of Foam and how the repository is structured.
 
-## Contributing to the VS Code Extension
+You can also see [existing issues](https://github.com/foambubble/foam/issues) and help out!
+Finally, the easiest way to help, is to use it and provide feedback by [submitting issues](https://github.com/foambubble/foam/issues/new/choose) or participating in the [Foam Community Discord](https://discord.gg/rtdZKgj)!
 
-If you're interested in contributing to the VS Code extension (aka `foam-vscode`), this guide will help you get things set up locally.
+## Contributing
+
+If you're interested in contributing, this short guide will help you get things set up locally.
 
 1. Clone the repo locally:
 
@@ -29,25 +32,36 @@ If you're interested in contributing to the VS Code extension (aka `foam-vscode`
 
    `yarn install`
 
-3. This project uses [Yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/).`foam-vscode` relies on `foam-core`. This means we need to compile it before we do any extension development. From the root, run the command:
+3. This project uses [Yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/). `foam-vscode` relies on `foam-core`. This means we need to compile it before we do any extension development. From the root, run the command:
 
-   `yarn workspace foam-core build`
+   `yarn build`
 
-4. Now we'll use the launch configuration defined at [`.vscode/launch.json`](https://github.com/foambubble/foam/blob/master/.vscode/launch.json) to start a new extension host of VS Code. From the root, or the `foam-vscode` workspace, press f5.
-5. In the new extension host of VS Code that launched, open a Foam workspace (e.g. your personal one, or a test-specific one created from foam-template). This is strictly not necessary, but the extension won't auto-run unless it's in a workspace with a `.vscode/foam.json` file.
-6. Test a command to make sure it's working as expected. Open the Command Palette (Ctrl/Cmd + Shift + P) and select "Foam: Update Markdown Reference List". If you see no errors, it's good to go!
+You should now be ready to start working!
+
+### The VS Code Extension
+
+This guide assumes you read the previous instructions and you're set up to work on Foam.
+
+1. Now we'll use the launch configuration defined at [`.vscode/launch.json`](https://github.com/foambubble/foam/blob/master/.vscode/launch.json) to start a new extension host of VS Code. From the root, or the `foam-vscode` workspace, press f5.
+
+2. In the new extension host of VS Code that launched, open a Foam workspace (e.g. your personal one, or a test-specific one created from [foam-template](https://github.com/foambubble/foam-template)). This is strictly not necessary, but the extension won't auto-run unless it's in a workspace with a `.vscode/foam.json` file.
+
+3. Test a command to make sure it's working as expected. Open the Command Palette (Ctrl/Cmd + Shift + P) and select "Foam: Update Markdown Reference List". If you see no errors, it's good to go!
 
 For more resources related to the VS Code Extension, check out the links below:
 
 - [[tutorial-adding-a-new-command-to-the-vs-code-extension]]
 
+---
+
+Feel free to modify and submit a PR if this guide is out-of-date or contains errors!
+
+---
+
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[good-first-task]: good-first-task "Good First Task"
-[roadmap]: roadmap "Roadmap"
-[principles]: principles "Principles"
-[code-of-conduct]: code-of-conduct "Code of Conduct"
-[recipes]: recipes "Recipes"
-[recommended-extensions]: recommended-extensions "Recommended Extensions"
-[tutorial-adding-a-new-command-to-the-vs-code-extension]: tutorial-adding-a-new-command-to-the-vs-code-extension "Tutorial: Adding a New Command to the VS Code Extension"
+[principles]: principles.md "Principles"
+[code-of-conduct]: code-of-conduct.md "Code of Conduct"
+[roadmap]: roadmap.md "Roadmap"
+[architecture]: architecture.md "Architecture"
+[tutorial-adding-a-new-command-to-the-vs-code-extension]: tutorial-adding-a-new-command-to-the-vs-code-extension.md "Tutorial: Adding a New Command to the VS Code Extension"
 [//end]: # "Autogenerated link references"

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

docs/creating-new-notes.md

@@ -1,11 +1,12 @@
 # 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]].
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[search-for-notes]: search-for-notes "Search for Notes"
-[graph-visualisation]: graph-visualisation "Graph visualisation"
+[search-for-notes]: search-for-notes.md "Search for Notes"
+[graph-visualisation]: graph-visualisation.md "Graph visualisation"
 [//end]: # "Autogenerated link references"

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

docs/customising-styles.md

@@ -5,6 +5,6 @@ You can edit `assets/css/style.scss` to change how published pages look.
 [[todo]] [[good-first-task]]
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[good-first-task]: good-first-task "Good First Task"
+[todo]: todo.md "Todo"
+[good-first-task]: good-first-task.md "Good First Task"
 [//end]: # "Autogenerated link references"

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"
+[note-macros]: note-macros.md "Custom Note Macros"
 [//end]: # "Autogenerated link references"
-

docs/diagrams-in-markdown.md

@@ -1,18 +1,33 @@
 # 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:
+
+- [Diagrams in Markdown](#diagrams-in-markdown)
+  - [Mermaid](#mermaid)
+  - [Draw.io](#drawio)
+    - [Using Draw.io](#using-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"
+[github-pages]: github-pages.md "Github Pages"
+[//end]: # "Autogenerated link references"

docs/eleventy-and-netlify.md

@@ -1,16 +1,16 @@
 # 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/). 
+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 
+- 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.
+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!

docs/foam-core.md

@@ -96,12 +96,13 @@ 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"
-[cli]: cli "Command Line Interface"
-[build-vs-assemble]: build-vs-assemble "Build vs Assemble"
-[wiki-links]: wiki-links "Wiki Links"
-[materialized-backlinks]: materialized-backlinks "Materialized Backlinks (stub)"
-[todo]: todo "Todo"
-[feature-comparison]: feature-comparison "Feature comparison"
-[foam-core-2020-07-11]: meeting-notes/foam-core-2020-07-11 "Foam Core 2020-07-11"
+[workspace-janitor]: workspace-janitor.md "Janitor"
+[cli]: cli.md "Command Line Interface"
+[build-vs-assemble]: build-vs-assemble.md "Build vs Assemble"
+[wiki-links]: wiki-links.md "Wiki Links"
+[link-reference-definitions]: link-reference-definitions.md "Link Reference Definitions"
+[materialized-backlinks]: materialized-backlinks.md "Materialized Backlinks (stub)"
+[todo]: todo.md "Todo"
+[feature-comparison]: feature-comparison.md "Feature comparison"
+[foam-core-2020-07-11]: meeting-notes/foam-core-2020-07-11.md "Foam Core 2020-07-11"
 [//end]: # "Autogenerated link references"

docs/foam-file-format.md

@@ -17,8 +17,6 @@ Here are a few specific constraints, mainly because our tooling is a bit fragmen
 - **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"
+[decision-needed]: decision-needed.md "Decision Needed"
+[wiki-links]: wiki-links.md "Wiki Links"
 [//end]: # "Autogenerated link references"

docs/foam-gatsby-template.md

@@ -0,0 +1,25 @@
+# Foam Gatsby Template
+
+You can use [foam-gatsby-template](https://github.com/mathieudutour/foam-gatsby-template) to generate a static site to host it online on Github or [Vercel](https://vercel.com). 
+
+## Publishing your foam to Github pages
+It comes configured with Github actions to auto deploy to Github pages when changes are pushed to your main branch.
+
+## Publishing your foam to Vercel
+
+When you're ready to publish, run a local build.
+```bash
+cd _layouts
+npm run build
+```
+
+Remove `public` from your .gitignore file then commit and push your public folder in `_layouts` to Github.
+
+Log into your Vercel account. (Create one if you don't have it already.)
+
+Import your project. Select `_layouts/public` as your root directory and click **Continue**. Then name your project and click **Deploy**.
+
+That's it! 
+
+
+

docs/foam-linter.md

@@ -1,11 +1,11 @@
 # Foam Linter (stub)
 
-**[[todo]] This [[roadmap]] item needs more specification work.** 
+**[[todo]] This [[roadmap]] item needs more specification work.**
 
 If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
 
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[roadmap]: roadmap "Roadmap"
-[//end]: # "Autogenerated link references"
+[todo]: todo.md "Todo"
+[roadmap]: roadmap.md "Roadmap"
+[//end]: # "Autogenerated link references"

docs/foam-local-plugins.md

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

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.md "Recommended Extensions"
+[foam-file-format]: foam-file-format.md "Foam File Format"
+[wiki-links]: wiki-links.md "Wiki Links"
+[link-formatting-and-autocompletion]: link-formatting-and-autocompletion.md "Link Formatting and Autocompletion"
+[//end]: # "Autogenerated link references"

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 then complete the authentication flow using your GitHub account
+
+1. Run the `GistPad: Open 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 creating arbitrary pages, you can 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" />

docs/git-flows-for-teams.md

@@ -1,10 +1,10 @@
 # Git Flows for Teams (stub)
 
-**[[todo]] This [[roadmap]] item needs more specification work.** 
+**[[todo]] This [[roadmap]] item needs more specification work.**
 
 If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[roadmap]: roadmap "Roadmap"
-[//end]: # "Autogenerated link references"
+[todo]: todo.md "Todo"
+[roadmap]: roadmap.md "Roadmap"
+[//end]: # "Autogenerated link references"

docs/git-integration.md

@@ -13,6 +13,6 @@ The quick and easy way is to use the Git: Commit All command after editing files
 This could be improved. [[todo]] [[good-first-task]]
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[good-first-task]: good-first-task "Good First Task"
+[todo]: todo.md "Todo"
+[good-first-task]: good-first-task.md "Good First Task"
 [//end]: # "Autogenerated link references"

docs/github-pages.md

@@ -4,9 +4,22 @@
 - The default GitHub Pages template is called [Primer](https://github.com/pages-themes/primer). See Primer docs for how to customise html layouts and templates.
 - GitHub Pages is built on [Jekyll](https://jekyllrb.com/), so it supports things like permalinks, front matter metadata etc.
 
+## Other templates
+There are many other templates which also support publish your foam workspace to github pages
+
+* gatsby-digital-garden
+    * [repo](https://github.com/mathieudutour/gatsby-digital-garden)
+    * [demo-website](https://mathieudutour.github.io/gatsby-digital-garden/)
+* foam-mkdocs-template
+    * [repo](https://github.com/Jackiexiao/foam-mkdocs-template)
+    * [demo-website](https://jackiexiao.github.io/foam/)
+* foam-jekyll-template
+    * [repo](https://github.com/hikerpig/foam-jekyll-template)
+    * [demo-website](https://wiki.hikerpig.cn/)
+
 [[todo]] [[good-first-task]] Improve this documentation
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[good-first-task]: good-first-task "Good First Task"
+[todo]: todo.md "Todo"
+[good-first-task]: good-first-task.md "Good First Task"
 [//end]: # "Autogenerated link references"

docs/gitlab-pages.md

@@ -11,13 +11,23 @@ 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) 
+Add another file to the root directory (the one with `readme.md` in it) called `_config.yaml` (no extension)
 
 ```yaml
 title: My Awesome Foam Project
 baseurl: "" # the subpath of your site, e.g. /blog
 url: "/" # the base hostname & protocol for your site
 theme: jekyll-theme-minimal
+plugins:
+  - jekyll-optional-front-matter
+optional_front_matter:
+  remove_originals: true
+defaults:
+  -
+    scope:
+      path: "" # we need to add this to properly render layouts
+    values:
+      layout: "default"
 ```
 
 You can choose a theme if you want from places like [Jekyll Themes](https://jekyllthemes.io/)
@@ -32,7 +42,7 @@ source "https://rubygems.org"
 gem "jekyll"
 gem "jekyll-theme-minimal"
 gem "jekyll-optional-front-matter"
-``` 
+```
 
 Commit the file and push it to gitlab.
 

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.md "Materialized Backlinks (stub)"
 [//end]: # "Autogenerated link references"

docs/graph-in-published-workspace.md

@@ -1,10 +1,10 @@
 # Graph in Published Workspace (stub)
 
-**[[todo]] This [[roadmap]] item needs more specification work.** 
+**[[todo]] This [[roadmap]] item needs more specification work.**
 
 If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[roadmap]: roadmap "Roadmap"
-[//end]: # "Autogenerated link references"
+[todo]: todo.md "Todo"
+[roadmap]: roadmap.md "Roadmap"
+[//end]: # "Autogenerated link references"

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

docs/how-to-write-recipes.md

@@ -15,7 +15,7 @@ Recipes are intended to document:
 
 The first section should be a bulleted list of extensions required to use this recipe. At a minimum, this section should list all additional, non-standard extensions.
 
-Ideally, you should also note which Foam [[recommended-extensions]] are responsible for providing this feature, so any issue reports can be directed to the correct repositories. 
+Ideally, you should also note which Foam [[recommended-extensions]] are responsible for providing this feature, so any issue reports can be directed to the correct repositories.
 
 When creating new recipes, if you don't know which extension does what, you can leave it out.
 
@@ -33,10 +33,10 @@ That's pretty much it!
 
 You can add [[recipes]] by creating a pull request to [foambubble/foam](https://github.com/foambubble/foam) on GitHub.
 
-Read more in our [[contribution-guide]]. 
+Read more in our [[contribution-guide]].
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[recommended-extensions]: recommended-extensions "Recommended Extensions"
-[recipes]: recipes "Recipes"
-[contribution-guide]: contribution-guide "Contribution Guide"
-[//end]: # "Autogenerated link references"
+[recommended-extensions]: recommended-extensions.md "Recommended Extensions"
+[recipes]: recipes.md "Recipes"
+[contribution-guide]: contribution-guide.md "Contribution Guide"
+[//end]: # "Autogenerated link references"

docs/images-from-your-clipboard.md

@@ -1,5 +1,5 @@
 # Images from your Clipboard
 
-You can directly link and paste images that are copied to the clipboard using the [Paste
+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.
+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.

docs/improve-default-workspace-settings.md

@@ -1,10 +1,10 @@
 # Improve Default Workspace Settings (stub)
 
-**[[todo]] This [[roadmap]] item needs more specification work.** 
+**[[todo]] This [[roadmap]] item needs more specification work.**
 
 If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[roadmap]: roadmap "Roadmap"
-[//end]: # "Autogenerated link references"
+[todo]: todo.md "Todo"
+[roadmap]: roadmap.md "Roadmap"
+[//end]: # "Autogenerated link references"

docs/improved-backlinking.md

@@ -1,11 +1,11 @@
 # Improved Backlinking (stub)
 
-**[[todo]] This [[roadmap]] item needs more specification work.** 
+**[[todo]] This [[roadmap]] item needs more specification work.**
 
 If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
 
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[roadmap]: roadmap "Roadmap"
-[//end]: # "Autogenerated link references"
+[todo]: todo.md "Todo"
+[roadmap]: roadmap.md "Roadmap"
+[//end]: # "Autogenerated link references"

docs/improved-static-site-generation.md

@@ -1,6 +1,6 @@
 # Improved Static Site Generation (stub)
 
-**[[todo]] This [[roadmap]] item needs more specification work.** 
+**[[todo]] This [[roadmap]] item needs more specification work.**
 
 If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
 
@@ -10,6 +10,6 @@ If you're interested in working on it, please start a conversation in [GitHub is
 
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[roadmap]: roadmap "Roadmap"
-[//end]: # "Autogenerated link references"
+[todo]: todo.md "Todo"
+[roadmap]: roadmap.md "Roadmap"
+[//end]: # "Autogenerated link references"

docs/inbox.md

@@ -11,8 +11,12 @@ Uncategorised thoughts, to be added
   - [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  
+  - 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

docs/index.md

@@ -11,7 +11,7 @@ You can use **Foam** for organising your research, keeping re-discoverable notes
 </p>
 
 <div class="website-only">
-    <a class="github-button" href="https://github.com/foambubble/foam" data-icon="octicon-star" data-size="large" data-show-count="true" aria-label="Star foambubble/foam on GitHub">Star</a> 
+    <a class="github-button" href="https://github.com/foambubble/foam" data-icon="octicon-star" data-size="large" data-show-count="true" aria-label="Star foambubble/foam on GitHub">Star</a>
     <a class="github-button" href="https://github.com/foambubble/foam-template" data-icon="octicon-repo-template" data-size="large" aria-label="Use this template foambubble/foam-template on GitHub">Use this template</a>
 </div>
 
@@ -62,7 +62,7 @@ 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.
 
@@ -74,6 +74,8 @@ After setting up the repository, open `.vscode/settings.json` and edit, add or r
 
 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
@@ -129,16 +131,55 @@ If that sounds like something you're interested in, I'd love to have you along o
     <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></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://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> <a href="https://github.com/foambubble/foam/commits?author=SanketDG" title="Code">💻</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>
+    <td align="center"><a href="https://ingalless.com"><img src="https://avatars3.githubusercontent.com/u/22981941?v=4" width="60px;" alt=""/><br /><sub><b>ingalless</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=ingalless" title="Code">💻</a> <a href="https://github.com/foambubble/foam/commits?author=ingalless" title="Documentation">📖</a></td>
+    <td align="center"><a href="http://jmg-duarte.github.io"><img src="https://avatars2.githubusercontent.com/u/15343819?v=4" width="60px;" alt=""/><br /><sub><b>José Duarte</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=jmg-duarte" title="Code">💻</a> <a href="https://github.com/foambubble/foam/commits?author=jmg-duarte" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://www.yenly.wtf"><img src="https://avatars1.githubusercontent.com/u/6759658?v=4" width="60px;" alt=""/><br /><sub><b>Yenly</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=yenly" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://www.hikerpig.cn"><img src="https://avatars1.githubusercontent.com/u/2259688?v=4" width="60px;" alt=""/><br /><sub><b>hikerpig</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=hikerpig" title="Code">💻</a></td>
+    <td align="center"><a href="http://sigfried.org"><img src="https://avatars1.githubusercontent.com/u/1586931?v=4" width="60px;" alt=""/><br /><sub><b>Sigfried Gold</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=Sigfried" title="Documentation">📖</a></td>
+    <td align="center"><a href="http://www.tristansokol.com"><img src="https://avatars3.githubusercontent.com/u/867661?v=4" width="60px;" alt=""/><br /><sub><b>Tristan Sokol</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=tristansokol" title="Code">💻</a></td>
+  </tr>
+  <tr>
+    <td align="center"><a href="https://umbrellait.com"><img src="https://avatars0.githubusercontent.com/u/49779373?v=4" width="60px;" alt=""/><br /><sub><b>Danil Rodin</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=umbrellait-danil-rodin" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://www.linkedin.com/in/scottjoewilliams/"><img src="https://avatars1.githubusercontent.com/u/2026866?v=4" width="60px;" alt=""/><br /><sub><b>Scott Williams</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=scott-joe" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://jackiexiao.github.io/blog"><img src="https://avatars2.githubusercontent.com/u/18050469?v=4" width="60px;" alt=""/><br /><sub><b>jackiexiao</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=Jackiexiao" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://generativist.substack.com/"><img src="https://avatars3.githubusercontent.com/u/78835?v=4" width="60px;" alt=""/><br /><sub><b>John B Nelson</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=jbn" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/asifm"><img src="https://avatars2.githubusercontent.com/u/3958387?v=4" width="60px;" alt=""/><br /><sub><b>Asif Mehedi</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=asifm" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/litanlitudan"><img src="https://avatars2.githubusercontent.com/u/4970420?v=4" width="60px;" alt=""/><br /><sub><b>Tan Li</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=litanlitudan" title="Code">💻</a></td>
+    <td align="center"><a href="http://shaunagordon.com"><img src="https://avatars1.githubusercontent.com/u/579361?v=4" width="60px;" alt=""/><br /><sub><b>Shauna Gordon</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=ShaunaGordon" title="Documentation">📖</a></td>
   </tr>
 </table>
 
@@ -155,13 +196,13 @@ 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"
-[known-issues]: known-issues "Known Issues"
-[roadmap]: roadmap "Roadmap"
-[principles]: principles "Principles"
-[contribution-guide]: contribution-guide "Contribution Guide"
+[graph-visualisation]: graph-visualisation.md "Graph visualisation"
+[backlinking]: backlinking.md "Backlinking"
+[recommended-extensions]: recommended-extensions.md "Recommended Extensions"
+[recipes]: recipes.md "Recipes"
+[frequently-asked-questions]: frequently-asked-questions.md "Frequently Asked Questions"
+[known-issues]: known-issues.md "Known Issues"
+[roadmap]: roadmap.md "Roadmap"
+[principles]: principles.md "Principles"
+[contribution-guide]: contribution-guide.md "Contribution Guide"
 [//end]: # "Autogenerated link references"

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.md "Math Support"
+[vercel]: vercel.md "Vercel"
+[//end]: # "Autogenerated link references"

docs/key-bindings.md

@@ -7,5 +7,5 @@
 - [ ]
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
+[todo]: todo.md "Todo"
 [//end]: # "Autogenerated link references"

docs/known-issues.md

@@ -11,5 +11,5 @@
   - [x] ~~This is because the link styling hack in `assets/css/style.scss`~~
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[graph-visualisation]: graph-visualisation "Graph visualisation"
+[graph-visualisation]: graph-visualisation.md "Graph visualisation"
 [//end]: # "Autogenerated link references"

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.md "Wiki Links"
+[recommended-extensions]: recommended-extensions.md "Recommended Extensions"
+[foam-file-format]: foam-file-format.md "Foam File Format"
+[principles]: principles.md "Principles"
+[//end]: # "Autogenerated link references"

docs/link-reference-definition-improvements.md

@@ -53,7 +53,7 @@ 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 
+  - 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
@@ -68,7 +68,7 @@ The potential solution:
   - 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. 
+  - 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):
@@ -111,7 +111,7 @@ The potential solution:
       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
@@ -135,8 +135,7 @@ UI-wise, the publish targets could be picked in some similar fashion as the run/
 - [tracking issue on GitHub](https://github.com/foambubble/foam/issues/16)
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[wiki-links]: wiki-links "Wiki Links"
-[roadmap]: roadmap "Roadmap"
-[link-reference-definitions]: link-reference-definitions "Link Reference Definitions"
-[backlinking]: backlinking "Backlinking"
+[wiki-links]: wiki-links.md "Wiki Links"
+[link-reference-definitions]: link-reference-definitions.md "Link Reference Definitions"
+[backlinking]: backlinking.md "Backlinking"
 [//end]: # "Autogenerated link references"

docs/link-reference-definitions.md

@@ -16,7 +16,7 @@ The following example:
   [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
+You can open the [raw markdown](https://foambubble.github.io/foam/foam-file-format.md) to see them at the bottom of this file
 
 ## Specification
 
@@ -24,14 +24,51 @@ The three components of a link reference definition are `[link-label]: link-targ
 
 - **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).
+  - 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"
-[wiki-links]: wiki-links "Wiki Links"
-[roadmap]: roadmap "Roadmap"
-[link-reference-definition-improvements]: link-reference-definition-improvements "Link Reference Definition Improvements"
-[//end]: # "Autogenerated link references"
+[workspace-janitor]: workspace-janitor.md "Janitor"
+[Todo]: todo.md "Todo"
+[link-reference-definition-improvements]: link-reference-definition-improvements.md "Link Reference Definition Improvements"
+[//end]: # "Autogenerated link references"

docs/linking-between-published-workspaces.md

@@ -1,10 +1,10 @@
 # Linking between Published Workspaces (stub)
 
-**[[todo]] This [[roadmap]] item needs more specification work.** 
+**[[todo]] This [[roadmap]] item needs more specification work.**
 
 If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[roadmap]: roadmap "Roadmap"
-[//end]: # "Autogenerated link references"
+[todo]: todo.md "Todo"
+[roadmap]: roadmap.md "Roadmap"
+[//end]: # "Autogenerated link references"

docs/make-backlinks-more-prominent.md

@@ -20,5 +20,5 @@ In the future we'll want to improve this feature by
 
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[materialized-backlinks]: materialized-backlinks "Materialized Backlinks (stub)"
-[//end]: # "Autogenerated link references"
+[materialized-backlinks]: materialized-backlinks.md "Materialized Backlinks (stub)"
+[//end]: # "Autogenerated link references"

docs/materialized-backlinks.md

@@ -1,6 +1,6 @@
 # Materialized Backlinks (stub)
 
-**[[todo]] This [[roadmap]] item needs more specification work.** 
+**[[todo]] This [[roadmap]] item needs more specification work.**
 
 If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
 
@@ -12,6 +12,6 @@ The idea would be to automatically generate lists of backlinks (and optionally,
 - Make Foam notes more portable to different apps and long-term storage
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[roadmap]: roadmap "Roadmap"
-[//end]: # "Autogenerated link references"
+[todo]: todo.md "Todo"
+[roadmap]: roadmap.md "Roadmap"
+[//end]: # "Autogenerated link references"

docs/math-support.md

@@ -4,7 +4,7 @@ layout: mathjax
 
 # Math Support
 
-The published 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`:
+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>
@@ -18,10 +18,25 @@ The published pages don't support math formulas by default. To enable this featu
 </script>
 ```
 
-Example of inline math: $e^{i \pi}+1=0$  
-Example of displayed math:  
+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.
 
-$$ 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}|}} $$  
+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`:
 
@@ -33,4 +48,4 @@ 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)
+Reference: [How to support latex in github-pages](https://stackoverflow.com/questions/26275645/how-to-support-latex-in-github-pages)

docs/mdx-by-default.md

@@ -1,10 +1,10 @@
 # MDX by Default(stub)
 
-**[[todo]] This [[roadmap]] item needs more specification work.** 
+**[[todo]] This [[roadmap]] item needs more specification work.**
 
 If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[roadmap]: roadmap "Roadmap"
-[//end]: # "Autogenerated link references"
+[todo]: todo.md "Todo"
+[roadmap]: roadmap.md "Roadmap"
+[//end]: # "Autogenerated link references"

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

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

docs/migrating-from-obsidian.md

@@ -1,11 +1,11 @@
 # Migrating from Obsidian (stub)
 
-**[[todo]] This [[roadmap]] item needs more specification work.** 
+**[[todo]] This [[roadmap]] item needs more specification work.**
 
 If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
 
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[roadmap]: roadmap "Roadmap"
-[//end]: # "Autogenerated link references"
+[todo]: todo.md "Todo"
+[roadmap]: roadmap.md "Roadmap"
+[//end]: # "Autogenerated link references"

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!

docs/migrating-from-roam.md

@@ -1,10 +1,10 @@
 # Migrating from Roam (stub)
 
-**[[todo]] This [[roadmap]] item needs more specification work.** 
+**[[todo]] This [[roadmap]] item needs more specification work.**
 
 If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[roadmap]: roadmap "Roadmap"
-[//end]: # "Autogenerated link references"
+[todo]: todo.md "Todo"
+[roadmap]: roadmap.md "Roadmap"
+[//end]: # "Autogenerated link references"

docs/mobile-apps.md

@@ -1,6 +1,6 @@
 # Mobile Apps
 
-We must always ask ourselves, [[build-vs-assemble]]. 
+We must always ask ourselves, [[build-vs-assemble]].
 
 This Roadmap item discusses existing assembled solutions, and some thoughts on future Foam mobile experience.
 
@@ -10,13 +10,15 @@ This Roadmap item discusses existing assembled solutions, and some thoughts on f
 
 #### Pros
 - Open source
-- Already a usable solution. 
+- Already a usable solution.
 - 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,6 @@ 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"
+[build-vs-assemble]: build-vs-assemble.md "Build vs Assemble"
+[workspace-janitor]: workspace-janitor.md "Janitor"
+[//end]: # "Autogenerated link references"

docs/new-note-for-testing.md

@@ -1,4 +0,0 @@
-
-[//begin]: # "Autogenerated link references for markdown compatibility"
-[unrelated]: unrelated "Unrelated"
-[//end]: # "Autogenerated link references"

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.md "Daily notes"
+[//end]: # "Autogenerated link references"
+

docs/officially-support-alternative-templates.md

@@ -1,6 +1,6 @@
 # Officially Support Alternative Templates (stub)
 
-**[[todo]] This [[roadmap]] item needs more specification work.** 
+**[[todo]] This [[roadmap]] item needs more specification work.**
 
 If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
 
@@ -8,6 +8,6 @@ If you're interested in working on it, please start a conversation in [GitHub is
 
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[roadmap]: roadmap "Roadmap"
-[//end]: # "Autogenerated link references"
+[todo]: todo.md "Todo"
+[roadmap]: roadmap.md "Roadmap"
+[//end]: # "Autogenerated link references"

docs/packaged-desktop-app.md

@@ -1,11 +1,11 @@
 # Packaged Desktop App (stub)
 
-**[[todo]] This [[roadmap]] item needs more specification work.** 
+**[[todo]] This [[roadmap]] item needs more specification work.**
 
 If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
 
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[roadmap]: roadmap "Roadmap"
-[//end]: # "Autogenerated link references"
+[todo]: todo.md "Todo"
+[roadmap]: roadmap.md "Roadmap"
+[//end]: # "Autogenerated link references"

docs/predefined-user-snippets.md

@@ -0,0 +1,53 @@
+# 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.md "Adding Custom Snippets"
+[//end]: # "Autogenerated link references"

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

docs/publishing-pages.md

@@ -23,5 +23,5 @@ Would be cool if Foam pages could be published. Some ideas here.
     - [ ] More granular access control? Email someone a link with a hash? [Testing](testing.md)
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[build-vs-assemble]: build-vs-assemble "Build vs Assemble"
+[build-vs-assemble]: build-vs-assemble.md "Build vs Assemble"
 [//end]: # "Autogenerated link references"

docs/publishing-permissions.md

@@ -1,6 +1,6 @@
 # Publishing Permissions(stub)
 
-**[[todo]] This [[roadmap]] item needs more specification work.** 
+**[[todo]] This [[roadmap]] item needs more specification work.**
 
 If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
 
@@ -10,6 +10,6 @@ If you're interested in working on it, please start a conversation in [GitHub is
 - Share specific page (with private hash)
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[roadmap]: roadmap "Roadmap"
-[//end]: # "Autogenerated link references"
+[todo]: todo.md "Todo"
+[roadmap]: roadmap.md "Roadmap"
+[//end]: # "Autogenerated link references"

docs/random-thoughts.md

@@ -1 +1 @@
-# Random thoughts
+# Random thoughts

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.md "Todo"
+[//end]: # "Autogenerated link references"

docs/recipes.md

@@ -23,6 +23,7 @@ Guides, tips and strategies for getting the most out of your Foam workspace!
 ## Take smart notes
 
 - Introduction to Zettelkasten [[todo]]
+- Clip webpages with [[web-clipper]]
 
 ## Discover
 - Explore your notes using [[graph-visualisation]]
@@ -33,12 +34,15 @@ Guides, tips and strategies for getting the most out of your Foam workspace!
 - 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]]
+- [[shows-image-preview-on-hover]]
 - [Markdown All-in-One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one) features [[todo]] [[good-first-task]]
   - Manage checklists
   - Automatic Table of Contents
@@ -49,16 +53,25 @@ 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 using official Foam template
+  - Publish to [[github-pages]]
+  - Publish to [[gitlab-pages]]
+  - Publish to [[azure-devops-wiki]]
+  - Publish to [[vercel]]
+- Publish using community templates
+  - [[eleventy-and-netlify]] by [@juanfrank77](https://github.com/juanfrank77)
+  - [[foam-gatsby-template]] by [@mathieudutour](https://github.com/mathieudutour)
+  - [foamy-nextjs](https://github.com/yenly/foamy-nextjs) by [@yenly](https://github.com/yenly)
 - Make the site your own by [[customising-styles]].
-- Math support [[math-support]]
+- 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
 
@@ -68,9 +81,7 @@ Guides, tips and strategies for getting the most out of your Foam workspace!
 
 ## 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
 
@@ -87,23 +98,35 @@ Thought of a recipe but don't see a category for them? Add them here and we'll o
 _See [[contribution-guide]] and [[how-to-write-recipes]]._
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[contribution-guide]: contribution-guide "Contribution Guide"
-[how-to-write-recipes]: how-to-write-recipes "How to Write Recipes"
-[todo]: todo "Todo"
-[graph-visualisation]: graph-visualisation "Graph visualisation"
-[backlinking]: backlinking "Backlinking"
-[unlinked-references]: unlinked-references "Unlinked references (stub)"
-[reference-lists]: reference-lists "Reference Lists"
-[wiki-links]: wiki-links "Wiki Links"
-[creating-new-notes]: creating-new-notes "Creating New 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"
-[git-integration]: git-integration "Git integration"
-[github-pages]: github-pages "Github Pages"
-[eleventy-and-netlify]: eleventy-and-netlify "Eleventy and Netlify"
-[customising-styles]: customising-styles "Customising Styles"
-[math-support]: math-support "Math Support"
+[contribution-guide]: contribution-guide.md "Contribution Guide"
+[how-to-write-recipes]: how-to-write-recipes.md "How to Write Recipes"
+[todo]: todo.md "Todo"
+[web-clipper]: web-clipper.md "Web Clipper"
+[graph-visualisation]: graph-visualisation.md "Graph visualisation"
+[backlinking]: backlinking.md "Backlinking"
+[unlinked-references]: unlinked-references.md "Unlinked references (stub)"
+[reference-lists]: reference-lists.md "Reference Lists"
+[wiki-links]: wiki-links.md "Wiki Links"
+[link-formatting-and-autocompletion]: link-formatting-and-autocompletion.md "Link Formatting and Autocompletion"
+[creating-new-notes]: creating-new-notes.md "Creating New Notes"
+[daily-notes]: daily-notes.md "Daily notes"
+[note-macros]: note-macros.md "Custom Note Macros"
+[diagrams-in-markdown]: diagrams-in-markdown.md "Diagrams in Markdown"
+[automatically-expand-urls-to-well-titled-links]: automatically-expand-urls-to-well-titled-links.md "Automatically Expand URLs to Well-Titled Links"
+[custom-markdown-preview-styles]: custom-markdown-preview-styles.md "Custom Markdown Preview Styles"
+[images-from-your-clipboard]: images-from-your-clipboard.md "Images from your Clipboard"
+[shows-image-preview-on-hover]: shows-image-preview-on-hover.md "Shows Image Preview on Hover"
+[good-first-task]: good-first-task.md "Good First Task"
+[git-integration]: git-integration.md "Git integration"
+[gistpad]: gistpad.md "GistPad"
+[github-pages]: github-pages.md "Github Pages"
+[gitlab-pages]: gitlab-pages.md "GitLab Pages"
+[eleventy-and-netlify]: eleventy-and-netlify.md "Eleventy and Netlify"
+[azure-devops-wiki]: azure-devops-wiki.md "Azure DevOps Wiki"
+[vercel]: vercel.md "Vercel"
+[customising-styles]: customising-styles.md "Customising Styles"
+[math-support]: math-support.md "Math Support"
+[katex-math-rendering]: katex-math-rendering.md "Katex Math Rendering"
+[capture-notes-with-drafts-pro]: capture-notes-with-drafts-pro.md "Capture Notes With Drafts Pro"
+[foam-gatsby-template]: foam-gatsby-template.md "Foam Gatsby Template"
 [//end]: # "Autogenerated link references"

docs/recommended-extensions.md

@@ -10,3 +10,16 @@ This list is subject to change. Especially the Git ones.
 - [Markdown All In One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one)
 - [Git Lens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens)
 
+
+## Extensions For Additional Features
+
+These extensions are not (yet?) defined in `.vscode/extensions.json`, but have been used by others and shown to play nice with Foam.
+
+- [Emojisense](https://marketplace.visualstudio.com/items?itemName=bierner.emojisense)
+- [Markdown Emoji](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-emoji) (adds `:smile:` syntax, works with emojisense to provide autocomplete for this syntax)
+- [Mermaid Support for Preview](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid)
+- [Mermaid Markdown Syntax Highlighting](https://marketplace.visualstudio.com/items?itemName=bpruitt-goddard.mermaid-markdown-syntax-highlighting)
+- [Paste Image](https://marketplace.visualstudio.com/items?itemName=mushan.vscode-paste-image)
+- [VSCode PDF Viewing](https://marketplace.visualstudio.com/items?itemName=tomoki1207.pdf)
+- [Markdown Extended](https://marketplace.visualstudio.com/items?itemName=jebbs.markdown-extended) (with `kbd` option disabled, `kbd` turns wiki-links into non-clickable buttons)
+- [GitDoc](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.gitdoc) (easy version management via git auto commits)

docs/refactoring-via-language-server-protocol.md

@@ -1,10 +1,10 @@
 # Refactoring via Language Server Protocol (stub)
 
-**[[todo]] This [[roadmap]] item needs more specification work.** 
+**[[todo]] This [[roadmap]] item needs more specification work.**
 
 If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[roadmap]: roadmap "Roadmap"
-[//end]: # "Autogenerated link references"
+[todo]: todo.md "Todo"
+[roadmap]: roadmap.md "Roadmap"
+[//end]: # "Autogenerated link references"

docs/reference-lists.md

@@ -6,11 +6,11 @@ Use [[backlinking]] for handy reference lists:
 
 - Add links like [[recommendation]], [[book]] etc.
 - Create a page by that name and use its back links to see all todo's, recommendations, etc.
-- Alternatively, higlight the `[[link]]` and `Cmd`+`Shift`+`F` to find all references without creating a page.
+- Alternatively, highlight the `[[link]]` and `Cmd`+`Shift`+`F` to find all references without creating a page.
 - [[todo]]: [[materialized-backlinks]] would be very useful here.
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[backlinking]: backlinking "Backlinking"
-[todo]: todo "Todo"
-[materialized-backlinks]: materialized-backlinks "Materialized Backlinks"
+[backlinking]: backlinking.md "Backlinking"
+[todo]: todo.md "Todo"
+[materialized-backlinks]: materialized-backlinks.md "Materialized Backlinks (stub)"
 [//end]: # "Autogenerated link references"

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"
-[//end]: # "Autogenerated link references"
+[unlinked-references]: unlinked-references.md "Unlinked references (stub)"
+[renaming-files]: renaming-files.md "Renaming files (stub)"
+[//end]: # "Autogenerated link references"