Setup Language Server boilerplate (#258)

.all-contributorsrc

@@ -212,8 +212,7 @@
       "avatar_url": "https://avatars3.githubusercontent.com/u/8980971?v=4",
       "profile": "https://sanketdg.github.io",
       "contributions": [
-        "doc",
-        "code"
+        "doc"
       ]
     },
     {
@@ -407,314 +406,6 @@
       "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"
-      ]
-    },
-    {
-      "login": "MCluck90",
-      "name": "Mike Cluck",
-      "avatar_url": "https://avatars1.githubusercontent.com/u/1753801?v=4",
-      "profile": "https://mcluck.tech",
-      "contributions": [
-        "code"
-      ]
-    },
-    {
-      "login": "bpugh",
-      "name": "Brandon Pugh",
-      "avatar_url": "https://avatars1.githubusercontent.com/u/684781?v=4",
-      "profile": "http://brandonpugh.com",
-      "contributions": [
-        "code"
-      ]
-    },
-    {
-      "login": "themaxdavitt",
-      "name": "Max Davitt",
-      "avatar_url": "https://avatars1.githubusercontent.com/u/27709025?v=4",
-      "profile": "https://max.davitt.me",
-      "contributions": [
-        "doc"
-      ]
-    },
-    {
-      "login": "anglinb",
-      "name": "Brian Anglin",
-      "avatar_url": "https://avatars3.githubusercontent.com/u/2637602?v=4",
-      "profile": "http://briananglin.me",
-      "contributions": [
-        "doc"
-      ]
-    },
-    {
-      "login": "elswork",
-      "name": "elswork",
-      "avatar_url": "https://avatars1.githubusercontent.com/u/1455507?v=4",
-      "profile": "http://deft.work",
-      "contributions": [
-        "doc"
-      ]
-    },
-    {
-      "login": "leonhfr",
-      "name": "léon h",
-      "avatar_url": "https://avatars.githubusercontent.com/u/19996318?v=4",
-      "profile": "http://leonh.fr/",
-      "contributions": [
-        "code"
-      ]
-    },
-    {
-      "login": "njnygaard",
-      "name": "Nikhil Nygaard",
-      "avatar_url": "https://avatars.githubusercontent.com/u/4606342?v=4",
-      "profile": "https://nygaard.site",
-      "contributions": [
-        "doc"
-      ]
-    },
-    {
-      "login": "nitwit-se",
-      "name": "Mark Dixon",
-      "avatar_url": "https://avatars.githubusercontent.com/u/1382124?v=4",
-      "profile": "http://www.nitwit.se",
-      "contributions": [
-        "code"
-      ]
-    },
-    {
-      "login": "joeltjames",
-      "name": "Joel James",
-      "avatar_url": "https://avatars.githubusercontent.com/u/3732400?v=4",
-      "profile": "https://github.com/joeltjames",
-      "contributions": [
-        "code"
-      ]
-    },
-    {
-      "login": "ryo33",
-      "name": "Hashiguchi Ryo",
-      "avatar_url": "https://avatars.githubusercontent.com/u/8780513?v=4",
-      "profile": "https://www.ryo33.com",
-      "contributions": [
-        "doc"
-      ]
-    },
-    {
-      "login": "movermeyer",
-      "name": "Michael Overmeyer",
-      "avatar_url": "https://avatars.githubusercontent.com/u/1459385?v=4",
-      "profile": "https://movermeyer.com",
-      "contributions": [
-        "code"
-      ]
-    },
-    {
-      "login": "derrickqin",
-      "name": "Derrick Qin",
-      "avatar_url": "https://avatars.githubusercontent.com/u/3038111?v=4",
-      "profile": "https://github.com/derrickqin",
-      "contributions": [
-        "doc"
-      ]
-    },
-    {
-      "login": "zomars",
-      "name": "Omar López",
-      "avatar_url": "https://avatars.githubusercontent.com/u/3504472?v=4",
-      "profile": "https://www.linkedin.com/in/zomars/",
-      "contributions": [
-        "doc"
-      ]
-    },
-    {
-      "login": "RobinKing",
-      "name": "Robin King",
-      "avatar_url": "https://avatars.githubusercontent.com/u/1583193?v=4",
-      "profile": "http://robincn.com",
-      "contributions": [
-        "code"
-      ]
-    },
-    {
-      "login": "dheepakg",
-      "name": "Dheepak ",
-      "avatar_url": "https://avatars.githubusercontent.com/u/4730170?v=4",
-      "profile": "http://twitter.com/deegovee",
-      "contributions": [
-        "doc"
-      ]
-    },
-    {
-      "login": "daniel-vera-g",
-      "name": "Daniel VG",
-      "avatar_url": "https://avatars.githubusercontent.com/u/28257108?v=4",
-      "profile": "https://github.com/daniel-vera-g",
-      "contributions": [
-        "doc"
-      ]
-    },
-    {
-      "login": "Barabazs",
-      "name": "Barabas",
-      "avatar_url": "https://avatars.githubusercontent.com/u/31799121?v=4",
-      "profile": "https://github.com/Barabazs",
-      "contributions": [
-        "code"
-      ]
-    },
-    {
-      "login": "EngincanV",
-      "name": "Engincan VESKE",
-      "avatar_url": "https://avatars.githubusercontent.com/u/43685404?v=4",
-      "profile": "http://enginveske@gmail.com",
-      "contributions": [
-        "doc"
-      ]
-    },
-    {
-      "login": "pderaaij",
-      "name": "Paul de Raaij",
-      "avatar_url": "https://avatars.githubusercontent.com/u/495374?v=4",
-      "profile": "http://www.paulderaaij.nl",
-      "contributions": [
-        "code"
-      ]
-    },
-    {
-      "login": "bronson",
-      "name": "Scott Bronson",
-      "avatar_url": "https://avatars.githubusercontent.com/u/1776?v=4",
-      "profile": "https://github.com/bronson",
-      "contributions": [
-        "doc"
-      ]
-    },
-    {
-      "login": "rafo",
-      "name": "Rafael Riedel",
-      "avatar_url": "https://avatars.githubusercontent.com/u/41793?v=4",
-      "profile": "http://rafaelriedel.de",
-      "contributions": [
-        "doc"
-      ]
     }
   ],
   "contributorsPerLine": 7,

.github/CONTRIBUTING.md

@@ -0,0 +1,14 @@
+# 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!

.github/ISSUE_TEMPLATE/bug.md

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

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +0,0 @@
-blank_issues_enabled: true
-contact_links:
-  - name: Question
-    url: https://foambubble.github.io/join-discord/g
-    about: Please ask and answer questions here.

.github/ISSUE_TEMPLATE/feature.md

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

.github/workflows/ci.yml

@@ -1,66 +0,0 @@
-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: Restore Dependencies and VS Code test instance
-        uses: actions/cache@v2
-        with:
-          path: |
-            node_modules
-            */*/node_modules
-            packages/foam-vscode/.vscode-test
-          key: ${{ runner.os }}-${{ hashFiles('**/yarn.lock') }}-${{ hashFiles('packages/foam-vscode/src/test/run-tests.ts') }}
-      - 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, windows-2019]
-    runs-on: ${{ matrix.os }}
-    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name != 'foambubble/foam'
-    env:
-      OS: ${{ matrix.os }}
-    steps:
-      - uses: actions/checkout@v1
-      - name: Setup Node
-        uses: actions/setup-node@v1
-        with:
-          node-version: '12'
-      - name: Restore Dependencies and VS Code test instance
-        uses: actions/cache@v2
-        with:
-          path: |
-            node_modules
-            */*/node_modules
-            packages/foam-vscode/.vscode-test
-          key: ${{ runner.os }}-${{ hashFiles('**/yarn.lock') }}-${{ hashFiles('packages/foam-vscode/src/test/run-tests.ts') }}
-      - name: Install Dependencies
-        run: yarn
-      - name: Build Packages
-        run: yarn build
-      - name: Run Tests
-        uses: GabrielBB/xvfb-action@v1.0
-        with:
-          run: yarn test

.github/workflows/foam-cli.yml

@@ -0,0 +1,25 @@
+name: Test foam-cli
+
+on:
+  pull_request:
+    paths:
+      - 'packages/foam-cli/**'
+  push:
+    paths:
+      - 'packages/foam-cli/**'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+      - uses: actions/setup-node@v1
+
+      - name: Install dependencies
+        run: yarn
+
+      # - name: Lint foam-lint
+      #   run: yarn workspace foam-cli lint
+
+      - name: Test foam-cli
+        run: yarn workspace foam-cli test

.github/workflows/foam-core.yml

@@ -0,0 +1,25 @@
+name: Test foam-core
+
+on:
+  pull_request:
+    paths:
+      - 'packages/foam-core/**'
+  push:
+    paths:
+      - 'packages/foam-core/**'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+      - uses: actions/setup-node@v1
+
+      - name: Install dependencies
+        run: yarn
+
+      - name: Lint foam-core
+        run: yarn workspace foam-core lint
+
+      - name: Test foam-core
+        run: yarn workspace foam-core test

.github/workflows/foam-vscode.yml

@@ -0,0 +1,29 @@
+name: Test foam-vscode
+
+on:
+  pull_request:
+    paths:
+      - 'packages/foam-vscode/**'
+  push:
+    paths:
+      - 'packages/foam-vscode/**'
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+      - uses: actions/setup-node@v1
+
+      - name: Install dependencies
+        run: yarn
+
+      - name: Lint foam-vscode
+        run: yarn workspace foam-vscode lint
+      - name: Test foam-vscode
+        run: yarn workspace foam-vscode test
+      # - name: Publish foam-vscode
+      #   if: github.ref == 'refs/heads/master'
+      #   run: yarn workspace foam-vscode publish-extension
+      #   with:
+      #     vsce_token: ${{ secrets.VSCE_TOKEN }}

.gitignore

@@ -4,8 +4,4 @@ node_modules
 *.tsbuildinfo
 *.vsix
 *.log
-out
 dist
-docs/_site
-docs/.sass-cache
-docs/.jekyll-metadata

.vscode/launch.json

@@ -4,21 +4,12 @@
 // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
 {
 	"version": "0.2.0",
-  "inputs": [
-    {
-      "id": "packageName",
-      "type": "pickString",
-      "description": "Select the package in which this test is located",
-      "options": ["foam-core", "foam-vscode"],
-      "default": "foam-core"
-    }
-  ],
 	"configurations": [
 		{
 			"type": "node",
 			"name": "vscode-jest-tests",
 			"request": "launch",
-			"runtimeArgs": ["workspace", "${input:packageName}", "run", "test"], // ${yarnWorkspaceName} is what we're missing
+			"runtimeArgs": ["workspace", "foam-core", "run", "test"], // ${yarnWorkspaceName} is what we're missing
 			"args": [
 					"--runInBand"
 			],
@@ -80,6 +71,25 @@
 			"cwd": "${workspaceFolder}/packages/foam-core",
 			"internalConsoleOptions": "openOnSessionStart",
 			"preLaunchTask": "${defaultBuildTask}"
+		},
+		{
+			"name": "Debug Language Server",
+			"type": "node",
+			"request": "attach",
+			"port": 6009,
+			// large timeout to account for typescript watch startup time
+			"timeout": 30000,
+			"restart": true,
+			"trace": true,
+			"localRoot": "${workspaceFolder}/packages/foam-language-server/src/",
+			"remoteRoot": "${workspaceFolder}/packages/foam-language-server/dist/",
+			"outFiles": ["${workspaceFolder}/packages/foam-language-server/dist/**/*.js"]
+		},
+	],
+	"compounds": [
+		{
+			"name": "Run Extension & Debug LSP",
+			"configurations": ["Run VSCode Extension", "Debug Language Server"]
 		}
 	]
 }

.vscode/settings.json

@@ -1,31 +1,15 @@
 // Place your settings in this file to overwrite default and user settings.
 {
-  "files.exclude": {
-    // set these to true to hide folders with the compiled JS files,
-    "packages/**/out": false,
-    "packages/**/dist": false
-  },
-  "search.exclude": {
-    // set this to false to include compiled JS folders in search results
-    "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",
-  "foam.files.ignore": [
-    "**/.vscode/**/*",
-    "**/_layouts/**/*",
-    "**/_site/**/*",
-    "**/node_modules/**/*",
-    "packages/**/*"
-  ],
-  "editor.defaultFormatter": "esbenp.prettier-vscode",
-  "prettier.requireConfig": true,
-  "editor.formatOnSave": true,
-  "editor.tabSize": 2,
-  "jest.debugCodeLens.showWhenTestStateIn": ["fail", "unknown", "pass"],
-  "gitdoc.enabled": false,
-  "jest.autoEnable": false,
-  "jest.runAllTestsFirst": false,
-  "search.mode": "reuseEditor"
-}
+    "files.exclude": {
+        // set these to true to hide folders with the compiled JS files,
+        "packages/**/out": false,
+        "packages/**/dist": false
+    },
+    "search.exclude": {
+        // set this to false to include compiled JS folders in search results
+        "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"
+}

LICENSE

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

docs/.vscode/settings.json

@@ -4,7 +4,7 @@
   "editor.wrappingIndent": "indent",
   "editor.overviewRulerBorder": false,
   "editor.lineHeight": 24,
-  "foam.edit.linkReferenceDefinitions": "withExtensions",
+  "workbench.colorTheme": "Gray Matter Light",
   "vscodeMarkdownNotes.noteCompletionConvention": "noExtension",
   "[markdown]": {
     "editor.quickSuggestions": {
@@ -15,15 +15,5 @@
   },
   "cSpell.language": "en-GB",
   "git.enableSmartCommit": true,
-  "git.postCommitCommand": "sync",
-  "spellright.language": [
-    "en"
-  ],
-  "spellright.documentTypes": [
-    "markdown",
-    "plaintext"
-  ],
-  "files.exclude": {
-    "_site/**": true
-  }
+  "git.postCommitCommand": "sync"
 }

docs/.vscode/spellright.dict

@@ -1 +0,0 @@
-Backlinking

docs/404.md

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

docs/Gemfile

@@ -1,37 +0,0 @@
-source "https://rubygems.org"
-
-# Hello! This is where you manage which Jekyll version is used to run.
-# When you want to use a different version, change it below, save the
-# file and run `bundle install`. Run Jekyll with `bundle exec`, like so:
-#
-#     bundle exec jekyll serve
-#
-# This will help ensure the proper Jekyll version is running.
-# Happy Jekylling!
-# gem "jekyll", "~> 3.9.0"
-
-# This is the default theme for new Jekyll sites. You may change this to anything you like.
-gem "minima", "~> 2.0"
-
-# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
-# uncomment the line below. To upgrade, run `bundle update github-pages`.
-gem "github-pages", "~> 209", group: :jekyll_plugins
-
-# If you have any plugins, put them here!
-group :jekyll_plugins do
-  gem "jekyll-feed", "~> 0.6"
-end
-
-# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
-# and associated library.
-install_if -> { RUBY_PLATFORM =~ %r!mingw|mswin|java! } do
-  gem "tzinfo", "~> 1.2"
-  gem "tzinfo-data"
-end
-
-# Performance-booster for watching directories on Windows
-gem "wdm", "~> 0.1.0", :install_if => Gem.win_platform?
-
-# kramdown v2 ships without the gfm parser by default. If you're using
-# kramdown v1, comment out this line.
-gem "kramdown-parser-gfm"

docs/Gemfile.lock

@@ -1,272 +0,0 @@
-GEM
-  remote: https://rubygems.org/
-  specs:
-    activesupport (6.0.3.4)
-      concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (>= 0.7, < 2)
-      minitest (~> 5.1)
-      tzinfo (~> 1.1)
-      zeitwerk (~> 2.2, >= 2.2.2)
-    addressable (2.7.0)
-      public_suffix (>= 2.0.2, < 5.0)
-    coffee-script (2.4.1)
-      coffee-script-source
-      execjs
-    coffee-script-source (1.11.1)
-    colorator (1.1.0)
-    commonmarker (0.17.13)
-      ruby-enum (~> 0.5)
-    concurrent-ruby (1.1.7)
-    dnsruby (1.61.5)
-      simpleidn (~> 0.1)
-    em-websocket (0.5.2)
-      eventmachine (>= 0.12.9)
-      http_parser.rb (~> 0.6.0)
-    ethon (0.12.0)
-      ffi (>= 1.3.0)
-    eventmachine (1.2.7)
-    execjs (2.7.0)
-    faraday (1.1.0)
-      multipart-post (>= 1.2, < 3)
-      ruby2_keywords
-    ffi (1.13.1)
-    forwardable-extended (2.6.0)
-    gemoji (3.0.1)
-    github-pages (209)
-      github-pages-health-check (= 1.16.1)
-      jekyll (= 3.9.0)
-      jekyll-avatar (= 0.7.0)
-      jekyll-coffeescript (= 1.1.1)
-      jekyll-commonmark-ghpages (= 0.1.6)
-      jekyll-default-layout (= 0.1.4)
-      jekyll-feed (= 0.15.1)
-      jekyll-gist (= 1.5.0)
-      jekyll-github-metadata (= 2.13.0)
-      jekyll-mentions (= 1.6.0)
-      jekyll-optional-front-matter (= 0.3.2)
-      jekyll-paginate (= 1.1.0)
-      jekyll-readme-index (= 0.3.0)
-      jekyll-redirect-from (= 0.16.0)
-      jekyll-relative-links (= 0.6.1)
-      jekyll-remote-theme (= 0.4.2)
-      jekyll-sass-converter (= 1.5.2)
-      jekyll-seo-tag (= 2.6.1)
-      jekyll-sitemap (= 1.4.0)
-      jekyll-swiss (= 1.0.0)
-      jekyll-theme-architect (= 0.1.1)
-      jekyll-theme-cayman (= 0.1.1)
-      jekyll-theme-dinky (= 0.1.1)
-      jekyll-theme-hacker (= 0.1.2)
-      jekyll-theme-leap-day (= 0.1.1)
-      jekyll-theme-merlot (= 0.1.1)
-      jekyll-theme-midnight (= 0.1.1)
-      jekyll-theme-minimal (= 0.1.1)
-      jekyll-theme-modernist (= 0.1.1)
-      jekyll-theme-primer (= 0.5.4)
-      jekyll-theme-slate (= 0.1.1)
-      jekyll-theme-tactile (= 0.1.1)
-      jekyll-theme-time-machine (= 0.1.1)
-      jekyll-titles-from-headings (= 0.5.3)
-      jemoji (= 0.12.0)
-      kramdown (= 2.3.0)
-      kramdown-parser-gfm (= 1.1.0)
-      liquid (= 4.0.3)
-      mercenary (~> 0.3)
-      minima (= 2.5.1)
-      nokogiri (>= 1.10.4, < 2.0)
-      rouge (= 3.23.0)
-      terminal-table (~> 1.4)
-    github-pages-health-check (1.16.1)
-      addressable (~> 2.3)
-      dnsruby (~> 1.60)
-      octokit (~> 4.0)
-      public_suffix (~> 3.0)
-      typhoeus (~> 1.3)
-    html-pipeline (2.14.0)
-      activesupport (>= 2)
-      nokogiri (>= 1.4)
-    http_parser.rb (0.6.0)
-    i18n (0.9.5)
-      concurrent-ruby (~> 1.0)
-    jekyll (3.9.0)
-      addressable (~> 2.4)
-      colorator (~> 1.0)
-      em-websocket (~> 0.5)
-      i18n (~> 0.7)
-      jekyll-sass-converter (~> 1.0)
-      jekyll-watch (~> 2.0)
-      kramdown (>= 1.17, < 3)
-      liquid (~> 4.0)
-      mercenary (~> 0.3.3)
-      pathutil (~> 0.9)
-      rouge (>= 1.7, < 4)
-      safe_yaml (~> 1.0)
-    jekyll-avatar (0.7.0)
-      jekyll (>= 3.0, < 5.0)
-    jekyll-coffeescript (1.1.1)
-      coffee-script (~> 2.2)
-      coffee-script-source (~> 1.11.1)
-    jekyll-commonmark (1.3.1)
-      commonmarker (~> 0.14)
-      jekyll (>= 3.7, < 5.0)
-    jekyll-commonmark-ghpages (0.1.6)
-      commonmarker (~> 0.17.6)
-      jekyll-commonmark (~> 1.2)
-      rouge (>= 2.0, < 4.0)
-    jekyll-default-layout (0.1.4)
-      jekyll (~> 3.0)
-    jekyll-feed (0.15.1)
-      jekyll (>= 3.7, < 5.0)
-    jekyll-gist (1.5.0)
-      octokit (~> 4.2)
-    jekyll-github-metadata (2.13.0)
-      jekyll (>= 3.4, < 5.0)
-      octokit (~> 4.0, != 4.4.0)
-    jekyll-mentions (1.6.0)
-      html-pipeline (~> 2.3)
-      jekyll (>= 3.7, < 5.0)
-    jekyll-optional-front-matter (0.3.2)
-      jekyll (>= 3.0, < 5.0)
-    jekyll-paginate (1.1.0)
-    jekyll-readme-index (0.3.0)
-      jekyll (>= 3.0, < 5.0)
-    jekyll-redirect-from (0.16.0)
-      jekyll (>= 3.3, < 5.0)
-    jekyll-relative-links (0.6.1)
-      jekyll (>= 3.3, < 5.0)
-    jekyll-remote-theme (0.4.2)
-      addressable (~> 2.0)
-      jekyll (>= 3.5, < 5.0)
-      jekyll-sass-converter (>= 1.0, <= 3.0.0, != 2.0.0)
-      rubyzip (>= 1.3.0, < 3.0)
-    jekyll-sass-converter (1.5.2)
-      sass (~> 3.4)
-    jekyll-seo-tag (2.6.1)
-      jekyll (>= 3.3, < 5.0)
-    jekyll-sitemap (1.4.0)
-      jekyll (>= 3.7, < 5.0)
-    jekyll-swiss (1.0.0)
-    jekyll-theme-architect (0.1.1)
-      jekyll (~> 3.5)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-cayman (0.1.1)
-      jekyll (~> 3.5)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-dinky (0.1.1)
-      jekyll (~> 3.5)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-hacker (0.1.2)
-      jekyll (> 3.5, < 5.0)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-leap-day (0.1.1)
-      jekyll (~> 3.5)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-merlot (0.1.1)
-      jekyll (~> 3.5)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-midnight (0.1.1)
-      jekyll (~> 3.5)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-minimal (0.1.1)
-      jekyll (~> 3.5)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-modernist (0.1.1)
-      jekyll (~> 3.5)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-primer (0.5.4)
-      jekyll (> 3.5, < 5.0)
-      jekyll-github-metadata (~> 2.9)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-slate (0.1.1)
-      jekyll (~> 3.5)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-tactile (0.1.1)
-      jekyll (~> 3.5)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-theme-time-machine (0.1.1)
-      jekyll (~> 3.5)
-      jekyll-seo-tag (~> 2.0)
-    jekyll-titles-from-headings (0.5.3)
-      jekyll (>= 3.3, < 5.0)
-    jekyll-watch (2.2.1)
-      listen (~> 3.0)
-    jemoji (0.12.0)
-      gemoji (~> 3.0)
-      html-pipeline (~> 2.2)
-      jekyll (>= 3.0, < 5.0)
-    kramdown (2.3.0)
-      rexml
-    kramdown-parser-gfm (1.1.0)
-      kramdown (~> 2.0)
-    liquid (4.0.3)
-    listen (3.3.3)
-      rb-fsevent (~> 0.10, >= 0.10.3)
-      rb-inotify (~> 0.9, >= 0.9.10)
-    mercenary (0.3.6)
-    mini_portile2 (2.5.1)
-    minima (2.5.1)
-      jekyll (>= 3.5, < 5.0)
-      jekyll-feed (~> 0.9)
-      jekyll-seo-tag (~> 2.1)
-    minitest (5.14.2)
-    multipart-post (2.1.1)
-    nokogiri (1.11.5)
-      mini_portile2 (~> 2.5.0)
-      racc (~> 1.4)
-    octokit (4.19.0)
-      faraday (>= 0.9)
-      sawyer (~> 0.8.0, >= 0.5.3)
-    pathutil (0.16.2)
-      forwardable-extended (~> 2.6)
-    public_suffix (3.1.1)
-    racc (1.5.2)
-    rb-fsevent (0.10.4)
-    rb-inotify (0.10.1)
-      ffi (~> 1.0)
-    rexml (3.2.5)
-    rouge (3.23.0)
-    ruby-enum (0.8.0)
-      i18n
-    ruby2_keywords (0.0.2)
-    rubyzip (2.3.0)
-    safe_yaml (1.0.5)
-    sass (3.7.4)
-      sass-listen (~> 4.0.0)
-    sass-listen (4.0.0)
-      rb-fsevent (~> 0.9, >= 0.9.4)
-      rb-inotify (~> 0.9, >= 0.9.7)
-    sawyer (0.8.2)
-      addressable (>= 2.3.5)
-      faraday (> 0.8, < 2.0)
-    simpleidn (0.1.1)
-      unf (~> 0.1.4)
-    terminal-table (1.8.0)
-      unicode-display_width (~> 1.1, >= 1.1.1)
-    thread_safe (0.3.6)
-    typhoeus (1.4.0)
-      ethon (>= 0.9.0)
-    tzinfo (1.2.8)
-      thread_safe (~> 0.1)
-    tzinfo-data (1.2020.4)
-      tzinfo (>= 1.0.0)
-    unf (0.1.4)
-      unf_ext
-    unf_ext (0.0.7.7)
-    unicode-display_width (1.7.0)
-    wdm (0.1.1)
-    zeitwerk (2.4.2)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  github-pages (~> 209)
-  jekyll-feed (~> 0.6)
-  kramdown-parser-gfm
-  minima (~> 2.0)
-  tzinfo (~> 1.2)
-  tzinfo-data
-  wdm (~> 0.1.0)
-
-BUNDLED WITH
-   2.1.2

docs/LICENSE.txt

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

docs/automatic-git-syncing.md

@@ -0,0 +1,11 @@
+# Automatic Git Syncing (stub)
+
+**[[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"

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

@@ -1,16 +1,16 @@
 # Automatically Expand URLs to Well-Titled Links
 
-With this #recipe you can convert a link to a fully-formed Markdown link, using the page's title as a display name. Useful for citations and creating link collections.
+Convert a link to a fully-formed Markdown link, using the page's title as a display name. Useful for citations and creating link collections.
 
 ## Required Extensions
 
-- [Markdown Link Expander](https://marketplace.visualstudio.com/items?itemName=skn0tt.markdown-link-expander) (not included in template)
+ - [Markdown Link Expander](https://marketplace.visualstudio.com/items?itemName=skn0tt.markdown-link-expander) (not included in template)
 
 Markdown Link Expander will scrape your URL's `<title>` tag to create a nice Markdown-style link.
 
 ## Instructions
 
-![Demo](../assets/images/prettify-links-demo.gif)
+![Demo](./assets/images/prettify-links-demo.gif)
 
 1. Highlight desired URL
 2. `Cmd` + `Shift` + `P`
@@ -22,3 +22,4 @@ Tip: If you paste a lot of links, give the action a custom [key binding](https:/
 ## Feedback and issues
 
 Have an idea for the extension? [Feel free to share! 🎉](https://github.com/Skn0tt/markdown-link-expander/issues)
+

docs/azure-devops-wiki.md

@@ -1,4 +1,4 @@
-# Publish to Azure DevOps Wiki
+# Azure DevOps Wiki
 
 Publish your Foam workspace as an Azure DevOps wiki.
 
@@ -8,45 +8,43 @@ The following recipe is written with the assumption that you already have an [Az
 
 ## Setup a Foam workspace
 
-1. Generate a Foam workspace using the [foam-template project](https://github.com/foambubble/foam-template).
+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.
+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)
+![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.
+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
@@ -60,7 +58,6 @@ While you are pushing changes to GitHub, you won't see the wiki updated if you d
   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).
+  
+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,8 +8,8 @@ When using [[wiki-links]], you can find all notes that link to a specific note i
 - Finding backlinks in published Foam workspaces via [[materialized-backlinks]] is on the [[roadmap]] but not yet implemented.
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[wiki-links]: ../wiki-links.md "Wiki Links"
-[make-backlinks-more-prominent]: ../recipes/make-backlinks-more-prominent.md "Make Backlinks More Prominent"
-[materialized-backlinks]: ../dev/materialized-backlinks.md "Materialized Backlinks (stub)"
-[roadmap]: ../dev/roadmap.md "Roadmap"
+[wiki-links]: wiki-links "Wiki Links"
+[make-backlinks-more-prominent]: make-backlinks-more-prominent "Make Backlinks More Prominent"
+[materialized-backlinks]: materialized-backlinks "Materialized Backlinks (stub)"
+[roadmap]: roadmap "Roadmap"
 [//end]: # "Autogenerated link references"

docs/big-vision.md

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

docs/block-references.md

@@ -0,0 +1,10 @@
+# Block References (stub)
+
+**[[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"

docs/blog.md

@@ -0,0 +1,7 @@
+# Foam Blog
+
+- [[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"
+[//end]: # "Autogenerated link references"

docs/blog/2020-07-11-three-weeks-in.md

@@ -0,0 +1,3 @@
+# Three Weeks In
+
+Todo

docs/build-vs-assemble.md

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

docs/capture-notes-with-drafts-pro.md

@@ -1,13 +1,15 @@
 # Capture Notes With Drafts Pro
 
-With this #recipe you can create notes on your iOS device, which will automatically be imported into Foam.
-
 ## 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)
@@ -68,7 +70,7 @@ const base = 'https://api.github.com';
 
 
 const posttime = new Date();
-const title = draft.title;
+const title = draft.title;  
 const txt = draft.processTemplate("[[line|3..]]");
 const mergedTags = [...draft.tags, ...requiredTags];
 const slugbase = title.toLowerCase().replace(/\s/g, "-");

docs/cli.md

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

docs/code-of-conduct.md

@@ -61,7 +61,7 @@ representative at an online or offline event.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported to the community leaders responsible for enforcement at `riki.code+foam@gmail.com`.
+reported to the community leaders responsible for enforcement at `jani.evakallio+foam@gmail.com`.
 
 All complaints will be reviewed and investigated promptly and fairly.
 
@@ -118,7 +118,7 @@ the community.
 
 This Code of Conduct is adapted from the [Contributor Covenant][homepage],
 version 2.0, available at
-<https://www.contributor-covenant.org/version/2/0/code_of_conduct.html>.
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
 
 Community Impact Guidelines were inspired by [Mozilla's code of conduct
 enforcement ladder](https://github.com/mozilla/diversity).
@@ -126,5 +126,7 @@ enforcement ladder](https://github.com/mozilla/diversity).
 [homepage]: https://www.contributor-covenant.org
 
 For answers to common questions about this code of conduct, see the FAQ at
-<https://www.contributor-covenant.org/faq>. Translations are available at
-<https://www.contributor-covenant.org/translations>.
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.
+
+

docs/contributing.md

@@ -0,0 +1,7 @@
+# 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,31 +1,25 @@
----
-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
+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:
 
-Before you start contributing we recommend that you read the following links:
+- 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 with our [[code-of-conduct]].
+- Feel free to open [GitHub issues](https://github.com/foambubble/foam/issues) to give me feedback and ideas for new features.
+- Foam code and documentation live in the monorepo at [foambubble/foam](https://github.com/foambubble/foam/)
+  - [/docs](https://github.com/foambubble/foam/docs): documentation and [[recipes]]
+  - [/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.
 
-- [[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!
+## Contributing to the VS Code Extension
 
-## Diving In
-
-We understand that diving in an unfamiliar codebase may seem scary,
-to make it easier for new contributors we provide some resources:
-
-- [[architecture]] - This document describes the architecture of Foam and how the repository is structured.
-
-You can also see [existing issues](https://github.com/foambubble/foam/issues) and help out!
-Finally, the easiest way to help, is to use it and provide feedback by [submitting issues](https://github.com/foambubble/foam/issues/new/choose) or participating in the [Foam Community Discord](https://foambubble.github.io/join-discord/g)!
-
-## Contributing
-
-If you're interested in contributing, this short guide will help you get things set up locally.
+If you're interested in contributing to the VS Code extension (aka `foam-vscode`), this guide will help you get things set up locally.
 
 1. Clone the repo locally:
 
@@ -35,41 +29,25 @@ If you're interested in contributing, this short guide will help you get things
 
    `yarn install`
 
-3. This project uses [Yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/). `foam-vscode` relies on `foam-core`. This means we need to compile it before we do any extension development. From the root, run the command:
+3. 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 build`
+   `yarn workspace foam-core build`
 
-You should now be ready to start working!
+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!
 
-### Testing
+For more resources related to the VS Code Extension, check out the links below:
 
-Code needs to come with tests.
-We use the following convention in Foam:
-
-- *.test.ts are unit tests
-- *.spec.ts are integration tests
-
-Also, note that tests in `foam-core` live in the `test` directory.
-Tests in `foam-vscode` live alongside the code in `src`.
-
-### The VS Code Extension
-
-This guide assumes you read the previous instructions and you're set up to work on Foam.
-
-1. Now we'll use the launch configuration defined at [`.vscode/launch.json`](https://github.com/foambubble/foam/blob/master/.vscode/launch.json) to start a new extension host of VS Code. Open the "Run and Debug" Activity (the icon with the bug on the far left) and select "Run VSCode Extension" in the pop-up menu. Now hit F5 or click the green arrow "play" button to fire up a new copy of VS Code with your extension installed.
-
-2. In the new extension host of VS Code that launched, open a Foam workspace (e.g. your personal one, or a test-specific one created from [foam-template](https://github.com/foambubble/foam-template)). This is strictly not necessary, but the extension won't auto-run unless it's in a workspace with a `.vscode/foam.json` file.
-
-3. Test a command to make sure it's working as expected. Open the Command Palette (Ctrl/Cmd + Shift + P) and select "Foam: Update Markdown Reference List". If you see no errors, it's good to go!
-
----
-
-Feel free to modify and submit a PR if this guide is out-of-date or contains errors!
-
----
+- [[tutorial-adding-a-new-command-to-the-vs-code-extension]]
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[principles]: principles.md "Principles"
-[code-of-conduct]: code-of-conduct.md "Code of Conduct"
-[architecture]: dev/architecture.md "Architecture"
+[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"
 [//end]: # "Autogenerated link references"

docs/creating-a-new-language.md

@@ -0,0 +1,13 @@
+# 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
+
+- Based on markdown
+- Could leverage mdx?
+- Shortcuts, like links between pages
+- Downside: Not markdown compatible, not so good for other tools
+  - Could it be a markdown superset?
+  - Or a language that transpiles to markdown and back, so it can be edited in "Foam" format and committed in MD so it's viewable on GH as markdown
+    - How imporant is it that links are navigable on GH? I guess it is

docs/creating-new-notes.md

@@ -2,13 +2,11 @@
 
 - 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 `Foam: Create New Note` and enter a **Title Case Name** to create `Title Case Name.md`
+- `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.
-  - The [[note-templates]] used by this command can be customized.
-- You shouldn't worry too much about categorizing your notes. You can always [[search-for-notes]], and explore them using the [[graph-visualisation]].
+- You shouldn't worry too much about categorising your notes. You can always [[search-for-notes]], and explore them using the [[graph-visualisation]].
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[note-templates]: note-templates "Note Templates"
-[search-for-notes]: ../recipes/search-for-notes "Search for Notes"
-[graph-visualisation]: graph-visualisation "Graph Visualisation"
+[search-for-notes]: search-for-notes "Search for Notes"
+[graph-visualisation]: graph-visualisation "Graph visualisation"
 [//end]: # "Autogenerated link references"

docs/custom-snippets.md

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

docs/customising-styles.md

@@ -0,0 +1,10 @@
+# Customising Styles
+
+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"
+[//end]: # "Autogenerated link references"

docs/daily-notes.md

@@ -2,7 +2,7 @@
 
 Automatically create a Daily Note by executing the "Foam: Open Daily Note" command. If a Daily Note for today's date already exists, the command opens the existing note.
 
-![Daily note feature in action](../assets/images/daily-note.gif)
+![Daily note feature in action](assets/images/daily-note.gif)
 
 ## Keyboard shortcut
 
@@ -14,8 +14,8 @@ By default, Daily Notes will be created in a file called `yyyy-mm-dd.md` in the
 
 These settings can be overridden in your workspace or global `.vscode/settings.json` file, using the [**dateformat** date masking syntax](https://github.com/felixge/node-dateformat#mask-options):
 
-```jsonc
-  "foam.openDailyNote.directory": "journal", // a relative directory path will get appended to the workspace root. An absolute directory path will be used unmodified.
+```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",
@@ -25,25 +25,30 @@ The above configuration would create a file `journal/note-2020-07-25.mdx`, with
 
 ## Daily Note Templates
 
-Daily notes can also make use of [templates](note-templates.md), by defining a special `.foam/templates/daily-note.md` template.
+In the future, Foam may provide a functionality for specifying a template for new Daily Notes and other types of documents.
 
-See [Note Templates](note-templates.md) for details of the features available in templates.
+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
 
-Foam provides an option for automatically opening your Daily Note when you open your Foam workspace. You can enable it by specifying the following configuration in your `.vscode/settings.json`:
+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
-{
-  // ...Other configurations
-  "foam.openDailyNote.onStartup": true
-}
+  "auto-run-command.rules": [
+    {
+      "condition": "hasFile: .vscode/foam.json",
+      "command": "foam-vscode.open-daily-note",
+      "message": "Have a nice day!"
+    }
+  ],
 ```
 
 ## Extend Functionality (Weekly, Monthly, Quarterly Notes)
 
 Please see [[note-macros]]
 
-[//begin]: # 'Autogenerated link references for markdown compatibility'
-[note-macros]: ../recipes/note-macros.md 'Custom Note Macros'
-[//end]: # 'Autogenerated link references'
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[note-macros]: note-macros "Custom Note Macros"
+[//end]: # "Autogenerated link references"

docs/decision-needed.md

@@ -0,0 +1,3 @@
+# Decision Needed
+
+Check backlinks

docs/decision.md

@@ -0,0 +1,2 @@
+# Decision
+

docs/dev/architecture.md

@@ -1,23 +0,0 @@
----
-tags: architecture
----
-# Architecture
-
-This document aims to provide a quick overview of the Foam architecture!
-
-Foam code and documentation live in the monorepo at [foambubble/foam](https://github.com/foambubble/foam/).
-
-- [/docs](https://github.com/foambubble/foam/tree/master/docs): documentation and [[recipes]].
-- [/packages/foam-core](https://github.com/foambubble/foam/tree/master/packages/foam-core) - Powers the core functionality in Foam across all platforms.
-- [/packages/foam-vscode](https://github.com/foambubble/foam/tree/master/packages/foam-vscode) - The core VSCode plugin.
-
-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.
-- [foam-cli](https://github.com/foambubble/foam-cli) - The Foam CLI tool.
-
-[//begin]: # "Autogenerated link references for markdown compatibility"
-[recipes]: ../recipes/recipes.md "Recipes"
-[recommended-extensions]: ../recommended-extensions.md "Recommended Extensions"
-[//end]: # "Autogenerated link references"

docs/diagrams-in-markdown.md

@@ -1,23 +1,22 @@
 # Diagrams in Markdown
 
-We have two alternative #recipe for displaying diagrams in markdown:
+We have two alternative recipes for displaying diagrams in markdown:
+
+- [Mermaid](#mermaid)
+- [Draw.io](#drawio)
 
-- [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 [[publish-to-github-pages]], and would require you to eject to another static site generation approach that supports Mermaid plugins.
+⚠️ 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
 
-[Draw.io](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio) extension allows you to create, edit, and display your diagrams without leaving Visual Studio Code. The `.drawio.svg` or `.drawio.png` files can be automatically embedded and displayed in published Foams, no export needed. FYI, the diagram below was made using Draw.io! You can check the diagram [here](../assets/images/diagram-drawio-demo.drawio.svg).
+[Draw.io](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio) extension allows you to create, edit, and display your diagrams without leaving Visual Studio Code. The `.drawio.svg` or `.drawio.png` files can be automatically embedded and displayed in published Foams, no export needed. FYI, the diagram below was made using Draw.io! You can check the diagram [here](./assets/images/diagram-drawio-demo.drawio.svg).
 
-![diagram-drawio-demo](../assets/images/diagram-drawio-demo.drawio.svg)
+![diagram-drawio-demo](./assets/images/diagram-drawio-demo.drawio.svg)
 
 ### Using Draw.io
 
@@ -26,6 +25,7 @@ You can use [Mermaid](https://marketplace.visualstudio.com/items?itemName=bierne
 3. Start drawing your diagram. Once you done, save it.
 4. Embed the diagram file as you embedding the image file, for example: `![My Diagram](my-diagram.drawio.svg)`
 
+
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[publish-to-github-pages]: ../publishing/publish-to-github-pages.md "Github Pages"
+[github-pages]: github-pages "Github Pages"
 [//end]: # "Autogenerated link references"

docs/eleventy-and-netlify.md

@@ -1,10 +1,9 @@
-# Publish to Netlify with Eleventy
+# 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
@@ -13,6 +12,8 @@ When you're ready to publish, import the GitHub repository you created with **fo
 
 Once that's done, all you have to do is make changes to your workspace in VS Code and push them to the main branch on GitHub. Netlify will recognize the changes, deploy them automatically and give you a link where your Foam is published.
 
+
 That's it!
 
 You can now see it online and use that link to share it with your friends, so that they can see it too.
+

docs/feature-comparison.md

@@ -0,0 +1,3 @@
+# Feature comparison
+
+- In order to understand what is needed, would be good to have a comparison.

docs/features/foam-logging-in-vscode.md

@@ -1,21 +0,0 @@
-# Foam logging in VsCode
-
-## Find the Foam log
-
-The Foam log can be found in the `Output` tab.
-
-1. To show the tab, click on `View > Output`.
-2. In the dropdown on the right of the tab, select `Foam`.
-
-![Find the foam log](../assets/images/foam-log.png)
-
-## Change the default logging level
-
-1. Open workspace settings (`cmd+,`, or execute the `Preferences: Open Workspace Settings` command)
-2. Look for the entry `Foam > Logging: Level`
-
-Set to debug when reporting an issue
-
-## Change the log level for the session
-
-Execute the command `Foam: Set log level`.

docs/features/git-integration.md

@@ -1,12 +0,0 @@
-# Git Integration
-
-There are (too) many ways to commit your changes to source control:
-
-- Using VS Code's own git integration
-  - The quick and easy way is to use the `Git: Commit All` command after editing files. The default Foam workspace settings will stage & sync all of your changes to the remote:
-- Using GitDoc for [[automatic-git-syncing]]
-- Whatever way you like to do it (CLI?)
-
-[//begin]: # "Autogenerated link references for markdown compatibility"
-[automatic-git-syncing]: ../recipes/automatic-git-syncing.md "Automatically Sync with Git"
-[//end]: # "Autogenerated link references"

docs/features/graph-visualisation.md

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

docs/features/note-templates.md

@@ -1,158 +0,0 @@
-# Note Templates
-
-Foam supports note templates. Templates are a way to customize the starting content for your notes (instead of always starting from an empty note).
-
-Note templates are files located in the special `.foam/templates` directory.
-
-## Quickstart
-
-Create a template:
-
-* Run the `Foam: Create New Template` command from the command palette
-* OR manually create a regular `.md` file in the `.foam/templates` directory
-
-![Create new template GIF](../assets/images/create-new-template.gif)
-
-_Theme: Ayu Light_
-
-To create a note from a template:
-
-* Run the `Foam: Create New Note From Template` command and follow the instructions. Don't worry if you've not created a template yet! You'll be prompted to create a new template if none exist.
-* OR run the `Foam: Create New Note` command, which uses the special default template (`.foam/templates/new-note.md`, if it exists)
-
-![Create new note from template GIF](../assets/images/create-new-note-from-template.gif)
-
-_Theme: Ayu Light_
-
-## Special templates
-### Default template
-
-The `.foam/templates/new-note.md` template is special in that it is the template that will be used by the `Foam: Create New Note` command.
-Customize this template to contain content that you want included every time you create a note.
-
-### Default daily note template
-
-The `.foam/templates/daily-note.md` template is special in that it is the template that will be used when creating daily notes (e.g. by using `Foam: Open Daily Note`).
-Customize this template to contain content that you want included every time you create a daily note.
-
-## Variables
-
-Templates can use all the variables available in [VS Code Snippets](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_variables).
-
-In addition, you can also use variables provided by Foam:
-
-| Name                 | Description                                                                                                                                             |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `FOAM_SELECTED_TEXT` | Foam will fill it with selected text when creating a new note, if any text is selected. Selected text will be replaced with a wikilink to the new note. |
-| `FOAM_TITLE`         | The title of the note. If used, Foam will prompt you to enter a title for the note.                                                                     |
-
-**Note:** neither the defaulting feature (eg. `${variable:default}`) nor the format feature (eg. `${variable/(.*)/${1:/upcase}/}`) (available to other variables) are available for these Foam-provided variables.
-
-## Metadata
-
-Templates can also contain metadata about the templates themselves. The metadata is defined in YAML "Frontmatter" blocks within the templates.
-
-| Name          | Description                                                                                                                      |
-| ------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `filepath`    | The filepath to use when creating the new note. If the filepath is a relative filepath, it is relative to the current workspace. |
-| `name`        | A human readable name to show in the template picker.                                                                            |
-| `description` | A human readable description to show in the template picker.                                                                     |
-
-Foam-specific variables (e.g. `$FOAM_TITLE`) can be used within template metadata. However, VS Code snippet variables are ([currently](https://github.com/foambubble/foam/pull/655)) not supported.
-
-### `filepath` attribute
-
-The `filepath` metadata attribute allows you to define a relative or absolute filepath to use when creating a note using the template.
-If the filepath is a relative filepath, it is relative to the current workspace.
-
-**Note:** While you can make use of the `filepath` attribute in [daily note](daily-notes.md) templates (`.foam/templates/daily-note.md`), there is currently no way to have `filepath` vary based on the date. This will be improved in the future. For now, you can customize the location of daily notes using the [`foam.openDailyNote` settings](daily-notes.md).
-
-#### Example of relative `filepath`
-
-For example, `filepath` can be used to customize `.foam/templates/new-note.md`, overriding the default `Foam: Create New Note` behaviour of opening the file in the same directory as the active file:
-
-```yaml
----
-# This will create the note in the "journal" subdirectory of the current workspace,
-# regardless of which file is the active file.
-foam_template:
-  filepath: 'journal/$FOAM_TITLE.md'
----
-```
-
-#### Example of absolute `filepath`
-
-`filepath` can be an absolute filepath, so that the notes get created in the same location, regardless of which file or workspace the editor currently has open.
-The format of an absolute filepath may vary depending on the filesystem used.
-
-```yaml
----
-foam_template:
-  # Unix / MacOS filesystems
-  filepath: '/Users/john.smith/foam/journal/$FOAM_TITLE.md'
-
-  # Windows filesystems
-  filepath: 'C:\Users\john.smith\Documents\foam\journal\$FOAM_TITLE.md'
----
-```
-
-### `name` and `description` attributes
-
-These attributes provide a human readable name and description to be shown in the template picker (e.g. When a user uses the `Foam: Create New Note From Template` command):
-
-![Template Picker annotated with attributes](../assets/images/template-picker-annotated.png)
-
-### Adding template metadata to an existing YAML Frontmatter block
-
-If your template already has a YAML Frontmatter block, you can add the Foam template metadata to it.
-
-#### Limitations
-
-Foam only supports adding the template metadata to *YAML* Frontmatter blocks. If the existing Frontmatter block uses some other format (e.g. JSON), you will have to add the template metadata to its own YAML Frontmatter block.
-
-Further, the template metadata must be provided as a [YAML block mapping](https://yaml.org/spec/1.2/spec.html#id2798057), with the attributes placed on the lines immediately following the `foam_template` line:
-
-```yaml
----
-existing_frontmatter: "Existing Frontmatter block"
-foam_template: # this is a YAML "Block" mapping ("Flow" mappings aren't supported)
-  name: My Note Template # Attributes must be on the lines immediately following `foam_template`
-  description: This is my note template
-  filepath: `journal/$FOAM_TITLE.md`
----
-This is the rest of the template
-```
-
-Due to the technical limitations of parsing the complex YAML format, unless the metadata is provided this specific form, Foam is unable to correctly remove the template metadata before creating the resulting note.
-
-If this limitation proves inconvenient to you, please let us know. We may be able to extend our parsing capabilities to cover your use case. In the meantime, you can add the template metadata without this limitation by providing it in its own YAML Frontmatter block.
-
-### Adding template metadata to its own YAML Frontmatter block
-
-You can add the template metadata to its own YAML Frontmatter block at the start of the template:
-
-```yaml
----
-foam_template:
-  name: My Note Template
-  description: This is my note template
-  filepath: `journal/$FOAM_TITLE.md`
----
-This is the rest of the template
-```
-
-If the note already has a Frontmatter block, a Foam-specific Frontmatter block can be added to the start of the template. The Foam-specific Frontmatter block must always be placed at the very beginning of the file, and only whitespace can separate the two Frontmatter blocks.
-
-```yaml
----
-foam_template:
-  name: My Note Template
-  description: This is my note template
-  filepath: `journal/$FOAM_TITLE.md`
----
-
----
-existing_frontmatter: "Existing Frontmatter block"
----
-This is the rest of the template
-```

docs/features/orphans.md

@@ -1,10 +0,0 @@
-# Orphans
-
-Foam helps you to find orphans: notes that have neither forward links nor backlinks.
-
-Orphans can be found in the Orphans panel.
-
-Two settings allows you to control the behaviour of the Orphans panel:
-
-- `foam.orphans.exclude`: list of glob patterns that will be used to exclude directories. For example, a value of `["journal/**/*"]` would exclude your daily notes.
-- `foam.orphans.groupBy`: sets the default view mode of the Orphans panel: either groups by folder (by default), or lists all orphans. The view can be toggled on the fly from the panel, but it won't overwrite the setting.

docs/features/tags.md

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

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

docs/foam-file-format.md

@@ -4,13 +4,19 @@ This file is an example of a valid Foam file. Essentially it's just a markdown f
 
 Here are a few specific constraints, mainly because our tooling is a bit fragmented. Most of these should be eventually lifted, and our requirement should just be "Markdown with `[[wiki-links]]`:
 
-- **The first top level `# Heading` will be used as title for the note.**
-  - If not available, we will use the file name
-- **File name should have extension `.md`**
+- **It needs to have a single top level `# Heading`.**
+  - This will be used as document title.
+    - [[decision-needed]] Do we need it?
+    - [[decision-needed]] How much to deviate from just markdown
+- **File name should not contain spaces,** e.g. `foam-file-format.md` is a valid name, but `Foam File Format.md` is not.
+  - This is a temporary limitation and will be lifted in future versions.
+  - Technically this actually works already, but may have some edge cases you don't want to deal with if you can avoid it.
+- **File name should have extension `.md` or `.markdown`**
   - This is a temporary limitation and will be lifted in future versions.
   - At least `.mdx` will be supported, but ideally we'll support any file that you can map to `Markdown` language mode in VS Code
 - **In addition to normal Markdown Links syntax you can use `[[media-wiki]]` links.** See [[wiki-links]] for more details.
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[wiki-links]: ../wiki-links.md "Wiki Links"
+[decision-needed]: decision-needed "Decision Needed"
+[wiki-links]: wiki-links "Wiki Links"
 [//end]: # "Autogenerated link references"

docs/foam-linter.md

@@ -0,0 +1,11 @@
+# Foam Linter (stub)
+
+**[[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"

docs/frequently-asked-questions.md

@@ -4,7 +4,6 @@
 
 - [Frequently Asked Questions](#frequently-asked-questions)
   - [Links/Graphs/BackLinks don't work. How do I enable them?](#linksgraphsbacklinks-dont-work-how-do-i-enable-them)
-  - [I don't want Foam enabled for all my workspaces](#i-dont-want-foam-enabled-for-all-my-workspaces)
 
 ## Links/Graphs/BackLinks don't work. How do I enable them?
 
@@ -12,11 +11,9 @@
 - 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]]
 
-## I don't want Foam enabled for all my workspaces
-Any extension you install in Visual Studio Code is enabled by default. Give the philosophy of Foam it works out of the box without doing any configuration upfront. In case you want to disable Foam for a specific workspace, or disable Foam by default and enable it for specific workspaces, it is advised to follow the best practices as [documented by Visual Studio Code](https://code.visualstudio.com/docs/editor/extension-marketplace#_manage-extensions)
-
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[recommended-extensions]: recommended-extensions.md "Recommended Extensions"
-[foam-file-format]: dev/foam-file-format.md "Foam File Format"
-[wiki-links]: wiki-links.md "Wiki Links"
-[//end]: # "Autogenerated link references"
+[recommended-extensions]: recommended-extensions "Recommended Extensions"
+[foam-file-format]: foam-file-format "Foam File Format"
+[wiki-links]: wiki-links "Wiki Links"
+[link-formatting-and-autocompletion]: link-formatting-and-autocompletion "Link Formatting and Autocompletion"
+[//end]: # "Autogenerated link references"

docs/gistpad.md

@@ -1,10 +1,6 @@
-# Write your notes in GitHub Gist
+# GistPad
 
-This #recipe will allow you 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.
-
-[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).
+[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" />
 
@@ -14,9 +10,9 @@ To start using GistPad for your Foam-based knowledge base, simply perform the fo
 
 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: Sign In` command, and provide a [GitHub token](https://github.com/settings/tokens/new) that includes the `repo` scope (and optionally `gist` and `delete_repo` scope, if you'd like to use GistPad for managing your GitHub content more holistically)
 
-1. Run the `GistPad: Open Repository` command and select the `Create repo from template...` or `Create private repo from template...` depending on your preference
+1. Run the `GistPad: Manage Repository` command and select the `Create repo from template...` or `Create private repo from template...` depending on your preference
 
 1. Select the `Foam-style wiki` template, and then specify a name for your Foam workspace (e.g. `my-foam-notes`, `johns-knowledge-base`)
 
@@ -50,6 +46,6 @@ You can view a page's backlinks using either of the following techniques:
 
 ## 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.
+In addition to create arbitrary pages, you can also use GistPad for journaling or capturing [daily notes](https://github.com/vsls-contrib/gistpad#daily-pages). Simply click the calendar icon in the `Repositories` tree, which will open up the page that represents today. If the page doesn't already exist, then it will be created in the workspace before being opened.
 
 <img width="700px" src="https://user-images.githubusercontent.com/116461/87234721-b356cc00-c388-11ea-946a-e7f9c92258a6.png" />

docs/git-flows-for-teams.md

@@ -0,0 +1,10 @@
+# Git Flows for Teams (stub)
+
+**[[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"

docs/git-integration.md

@@ -0,0 +1,18 @@
+# Git integration
+
+There are (too) many ways to commit your changes to source control:
+
+- Using VS Code's own git integration
+- Using GitLens (included in Foam for inline blame)
+- Whatever way you like to do it (CLI?)
+
+The quick and easy way is to use the Git: Commit All command after editing files. The default Foam workspace settings will stage & sync all of your changes to the remote:
+
+- `Cmd` + `Shift` + `P` (`Ctrl` + `Shift` + `P` for Windows), execute `Git: Commit All`
+
+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"
+[//end]: # "Autogenerated link references"

docs/github-pages.md

@@ -0,0 +1,12 @@
+# Github Pages
+
+- The [Foam template](https://github.com/foambubble/foam-template) is **GitHub Pages** ready, all you have to do is [turn it on in your repository settings](https://guides.github.com/features/pages/).
+- The default GitHub Pages template is called [Primer](https://github.com/pages-themes/primer). See Primer docs for how to customise html layouts and templates.
+- GitHub Pages is built on [Jekyll](https://jekyllrb.com/), so it supports things like permalinks, front matter metadata etc.
+
+[[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"
+[//end]: # "Autogenerated link references"

docs/gitlab-pages.md

@@ -11,24 +11,13 @@ 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/)
@@ -43,7 +32,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.md "Materialized Backlinks (stub)"
+[materialized-backlinks]: materialized-backlinks "Materialized Backlinks (stub)"
 [//end]: # "Autogenerated link references"

docs/graph-in-published-workspace.md

@@ -0,0 +1,10 @@
+# Graph in Published Workspace (stub)
+
+**[[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"

docs/graph-visualisation.md

@@ -0,0 +1,9 @@
+# Graph visualisation
+
+`Cmd` + `Shift` + `P` (`Ctrl` + `Shift` + `P` for Windows), type `Show graph`.
+
+(Depends on [Markdown Links](https://marketplace.visualstudio.com/items?itemName=tchayen.markdown-links).)
+
+![Demo of graph visualiser](assets/images/foam-navigation-demo.gif)
+
+

docs/how-to-write-recipes.md

@@ -3,7 +3,6 @@
 This is an example of how to structure a Recipe. The first paragraph or two should explain the purpose of the recipe succinctly, including why it's useful, if that's not obvious.
 
 Recipes are intended to document:
-
 - How to use Foam's basic features
 - Power user pro-tips
 - Useful customisations of the default Foam environment
@@ -11,12 +10,12 @@ Recipes are intended to document:
 
 ## Required Extensions
 
-- **[Hacker Typer](https://marketplace.visualstudio.com/items?itemName=jevakallio.vscode-hacker-typer)** (not really required for this recipe, just an example)
-- [Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode) (installed by default)
+ - **[Hacker Typer](https://marketplace.visualstudio.com/items?itemName=jevakallio.vscode-hacker-typer)** (not really required for this recipe, just an example)
+ - [Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode) (installed by default)
 
 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.
 
@@ -24,7 +23,7 @@ When creating new recipes, if you don't know which extension does what, you can
 
 Here we describe how the extension should be used.
 
-![Demo](../assets/images/foam-navigation-demo.gif)
+![Demo](assets/images/foam-navigation-demo.gif)
 
 You may include a screenshot or GIF of the feature in action by uploading an image to the `assets/images` directory. Please try to keep GIFs as small as possible by recording them with a low frame rate.
 
@@ -34,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.md "Recommended Extensions"
-[recipes]: recipes.md "Recipes"
-[contribution-guide]: ../contribution-guide.md "Contribution Guide"
-[//end]: # "Autogenerated link references"
+[recommended-extensions]: recommended-extensions "Recommended Extensions"
+[recipes]: recipes "Recipes"
+[contribution-guide]: contribution-guide "Contribution Guide"
+[//end]: # "Autogenerated link references"

docs/images-from-your-clipboard.md

@@ -1,9 +1,5 @@
-# Add images to your notes
-
-This #recipe allows you to paste images on to your notes.
+# Images from your Clipboard
 
 You can directly link and paste images that are copied to the clipboard using either the [Paste
 Image](https://marketplace.visualstudio.com/items?itemName=mushan.vscode-paste-image)
-extension, or the [Markdown Image](https://marketplace.visualstudio.com/items?itemName=hancel.markdown-image) extension.
-
-The former does not have MDX support (yet), the latter does.
+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

@@ -0,0 +1,10 @@
+# Improve Default Workspace Settings (stub)
+
+**[[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"

docs/improved-backlinking.md

@@ -0,0 +1,11 @@
+# Improved Backlinking (stub)
+
+**[[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"

docs/improved-static-site-generation.md

@@ -0,0 +1,15 @@
+# Improved Static Site Generation (stub)
+
+**[[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).
+
+## Notes
+
+- We should consider moving to gatsby, similar to [Foam Gatsby Template](https://mathieudutour.github.io/foam-gatsby-template/)
+
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[todo]: todo "Todo"
+[roadmap]: roadmap "Roadmap"
+[//end]: # "Autogenerated link references"

docs/inbox.md

@@ -5,7 +5,7 @@ Uncategorised thoughts, to be added
 - Release notes
 - Markdown Preview
   - It's possible to customise the markdown preview styling. **Maybe make it use local foam workspace styles for live preview of the site??**
-    - See: <https://marketplace.visualstudio.com/items?itemName=bierner.markdown-preview-github-styles>
+    - See: https://marketplace.visualstudio.com/items?itemName=bierner.markdown-preview-github-styles
 - Use VS Code [CodeTour](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.codetour) for onboarding
 - Investigate other similar extensions:
   - [Unotes](https://marketplace.visualstudio.com/items?itemName=ryanmcalister.Unotes)
@@ -15,8 +15,14 @@ Uncategorised thoughts, to be added
   - When you want to open a Foam published website in your own VS Code, we could have a "Open in Foam" link that opens the link in VS Code via a url binding (if possible), downloads the github repo locally, and opens it as a Foam workspace.
   - Every Foam could have a different theme even in the editor, so you'll see it like they see it
     - UI and layout design of your workspace can become a thing
+- Developer documentation
+  - GistPad has a good vs code contrib primer: https://github.com/jevakallio/gistpad/blob/master/CONTRIBUTING.md  
 - VS Code Notebooks API
-  - <https://code.visualstudio.com/api/extension-guides/notebook>
+  - https://code.visualstudio.com/api/extension-guides/notebook
+- Snippets in template
+- Foam as a (VS Code) language
+  - Syntax highlighting
+  - Snippets
 - Future architecture
   - Could we do publish-related settings as a pre-push git hook, e.g. generating footnote labels
   - Running them on Github Actions to edit stuff as it comes in
@@ -30,5 +36,14 @@ Uncategorised thoughts, to be added
 - Should support Netlify deploys out of the box
 - Foam should tick at the same frequency as your brain, and the Foam graph you build should match the mental model you have in your head, making navigation effortless.
   - Maps have persistent topologies. As the graph grows, you should be able to visualise where an idea belongs. Maybe a literal map? And island? A DeckGL visualisation?
+- Write about the history and process of Foam
+  - In ways, Wallet was the first iteration of Foam-like environment
+- Should we support directories?
+  - Some tools might get more complicated to build
+  - The pressure to categorize and create hierachies can become distracting
+  - Is there value in folderizing?
+  - Use case: Writing docs in a codebase
 
 Testing: This file is served from the /docs directory.
+
+

docs/index.md

@@ -7,11 +7,11 @@ You can use **Foam** for organising your research, keeping re-discoverable notes
 **Foam** is free, open source, and extremely extensible to suit your personal workflow. You own the information you create with Foam, and you're free to share it, and collaborate on it with anyone you want.
 
 <p class="announcement">
-  <b>New!</b> Join <a href="https://foambubble.github.io/join-discord/w" target="_blank">Foam community Discord</a> for users and contributors!
+  <b>New!</b> Join <a href="https://discord.gg/rtdZKgj" target="_blank">Foam community Discord</a> for users and contributors!
 </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>
 
@@ -48,7 +48,7 @@ Like the soapy suds it's named after, **Foam** is mostly air.
 
 1. The editing experience of **Foam** is powered by VS Code, enhanced by workspace settings that glue together [[recommended-extensions]] and preferences optimised for writing and navigating information.
 2. To back up, collaborate on and share your content between devices, Foam pairs well with [GitHub](http://github.com/).
-3. To publish your content, you can set it up to publish to [GitHub Pages](https://pages.github.com/), or to any website hosting platform like [Netlify](http://netlify.com/) or [Vercel](https://vercel.com).
+3. To publish your content, you can set it up to publish to [GitHub Pages](https://pages.github.com/) with zero code and zero config, or to any website hosting platform like [Netlify](http://netlify.com/) or [Vercel](https://vercel.com).
 
 > **Fun fact**: This documentation was researched, written and published using **Foam**.
 
@@ -66,7 +66,7 @@ These instructions assume you have a GitHub account, and you have Visual Studio
 
 2. [Clone the repository locally](https://help.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) and open it in VS Code.
 
-   *Open the repository as a folder using the `File > Open...` menu item. In VS Code, "open workspace" refers to [multi-root workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces).*
+    *Open the repository as a folder using the `File > Open...` menu item. In VS Code, "open workspace" refers to [multi-root workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces).*
 
 3. When prompted to install recommended extensions, click **Install all** (or **Show Recommendations** if you want to review and install them one by one)
 
@@ -76,7 +76,7 @@ To learn more about how to use **Foam**, read the [[recipes]].
 
 Getting stuck in the setup? Read the [[frequently-asked-questions]].
 
-Check our [issues on GitHub](http://github.com/foambubble/foam/issues) if you get stuck on something, and create a new one if something doesn't seem right!
+There are [[known-issues]], and I'm sure, many unknown issues! Please [report them on GitHub](http://github.com/foambubble/foam/issues)!
 
 ## Features
 
@@ -96,120 +96,80 @@ I am using it as my personal thinking tool. By making it public, I hope to learn
 
 If that sounds like something you're interested in, I'd love to have you along on the journey.
 
+- Check out [[roadmap]] to see what's in the plans
 - Read about our [[principles]] to understand Foam's philosophy and direction
 - Read the [[contribution-guide]] guide to learn how to participate.
 - Feel free to open [GitHub issues](https://github.com/foambubble/foam/issues) to give me feedback and ideas for new features.
 
 ## Thanks and attribution
 
+**Foam** is built by [Jani Eväkallio](https://github.com/jevakallio) ([@jevakallio](https://twitter.com/jevakallio)), and all our contributors:
+
 <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
 <!-- prettier-ignore-start -->
 <!-- markdownlint-disable -->
 <table>
   <tr>
-    <td align="center"><a href="https://jevakallio.dev/"><img src="https://avatars1.githubusercontent.com/u/1203949?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Jani Eväkallio</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=jevakallio" title="Code">💻</a> <a href="https://github.com/foambubble/foam/commits?author=jevakallio" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://joeprevite.com/"><img src="https://avatars3.githubusercontent.com/u/3806031?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Joe Previte</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=jsjoeio" title="Code">💻</a> <a href="https://github.com/foambubble/foam/commits?author=jsjoeio" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://github.com/riccardoferretti"><img src="https://avatars3.githubusercontent.com/u/457005?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Riccardo</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=riccardoferretti" title="Code">💻</a> <a href="https://github.com/foambubble/foam/commits?author=riccardoferretti" title="Documentation">📖</a></td>
-    <td align="center"><a href="http://ojanaho.com/"><img src="https://avatars0.githubusercontent.com/u/2180090?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Janne Ojanaho</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=jojanaho" title="Code">💻</a> <a href="https://github.com/foambubble/foam/commits?author=jojanaho" title="Documentation">📖</a></td>
-    <td align="center"><a href="http://bypaulshen.com/"><img src="https://avatars3.githubusercontent.com/u/2266187?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Paul Shen</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=paulshen" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://github.com/coffenbacher"><img src="https://avatars0.githubusercontent.com/u/245867?v=4?s=60" width="60px;" alt=""/><br /><sub><b>coffenbacher</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=coffenbacher" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://mathieu.dutour.me/"><img src="https://avatars2.githubusercontent.com/u/3254314?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Mathieu Dutour</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=mathieudutour" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://jevakallio.dev/"><img src="https://avatars1.githubusercontent.com/u/1203949?v=4" width="60px;" alt=""/><br /><sub><b>Jani Eväkallio</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=jevakallio" title="Code">💻</a> <a href="https://github.com/foambubble/foam/commits?author=jevakallio" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://joeprevite.com/"><img src="https://avatars3.githubusercontent.com/u/3806031?v=4" width="60px;" alt=""/><br /><sub><b>Joe Previte</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=jsjoeio" title="Code">💻</a> <a href="https://github.com/foambubble/foam/commits?author=jsjoeio" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/riccardoferretti"><img src="https://avatars3.githubusercontent.com/u/457005?v=4" width="60px;" alt=""/><br /><sub><b>Riccardo</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=riccardoferretti" title="Code">💻</a> <a href="https://github.com/foambubble/foam/commits?author=riccardoferretti" title="Documentation">📖</a></td>
+    <td align="center"><a href="http://ojanaho.com/"><img src="https://avatars0.githubusercontent.com/u/2180090?v=4" width="60px;" alt=""/><br /><sub><b>Janne Ojanaho</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=jojanaho" title="Code">💻</a> <a href="https://github.com/foambubble/foam/commits?author=jojanaho" title="Documentation">📖</a></td>
+    <td align="center"><a href="http://bypaulshen.com/"><img src="https://avatars3.githubusercontent.com/u/2266187?v=4" width="60px;" alt=""/><br /><sub><b>Paul Shen</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=paulshen" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/coffenbacher"><img src="https://avatars0.githubusercontent.com/u/245867?v=4" width="60px;" alt=""/><br /><sub><b>coffenbacher</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=coffenbacher" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://mathieu.dutour.me/"><img src="https://avatars2.githubusercontent.com/u/3254314?v=4" width="60px;" alt=""/><br /><sub><b>Mathieu Dutour</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=mathieudutour" title="Documentation">📖</a></td>
   </tr>
   <tr>
-    <td align="center"><a href="https://github.com/presidentelect"><img src="https://avatars2.githubusercontent.com/u/1242300?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Michael Hansen</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=presidentelect" title="Documentation">📖</a></td>
-    <td align="center"><a href="http://klickverbot.at/"><img src="https://avatars1.githubusercontent.com/u/19335?v=4?s=60" width="60px;" alt=""/><br /><sub><b>David Nadlinger</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=dnadlinger" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://pluckd.co/"><img src="https://avatars2.githubusercontent.com/u/20598571?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Fernando</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=MrCordeiro" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://github.com/jfgonzalez7"><img src="https://avatars3.githubusercontent.com/u/58857736?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Juan Gonzalez</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=jfgonzalez7" title="Documentation">📖</a></td>
-    <td align="center"><a href="http://www.louiechristie.com/"><img src="https://avatars1.githubusercontent.com/u/6807448?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Louie Christie</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=louiechristie" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://supersandro.de/"><img src="https://avatars2.githubusercontent.com/u/7258858?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Sandro</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=SuperSandro2000" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://github.com/Skn0tt"><img src="https://avatars1.githubusercontent.com/u/14912729?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Simon Knott</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=Skn0tt" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/presidentelect"><img src="https://avatars2.githubusercontent.com/u/1242300?v=4" width="60px;" alt=""/><br /><sub><b>Michael Hansen</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=presidentelect" title="Documentation">📖</a></td>
+    <td align="center"><a href="http://klickverbot.at/"><img src="https://avatars1.githubusercontent.com/u/19335?v=4" width="60px;" alt=""/><br /><sub><b>David Nadlinger</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=dnadlinger" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://pluckd.co/"><img src="https://avatars2.githubusercontent.com/u/20598571?v=4" width="60px;" alt=""/><br /><sub><b>Fernando</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=MrCordeiro" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/jfgonzalez7"><img src="https://avatars3.githubusercontent.com/u/58857736?v=4" width="60px;" alt=""/><br /><sub><b>Juan Gonzalez</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=jfgonzalez7" title="Documentation">📖</a></td>
+    <td align="center"><a href="http://www.louiechristie.com/"><img src="https://avatars1.githubusercontent.com/u/6807448?v=4" width="60px;" alt=""/><br /><sub><b>Louie Christie</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=louiechristie" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://supersandro.de/"><img src="https://avatars2.githubusercontent.com/u/7258858?v=4" width="60px;" alt=""/><br /><sub><b>Sandro</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=SuperSandro2000" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/Skn0tt"><img src="https://avatars1.githubusercontent.com/u/14912729?v=4" width="60px;" alt=""/><br /><sub><b>Simon Knott</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=Skn0tt" title="Documentation">📖</a></td>
   </tr>
   <tr>
-    <td align="center"><a href="https://styfle.dev/"><img src="https://avatars1.githubusercontent.com/u/229881?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Steven</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=styfle" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://github.com/Georift"><img src="https://avatars2.githubusercontent.com/u/859430?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Tim</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=Georift" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://github.com/sauravkhdoolia"><img src="https://avatars1.githubusercontent.com/u/34188267?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Saurav Khdoolia</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=sauravkhdoolia" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://anku.netlify.com/"><img src="https://avatars1.githubusercontent.com/u/22813027?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Ankit Tiwari</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=anku255" title="Documentation">📖</a> <a href="https://github.com/foambubble/foam/commits?author=anku255" title="Tests">⚠️</a> <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?s=60" width="60px;" alt=""/><br /><sub><b>Ayush Baweja</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=ayushbaweja" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://github.com/TaiChi-IO"><img src="https://avatars3.githubusercontent.com/u/65092992?v=4?s=60" 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?s=60" 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>
+    <td align="center"><a href="https://styfle.dev/"><img src="https://avatars1.githubusercontent.com/u/229881?v=4" width="60px;" alt=""/><br /><sub><b>Steven</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=styfle" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/Georift"><img src="https://avatars2.githubusercontent.com/u/859430?v=4" width="60px;" alt=""/><br /><sub><b>Tim</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=Georift" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/sauravkhdoolia"><img src="https://avatars1.githubusercontent.com/u/34188267?v=4" width="60px;" alt=""/><br /><sub><b>Saurav Khdoolia</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=sauravkhdoolia" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://anku.netlify.com/"><img src="https://avatars1.githubusercontent.com/u/22813027?v=4" width="60px;" alt=""/><br /><sub><b>Ankit Tiwari</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=anku255" title="Documentation">📖</a> <a href="https://github.com/foambubble/foam/commits?author=anku255" title="Tests">⚠️</a> <a href="https://github.com/foambubble/foam/commits?author=anku255" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/ayushbaweja"><img src="https://avatars1.githubusercontent.com/u/44344063?v=4" width="60px;" alt=""/><br /><sub><b>Ayush Baweja</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=ayushbaweja" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/TaiChi-IO"><img src="https://avatars3.githubusercontent.com/u/65092992?v=4" width="60px;" alt=""/><br /><sub><b>TaiChi-IO</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=TaiChi-IO" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/juanfrank77"><img src="https://avatars1.githubusercontent.com/u/12146882?v=4" width="60px;" alt=""/><br /><sub><b>Juan F Gonzalez </b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=juanfrank77" title="Documentation">📖</a></td>
   </tr>
   <tr>
-    <td align="center"><a href="https://sanketdg.github.io"><img src="https://avatars3.githubusercontent.com/u/8980971?v=4?s=60" 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?s=60" 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?s=60" 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?s=60" 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?s=60" 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?s=60" 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?s=60" 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>
+    <td align="center"><a href="https://sanketdg.github.io"><img src="https://avatars3.githubusercontent.com/u/8980971?v=4" width="60px;" alt=""/><br /><sub><b>Sanket Dasgupta</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=SanketDG" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/nstafie"><img src="https://avatars1.githubusercontent.com/u/10801854?v=4" width="60px;" alt=""/><br /><sub><b>Nicholas Stafie</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=nstafie" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/francishamel"><img src="https://avatars3.githubusercontent.com/u/36383308?v=4" width="60px;" alt=""/><br /><sub><b>Francis Hamel</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=francishamel" title="Code">💻</a></td>
+    <td align="center"><a href="http://digiguru.co.uk"><img src="https://avatars1.githubusercontent.com/u/619436?v=4" width="60px;" alt=""/><br /><sub><b>digiguru</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=digiguru" title="Code">💻</a> <a href="https://github.com/foambubble/foam/commits?author=digiguru" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://github.com/chirag-singhal"><img src="https://avatars3.githubusercontent.com/u/42653703?v=4" width="60px;" alt=""/><br /><sub><b>CHIRAG SINGHAL</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=chirag-singhal" title="Code">💻</a></td>
+    <td align="center"><a href="https://github.com/lostintangent"><img src="https://avatars3.githubusercontent.com/u/116461?v=4" width="60px;" alt=""/><br /><sub><b>Jonathan Carter</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=lostintangent" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://www.synesthesia.co.uk"><img src="https://avatars3.githubusercontent.com/u/181399?v=4" width="60px;" alt=""/><br /><sub><b>Julian Elve</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=synesthesia" title="Documentation">📖</a></td>
   </tr>
   <tr>
-    <td align="center"><a href="https://github.com/thomaskoppelaar"><img src="https://avatars3.githubusercontent.com/u/36331365?v=4?s=60" 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?s=60" 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?s=60" 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?s=60" 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?s=60" 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?s=60" 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?s=60" 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>
+    <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?s=60" 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?s=60" 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?s=60" 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?s=60" 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?s=60" 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?s=60" 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?s=60" 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>
+    <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?s=60" 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?s=60" 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?s=60" 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?s=60" 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?s=60" 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?s=60" 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?s=60" 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?s=60" 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?s=60" 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?s=60" 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?s=60" 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?s=60" 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?s=60" 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?s=60" 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>
-  <tr>
-    <td align="center"><a href="https://mcluck.tech"><img src="https://avatars1.githubusercontent.com/u/1753801?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Mike Cluck</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=MCluck90" title="Code">💻</a></td>
-    <td align="center"><a href="http://brandonpugh.com"><img src="https://avatars1.githubusercontent.com/u/684781?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Brandon Pugh</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=bpugh" title="Code">💻</a></td>
-    <td align="center"><a href="https://max.davitt.me"><img src="https://avatars1.githubusercontent.com/u/27709025?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Max Davitt</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=themaxdavitt" title="Documentation">📖</a></td>
-    <td align="center"><a href="http://briananglin.me"><img src="https://avatars3.githubusercontent.com/u/2637602?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Brian Anglin</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=anglinb" title="Documentation">📖</a></td>
-    <td align="center"><a href="http://deft.work"><img src="https://avatars1.githubusercontent.com/u/1455507?v=4?s=60" width="60px;" alt=""/><br /><sub><b>elswork</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=elswork" title="Documentation">📖</a></td>
-    <td align="center"><a href="http://leonh.fr/"><img src="https://avatars.githubusercontent.com/u/19996318?v=4?s=60" width="60px;" alt=""/><br /><sub><b>léon h</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=leonhfr" title="Code">💻</a></td>
-    <td align="center"><a href="https://nygaard.site"><img src="https://avatars.githubusercontent.com/u/4606342?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Nikhil Nygaard</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=njnygaard" title="Documentation">📖</a></td>
-  </tr>
-  <tr>
-    <td align="center"><a href="http://www.nitwit.se"><img src="https://avatars.githubusercontent.com/u/1382124?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Mark Dixon</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=nitwit-se" title="Code">💻</a></td>
-    <td align="center"><a href="https://github.com/joeltjames"><img src="https://avatars.githubusercontent.com/u/3732400?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Joel James</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=joeltjames" title="Code">💻</a></td>
-    <td align="center"><a href="https://www.ryo33.com"><img src="https://avatars.githubusercontent.com/u/8780513?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Hashiguchi Ryo</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=ryo33" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://movermeyer.com"><img src="https://avatars.githubusercontent.com/u/1459385?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Michael Overmeyer</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=movermeyer" title="Code">💻</a></td>
-    <td align="center"><a href="https://github.com/derrickqin"><img src="https://avatars.githubusercontent.com/u/3038111?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Derrick Qin</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=derrickqin" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://www.linkedin.com/in/zomars/"><img src="https://avatars.githubusercontent.com/u/3504472?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Omar López</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=zomars" title="Documentation">📖</a></td>
-    <td align="center"><a href="http://robincn.com"><img src="https://avatars.githubusercontent.com/u/1583193?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Robin King</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=RobinKing" title="Code">💻</a></td>
-  </tr>
-  <tr>
-    <td align="center"><a href="http://twitter.com/deegovee"><img src="https://avatars.githubusercontent.com/u/4730170?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Dheepak </b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=dheepakg" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://github.com/daniel-vera-g"><img src="https://avatars.githubusercontent.com/u/28257108?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Daniel VG</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=daniel-vera-g" title="Documentation">📖</a></td>
-    <td align="center"><a href="https://github.com/Barabazs"><img src="https://avatars.githubusercontent.com/u/31799121?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Barabas</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=Barabazs" title="Code">💻</a></td>
-    <td align="center"><a href="http://enginveske@gmail.com"><img src="https://avatars.githubusercontent.com/u/43685404?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Engincan VESKE</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=EngincanV" title="Documentation">📖</a></td>
-    <td align="center"><a href="http://www.paulderaaij.nl"><img src="https://avatars.githubusercontent.com/u/495374?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Paul de Raaij</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=pderaaij" title="Code">💻</a></td>
-    <td align="center"><a href="https://github.com/bronson"><img src="https://avatars.githubusercontent.com/u/1776?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Scott Bronson</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=bronson" title="Documentation">📖</a></td>
-    <td align="center"><a href="http://rafaelriedel.de"><img src="https://avatars.githubusercontent.com/u/41793?v=4?s=60" width="60px;" alt=""/><br /><sub><b>Rafael Riedel</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=rafo" title="Documentation">📖</a></td>
+    <td align="center"><a href="https://spencerwoo.com"><img src="https://avatars2.githubusercontent.com/u/32114380?v=4" width="60px;" alt=""/><br /><sub><b>Spencer Woo</b></sub></a><br /><a href="https://github.com/foambubble/foam/commits?author=spencerwooo" title="Documentation">📖</a></td>
   </tr>
 </table>
 
-<!-- markdownlint-restore -->
+<!-- markdownlint-enable -->
 <!-- prettier-ignore-end -->
-
 <!-- ALL-CONTRIBUTORS-LIST:END -->
 
 **Foam** was inspired by [Roam Research](https://roamresearch.com/) and the [Zettelkasten methodology](https://zettelkasten.de/posts/overview)
@@ -218,14 +178,16 @@ If that sounds like something you're interested in, I'd love to have you along o
 
 ## License
 
-Foam is licensed under the [MIT license](LICENSE.txt).
+Foam is licensed under the [MIT license](license).
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[graph-visualisation]: features/graph-visualisation.md "Graph Visualisation"
-[backlinking]: features/backlinking.md "Backlinking"
-[recommended-extensions]: recommended-extensions.md "Recommended Extensions"
-[recipes]: recipes/recipes.md "Recipes"
-[frequently-asked-questions]: frequently-asked-questions.md "Frequently Asked Questions"
-[principles]: principles.md "Principles"
-[contribution-guide]: contribution-guide.md "Contribution Guide"
+[graph-visualisation]: graph-visualisation "Graph visualisation"
+[backlinking]: backlinking "Backlinking"
+[recommended-extensions]: recommended-extensions "Recommended Extensions"
+[recipes]: recipes "Recipes"
+[frequently-asked-questions]: frequently-asked-questions "Frequently Asked Questions"
+[known-issues]: known-issues "Known Issues"
+[roadmap]: roadmap "Roadmap"
+[principles]: principles "Principles"
+[contribution-guide]: contribution-guide "Contribution Guide"
 [//end]: # "Autogenerated link references"

docs/katex-math-rendering.md

@@ -1,12 +1,12 @@
 # Katex Math Rendering
 
-Apart from using the method mentioned in [[math-support-with-mathjax]], 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.
+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 [[publish-to-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 [[publish-to-vercel]] first.
+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 [[publish-to-vercel]].
+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
 
@@ -53,6 +53,6 @@ You may have noticed that we only made modifications to the template `_layouts/p
 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-with-mathjax]: math-support-with-mathjax.md "Math Support"
-[publish-to-vercel]: publish-to-vercel.md "Publish to Vercel"
+[math-support]: math-support "Math Support"
+[vercel]: vercel "Vercel"
 [//end]: # "Autogenerated link references"

docs/key-bindings.md

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

docs/known-issues.md

@@ -0,0 +1,15 @@
+# Known Issues
+
+- [ ] Aggressive autocompletion in Markdown files. You can turn `editor.quickSuggestions` off in [.vscode/settings.json].
+- [ ] Reference link lists have multiple issues ([Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode))
+  - [ ] Reference lists don't update in the background when other files are changed
+  - [ ] Notes don't get removed from reference lists when notes are deleted/renamed
+    - [ ] Workaround: Restart VS Code
+  - [ ] Links are case-sensitive (should not be)
+- [x] ~~[[graph-visualisation]] does not detect with wiki-links ([Markdown Links](https://marketplace.visualstudio.com/items?itemName=tchayen.markdown-links))~~
+- [x] ~~wiki-links aren't searchable on website~~
+  - [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"
+[//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 "Wiki Links"
+[recommended-extensions]: recommended-extensions "Recommended Extensions"
+[foam-file-format]: foam-file-format "Foam File Format"
+[principles]: principles "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,11 +68,10 @@ 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):
-
     ```typescript
     // settings json
     // see enumerations below for explanations on values
@@ -112,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
@@ -121,7 +120,6 @@ The potential solution:
     }
 
     ```
-
   - With Foam repo, just use edit-time link reference definitions with '.md' extension - this makes the links work in the Github UI
   - Have publish target defined for Github pages, that doesn't use '.md' extension, but still has the link reference definitions. Generate the output into gh-pages branch (or separate repo) with automation.
     - This naturally requires first removing the existing link reference definitions during the build
@@ -137,7 +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.md "Wiki Links"
-[link-reference-definitions]: ../features/link-reference-definitions.md "Link Reference Definitions"
-[backlinking]: ../features/backlinking.md "Backlinking"
+[wiki-links]: wiki-links "Wiki Links"
+[link-reference-definitions]: link-reference-definitions "Link Reference Definitions"
+[backlinking]: backlinking "Backlinking"
 [//end]: # "Autogenerated link references"

docs/link-reference-definitions.md

@@ -7,20 +7,16 @@ When you use `[[wiki-links]]`, the [foam-vscode](https://github.com/foambubble/f
 ## Example
 
 The following example:
-
   ```md
   - [[wiki-links]]
   - [[github-pages]]
   ```
-
 ...generates the following link reference definitions to the bottom of the file:
-
   ```md
   [wiki-links]: wiki-links "Wiki Links"
   [github-pages]: github-pages "Github Pages"
   ```
-
-You can open the [raw markdown](https://foambubble.github.io/foam/features/link-reference-definitions.md) to see them at the bottom of this file
+You can open the [raw markdown](https://raw.githubusercontent.com/foambubble/foam/master/foam-file-format.md) to see them at the bottom of this file
 
 ## Specification
 
@@ -33,22 +29,21 @@ The three components of a link reference definition are `[link-label]: link-targ
 
 ## Configuration
 
-You can choose to generate link reference definitions with or without file extensions, depending on the target, or to disable the generation altogether. As a rule of thumb:
+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.
+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"`
-- `"foam.edit.linkReferenceDefinitions": "off"`
 
 ### Ignoring files
 
-Sometimes, you may want to ignore certain files or folders, so that Foam doesn't generate link reference definitions to them.
+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.
 
@@ -63,16 +58,16 @@ You can ignore the `_site` directory by adding the following to your `.vscode/se
   },
 ```
 
-After changing the setting in your workspace, you can run the [[workspace-janitor]] command to convert all existing definitions.
+After changing the setting in your workspace, you can run the [[workspace-janitor]] command to convert all existing definitions. 
 
-[[todo]] _Implement a `foam.eclude
+[[Todo]] _Implement a `foam.eclude
 
 ## Future improvements
 
 See [[link-reference-definition-improvements]] for further discussion on current problems and potential solutions.
 
+
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[workspace-janitor]: workspace-janitor.md "Janitor"
-[todo]: ../dev/todo.md "Todo"
-[link-reference-definition-improvements]: ../dev/link-reference-definition-improvements.md "Link Reference Definition Improvements"
+[workspace-janitor]: workspace-janitor "Janitor"
+[link-reference-definition-improvements]: link-reference-definition-improvements "Link Reference Definition Improvements"
 [//end]: # "Autogenerated link references"

docs/linking-between-published-workspaces.md

@@ -0,0 +1,10 @@
+# Linking between Published Workspaces (stub)
+
+**[[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"

docs/make-backlinks-more-prominent.md

@@ -2,11 +2,9 @@
 
 One of the most most common early feature requests in Foam is to make the Markdown Notes Backlinks Explorer more prominent.
 
-This #recipe shows you how to do that.
-
 At the moment, you can drag the explorer pane to your bottom pane, and either show it side by side with another pane, or have take the full width of the editor:
 
-![Demo of dragging and dropping the pane](../assets/images/demo-backlinks-explorer.gif)
+![Demo of dragging and dropping the pane](assets/images/demo-backlinks-explorer.gif)
 
 In the future we'll want to improve this feature by
 
@@ -16,6 +14,11 @@ In the future we'll want to improve this feature by
 - Make back links editable using [VS Code Search Editors](https://code.visualstudio.com/updates/v1_43#_search-editors)
   - [Suggested by @Jash on Discord](https://discordapp.com/channels/729975036148056075/729978910363746315/730999992419876956)
 
+
+
+
+
+
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[materialized-backlinks]: ../dev/materialized-backlinks.md "Materialized Backlinks (stub)"
-[//end]: # "Autogenerated link references"
+[materialized-backlinks]: materialized-backlinks "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.md "Todo"
-[roadmap]: roadmap.md "Roadmap"
-[//end]: # "Autogenerated link references"
+[todo]: todo "Todo"
+[roadmap]: roadmap "Roadmap"
+[//end]: # "Autogenerated link references"

docs/math-support.md

@@ -18,9 +18,9 @@ Published Foam pages don't support math formulas by default. To enable this feat
 </script>
 ```
 
-This approach uses the [MathJax](https://www.mathjax.org/) library to render anything delimited by ```$``` (customizable in the snippet above) pairs to inline math and ```$$``` to blocks of math (like a html div tag) using with the AMS-LaTeX dialect embedded within MathJax.
+This approach uses the [MathJax](https://www.mathjax.org/) library to render anything delimited by ```$``` (customizable in the snippet above) pairs to inline math and ```$$``` to blocks of math (like a html div tag) using with the AMS-LaTeX dialect embedded within MathJax. 
 
-Example of inline math using `$...$`:
+Example of inline math using `$...$`: 
 
 `$e^{i \pi}+1=0$`, becomes $e^{i \pi}+1=0$
 
@@ -30,7 +30,7 @@ Example of a math block using `$$...$$`:
 
 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}|}} $$
+$$ 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
 

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

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

@@ -13,7 +13,6 @@ Present: @jevakallio, @riccardoferretti
 
 - Land work to master
   - Create a foam-core package
-
   -
 
 ### Open questions
@@ -123,6 +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]: ../dev/todo.md "Todo"
-[Index]: ../index.md "Foam"
+[todo]: ../todo "Todo"
+[Index]: ../index "Foam"
 [//end]: # "Autogenerated link references"

docs/migrating-from-obsidian.md

@@ -1,10 +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]: ../dev/todo.md "Todo"
-[roadmap]: ../dev/roadmap.md "Roadmap"
-[//end]: # "Autogenerated link references"
+[todo]: todo "Todo"
+[roadmap]: roadmap "Roadmap"
+[//end]: # "Autogenerated link references"

docs/migrating-from-onenote.md

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

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

docs/mobile-apps.md

@@ -1,17 +1,16 @@
-# Take notes on mobile phones
+# Mobile Apps
 
-This #recipe offers solutions to taking Foam notes on the go.
+We must always ask ourselves, [[build-vs-assemble]]. 
 
-For the time being we have decided to not build a mobile app, but rely on third parties (see [[build-vs-assemble]]).
+This Roadmap item discusses existing assembled solutions, and some thoughts on future Foam mobile experience.
 
-The most promising options are:
+## Existing solutions
 
 ### [GitJournal](https://gitjournal.io/)
 
-Pros
-
+#### 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
@@ -19,29 +18,13 @@ Pros
 - Supports Backlinks
 - Developer is happy to prioritize Foam compatibility
 
-Cons
-
+#### Cons
 - 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.
 
 Verdict: Good. By far best effort/outcome ratio would be to help improve GitJournal rather than building a [bespoke mobile app](#bespoke-mobile-app-for-foam).
 
-### GitHub Codespaces
-
-Pros
-
-- Works out of the box just like the desktop app
-
-Cons
-
-- not generally available quite yet
-- [Pricing](https://docs.github.com/en/free-pro-team@latest/github/developing-online-with-codespaces/about-billing-for-codespaces)
-
-For a quick demo, see <https://www.youtube.com/watch?v=KI5m4Uy8_4I>.
-
-Verdict: Good. Pricing should be reasonable for taking notes on the fly. Harder to assess for people who would constantly use Foam from mobile phone.
-
 ## Bespoke mobile app for Foam
 
 Given we already have a solution, why would we spend time and effort building a bespoke mobile app?
@@ -56,9 +39,11 @@ If such an app was worth building, it would have to have the following features:
 - Ability to search and navigate forward links and back links (onlly in paid GitJournal version)
 - Killer feature that makes it the best note taking tool for Foam (?)
 
-Given the effort vs reward ratio, it's a low priority for core team, but if someone wants to work on this, we can provide support! Talk to us on the #mobile-apps channel on [Foam Discord](https://foambubble.github.io/join-discord/w).
+Given the effort vs reward ratio, it's a low priority for core team, but if someone wants to work on this, we can provide support! Talk to us on the #mobile-apps channel on [Foam Discord](https://discord.gg/rtdZKgj).
+
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[build-vs-assemble]: ../dev/build-vs-assemble.md "Build vs Assemble"
-[workspace-janitor]: ../features/workspace-janitor.md "Janitor"
+[build-vs-assemble]: build-vs-assemble "Build vs Assemble"
+[wiki-links]: wiki-links "Wiki Links"
+[workspace-janitor]: workspace-janitor "Janitor"
 [//end]: # "Autogenerated link references"

docs/note-macros.md

@@ -1,6 +1,6 @@
 # Custom Note Macros
 
-This #recipe allows you to create 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
 
@@ -56,3 +56,8 @@ in `keybindings.json` (Code|File > Preferences > Keyboard Shortcuts) add binding
 If you have any issues or questions please look at the [README.md](https://github.com/kneely/note-macros#note-macros) on the [note-macros](https://github.com/kneely/note-macros) GitHub.
 
 If you run into any issues that are not fixed by referring to the README or feature requests please open an [issue](https://github.com/kneely/note-macros/issues).
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[daily-notes]: daily-notes "Daily notes"
+[//end]: # "Autogenerated link references"
+

docs/officially-support-alternative-templates.md

@@ -0,0 +1,13 @@
+# Officially Support Alternative Templates (stub)
+
+**[[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).
+
+## Notes
+
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[todo]: todo "Todo"
+[roadmap]: roadmap "Roadmap"
+[//end]: # "Autogenerated link references"

docs/packaged-desktop-app.md

@@ -0,0 +1,11 @@
+# Packaged Desktop App (stub)
+
+**[[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"

docs/predefined-user-snippets.md

@@ -1,6 +1,6 @@
 # Pre-defined User Snippets
 
-This #recipe allows us to introduce Roam style commands to Foam, by using [VS Code Snippets](https://code.visualstudio.com/docs/editor/userdefinedsnippets). Consider the below snippets:
+Having pre-defined user snippets would enable us to introduce Roam style commands to Foam. Consider the below snippets:
 
 ```json
 {
@@ -24,7 +24,7 @@ This #recipe allows us to introduce Roam style commands to Foam, by using [VS Co
 ```
 
 Which would look like:
-![GIF demonstrating User Snippets](../assets/images/snippets.gif)
+![GIF demonstrating User Snippets](./assets/images/snippets.gif)
 
 Using snippets enables Foam users to add [[custom-snippets]] themselves so they live alongside the first-class `/commands`.
 
@@ -44,10 +44,16 @@ Some markdown syntax is difficult for users who have never authored markdown bef
 ```
 
 We could provide snippets that expand out into the associated markdown syntax, like in the below GIF:
-![GIF demonstrating markdown snippets](../assets/images/markdown-snippets.gif)
+![GIF demonstrating markdown snippets](./assets/images/markdown-snippets.gif)
 
 The JSON for these snippets can be found [here](https://github.com/foambubble/foam/pull/192#issuecomment-666736270).
 
-[//begin]: # "Autogenerated link references for markdown compatibility"
-[custom-snippets]: ../features/custom-snippets.md "Adding Custom Snippets"
-[//end]: # "Autogenerated link references"
+[//begin]: # 'Autogenerated link references for markdown compatibility'
+[custom-snippets]: custom-snippets 'Adding Custom Snippets'
+[//end]: # 'Autogenerated link references'
+[//begin]: # 'Autogenerated link references for markdown compatibility'
+[custom-snippets]: custom-snippets 'Adding Custom Snippets'
+[//end]: # 'Autogenerated link references'
+[//begin]: # 'Autogenerated link references for markdown compatibility'
+[custom-snippets]: custom-snippets 'Adding Custom Snippets'
+[//end]: # 'Autogenerated link references'

docs/principles.md

@@ -30,14 +30,14 @@ This principle may seem like it contradicts [Foam wants you to own your thoughts
 > [...] environments that build walls around good ideas tend to be less innovative in the long run than more open-ended environments. Good ideas may not want to be free, but they do want to connect, fuse, recombine. —_Steven Johnson, Where Good Ideas Come From_
 
 - **Foam should make it easy to publish your knowledge graph.** With zero code, you should be able to make your graph public to the world. You should have full control over how it looks, feels, and where it's hosted.
-- **Foam should make it easy to collaborate on ideas.** Foam should allow you to work closely together with your collaborators, and accept feedback, input and improvements from others.
-- **Foam should make it easy to publish what you choose.** Foam should double as a low-barrier blog/publishing platform, so you can share content to an audience without inviting them to intrude on your entire workspace.
+- **Foam should make it easy to collaborate on ideas.** Foam should allow you to work closely together with your collaborators, and accept feedback, input and improvements from others. _(Work in progress, see [[roadmap]]_.
+- **Foam should make it easy to publish what you choose.** Foam should double as a low-barrier blog/publishing platform, so you can share content to an audience without inviting them to intrude on your entire workspace. _(Work in progress, see [[roadmap]]_.
 
 ## 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](https://github.com/foambubble/foam). See also: [[contribution-guide]].
-- **Foam is open source.** Feel free to fork it, improve it and remix it. Just don't sell it, as per our [license](LICENSE.txt).
+- **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).
 
 ## Foam is for hackers, not only for programmers
@@ -49,8 +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"
-[recipes]: recipes/recipes.md "Recipes"
-[recommended-extensions]: recommended-extensions.md "Recommended Extensions"
-[contribution-guide]: contribution-guide.md "Contribution Guide"
-[code-of-conduct]: code-of-conduct.md "Code of Conduct"
+[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"
 [//end]: # "Autogenerated link references"