v0.22.2

* Show note block in panels on hover preview
* Show tag references within tag explorer
* Improved structure of view related commands
* Refactored grouped resources tree data provider and added support for placeholders filter
  - Consolidated the naming of the accessory commands
  - Consolidated the management of the state/context related to grouping
  - Removed group-by config, simply restore the last used setting
  - Added filter to only show the placeholders related to the open file
* Refreshing placeholders when changing editor and filtering by active document

.all-contributorsrc

@@ -175,7 +175,8 @@
       "profile": "https://anku.netlify.com/",
       "contributions": [
         "doc",
-        "test"
+        "test",
+        "code"
       ]
     },
     {
@@ -211,7 +212,8 @@
       "avatar_url": "https://avatars3.githubusercontent.com/u/8980971?v=4",
       "profile": "https://sanketdg.github.io",
       "contributions": [
-        "doc"
+        "doc",
+        "code"
       ]
     },
     {
@@ -241,6 +243,785 @@
         "code",
         "doc"
       ]
+    },
+    {
+      "login": "chirag-singhal",
+      "name": "CHIRAG SINGHAL",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/42653703?v=4",
+      "profile": "https://github.com/chirag-singhal",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "lostintangent",
+      "name": "Jonathan Carter",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/116461?v=4",
+      "profile": "https://github.com/lostintangent",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "synesthesia",
+      "name": "Julian Elve",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/181399?v=4",
+      "profile": "https://www.synesthesia.co.uk",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "thomaskoppelaar",
+      "name": "Thomas Koppelaar",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/36331365?v=4",
+      "profile": "https://github.com/thomaskoppelaar",
+      "contributions": [
+        "question",
+        "code",
+        "userTesting"
+      ]
+    },
+    {
+      "login": "MehraAkshay",
+      "name": "Akshay",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/8671497?v=4",
+      "profile": "http://www.akshaymehra.com",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "johnlindquist",
+      "name": "John Lindquist",
+      "avatar_url": "https://avatars0.githubusercontent.com/u/36073?v=4",
+      "profile": "http://johnlindquist.com",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "epicfaace",
+      "name": "Ashwin Ramaswami",
+      "avatar_url": "https://avatars2.githubusercontent.com/u/1689183?v=4",
+      "profile": "https://ashwin.run/",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "Klaudioz",
+      "name": "Claudio Canales",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/632625?v=4",
+      "profile": "https://github.com/Klaudioz",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "vitaly-pevgonen",
+      "name": "vitaly-pevgonen",
+      "avatar_url": "https://avatars0.githubusercontent.com/u/6272738?v=4",
+      "profile": "https://github.com/vitaly-pevgonen",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "dshemetov",
+      "name": "Dmitry Shemetov",
+      "avatar_url": "https://avatars0.githubusercontent.com/u/1810426?v=4",
+      "profile": "https://dshemetov.github.io",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "hooncp",
+      "name": "hooncp",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/48883554?v=4",
+      "profile": "https://github.com/hooncp",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "martinlaws",
+      "name": "Martin Laws",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/13721239?v=4",
+      "profile": "http://rt-canada.ca",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "sksmith",
+      "name": "Sean K Smith",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/2085441?v=4",
+      "profile": "http://seanksmith.me",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "kneely",
+      "name": "Kevin Neely",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/37545028?v=4",
+      "profile": "https://www.linkedin.com/in/kevin-neely/",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "ariefrahmansyah",
+      "name": "Arief Rahmansyah",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/8122852?v=4",
+      "profile": "https://ariefrahmansyah.dev",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "vHanda",
+      "name": "Vishesh Handa",
+      "avatar_url": "https://avatars2.githubusercontent.com/u/426467?v=4",
+      "profile": "http://vhanda.in",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "HeroicHitesh",
+      "name": "Hitesh Kumar",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/37622734?v=4",
+      "profile": "http://www.linkedin.com/in/heroichitesh",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "spencerwooo",
+      "name": "Spencer Woo",
+      "avatar_url": "https://avatars2.githubusercontent.com/u/32114380?v=4",
+      "profile": "https://spencerwoo.com",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "ingalless",
+      "name": "ingalless",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/22981941?v=4",
+      "profile": "https://ingalless.com",
+      "contributions": [
+        "code",
+        "doc"
+      ]
+    },
+    {
+      "login": "jmg-duarte",
+      "name": "José Duarte",
+      "avatar_url": "https://avatars2.githubusercontent.com/u/15343819?v=4",
+      "profile": "http://jmg-duarte.github.io",
+      "contributions": [
+        "code",
+        "doc"
+      ]
+    },
+    {
+      "login": "yenly",
+      "name": "Yenly",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/6759658?v=4",
+      "profile": "https://www.yenly.wtf",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "hikerpig",
+      "name": "hikerpig",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/2259688?v=4",
+      "profile": "https://www.hikerpig.cn",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "Sigfried",
+      "name": "Sigfried Gold",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/1586931?v=4",
+      "profile": "http://sigfried.org",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "tristansokol",
+      "name": "Tristan Sokol",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/867661?v=4",
+      "profile": "http://www.tristansokol.com",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "umbrellait-danil-rodin",
+      "name": "Danil Rodin",
+      "avatar_url": "https://avatars0.githubusercontent.com/u/49779373?v=4",
+      "profile": "https://umbrellait.com",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "scott-joe",
+      "name": "Scott Williams",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/2026866?v=4",
+      "profile": "https://www.linkedin.com/in/scottjoewilliams/",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "Jackiexiao",
+      "name": "jackiexiao",
+      "avatar_url": "https://avatars2.githubusercontent.com/u/18050469?v=4",
+      "profile": "https://jackiexiao.github.io/blog",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "jbn",
+      "name": "John B Nelson",
+      "avatar_url": "https://avatars3.githubusercontent.com/u/78835?v=4",
+      "profile": "https://generativist.substack.com/",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "asifm",
+      "name": "Asif Mehedi",
+      "avatar_url": "https://avatars2.githubusercontent.com/u/3958387?v=4",
+      "profile": "https://github.com/asifm",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "litanlitudan",
+      "name": "Tan Li",
+      "avatar_url": "https://avatars2.githubusercontent.com/u/4970420?v=4",
+      "profile": "https://github.com/litanlitudan",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "ShaunaGordon",
+      "name": "Shauna Gordon",
+      "avatar_url": "https://avatars1.githubusercontent.com/u/579361?v=4",
+      "profile": "http://shaunagordon.com",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "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"
+      ]
+    },
+    {
+      "login": "Pearcekieser",
+      "name": "Pearcekieser",
+      "avatar_url": "https://avatars.githubusercontent.com/u/5055971?v=4",
+      "profile": "https://github.com/Pearcekieser",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "theowenyoung",
+      "name": "Owen Young",
+      "avatar_url": "https://avatars.githubusercontent.com/u/62473795?v=4",
+      "profile": "https://github.com/theowenyoung",
+      "contributions": [
+        "doc",
+        "content"
+      ]
+    },
+    {
+      "login": "ksprashu",
+      "name": "Prashanth Subrahmanyam",
+      "avatar_url": "https://avatars.githubusercontent.com/u/476729?v=4",
+      "profile": "http://www.prashu.com",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "JonasSprenger",
+      "name": "Jonas SPRENGER",
+      "avatar_url": "https://avatars.githubusercontent.com/u/25108895?v=4",
+      "profile": "https://github.com/JonasSprenger",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "Laptop765",
+      "name": "Paul",
+      "avatar_url": "https://avatars.githubusercontent.com/u/1468359?v=4",
+      "profile": "https://github.com/Laptop765",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "eltociear",
+      "name": "Ikko Ashimine",
+      "avatar_url": "https://avatars.githubusercontent.com/u/22633385?v=4",
+      "profile": "https://bandism.net/",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "memeplex",
+      "name": "memeplex",
+      "avatar_url": "https://avatars.githubusercontent.com/u/2845433?v=4",
+      "profile": "https://github.com/memeplex",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "AndreiD049",
+      "name": "AndreiD049",
+      "avatar_url": "https://avatars.githubusercontent.com/u/52671223?v=4",
+      "profile": "https://github.com/AndreiD049",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "iam-yan",
+      "name": "Yan",
+      "avatar_url": "https://avatars.githubusercontent.com/u/48427014?v=4",
+      "profile": "https://github.com/iam-yan",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "jimt",
+      "name": "Jim Tittsler",
+      "avatar_url": "https://avatars.githubusercontent.com/u/180326?v=4",
+      "profile": "https://WikiEducator.org/User:JimTittsler",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "MalcolmMielle",
+      "name": "Malcolm Mielle",
+      "avatar_url": "https://avatars.githubusercontent.com/u/4457840?v=4",
+      "profile": "http://malcolmmielle.wordpress.com/",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "veesar",
+      "name": "Veesar",
+      "avatar_url": "https://avatars.githubusercontent.com/u/74916913?v=4",
+      "profile": "https://snippets.page/",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "bentongxyz",
+      "name": "bentongxyz",
+      "avatar_url": "https://avatars.githubusercontent.com/u/60358804?v=4",
+      "profile": "https://github.com/bentongxyz",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "techCarpenter",
+      "name": "Brian DeVries",
+      "avatar_url": "https://avatars.githubusercontent.com/u/42778030?v=4",
+      "profile": "https://brianjdevries.com",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "cliffordfajardo",
+      "name": "Clifford Fajardo ",
+      "avatar_url": "https://avatars.githubusercontent.com/u/6743796?v=4",
+      "profile": "http://Cliffordfajardo.com",
+      "contributions": [
+        "tool"
+      ]
+    },
+    {
+      "login": "chrisUsick",
+      "name": "Chris Usick",
+      "avatar_url": "https://avatars.githubusercontent.com/u/6589365?v=4",
+      "profile": "http://cu-dev.ca",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "josephdecock",
+      "name": "Joe DeCock",
+      "avatar_url": "https://avatars.githubusercontent.com/u/1145533?v=4",
+      "profile": "https://github.com/josephdecock",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "drewtyler",
+      "name": "Drew Tyler",
+      "avatar_url": "https://avatars.githubusercontent.com/u/5640816?v=4",
+      "profile": "http://www.drewtyler.com",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "Lauviah0622",
+      "name": "Lauviah0622",
+      "avatar_url": "https://avatars.githubusercontent.com/u/43416399?v=4",
+      "profile": "https://github.com/Lauviah0622",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "joshdover",
+      "name": "Josh Dover",
+      "avatar_url": "https://avatars.githubusercontent.com/u/1813008?v=4",
+      "profile": "https://www.elastic.co/elastic-agent",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "phelma",
+      "name": "Phil Helm",
+      "avatar_url": "https://avatars.githubusercontent.com/u/4057948?v=4",
+      "profile": "http://phelm.co.uk",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "lingyv-li",
+      "name": "Larry Li",
+      "avatar_url": "https://avatars.githubusercontent.com/u/8937944?v=4",
+      "profile": "https://github.com/lingyv-li",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "infogulch",
+      "name": "Joe Taber",
+      "avatar_url": "https://avatars.githubusercontent.com/u/133882?v=4",
+      "profile": "https://github.com/infogulch",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "readingsnail",
+      "name": "Woosuk Park",
+      "avatar_url": "https://avatars.githubusercontent.com/u/1904967?v=4",
+      "profile": "https://www.readingsnail.pe.kr",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "dmurph",
+      "name": "Daniel Murphy",
+      "avatar_url": "https://avatars.githubusercontent.com/u/294026?v=4",
+      "profile": "http://www.dmurph.com",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "Dominic-DallOsto",
+      "name": "Dominic D",
+      "avatar_url": "https://avatars.githubusercontent.com/u/26859884?v=4",
+      "profile": "https://github.com/Dominic-DallOsto",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "elgirafo",
+      "name": "luca",
+      "avatar_url": "https://avatars.githubusercontent.com/u/80516439?v=4",
+      "profile": "http://elgirafo.xyz",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "Lloyd-Jackman-UKPL",
+      "name": "Lloyd Jackman",
+      "avatar_url": "https://avatars.githubusercontent.com/u/55206370?v=4",
+      "profile": "https://github.com/Lloyd-Jackman-UKPL",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "sn3akiwhizper",
+      "name": "sn3akiwhizper",
+      "avatar_url": "https://avatars.githubusercontent.com/u/102705294?v=4",
+      "profile": "http://sn3akiwhizper.github.io",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "jonathanpberger",
+      "name": "jonathan berger",
+      "avatar_url": "https://avatars.githubusercontent.com/u/41085?v=4",
+      "profile": "http://jonathanpberger.com/",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "badsketch",
+      "name": "Daniel Wang",
+      "avatar_url": "https://avatars.githubusercontent.com/u/8953212?v=4",
+      "profile": "https://github.com/badsketch",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "tlylt",
+      "name": "Liu YongLiang",
+      "avatar_url": "https://avatars.githubusercontent.com/u/41845017?v=4",
+      "profile": "http://yongliangliu.com",
+      "contributions": [
+        "doc"
+      ]
+    },
+    {
+      "login": "Skakerman",
+      "name": "Scott Akerman",
+      "avatar_url": "https://avatars.githubusercontent.com/u/15224439?v=4",
+      "profile": "http://scottakerman.com",
+      "contributions": [
+        "code"
+      ]
+    },
+    {
+      "login": "jimgraham",
+      "name": "Jim Graham",
+      "avatar_url": "https://avatars.githubusercontent.com/u/430293?v=4",
+      "profile": "http://www.jim-graham.net/",
+      "contributions": [
+        "code"
+      ]
     }
   ],
   "contributorsPerLine": 7,

.eslintrc.json

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

.github/ISSUE_TEMPLATE/bug_report.yml

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

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+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_request.yml

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

.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    branches:
+      - master
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-22.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v1
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+      - name: Restore Dependencies and VS Code test instance
+        uses: actions/cache@v3
+        with:
+          path: |
+            node_modules
+            */*/node_modules
+            packages/foam-vscode/.vscode-test
+          key: ${{ runner.os }}-${{ hashFiles('**/yarn.lock', 'packages/foam-vscode/src/test/run-tests.ts') }}-${{ secrets.CACHE_VERSION }}
+      - name: Install Dependencies
+        run: yarn
+      - name: Check Lint Rules
+        run: yarn lint
+
+  test:
+    name: Build and Test
+    strategy:
+      matrix:
+        os: [macos-12, ubuntu-22.04, windows-2022]
+    runs-on: ${{ matrix.os }}
+    env:
+      OS: ${{ matrix.os }}
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v1
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+      - name: Restore Dependencies and VS Code test instance
+        uses: actions/cache@v3
+        with:
+          path: |
+            node_modules
+            */*/node_modules
+            packages/foam-vscode/.vscode-test
+          key: ${{ runner.os }}-${{ hashFiles('**/yarn.lock', 'packages/foam-vscode/src/test/run-tests.ts') }}-${{ secrets.CACHE_VERSION }}
+      - name: Install Dependencies
+        run: yarn
+      - name: Build Packages
+        run: yarn build
+      - name: Run Tests
+        uses: GabrielBB/xvfb-action@v1.4
+        with:
+          run: yarn test --stream

.github/workflows/update-docs.yml

@@ -0,0 +1,43 @@
+name: Update Docs
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - docs/user/**/*
+  workflow_dispatch:
+
+jobs:
+  update-docs:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          repository: foambubble/foam-template
+          path: foam-template
+      - uses: actions/checkout@v3
+        with:
+          path: foam
+      - name: Copy and fixup user docs files          
+        id: copy
+        run: |
+          rm -r foam-template/docs
+          cp -r foam/docs/user foam-template/docs
+
+          # Strip autogenerated wikileaks references because
+          # they are not an appropriate default user experience.
+          (cd foam-template/docs; sed -i '/\[\/\/begin\]/,/\[\/\/end\]/d' $(find . -type f -name \*.md))
+
+          # Set the commit message format
+          echo "message=Docs sync @ $(cd foam; git log --pretty='format:%h %s')" >> $GITHUB_OUTPUT
+      - uses: peter-evans/create-pull-request@v4
+        with:
+          token: ${{ secrets.FOAM_DOCS_SYNC_TOKEN }}
+          path: foam-template
+          commit-message: ${{ steps.copy.outputs.message }}
+          branch: bot/foam-docs-sync
+          delete-branch: true
+          title: Sync docs from foam
+          body: Copy docs from main foam repo

.gitignore

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

.vscode/launch.json

@@ -3,47 +3,51 @@
 // Hover to view descriptions of existing attributes.
 // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
 {
-	"version": "0.2.0",
-	"configurations": [
-		{
-             // This task is also defined in packages/foam-vscode/.vscode/launch.json
-             // for when running separately outside of the monorepo environment
-			"name": "Run Extension",
-            "type": "extensionHost",
-			"request": "launch",
-			"runtimeExecutable": "${execPath}",
-			"args": [
-				"--extensionDevelopmentPath=${workspaceFolder}/packages/foam-vscode"
-			],
-			"outFiles": [
-				"${workspaceFolder}/packages/foam-vscode/out/**/*.js"
-			],
-			"preLaunchTask": "Build foam-vscode"
-		},
-		{
-            // This task is also defined in packages/foam-vscode/.vscode/launch.json
-            // for when running separately outside of the monorepo environment
-			"name": "Extension Tests",
-			"type": "extensionHost",
-			"request": "launch",
-			"runtimeExecutable": "${execPath}",
-			"args": [
-				"--extensionDevelopmentPath=${workspaceFolder}/packages/foam-vscode",
-				"--extensionTestsPath=${workspaceFolder}/packages/foam-vscode/out/test/suite/index"
-			],
-			"outFiles": [
-				"${workspaceFolder}/packages/foam-vscode/out/test/**/*.js"
-			],
-			"preLaunchTask": "Build foam-vscode"
-		},
-		{
-			"type": "node",
-			"request": "launch",
-			"name": "Workspace Manager tests",
-			"program": "${workspaceFolder}/node_modules/tsdx/dist/index.js",
-			"args": ["test"],
-			"cwd": "${workspaceFolder}/packages/foam-core",
-			"internalConsoleOptions": "openOnSessionStart"
-		}
-	]
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug Jest Tests",
+      "type": "extensionHost",
+      "request": "launch",
+      "args": [
+        "${workspaceFolder}/packages/foam-vscode/.test-workspace",
+        "--disable-extensions",
+        "--disable-workspace-trust",
+        "--extensionDevelopmentPath=${workspaceFolder}/packages/foam-vscode",
+        "--extensionTestsPath=${workspaceFolder}/packages/foam-vscode/out/test/suite"
+      ],
+      "outFiles": [
+        "${workspaceFolder}/packages/foam-vscode/out/**/*.js"
+      ],
+      "preLaunchTask": "${defaultBuildTask}"
+    },
+    {
+      "name": "Run VSCode Extension",
+      "type": "extensionHost",
+      "request": "launch",
+      "runtimeExecutable": "${execPath}",
+      "args": [
+        "--extensionDevelopmentPath=${workspaceFolder}/packages/foam-vscode"
+      ],
+      "outFiles": [
+        "${workspaceFolder}/packages/foam-vscode/out/**/*.js"
+      ],
+      "preLaunchTask": "${defaultBuildTask}"
+    },
+    {
+      "type": "node",
+      "name": "vscode-jest-tests",
+      "request": "launch",
+      "console": "integratedTerminal",
+      "internalConsoleOptions": "neverOpen",
+      "disableOptimisticBPs": true,
+      "cwd": "${workspaceFolder}/packages/foam-vscode",
+      "runtimeExecutable": "yarn",
+      "args": [
+        "jest",
+        "--runInBand",
+        "--watchAll=false"
+      ]
+    }
+  ]
 }

.vscode/settings.json

@@ -1,15 +1,35 @@
 // 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"
-}
+  "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.edit.linkReferenceDefinitions": "withExtensions",
+  "foam.files.ignore": [
+    "**/.vscode/**/*",
+    "**/_layouts/**/*",
+    "**/_site/**/*",
+    "**/node_modules/**/*",
+    "packages/**/*"
+  ],
+  "editor.tabSize": 2,
+  "editor.formatOnSave": true,
+  "editor.formatOnSaveMode": "file",
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "jest.autoRun": "off",
+  "jest.rootPath": "packages/foam-vscode",
+  "jest.jestCommandLine": "yarn jest",
+  "gitdoc.enabled": false,
+  "search.mode": "reuseEditor",
+  "[typescript]": {
+    "editor.defaultFormatter": "esbenp.prettier-vscode"
+  }
+}

.vscode/tasks.json

@@ -1,22 +1,31 @@
 // See https://go.microsoft.com/fwlink/?LinkId=733558
 // for the documentation about the tasks.json format
 {
-	"version": "2.0.0",
-	"tasks": [
-		{
-            // This task is also defined in packages/foam-vscode/.vscode/tasks.json
-            // for when running separately outside of the monorepo environment
-            "type": "npm",
-            "script": "watch",
-            "label": "Build foam-vscode",
-            "path": "packages/foam-vscode",
-            "problemMatcher": "$tsc-watch",
-			"isBackground": true,
-			"presentation": {
-				"reveal": "silent",
-				"revealProblems": "onProblem",
-				"focus": true
-			}
-		}
-	]
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "watch: foam-vscode",
+      "type": "npm",
+      "script": "watch",
+      "problemMatcher": "$tsc-watch",
+      "isBackground": true,
+      "presentation": {
+        "reveal": "always"
+      },
+      "group": {
+        "kind": "build",
+        "isDefault": true
+      }
+    },
+    {
+      "label": "test: all packages",
+      "type": "npm",
+      "script": "test",
+      "problemMatcher": [],
+      "group": {
+        "kind": "test",
+        "isDefault": true
+      }
+    }
+  ]
 }

.yarnrc

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

CONTRIBUTING.md

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

LICENSE

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

docs/.vscode/custom-tag-style.css

@@ -0,0 +1,4 @@
+.foam-tag{
+  color:#ffffff;
+  background-color: #000000;
+}

docs/.vscode/extensions.json

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

docs/.vscode/settings.json

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

docs/.vscode/spellright.dict

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

docs/404.md

@@ -0,0 +1,12 @@
+# 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/Achieving Greater Privacy and Security.md

@@ -0,0 +1,29 @@
+# Achieving Greater Privacy and Security
+
+Foam, at its heart and committed to in its [Principles](https://foambubble.github.io/foam/principles), allows the user to control their content in a flexible and non-prescriptive manner.  This extends to user preferences, or requirements depending on application and context, around both privacy and security.  One way that these use cases can be met is through the use of open-source and not-for-profit mechanisms in the user's workflow to provide a functional equivalence.
+
+Here are a few suggestions on increasing privacy and security when using Foam.
+## VS Codium: The Open Source build of VS Code 
+
+Foam is built upon VS Code, itself a Microsoft product built on top of an open source project.
+
+As can be found [here](https://github.com/Microsoft/vscode/issues/60#issuecomment-161792005) the **VS Code product itself is not fully open source**. This means that its inner workings are not fully transparent, facilitating the collection and distribution of your data, as specified in its [Privacy Statement](https://devblogs.microsoft.com/visualstudio/privacy/).  
+
+If you prefer a fully open source editor based on the same core of VS Code (and for most intents and purposes equivalent to it), you can try [VSCodium](https://github.com/VSCodium).  
+In its own introduction it is described as, "Binary releases of VS Code without MS branding/telemetry/licensing".  Installation packages are easily available across Windows, Unix and Linux (or you can build it from source!).
+Access to the VS Code marketplace of add-ons remains in place, including the Foam extension.
+
+The change you will notice in using VS Code versus VS Codium - simply speaking, none. It is, in just about every way you will think of, the same IDE, just without the Microsoft proprietary licence and telemetry.  Your Foam experience will remain as smooth and productive as before the change.
+
+## Version Control and Replication
+
+In Foam's [Getting Started](https://foambubble.github.io/foam/#getting-started) section, the set up describes how to set up your notes with a GitHub repository in using the template provided.  Doing so provides the user with the ability to see commits made and therefore versions of their notes, allows the user to work across devices or collaborate effectively with other users, and makes publishing to GitHub pages easy.
+It's important at the same time to point out the closed-source nature of GitHub, being owned by Microsoft.
+
+One alternative approach could be to use [GitLab](https://gitlab.com/), an open source alternative to GitHub.  Whilst it improves on the aspect of transparency, it does also collect usage details and sends your content across the internet.  
+And of course data is still stored in clear in the cloud, making it susceptible to hacks of the service.
+
+A more private approach would manage replication between devices and users with a serverless mechanism like [Syncthing](https://syncthing.net).  Its continuous synchronisation means that changes in files are seen almost instantly and offers the choice of using only local network connections or securely using public relays when a local network connection is unavailable.  This means that having two connected devices online will have them synchronised, but it is worth noting that the continuous synchronisation could result in corruption if two users worked on the same file simultaneously and it doesn't offer the same kind of version control that git does (though versioning support can be found and is described [here](https://docs.syncthing.net/users/versioning.html)).  It is also not advisable to attempt to use a continuous synchronisation tool to sync local git repositories as the risk of corruption on the git files is high (see [here](https://forum.syncthing.net/t/can-syncthing-reliably-sync-local-git-repos-not-github/8404/18)).
+
+If you need the version control and collaboration, but do not want to compromise on your privacy, the best course of action is to host the open source GitLab  server software yourself.  The steps (well described [here](https://www.techrepublic.com/article/how-to-set-up-a-gitlab-server-and-host-your-own-git-repositories/)) are not especially complex by any means and can be used exclusively on the local network, if required, offering a rich experience of "built-in version control, issue tracking, code review, CI/CD, and more", according to its website, [GitLab / GitLab Community Edition · GitLab](https://gitlab.com/rluna-gitlab/gitlab-ce).
+

docs/Gemfile

@@ -0,0 +1,37 @@
+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

@@ -0,0 +1,272 @@
+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

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

docs/_layouts/foam.html

@@ -0,0 +1,52 @@
+---
+layout: default
+---
+
+<script type="text/javascript">
+// NOTE: this should be in sync with the settings/usage in the vscode extension
+// atm it's just a wide superset of md extensions to cover a wide range of cases
+var MD_EXT = ['.md', '.markdown', '.mdx', '.mdown', '.mkdn', '.mkd', '.mdwn', '.mdtxt', '.mdtext', '.text', '.Rmd'];
+function normalizeMdLink(link) {
+  var url = new URL(link);
+  var mdFileExt = MD_EXT.find(ext => url.pathname.endsWith(ext));
+  if (mdFileExt) {
+    url.pathname = url.pathname.slice(0, mdFileExt.length * -1);
+  }
+  return url.toString();
+}
+
+window.addEventListener('DOMContentLoaded', (event) => {
+  document
+    .querySelectorAll(".markdown-body a[title]:not([href^=http])")
+    .forEach((a) => {
+      // filter to only wikilinks
+      var prev = a.previousSibling;
+      var next = a.nextSibling;
+      if (
+        prev instanceof Text && prev.textContent.endsWith('[') &&
+        next instanceof Text && next.textContent.startsWith(']')
+      ) {
+
+        // remove surrounding brackets
+        prev.textContent = prev.textContent.slice(0, -1);
+        next.textContent = next.textContent.slice(1);
+
+        // add CSS list for styling
+        a.classList.add('wikilink');
+
+        // replace page-link with "Page Title"...
+        a.innerText = a.title;
+
+        // ...and normalize the links to allow html pages navigation
+        a.href = normalizeMdLink(a.href);
+      }
+    });
+
+  document.querySelectorAll(".github-only").forEach((el) => {
+    el.remove();
+  });
+});
+</script>
+
+
+{{ content }}

docs/_layouts/home.html

@@ -1,25 +1,16 @@
 ---
-layout: default
+layout: foam
 ---
 
 <script async defer src="https://buttons.github.io/buttons.js"></script>
 
 {{ content }}
 
-<script type="text/javascript">
-  // Hack: Replace page-link with "Page Title"
-  document
-    .querySelectorAll(".markdown-body a[title]:not([href^=http])")
-    .forEach((a) => {
-      a.innerText = a.title;
-    });
-
-  document.querySelectorAll(".github-only").forEach((el) => {
-    el.remove();
-  });
-
+<script>
+window.addEventListener('DOMContentLoaded', (event) => {
   var duplicateHeading = document.querySelector("h1:not(#foam)");
   if (duplicateHeading && duplicateHeading.remove) {
     duplicateHeading.remove();
   }
+});
 </script>

docs/_layouts/mathjax.html

@@ -1,22 +1,9 @@
 ---
-layout: default
+layout: foam
 ---
 
 {{ content }}
 
-<script type="text/javascript">
-  // Hack: Replace page-link with "Page Title"
-  document
-    .querySelectorAll(".markdown-body a[title]:not([href^=http])")
-    .forEach((a) => {
-      a.innerText = a.title;
-    });
-
-  document.querySelectorAll(".github-only").forEach((el) => {
-    el.remove();
-  });
-</script>
-
 <script src="https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML" type="text/javascript"></script>
 <script type="text/x-mathjax-config">
     MathJax.Hub.Config({

docs/_layouts/page.html

@@ -1,18 +1,5 @@
 ---
-layout: default
+layout: foam
 ---
 
 {{ content }}
-
-<script type="text/javascript">
-  // Hack: Replace page-link with "Page Title"
-  document
-    .querySelectorAll(".markdown-body a[title]:not([href^=http])")
-    .forEach((a) => {
-      a.innerText = a.title;
-    });
-
-  document.querySelectorAll(".github-only").forEach((el) => {
-    el.remove();
-  });
-</script>

docs/assets/css/style.scss

@@ -52,6 +52,16 @@ blockquote {
     "DejaVu Serif", "Bitstream Vera Serif", "Liberation Serif", Georgia, serif;
 }
 
+.wikilink:before {
+  content: "[[";
+  opacity: 0.5;
+}
+
+.wikilink:after {
+  content: "]]";
+  opacity: 0.5;
+}
+
 .github-only {
   display: none;
 }

docs/assets/images/diagram-drawio-demo.drawio.svg

@@ -0,0 +1,68 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="281px" height="181px" viewBox="-0.5 -0.5 281 181" content="&lt;mxfile host=&quot;dd26700e-36c4-4a92-a6df-21c7be0d8350&quot; modified=&quot;2020-08-31T10:44:14.509Z&quot; agent=&quot;5.0 (Macintosh; Intel Mac OS X 10_15_4) AppleWebKit/537.36 (KHTML, like Gecko) Code/1.48.2 Chrome/78.0.3904.130 Electron/7.3.2 Safari/537.36&quot; etag=&quot;ygaBEVmOlivkHZFzXaxy&quot; version=&quot;13.1.3&quot;&gt;&lt;diagram id=&quot;6hGFLwfOUW9BJ-s0fimq&quot; name=&quot;Page-1&quot;&gt;1ZVNT4NAEIZ/DVdT2NrWq7XqQU89aI+bMsKahSHboYC/3qXMAhvUmJi08QTzzMcy72yGQKyz+sHIIn3GGHQQzeI6EHdBFIXLcGUfLWmYhMvrjiRGxcwGsFUfwHDGtFQxHLxAQtSkCh/uMc9hTx6TxmDlh72h9k8tZAITsN1LPaUvKqa0o6toOfBHUEnqTg4XN50nky6YOzmkMsZqhMQmEGuDSN1bVq9Bt+o5Xbq8+2+8/YcZyOk3Caz7gRrXG8S2VTbRUIoJ5lJvBnprsMxjaAvMrDXEPCEWFoYWvgNRw3OTJaFFKWWavVArem3Tr+z5nbkbue5qLn0yGmfkZJou69qZu7FvSDtZLq9rsO3qW4kYHbA0e46K+FZJkwBHiX489mIDZmBPsSEGtCR19KtLvmBJHzfMwL7wGL4eyeKyI1n+o5HMzzQSPvoodekXHQ3JH0GVKoJtIU8fX9k16MvN9cAQ1D9rMO2OE6I5rxC3RN1KqYaN1LN0tI0Ws78LIiaCRBcXJFz4gvQCnUOQ+UQQcXFBRHQ+Qaw5/LROvtG/X2w+AQ==&lt;/diagram&gt;&lt;/mxfile&gt;">
+    <defs/>
+    <g>
+        <path d="M 110 60 L 110 90 L 60 90 L 60 113.63" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/>
+        <path d="M 60 118.88 L 56.5 111.88 L 60 113.63 L 63.5 111.88 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/>
+        <path d="M 170 60 L 170 90 L 220 90 L 220 113.63" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/>
+        <path d="M 220 118.88 L 216.5 111.88 L 220 113.63 L 223.5 111.88 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/>
+        <rect x="80" y="0" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 30px; margin-left: 81px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">
+                                1
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="140" y="34" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    1
+                </text>
+            </switch>
+        </g>
+        <rect x="0" y="120" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 150px; margin-left: 1px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">
+                                2
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="60" y="154" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    2
+                </text>
+            </switch>
+        </g>
+        <rect x="160" y="120" width="120" height="60" fill="#ffffff" stroke="#000000" pointer-events="all"/>
+        <g transform="translate(-0.5 -0.5)">
+            <switch>
+                <foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility">
+                    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 118px; height: 1px; padding-top: 150px; margin-left: 161px;">
+                        <div style="box-sizing: border-box; font-size: 0; text-align: center; ">
+                            <div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">
+                                3
+                            </div>
+                        </div>
+                    </div>
+                </foreignObject>
+                <text x="220" y="154" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">
+                    3
+                </text>
+            </switch>
+        </g>
+    </g>
+    <switch>
+        <g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/>
+        <a transform="translate(0,-5)" xlink:href="https://desk.draw.io/support/solutions/articles/16000042487" target="_blank">
+            <text text-anchor="middle" font-size="10px" x="50%" y="100%">
+                Viewer does not support full SVG 1.1
+            </text>
+        </a>
+    </switch>
+</svg>

docs/automatic-git-syncing.md

@@ -1,11 +0,0 @@
-# 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/big-vision.md

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

docs/block-references.md

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

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

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

docs/contributing.md

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

docs/contribution-guide.md

@@ -1,53 +0,0 @@
-# Contribution Guide
-
-> [[todo]] [[good-first-task]] This contribution guide itself could be improved 😅
-
-Foam is open to contributions of any kind, including but not limited to code, documentation, ideas and feedback. Here are some general tips on how to get started on contributing to Foam:
-
-- Use Foam for yourself, figure out what could be improved.
-- Check out [[roadmap]] to see what's already in the plans. I have thoughts about how to implement some of these, but open to ideas and code contributions!
-- Read about our [[principles]] to understand Foam's philosophy and direction
-- Read and act in accordance of our [[code-of-conduct]].
-- Feel free to open [GitHub issues](https://github.com/foambubble/foam/issues) to give me feedback and ideas for new features.
-- Foam code and documentation live in the monorepo at [foambubble/foam](https://github.com/foambubble/foam/)
-  - [/docs](https://github.com/foambubble/foam/docs): documentation and [[recipes]]
-  - [/packages/foam-vscode](https://github.com/foambubble/foam/tree/master/packages/foam-vscode): the core VSCode plugin
-  - [/packages/foam-core](https://github.com/foambubble/foam/tree/master/packages/foam-core): powers the core functionality in Foam across all platforms
-- Exceptions to the monorepo are:
-  - The starter template at [foambubble/foam-template](https://github.com/foambubble/)
-  - All other [[recommended-extensions]] live in their respective GitHub repos.
-
-## Contributing to the VS Code Extension
-
-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:
-
-   `git clone https://github.com/foambubble/foam.git`
-
-2. Install the necessary dependencies by running this command from the root:
-
-   `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:
-
-   `yarn workspace foam-core build`
-
-4. Now we'll use the launch configuration defined at [`.vscode/launch.json`](https://github.com/foambubble/foam/blob/master/.vscode/launch.json) to start a new extension host of VS Code. From the root, or the `foam-vscode` workspace, press f5.
-5. In the new extension host of VS Code that launched, open a Foam workspace (e.g. your personal one, or a test-specific one created from foam-template). This is strictly not necessary, but the extension won't auto-run unless it's in a workspace with a `.vscode/foam.json` file.
-6. Test a command to make sure it's working as expected. Open the Command Palette (Ctrl/Cmd + Shift + P) and select "Foam: Update Markdown Reference List". If you see no errors, it's good to go!
-
-For more resources related to the VS Code Extension, check out the links below:
-
-- [[tutorial-adding-a-new-command-to-the-vs-code-extension]]
-
-[//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[good-first-task]: good-first-task "Good First Task"
-[roadmap]: roadmap "Roadmap"
-[principles]: principles "Principles"
-[code-of-conduct]: code-of-conduct "Code of Conduct"
-[recipes]: recipes "Recipes"
-[recommended-extensions]: recommended-extensions "Recommended Extensions"
-[tutorial-adding-a-new-command-to-the-vs-code-extension]: tutorial-adding-a-new-command-to-the-vs-code-extension "Tutorial: Adding a New Command to the VS Code Extension"
-[//end]: # "Autogenerated link references"

docs/creating-a-new-language.md

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

@@ -1,11 +0,0 @@
-# Creating New Notes
-
-- Write out a new `[[wiki-link]]` and `Cmd` + `Click` to create a new file.
-- `Cmd` + `Shift` + `P` (`Ctrl` + `Shift` + `P` for Windows), execute `New Note` from [VS Code Markdown Notes](<(https://marketplace.visualstudio.com/items?itemName=kortina.vscode-markdown-notes)>) and enter a **Title Case Name** to create `title-case-name.md`
-  - Add a keyboard binding to make creating new notes easier.
-- You shouldn't worry too much about categorising your notes. You can always [[search-for-notes]], and explore them using the [[graph-visualisation]].
-
-[//begin]: # "Autogenerated link references for markdown compatibility"
-[search-for-notes]: search-for-notes "Search for Notes"
-[graph-visualisation]: graph-visualisation "Graph visualisation"
-[//end]: # "Autogenerated link references"

docs/custom-markdown-preview-styles.md

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

docs/customising-styles.md

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

@@ -1,36 +0,0 @@
-# Daily notes
-
-The idea is to make it easier for people to be able to create Daily notes.
-
-This feature is open for discussion at [foambubble/foam#54](https://github.com/foambubble/foam/issues/54).
-
-## Must have
-
-- Should exist as part of [foam-vscode](https://github.com/foambubble/foam/tree/master/packages/foam-vscode) extension 
-- A new command "Foam: Open Daily Note", which creates new file and focuses into it, or opens the existing file for today if it exists already.
-  - File should have a Level 1 `# Heading`
-- Extension should define a hotkey for it (TBD? What do other apps do?)
-
-## Should have
-
-- Settings to customise:
-  - Format of file name, default to `yyyy-mm-dd`
-  - Format of title
-    - Default to same as file name
-    - Allow override e.g. `MMMMM D, YYYY`, to July 8. 2020 (locale specific)
-  - Extension of file, default to `.md`
-  - Directory into which file should be created, default to `./` (workspace root)
-    - Should create directory if needed
-
-## Could have
-- Automatically update a "daily notes" index file, newest first. Format TBD
-  - A custom note template .md file that could be stored in `.vscode/` directory (would supercede having to format the title)
-    - This could be useful for people who e.g. want there to be a format for every day's notes with fixed questions and stuff.
-  - Maybe we could do it with just back links or tags, by putting e.g. `[[daily]]` into the note template
-  - If files were named in alphabetic sortable order, and back links would display in reverse order, newest would always come on top
-
-[//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[roadmap]: roadmap "Roadmap"
-[//end]: # "Autogenerated link references"
-

docs/decision-needed.md

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

docs/decision.md

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

docs/dev/about-docs.md

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

docs/dev/build-vs-assemble.md

@@ -3,14 +3,10 @@
 The Foam prototype is built by assembling third-party extensions, which seems like a good strategy because
 
 - It supports picking and mixing of tools and workflows
-- Less code to write an maintain
+- Less code to write and maintain
 
 But there's also a bunch of roadmap items that are hard to implement this way, as the third party plugins don't do exactly what we want them to do (e.g. Markdown All In One is not compatible with [[referencing-notes-by-title]].
 
 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/dev/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 `jani.evakallio+foam@gmail.com`.
+reported to the community leaders responsible for enforcement at `riki.code+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,9 +126,5 @@ enforcement ladder](https://github.com/mozilla/diversity).
 [homepage]: https://www.contributor-covenant.org
 
 For answers to common questions about this code of conduct, see the FAQ at
-https://www.contributor-covenant.org/faq. Translations are available at
-https://www.contributor-covenant.org/translations.
-
-[//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
-[//end]: # "Autogenerated link references"
+<https://www.contributor-covenant.org/faq>. Translations are available at
+<https://www.contributor-covenant.org/translations>.

docs/dev/contribution-guide.md

@@ -0,0 +1,113 @@
+---
+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. For a comprehensive guide about contributing to open-source projects in general, [see here](https://sqldbawithabeard.com/2019/11/29/how-to-fork-a-github-repository-and-contribute-to-an-open-source-project/).
+
+## Getting Up To Speed
+
+Before you start contributing we recommend that you read the following links:
+
+- [[principles]] - This document describes the guiding principles behind Foam.
+- [[code-of-conduct]] - Rules we hope every contributor aims to follow, allowing everyone to participate in our community!
+
+## Diving In
+
+We understand that diving in an unfamiliar codebase may seem scary,
+to make it easier for new contributors we provide some resources:
+
+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 (assuming [node.js >= v16](https://nodejs.org/) and [yarn](https://yarnpkg.com/) are already installed on your system).
+
+1. Fork the project to your Github account by clicking the "Fork" button on the top right hand corner of the project's [home repository page](https://github.com/foambubble/foam).
+2. Clone your newly forked repo locally:
+
+   `git clone https://github.com/your_username/foam.git`
+
+3. Install the necessary dependencies by running this command from the root of the cloned repository:
+
+   `yarn install`
+
+4. From the repository root, run the command:
+
+   `yarn build`
+
+You should now be ready to start working!
+
+### Structure of the project
+
+Foam code and documentation live in the monorepo at [foambubble/foam](https://github.com/foambubble/foam/).
+
+- [/docs](https://github.com/foambubble/foam/tree/master/docs): documentation and [[recipes]].
+
+Exceptions to the monorepo are:
+
+- The starter template at [foambubble/foam-template](https://github.com/foambubble/)
+- All other [[recommended-extensions]] live in their respective GitHub repos
+
+This project uses [Yarn workspaces](https://classic.yarnpkg.com/en/docs/workspaces/). 
+
+Originally Foam had:
+
+- [/packages/foam-core](https://github.com/foambubble/foam/tree/ee7a8919761f168d3931079adf21c5ad4d63db59/packages/foam-core) - Powers the core functionality in Foam across all platforms.
+- [/packages/foam-vscode](https://github.com/foambubble/foam/tree/master/packages/foam-vscode) - The core VS Code plugin.
+
+To improve DX we have moved the `foam-core` module into `packages/foam-vscode/src/core`, but from a development point of view it's useful to think of the `foam-vscode/src/core` "submodule" as something that might be extracted in the future.
+
+For all intents and purposes this means two things:
+
+1. nothing in `foam-vscode/src/core` should depend on files outside of this directory
+2. code in `foam-vscode/src/core` should NOT depend on `vscode` library
+
+We have kept the yarn workspace for the time being as we might use it to pull out `foam-core` in the future, or we might need it for other packages that the VS Code plugin could depend upon (e.g. currently the graph visualization is inside the module, but it might be pulled out if its complexity increases).
+
+### Testing
+
+Code needs to come with tests.
+We use the following convention in Foam:
+
+- `*.test.ts` are unit tests
+- `*.spec.ts` are integration tests
+
+Tests live alongside the code in `src`.
+
+### The VS Code Extension
+
+This guide assumes you read the previous instructions and you're set up to work on Foam.
+
+1. Now we'll use the launch configuration defined at [`.vscode/launch.json`](https://github.com/foambubble/foam/blob/master/.vscode/launch.json) to start a new extension host of VS Code. 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!
+
+### Submitting a Pull Request (PR)
+
+After you have made your changes to your copy of the project, it is time to try and merge those changes into the public community project.
+
+1. Return to the project's [home repository page](https://github.com/foambubble/foam).
+2. Github should show you an button called "Compare & pull request" linking your forked repository to the community repository.
+3. Click that button and confirm that your repository is going to be merged into the community repository. See [this guide](https://sqldbawithabeard.com/2019/11/29/how-to-fork-a-github-repository-and-contribute-to-an-open-source-project/) for more specifics.
+4. Add as many relevant details to the PR message to make it clear to the project maintainers and other members of the community what you have accomplished with your new changes. Link to any issues the changes are related to.
+5. Your PR will then need to be reviewed and accepted by the other members of the community. Any discussion about the changes will occur in your PR thread.
+6. Once reviewed and accept you can complete the merge request!
+7. Finally rest and watch the sun rise on a grateful universe... Or start tackling the other open issues ;)
+
+---
+
+Feel free to modify and submit a PR if this guide is out-of-date or contains errors!
+
+---
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[principles]: ../principles.md "Principles"
+[code-of-conduct]: code-of-conduct.md "Code of Conduct"
+[recipes]: ../user/recipes/recipes.md "Recipes"
+[recommended-extensions]: ../user/getting-started/recommended-extensions.md "Recommended Extensions"
+[//end]: # "Autogenerated link references"

docs/dev/foam-file-format.md

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

docs/dev/good-first-task.md

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

docs/dev/mdx-by-default.md

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

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

@@ -13,6 +13,7 @@ Present: @jevakallio, @riccardoferretti
 
 - Land work to master
   - Create a foam-core package
+
   -
 
 ### Open questions
@@ -122,5 +123,6 @@ How others solve this:
 - Unique ids -- could support optionally as part of file name or front matter metadata. Should not be required.
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: ../todo "Todo"
+[todo]: ../todo.md "Todo"
+[Index]: ../../index.md "Foam"
 [//end]: # "Autogenerated link references"

docs/dev/proposals/foam-core.md

@@ -9,7 +9,7 @@
   - Visualizations
     - Tag clouds
     - Graph
-    - Should we have a package for visualisation?
+    - Should we have a package for visualization?
       - [[build-vs-assemble]]
       - Not everything needs to live in the Foam repo
   - Web based UI (Monaco)
@@ -17,7 +17,7 @@
 `foam-core`'s primary responsibility is to build an API on top of a workspace of markdown files, which allows us to:
 
 - Treat files as a graph, based on links
-  - Can be either [[wiki-links]] or relative `[markdown](links.md)` style
+  - Can be either [[wikilinks]] or relative `[markdown](links.md)` style
   - We need to know about the edges (connections) as well as nodes
     - What link points to what other file, etc.
     - Needs to have the exact link text, e.g. even if `[[some-page]]` or `[[some-page.md]]` or `[[Some Page]]` point to the same document (`./some-page.md`), we need to know which format was used, so [[link-reference-definitions]] can be generated correctly
@@ -61,11 +61,11 @@ Here are some example use cases that the core should support. They don't need to
 
 - Adding and editing page content
   - [[materialized-backlinks]]
-  - [[link-reference-definitions]] for [[wiki-links]]
+  - [[link-reference-definitions]] for [[wikilinks]]
   - [Frontmatter](https://jekyllrb.com/docs/front-matter/)
 - Finding all documents with `#tag`
 - Finding all documents with instances of `[[link]]`
-- Visualisations
+- Visualizations
 - Full text search
 
   - Or, if search is too expensive/complex, when given a list of file names and line/column positions from VS Code search API, can return the document context (e.g. full paragraph, preceding/following line etc)
@@ -96,12 +96,12 @@ Useful for knowing what needs to be supported. See [[feature-comparison]].
 - [[foam-core-2020-07-11]]
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[workspace-janitor]: workspace-janitor "Workspace Janitor"
-[cli]: cli "Command Line Interface"
-[build-vs-assemble]: build-vs-assemble "Build vs Assemble"
-[wiki-links]: wiki-links "Wiki Links"
-[materialized-backlinks]: materialized-backlinks "Materialized Backlinks (stub)"
-[todo]: todo "Todo"
-[feature-comparison]: feature-comparison "Feature comparison"
-[foam-core-2020-07-11]: meeting-notes/foam-core-2020-07-11 "Foam Core 2020-07-11"
+[workspace-janitor]: ../../user/tools/workspace-janitor.md "Janitor"
+[cli]: ../../user/tools/cli.md "Command Line Interface"
+[build-vs-assemble]: ../build-vs-assemble.md "Build vs Assemble"
+[wikilinks]: ../../user/features/wikilinks.md "Wikilinks"
+[link-reference-definitions]: ../../user/features/link-reference-definitions.md "Link Reference Definitions"
+[materialized-backlinks]: materialized-backlinks.md "Materialized Backlinks (stub)"
+[todo]: ../todo.md "Todo"
+[foam-core-2020-07-11]: ../meeting-notes/foam-core-2020-07-11.md "Foam Core 2020-07-11"
 [//end]: # "Autogenerated link references"

docs/dev/proposals/inclusion-of-notes.md

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

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

@@ -4,13 +4,13 @@
 
 ### File-by-file Insertion
 
-For the time being, if you want to get [[wiki-links]] into all files within the workspace, you'll need to generate the link reference definitions yourself file-by-file (with the assistance of Foam).
+For the time being, if you want to get [[wikilinks]] into all files within the workspace, you'll need to generate the link reference definitions yourself file-by-file (with the assistance of Foam).
 
 ### Wikilinks don't work on GitHub
 
 > **TL;DR;** [workaround](#workaround) in the end of the chapter.
 
-If you click any of the wiki-links on GitHub web UI (such as the `README.md` of a project), you'll notice that the links break with a 404 error.
+If you click any of the wikilinks on GitHub web UI (such as the `README.md` of a project), you'll notice that the links break with a 404 error.
 
 At the time of writing (June 28 2020) this is a known, but unsolved error. To understand why this is the case, we need to understand what we are trading off.
 
@@ -53,13 +53,13 @@ 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
 - During build-time (when converting markdown to html for publishing purposes)
   - link reference definitions are needed, if the files are published via such tools (or to such platforms) that don't understand wikilinks
-  - link reference definitions might have to be in different formats depending on the publish target (e.g. Github pages vs Github UI)
+  - link reference definitions might have to be in different formats depending on the publish target (e.g. GitHub pages vs GitHub UI)
 
 The potential solution:
 
@@ -68,10 +68,11 @@ 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
@@ -111,7 +112,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
@@ -120,8 +121,9 @@ The potential solution:
     }
 
     ```
-  - With Foam repo, just use edit-time link reference definitions with '.md' extension - this makes the links work in the Github UI
-  - Have publish target defined for Github pages, that doesn't use '.md' extension, but still has the link reference definitions. Generate the output into gh-pages branch (or separate repo) with automation.
+
+  - With Foam repo, just use edit-time link reference definitions with '.md' extension - this makes the links work in the GitHub UI
+  - Have publish target defined for GitHub pages, that doesn't use '.md' extension, but still has the link reference definitions. Generate the output into gh-pages branch (or separate repo) with automation.
     - This naturally requires first removing the existing link reference definitions during the build
 - Other
   - To clean up the search results, remove link reference definition section guards (assuming that these are not defined by the markdown spec). Use unifiedjs parse trees to identify if there's missing (or surplus) definitions (check if they are identified properly by the library), and just add the needed definitions to the bottom of the file (without guards) AND remove them if they are not needed (anywhere from the file).
@@ -135,8 +137,7 @@ UI-wise, the publish targets could be picked in some similar fashion as the run/
 - [tracking issue on GitHub](https://github.com/foambubble/foam/issues/16)
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[wiki-links]: wiki-links "Wiki Links"
-[roadmap]: roadmap "Roadmap"
-[link-reference-definitions]: link-reference-definitions "Link Reference Definitions"
-[backlinking]: backlinking "Backlinking"
+[wikilinks]: ../../user/features/wikilinks.md "Wikilinks"
+[link-reference-definitions]: ../../user/features/link-reference-definitions.md "Link Reference Definitions"
+[backlinking]: ../../user/features/backlinking.md "Backlinking"
 [//end]: # "Autogenerated link references"

docs/dev/proposals/materialized-backlinks.md

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

docs/dev/proposals/roadmap.md

@@ -6,16 +6,12 @@ Some of these items can be achieved by combining existing tools, but others may
 
 Items that are already being worked on. Roadmap items in this stage should have an owner.
 
-- [@jevakallio](https://github.com/jevakallio): [[cli]]
-
 ## High priority
 
 Items we plan on working next. Items in this stage don't need to have an owner, but before we start working on them should have enough specification that they can be picked up and worked on without having to seek consensus.
 
 If you want to pick up work in this category, you should have a plan on how long the implementation will approximately take so we don't block progress by sitting on high priority issues.
 
-- [[workspace-janitor]]
-  
 ## Backlog
 
 Everything else, categorised into themes. Just because something is on this list doesn't mean it'll get done. If you're interested in working on items in this category, check the [[contribution-guide]] for how to get started.
@@ -27,15 +23,15 @@ If a roadmap item is a stub, **consider** opening a [GitHub issue](https://githu
 ### Known issues
 
 - [[improve-default-workspace-settings]]
+  - Discussion: [foam#270](https://github.com/foambubble/foam/issues/270)
 - Improve [[git-integration]]
-- Fix [[wiki-links]] compatibility issues
+- Fix [[wikilinks]] compatibility issues
 - Simplify [[foam-file-format]]
 
 ### Core features
 
 - [[renaming-files]]
 - [[unlinked-references]]
-- [[daily-notes]]
 - [[block-references]]
 - [[improved-backlinking]]
   - UX: [[make-backlinks-more-prominent]]
@@ -44,6 +40,7 @@ If a roadmap item is a stub, **consider** opening a [GitHub issue](https://githu
 - [[git-flows-for-teams]]
 - [[user-settings]]
 - [[link-reference-definitions]]
+- [[predefined-user-snippets]]
 
 ### Publishing
 
@@ -66,51 +63,41 @@ If a roadmap item is a stub, **consider** opening a [GitHub issue](https://githu
 
 ### Migration
 
+The community is working on a number of automated scripts to help you migrate to Foam. The main work of developing such a method involves exporting your notes, converting them to the Markdown format, and then making sure that the links between notes (if you had those) still work.
+
 - [[migrating-from-roam]]
   - Discussion: [foam#55](https://github.com/foambubble/foam/issues/55)
 - [[migrating-from-obsidian]]
   - Discussion: [foam#46](https://github.com/foambubble/foam/issues/46)
+- [[migrating-from-onenote]]
+  - Discussion: [foam#151](https://github.com/foambubble/foam/issues/151)
 - _Migration from other tools..._
 
-### integration
+### Integration
+
 - _Integrations to third party tools_...
-  
+
 ### Wild ideas
 
 - [[foam-linter]]
 - [[refactoring-via-language-server-protocol]]
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[build-vs-assemble]: build-vs-assemble "Build vs Assemble"
-[recipes]: recipes "Recipes"
-[cli]: cli "Command Line Interface"
-[workspace-janitor]: workspace-janitor "Workspace Janitor"
-[contribution-guide]: contribution-guide "Contribution Guide"
-[improve-default-workspace-settings]: improve-default-workspace-settings "Improve Default Workspace Settings (stub)"
-[git-integration]: git-integration "Git integration"
-[wiki-links]: wiki-links "Wiki Links"
-[foam-file-format]: foam-file-format "Foam File Format"
-[renaming-files]: renaming-files "Renaming files (stub)"
-[unlinked-references]: unlinked-references "Unlinked references (stub)"
-[daily-notes]: daily-notes "Daily notes"
-[block-references]: block-references "Block References (stub)"
-[improved-backlinking]: improved-backlinking "Improved Backlinking (stub)"
-[materialized-backlinks]: materialized-backlinks "Materialized Backlinks (stub)"
-[automatic-git-syncing]: automatic-git-syncing "Automatic Git Syncing (stub)"
-[git-flows-for-teams]: git-flows-for-teams "Git Flows for Teams (stub)"
-[officially-support-alternative-templates]: officially-support-alternative-templates "Officially Support Alternative Templates (stub)"
-[improved-static-site-generation]: improved-static-site-generation "Improved Static Site Generation (stub)"
-[mdx-by-default]: mdx-by-default "MDX by Default(stub)"
-[search-in-published-workspace]: search-in-published-workspace "Search in Published Workspace (stub)"
-[graph-in-published-workspace]: graph-in-published-workspace "Graph in Published Workspace (stub)"
-[linking-between-published-workspaces]: linking-between-published-workspaces "Linking between Published Workspaces (stub)"
-[publishing-permissions]: publishing-permissions "Publishing Permissions(stub)"
-[mobile-apps]: mobile-apps "Mobile Apps"
-[packaged-desktop-app]: packaged-desktop-app "Packaged Desktop App (stub)"
-[web-editor]: web-editor "Web Editor (stub)"
-[migrating-from-roam]: migrating-from-roam "Migrating from Roam (stub)"
-[migrating-from-obsidian]: migrating-from-obsidian "Migrating from Obsidian (stub)"
-[foam-linter]: foam-linter "Foam Linter (stub)"
-[refactoring-via-language-server-protocol]: refactoring-via-language-server-protocol "Refactoring via Language Server Protocol (stub)"
-[make-backlinks-more-prominent]: make-backlinks-more-prominent "Make Backlinks More Prominent"
-[//end]: # "Autogenerated link references"
+[build-vs-assemble]: ../build-vs-assemble.md "Build vs Assemble"
+[recipes]: ../../user/recipes/recipes.md "Recipes"
+[contribution-guide]: ../contribution-guide.md "Contribution Guide"
+[wikilinks]: ../../user/features/wikilinks.md "Wikilinks"
+[foam-file-format]: ../foam-file-format.md "Foam File Format"
+[unlinked-references]: ../unlinked-references.md "Unlinked references (stub)"
+[make-backlinks-more-prominent]: ../../user/recipes/make-backlinks-more-prominent.md "Make Backlinks More Prominent"
+[materialized-backlinks]: materialized-backlinks.md "Materialized Backlinks (stub)"
+[automatic-git-syncing]: ../../user/recipes/automatic-git-syncing.md "Automatically Sync with Git"
+[link-reference-definitions]: ../../user/features/link-reference-definitions.md "Link Reference Definitions"
+[predefined-user-snippets]: ../../user/recipes/predefined-user-snippets.md "Pre-defined User Snippets"
+[mdx-by-default]: ../mdx-by-default.md "MDX by Default(stub)"
+[publishing-permissions]: ../publishing-permissions.md "Publishing Permissions(stub)"
+[cli]: ../../user/tools/cli.md "Command Line Interface"
+[migrating-from-roam]: ../../user/recipes/migrating-from-roam.md "Migrating from Roam (stub)"
+[migrating-from-obsidian]: ../../user/recipes/migrating-from-obsidian.md "Migrating from Obsidian (stub)"
+[migrating-from-onenote]: ../../user/recipes/migrating-from-onenote.md "Migrating from OneNote"
+[//end]: # "Autogenerated link references"

docs/dev/proposals/templates-v2.md

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

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

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

docs/dev/publishing-permissions.md

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

docs/dev/releasing-foam.md

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

docs/dev/todo.md

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