Reorganized and updated foam docs (#398)

* reorganized and updated foam docs

* minor changes to vscode extension readme

* added 404 page and minor changes

Co-authored-by: Joe Previte <jjprevite@gmail.com>

.github/workflows/ci.yml

@@ -20,6 +20,13 @@ jobs:
         uses: actions/setup-node@v1
         with:
           node-version: '12'
+      - name: Restore Dependencies
+        uses: actions/cache@v2
+        with:
+          path: |
+            node_modules
+            */*/node_modules
+          key: ${{ runner.os }}-${{ hashFiles('**/yarn.lock') }}
       - name: Install Dependencies
         run: yarn
       - name: Check Lint Rules
@@ -40,6 +47,13 @@ jobs:
         uses: actions/setup-node@v1
         with:
           node-version: '12'
+      - name: Restore Dependencies
+        uses: actions/cache@v2
+        with:
+          path: |
+            node_modules
+            */*/node_modules
+          key: ${{ runner.os }}-${{ hashFiles('**/yarn.lock') }}
       - name: Install Dependencies
         run: yarn
       - name: Build Packages

.gitignore

@@ -5,3 +5,6 @@ node_modules
 *.vsix
 *.log
 dist
+docs/_site
+docs/.sass-cache
+docs/.jekyll-metadata

docs/.vscode/settings.json

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

docs/.vscode/spellright.dict

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

docs/404.md

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

docs/Gemfile

@@ -0,0 +1,38 @@
+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,270 @@
+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.4.0)
+    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.10.10)
+      mini_portile2 (~> 2.4.0)
+    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)
+    rb-fsevent (0.10.4)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rexml (3.2.4)
+    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/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.md "Todo"
-[roadmap]: roadmap.md "Roadmap"
-[//end]: # "Autogenerated link references"

docs/big-vision.md

@@ -14,5 +14,5 @@
 
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo.md "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.md "Todo"
-[roadmap]: roadmap.md "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.md "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/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.
 

docs/contribution-guide.md

@@ -14,7 +14,6 @@ Before you start contributing we recommend that you read the following links:
 ## Diving In
 We understand that diving in an unfamiliar codebase may seem scary,
 to make it easier for new contributors we provide some resources:
-- [[roadmap]] - You can read our roadmap to see what is coming to Foam, many of these are open to suggestions!
 - [[architecture]] - This document describes the architecture of Foam and how the repository is structured.
 
 You can also see [existing issues](https://github.com/foambubble/foam/issues) and help out!
@@ -61,7 +60,5 @@ Feel free to modify and submit a PR if this guide is out-of-date or contains err
 [//begin]: # "Autogenerated link references for markdown compatibility"
 [principles]: principles.md "Principles"
 [code-of-conduct]: code-of-conduct.md "Code of Conduct"
-[roadmap]: roadmap.md "Roadmap"
-[architecture]: architecture.md "Architecture"
-[tutorial-adding-a-new-command-to-the-vs-code-extension]: tutorial-adding-a-new-command-to-the-vs-code-extension.md "Tutorial: Adding a New Command to the VS Code Extension"
+[architecture]: dev/architecture.md "Architecture"
 [//end]: # "Autogenerated link references"

docs/creating-a-new-language.md

@@ -1,13 +0,0 @@
-# Creating a New Language
-
-## Creating a new language
-
-What if we created a new language that made it more ergonomic to use VS Code as a Foam workspace
-
-- Based on markdown
-- Could leverage mdx?
-- Shortcuts, like links between pages
-- Downside: Not markdown compatible, not so good for other tools
-  - Could it be a markdown superset?
-  - Or a language that transpiles to markdown and back, so it can be edited in "Foam" format and committed in MD so it's viewable on GH as markdown
-    - How imporant is it that links are navigable on GH? I guess it is

docs/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.md "Todo"
-[good-first-task]: good-first-task.md "Good First Task"
-[//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/architecture.md

@@ -16,6 +16,6 @@ Exceptions to the monorepo are:
 - All other [[recommended-extensions]] live in their respective GitHub repos.
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[recipes]: recipes.md "Recipes"
-[recommended-extensions]: recommended-extensions.md "Recommended Extensions"
-[//end]: # "Autogenerated link references"
+[recipes]: ../recipes/recipes.md "Recipes"
+[recommended-extensions]: ../recommended-extensions.md "Recommended Extensions"
+[//end]: # "Autogenerated link references"

docs/dev/build-vs-assemble.md

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

docs/dev/foam-core.md

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

docs/dev/foam-file-format.md

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

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

@@ -135,7 +135,7 @@ UI-wise, the publish targets could be picked in some similar fashion as the run/
 - [tracking issue on GitHub](https://github.com/foambubble/foam/issues/16)
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[wiki-links]: wiki-links.md "Wiki Links"
-[link-reference-definitions]: link-reference-definitions.md "Link Reference Definitions"
-[backlinking]: backlinking.md "Backlinking"
+[wiki-links]: ../wiki-links.md "Wiki Links"
+[link-reference-definitions]: ../features/link-reference-definitions.md "Link Reference Definitions"
+[backlinking]: ../features/backlinking.md "Backlinking"
 [//end]: # "Autogenerated link references"

docs/dev/materialized-backlinks.md

@@ -11,7 +11,7 @@ The idea would be to automatically generate lists of backlinks (and optionally,
 - Make every link two-way navigable in published sites
 - Make Foam notes more portable to different apps and long-term storage
 
+
 [//begin]: # "Autogenerated link references for markdown compatibility"
 [todo]: todo.md "Todo"
-[roadmap]: roadmap.md "Roadmap"
-[//end]: # "Autogenerated link references"
+[//end]: # "Autogenerated link references"

docs/dev/mdx-by-default.md

@@ -6,5 +6,4 @@ If you're interested in working on it, please start a conversation in [GitHub is
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
 [todo]: todo.md "Todo"
-[roadmap]: roadmap.md "Roadmap"
 [//end]: # "Autogenerated link references"

docs/dev/publishing-permissions.md

@@ -11,5 +11,4 @@ If you're interested in working on it, please start a conversation in [GitHub is
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
 [todo]: todo.md "Todo"
-[roadmap]: roadmap.md "Roadmap"
 [//end]: # "Autogenerated link references"

docs/dev/roadmap.md

@@ -1,3 +1,4 @@
+@@ -0,0 +1,125 @@
 # Roadmap
 
 Some of these items can be achieved by combining existing tools, but others may require us to build bespoke software solutions. See [[build-vs-assemble]] to understand trade-offs between these approaches. If a feature can be implemented by contributing to [[recipes]], it should.
@@ -6,16 +7,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.
@@ -88,38 +85,21 @@ The community is working on a number of automated scripts to help you migrate to
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
 [build-vs-assemble]: build-vs-assemble.md "Build vs Assemble"
-[recipes]: recipes.md "Recipes"
-[cli]: cli.md "Command Line Interface"
-[workspace-janitor]: workspace-janitor.md "Janitor"
-[contribution-guide]: contribution-guide.md "Contribution Guide"
-[improve-default-workspace-settings]: improve-default-workspace-settings.md "Improve Default Workspace Settings (stub)"
-[git-integration]: git-integration.md "Git integration"
-[wiki-links]: wiki-links.md "Wiki Links"
+[recipes]: ../recipes/recipes.md "Recipes"
+[contribution-guide]: ../contribution-guide.md "Contribution Guide"
+[git-integration]: ../features/git-integration.md "Git integration"
+[wiki-links]: ../wiki-links.md "Wiki Links"
 [foam-file-format]: foam-file-format.md "Foam File Format"
-[renaming-files]: renaming-files.md "Renaming files (stub)"
 [unlinked-references]: unlinked-references.md "Unlinked references (stub)"
-[block-references]: block-references.md "Block References (stub)"
-[improved-backlinking]: improved-backlinking.md "Improved Backlinking (stub)"
-[make-backlinks-more-prominent]: make-backlinks-more-prominent.md "Make Backlinks More Prominent"
+[make-backlinks-more-prominent]: ../recipes/make-backlinks-more-prominent.md "Make Backlinks More Prominent"
 [materialized-backlinks]: materialized-backlinks.md "Materialized Backlinks (stub)"
-[automatic-git-syncing]: automatic-git-syncing.md "Automatic Git Syncing (stub)"
-[git-flows-for-teams]: git-flows-for-teams.md "Git Flows for Teams (stub)"
-[user-settings]: user-settings.md "User Settings (stub)"
-[link-reference-definitions]: link-reference-definitions.md "Link Reference Definitions"
-[predefined-user-snippets]: predefined-user-snippets.md "Pre-defined User Snippets"
-[officially-support-alternative-templates]: officially-support-alternative-templates.md "Officially Support Alternative Templates (stub)"
-[improved-static-site-generation]: improved-static-site-generation.md "Improved Static Site Generation (stub)"
+[automatic-git-syncing]: ../recipes/automatic-git-syncing.md "Automatically Sync with Git"
+[link-reference-definitions]: ../features/link-reference-definitions.md "Link Reference Definitions"
+[predefined-user-snippets]: ../recipes/predefined-user-snippets.md "Pre-defined User Snippets"
 [mdx-by-default]: mdx-by-default.md "MDX by Default(stub)"
-[search-in-published-workspace]: search-in-published-workspace.md "Search in Published Workspace (stub)"
-[graph-in-published-workspace]: graph-in-published-workspace.md "Graph in Published Workspace (stub)"
-[linking-between-published-workspaces]: linking-between-published-workspaces.md "Linking between Published Workspaces (stub)"
 [publishing-permissions]: publishing-permissions.md "Publishing Permissions(stub)"
-[mobile-apps]: mobile-apps.md "Mobile Apps"
-[packaged-desktop-app]: packaged-desktop-app.md "Packaged Desktop App (stub)"
-[web-editor]: web-editor.md "Web Editor (stub)"
-[migrating-from-roam]: migrating-from-roam.md "Migrating from Roam (stub)"
-[migrating-from-obsidian]: migrating-from-obsidian.md "Migrating from Obsidian (stub)"
-[migrating-from-onenote]: migrating-from-onenote.md "Migrating from OneNote"
-[foam-linter]: foam-linter.md "Foam Linter (stub)"
-[refactoring-via-language-server-protocol]: refactoring-via-language-server-protocol.md "Refactoring via Language Server Protocol (stub)"
+[cli]: ../features/cli.md "Command Line Interface"
+[migrating-from-roam]: ../recipes/migrating-from-roam.md "Migrating from Roam (stub)"
+[migrating-from-obsidian]: ../recipes/migrating-from-obsidian.md "Migrating from Obsidian (stub)"
+[migrating-from-onenote]: ../recipes/migrating-from-onenote.md "Migrating from OneNote"
 [//end]: # "Autogenerated link references"

docs/dev/todo.md

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

docs/dev/unlinked-references.md

@@ -16,5 +16,4 @@ Implementing this is on the [[roadmap]], but for the time being you can achieve
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
 [todo]: todo.md "Todo"
-[roadmap]: roadmap.md "Roadmap"
 [//end]: # "Autogenerated link references"

docs/feature-comparison.md

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

docs/features/backlinking.md

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

docs/features/creating-new-notes.md

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

docs/features/custom-snippets.md

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

docs/features/daily-notes.md

@@ -2,7 +2,7 @@
 
 Automatically create a Daily Note by executing the "Foam: Open Daily Note" command. If a Daily Note for today's date already exists, the command opens the existing note.
 
-![Daily note feature in action](assets/images/daily-note.gif)
+![Daily note feature in action](../assets/images/daily-note.gif)
 
 ## Keyboard shortcut
 
@@ -50,5 +50,5 @@ If you want this behavior now, you can use the excellent [Auto Run Command](http
 Please see [[note-macros]]
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[note-macros]: note-macros.md "Custom Note Macros"
+[note-macros]: ../recipes/note-macros.md "Custom Note Macros"
 [//end]: # "Autogenerated link references"

docs/features/foam-local-plugins.md

@@ -54,5 +54,5 @@ When Foam is loaded it will check whether the experimental local plugin feature
 Currently for simplicity we keep everything in one file. We might in the future split the plugin by domain (e.g. vscode, cli, core, ...)
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo.md "Todo"
+[todo]: ../dev/todo.md "Todo"
 [//end]: # "Autogenerated link references"

docs/features/git-integration.md

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

docs/features/graph-visualisation.md

@@ -0,0 +1,16 @@
+# Graph Visualisation
+
+Foam comes with a graph visualisation.
+The graph will:
+- allow you to highlight a node by hovering on it, to quickly see how it's connected to the rest of your notes
+- allow you to select one or more (by keeping `SHIFT` pressed while selecting) nodes by clicking on them, to better understand the structure of your notes
+- to navigate to a note by clicking on it while pressing `CTRL` or `CMD`
+- automatically center the graph on the currently edited note, to immediately see it's connections
+
+### Markdown Links
+Another extension that provides a great graph visualisation is [Markdown Links](https://marketplace.visualstudio.com/items?itemName=tchayen.markdown-links).
+The extension doesn't use the Foam model, so discrepancies might arise, but it's a great visualisation extension nonetheless!
+
+- Use the `Markdown Links: Show Graph` command to see the graph
+![Demo of graph visualiser](../assets/images/foam-navigation-demo.gif)
+

docs/features/key-bindings.md

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

docs/features/link-reference-definitions.md

@@ -60,7 +60,7 @@ You can ignore the `_site` directory by adding the following to your `.vscode/se
 
 After changing the setting in your workspace, you can run the [[workspace-janitor]] command to convert all existing definitions.
 
-[[Todo]] _Implement a `foam.eclude
+[[todo]] _Implement a `foam.eclude
 
 ## Future improvements
 
@@ -69,6 +69,6 @@ See [[link-reference-definition-improvements]] for further discussion on current
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
 [workspace-janitor]: workspace-janitor.md "Janitor"
-[Todo]: todo.md "Todo"
-[link-reference-definition-improvements]: link-reference-definition-improvements.md "Link Reference Definition Improvements"
+[todo]: ../dev/todo.md "Todo"
+[link-reference-definition-improvements]: ../dev/link-reference-definition-improvements.md "Link Reference Definition Improvements"
 [//end]: # "Autogenerated link references"

docs/features/note-templates.md

@@ -0,0 +1,11 @@
+# Note Templates
+
+Foam supports note templates.
+
+Note templates live in `.foam/templates`, just create regular `.md` files there to add templates.
+
+To create a note from a template, execute the `Create New Note From Template` command and follow the instructions.
+
+Templates can use all the variables available in [VS Code Snippets](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_variables).
+
+

docs/features/tags.md

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

docs/features/workspace-janitor.md

@@ -17,7 +17,7 @@ In the future, Janitor can help you with
 
 Execute the "Foam: Run Janitor" command from the command palette.
 
-![Foam Janitor demo](assets/images/foam-janitor-demo.gif)
+![Foam Janitor demo](../assets/images/foam-janitor-demo.gif)
 
 ## Using Janitor from command line (Experimental)
 
@@ -36,5 +36,5 @@ You can also run the Janitor from a GitHub action to ensure that all changes com
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
 [link-reference-definitions]: link-reference-definitions.md "Link Reference Definitions"
-[materialized-backlinks]: materialized-backlinks.md "Materialized Backlinks (stub)"
+[materialized-backlinks]: ../dev/materialized-backlinks.md "Materialized Backlinks (stub)"
 [//end]: # "Autogenerated link references"

docs/foam-linter.md

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

docs/frequently-asked-questions.md

@@ -13,7 +13,6 @@
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
 [recommended-extensions]: recommended-extensions.md "Recommended Extensions"
-[foam-file-format]: foam-file-format.md "Foam File Format"
+[foam-file-format]: dev/foam-file-format.md "Foam File Format"
 [wiki-links]: wiki-links.md "Wiki Links"
-[link-formatting-and-autocompletion]: link-formatting-and-autocompletion.md "Link Formatting and Autocompletion"
 [//end]: # "Autogenerated link references"

docs/git-flows-for-teams.md

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

docs/git-integration.md

@@ -1,18 +0,0 @@
-# Git integration
-
-There are (too) many ways to commit your changes to source control:
-
-- Using VS Code's own git integration
-- Using GitLens (included in Foam for inline blame)
-- Whatever way you like to do it (CLI?)
-
-The quick and easy way is to use the Git: Commit All command after editing files. The default Foam workspace settings will stage & sync all of your changes to the remote:
-
-- `Cmd` + `Shift` + `P` (`Ctrl` + `Shift` + `P` for Windows), execute `Git: Commit All`
-
-This could be improved. [[todo]] [[good-first-task]]
-
-[//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo.md "Todo"
-[good-first-task]: good-first-task.md "Good First Task"
-[//end]: # "Autogenerated link references"

docs/graph-in-published-workspace.md

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

docs/graph-visualisation.md

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

docs/improve-default-workspace-settings.md

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

docs/improved-backlinking.md

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

docs/improved-static-site-generation.md

@@ -1,15 +0,0 @@
-# Improved Static Site Generation (stub)
-
-**[[todo]] This [[roadmap]] item needs more specification work.**
-
-If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
-
-## Notes
-
-- We should consider moving to gatsby, similar to [Foam Gatsby Template](https://mathieudutour.github.io/foam-gatsby-template/)
-
-
-[//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo.md "Todo"
-[roadmap]: roadmap.md "Roadmap"
-[//end]: # "Autogenerated link references"

docs/inbox.md

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

docs/index.md

@@ -96,15 +96,12 @@ I am using it as my personal thinking tool. By making it public, I hope to learn
 
 If that sounds like something you're interested in, I'd love to have you along on the journey.
 
-- Check out [[roadmap]] to see what's in the plans
 - Read about our [[principles]] to understand Foam's philosophy and direction
 - Read the [[contribution-guide]] guide to learn how to participate.
 - Feel free to open [GitHub issues](https://github.com/foambubble/foam/issues) to give me feedback and ideas for new features.
 
 ## Thanks and attribution
 
-**Foam** is built by [Jani Eväkallio](https://github.com/jevakallio) ([@jevakallio](https://twitter.com/jevakallio)), and all our contributors:
-
 <!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
 <!-- prettier-ignore-start -->
 <!-- markdownlint-disable -->
@@ -196,13 +193,11 @@ If that sounds like something you're interested in, I'd love to have you along o
 Foam is licensed under the [MIT license](license).
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[graph-visualisation]: graph-visualisation.md "Graph visualisation"
-[backlinking]: backlinking.md "Backlinking"
+[graph-visualisation]: features/graph-visualisation.md "Graph visualisation"
+[backlinking]: features/backlinking.md "Backlinking"
 [recommended-extensions]: recommended-extensions.md "Recommended Extensions"
-[recipes]: recipes.md "Recipes"
+[recipes]: recipes/recipes.md "Recipes"
 [frequently-asked-questions]: frequently-asked-questions.md "Frequently Asked Questions"
-[known-issues]: known-issues.md "Known Issues"
-[roadmap]: roadmap.md "Roadmap"
 [principles]: principles.md "Principles"
 [contribution-guide]: contribution-guide.md "Contribution Guide"
 [//end]: # "Autogenerated link references"

docs/known-issues.md

@@ -1,15 +0,0 @@
-# Known Issues
-
-- [ ] Aggressive autocompletion in Markdown files. You can turn `editor.quickSuggestions` off in [.vscode/settings.json].
-- [ ] Reference link lists have multiple issues ([Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode))
-  - [ ] Reference lists don't update in the background when other files are changed
-  - [ ] Notes don't get removed from reference lists when notes are deleted/renamed
-    - [ ] Workaround: Restart VS Code
-  - [ ] Links are case-sensitive (should not be)
-- [x] ~~[[graph-visualisation]] does not detect with wiki-links ([Markdown Links](https://marketplace.visualstudio.com/items?itemName=tchayen.markdown-links))~~
-- [x] ~~wiki-links aren't searchable on website~~
-  - [x] ~~This is because the link styling hack in `assets/css/style.scss`~~
-
-[//begin]: # "Autogenerated link references for markdown compatibility"
-[graph-visualisation]: graph-visualisation.md "Graph visualisation"
-[//end]: # "Autogenerated link references"

docs/link-formatting-and-autocompletion.md

@@ -1,75 +0,0 @@
-# Link Formatting and Autocompletion
-
-When coming from Roam, Obsidian and such tools, you may be used to writing [[wiki-links]] in `[[Title Case Format]]`. Foam will eventually support this syntax (see: [foambubble/rfcs#3](https://github.com/foambubble/rfcs/pull/3)), but for the time being, we do not.
-
-Foam relies heavily on our [[recommended-extensions]], and each extension has slightly different semantics and edge cases. This is a short guide on how to name your files, format your links, and configure your editor so that you can enjoy Foam until our implementation catches up with our aspirations.
-
-## Short version
-
-- Name your files in `lower-dash-case.md`.
-  - Read on: [How to name your files](#how-to-name-your-files)
-- Use [[wiki-links]] that match the file name exactly, without file extension: `[[lower-dash-case]]`
-  - Read on: [How to format your links](#how-to-format-your-links)
-  - Read on: [How to autocomplete your links correctly](#how-to-autocomplete-your-links-correctly)
-- Ensure every file has a `# Heading` element
-  - This will be used as your document title.
-
-## How to name your files
-
-As described in [[foam-file-format]], **Foam file names should not contain spaces.** Because of the [Markdown Notes](https://marketplace.visualstudio.com/items?itemName=kortina.vscode-markdown-notes) extension's default behaviour, we recommend naming your files in lower-dash-case: `foam-file-format.md`.
-
-ℹ️ This means:
-- All lowercase
-- No spaces, punctuation or special characters
-- Using dashes as word separators
-- Ending with a `.md` extension
-
-✅ Valid lower-dash-case file names include:
-- `roadmap.md`
-- `foam-file-format.md`
-- `f-f-f-f-falling.md`
-
-❌ Some invalid names include:
-
-- `Roadmap.md` (Name should not be capitalised)
-- `foam file format.md` (Name should not have spaces)
-- `f-f-f-f-falling!.md` (Name should not have special characters)
-
-Some of these file names may work for a subset of use cases (for example, if you don't publish your Foam site), but we'd still recommend following these rules.
-
-As per [[foam-file-format]], we eventually want to make Foam a lot more lenient. As per our [[principles]], you should be able to focus on your work and not fight against Foam. We're not there yet, but we'll get there.
-
-## How to format your links
-
-Use [[wiki-links]] to link between files. Each link:
-- **Should match file name exactly**: `[[foam-file-format]]`, not `[[Foam File Format]]`
-  - If you're reading this document on the Foam website, you might think: "That's not right!" What about links like [[foam-file-format]]! That uses spaces, capitalised letters, and everything!
-  - But if you look at the <a href="link-formatting-and-autocompletion.md">raw version of this document</a>, you'll see that the link is actually written as `[[foam-file-format]]`: we make it look nicer with a bit of web magic and a sprinkle of JavaScript.
-- **Not include a file extension**: `[[foam-file-format]]`, not `[[foam-file-format.md]]`.
-  - You might ask: If I can't use the `.md` extension, why does Foam autocomplete it for me?
-  - The answer is: It's a setting. See [How to autocomplete your links correctly](#how-to-autocomplete-your-links-correctly) below.
-
-## How to autocomplete your links correctly
-
-Foam autocompletion is provided by [Markdown Notes](https://marketplace.visualstudio.com/items?itemName=kortina.vscode-markdown-notes). The default behaviour of Markdown Notes Autocomplete is to suffix `.md` to the end of suggestion, such as in the below screenshot:
-
-![Autocomplete from Markdown Notes with file extension](./assets/images/md-notes-autocomplete-with-extension.png)
-
-To change this behaviour, add the below to your `.vscode/settings.json` file:
-
-```json
-"vscodeMarkdownNotes.noteCompletionConvention": "noExtension"
-```
-
-Now your autocomplete will look like the below screenshot:
-
-![Autocomplete from Markdown Notes without file extension](./assets/images/md-notes-autocomplete-no-extension.png)
-
-If you created your Foam from the official [foam-template](https://github.com/foambubble/foam-template) project after 27th July 2020, this setting should be already correctly set.
-
-[//begin]: # "Autogenerated link references for markdown compatibility"
-[wiki-links]: wiki-links.md "Wiki Links"
-[recommended-extensions]: recommended-extensions.md "Recommended Extensions"
-[foam-file-format]: foam-file-format.md "Foam File Format"
-[principles]: principles.md "Principles"
-[//end]: # "Autogenerated link references"

docs/linking-between-published-workspaces.md

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

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

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

docs/officially-support-alternative-templates.md

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

docs/packaged-desktop-app.md

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

docs/principles.md

@@ -30,13 +30,13 @@ This principle may seem like it contradicts [Foam wants you to own your thoughts
 > [...] environments that build walls around good ideas tend to be less innovative in the long run than more open-ended environments. Good ideas may not want to be free, but they do want to connect, fuse, recombine. —_Steven Johnson, Where Good Ideas Come From_
 
 - **Foam should make it easy to publish your knowledge graph.** With zero code, you should be able to make your graph public to the world. You should have full control over how it looks, feels, and where it's hosted.
-- **Foam should make it easy to collaborate on ideas.** Foam should allow you to work closely together with your collaborators, and accept feedback, input and improvements from others. _(Work in progress, see [[roadmap]]_.
-- **Foam should make it easy to publish what you choose.** Foam should double as a low-barrier blog/publishing platform, so you can share content to an audience without inviting them to intrude on your entire workspace. _(Work in progress, see [[roadmap]]_.
+- **Foam should make it easy to collaborate on ideas.** Foam should allow you to work closely together with your collaborators, and accept feedback, input and improvements from others.
+- **Foam should make it easy to publish what you choose.** Foam should double as a low-barrier blog/publishing platform, so you can share content to an audience without inviting them to intrude on your entire workspace.
 
 ## Foam allows people to collaborate in discovering better ways to work, together.
 
 - **Foam is a collection of ideas.** Foam was released to the public not to share the few good ideas in it, but to learn many good ideas from others. As you improve your own workflow, share your work on your own Foam blog.
-- **Foam is open for contributions.** If you use a tool or workflow that you like that fits these principles, please contribute them back to the Foam template as [[recipes]], [[recommended-extensions]] or documentation in [this workspace](https://github.com/foambubble/foam). See also: [[roadmap]] and [[contribution-guide]].
+- **Foam is open for contributions.** If you use a tool or workflow that you like that fits these principles, please contribute them back to the Foam template as [[recipes]], [[recommended-extensions]] or documentation in [this workspace](https://github.com/foambubble/foam). See also: [[contribution-guide]].
 - **Foam is open source.** Feel free to fork it, improve it and remix it. Just don't sell it, as per our [license](license).
 - **Foam is not Roam.** This project was inspired by Roam Research, but we're not limited by what Roam does. No idea is too big (though if it doesn't fit with Foam's core workflow, we might make it a [[recipes]] page instead).
 
@@ -48,9 +48,9 @@ While Foam uses tools popular among computer programmers, Foam should be inclusi
 - **Foam is not just for programmers.** If you're a programmer, feel free to write scripts and extensions to support your own workflow, and publish them for others to use, but the out of the box Foam experience should not require you to know how to do so. You should, however, be curious and open to adopting new tools that are unfamiliar to you, and evaluate whether they could work for you.
 - **Foam is for everyone** As a foam user, you support everyone's quest for knowledge and self-improvement, not only your own, or folks' who look like you. All participants in Foam repositories, discussion forums, physical and virtual meeting spaces etc are expected to respect each other as described in our [[code-of-conduct]]. **Foam is not for toxic tech bros.**
 
+
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[roadmap]: roadmap.md "Roadmap"
-[recipes]: recipes.md "Recipes"
+[recipes]: recipes/recipes.md "Recipes"
 [recommended-extensions]: recommended-extensions.md "Recommended Extensions"
 [contribution-guide]: contribution-guide.md "Contribution Guide"
 [code-of-conduct]: code-of-conduct.md "Code of Conduct"

docs/publishing/generate-gatsby-site.md

@@ -1,8 +1,8 @@
-# Foam Gatsby Template
+# Generate a site using Gatsby
 
-You can use [foam-gatsby-template](https://github.com/mathieudutour/foam-gatsby-template) to generate a static site to host it online on Github or [Vercel](https://vercel.com). 
+You can use [foam-gatsby-template](https://github.com/mathieudutour/foam-gatsby-template) to generate a static site to host it online on Github or [Vercel](https://vercel.com).
 
-## Publishing your foam to Github pages
+## Publishing your foam to GitHub pages
 It comes configured with Github actions to auto deploy to Github pages when changes are pushed to your main branch.
 
 ## Publishing your foam to Vercel
@@ -19,7 +19,6 @@ Log into your Vercel account. (Create one if you don't have it already.)
 
 Import your project. Select `_layouts/public` as your root directory and click **Continue**. Then name your project and click **Deploy**.
 
-That's it! 
-
+That's it!
 
 

docs/publishing/index.md

@@ -2,8 +2,6 @@
 
 Foam pages can be published.
 
-##
-
 ## Foam site generator?
 
 Another case of the [[build-vs-assemble]] dilemma. We could provide a better publishing experience by building a bespoke static site generator (or a gatsby plugin) that's aware of Foam conventions (backlinks etc.)
@@ -23,5 +21,5 @@ Would be cool if Foam pages could be published. Some ideas here.
     - [ ] More granular access control? Email someone a link with a hash? [Testing](testing.md)
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[build-vs-assemble]: build-vs-assemble.md "Build vs Assemble"
+[build-vs-assemble]: ../dev/build-vs-assemble.md "Build vs Assemble"
 [//end]: # "Autogenerated link references"

docs/publishing/math-support-with-katex.md

@@ -1,12 +1,12 @@
 # Katex Math Rendering
 
-Apart from using the method mentioned in [[math-support]], we can also use KaTeX to render our math equations in Foam. The caveat is: we can't rely on GitHub Pages to host and deploy our website anymore, because the plugin we'll be using to let Jekyll support KaTeX doesn't play well together with GitHub Pages.
+Apart from using the method mentioned in [[math-support-with-mathjax]], we can also use KaTeX to render our math equations in Foam. The caveat is: we can't rely on GitHub Pages to host and deploy our website anymore, because the plugin we'll be using to let Jekyll support KaTeX doesn't play well together with GitHub Pages.
 
-The alternative solution is to using [[vercel]] for building and publishing our website, so before you start integrating KaTeX into your Foam project, please follow the instructions to host your Foam workspace on [[vercel]] first.
+The alternative solution is to using [[publish-to-vercel]] for building and publishing our website, so before you start integrating KaTeX into your Foam project, please follow the instructions to host your Foam workspace on [[publish-to-vercel]] first.
 
 ## Adding required plugins
 
-Add the plugin `jekyll-katex` to your Foam workspace's `_config.yml` and `Gemfile` if you haven't done so already. For detailed instructions, please refer to the `#Adding a _config.yml` and `#Adding a Gemfile` in [[vercel]].
+Add the plugin `jekyll-katex` to your Foam workspace's `_config.yml` and `Gemfile` if you haven't done so already. For detailed instructions, please refer to the `#Adding a _config.yml` and `#Adding a Gemfile` in [[publish-to-vercel]].
 
 ## Loading KaTeX JS and CSS
 
@@ -53,6 +53,6 @@ You may have noticed that we only made modifications to the template `_layouts/p
 Finally, if all goes well, then our site hosted on Vercel will support rendering math equations with KaTeX after commiting these changes to GitHub. Here's a demo of the default template with KaTeX support: [Foam Template with KaTeX support](https://foam-template.vercel.app/).
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[math-support]: math-support.md "Math Support"
-[vercel]: vercel.md "Vercel"
+[math-support-with-mathjax]: math-support-with-mathjax.md "Math Support"
+[publish-to-vercel]: publish-to-vercel.md "Publish to Vercel"
 [//end]: # "Autogenerated link references"

docs/publishing/publish-to-azure-devops-wiki.md

@@ -1,4 +1,4 @@
-# Azure DevOps Wiki
+# Publish to Azure DevOps Wiki
 
 Publish your Foam workspace as an Azure DevOps wiki.
 
@@ -25,7 +25,7 @@ readme
 
 A published workspace looks like this:
 
-![Azure DevOps wiki](assets/images/azure-devops-wiki-demo.png)
+![Azure DevOps wiki](../assets/images/azure-devops-wiki-demo.png)
 
 There is default table of contents pane to the left of the wiki content. Here, you'll find a list of all directories that are present in your Foam workspace, and all wiki pages. Page names are derived from files names, and they are listed in alphabetical order. You may reorder pages by adding filenames without `.md` extension to `.order` file.
 

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

@@ -4,6 +4,27 @@
 - The default GitHub Pages template is called [Primer](https://github.com/pages-themes/primer). See Primer docs for how to customise html layouts and templates.
 - GitHub Pages is built on [Jekyll](https://jekyllrb.com/), so it supports things like permalinks, front matter metadata etc.
 
+## How to publish locally
+
+If you want to test your published foam, follow the instructions:
+- https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/creating-a-github-pages-site-with-jekyll
+- https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/testing-your-github-pages-site-locally-with-jekyll
+
+Assuming you have installed ruby/jekyll and the rest:
+- `touch Gemfile`
+  - open the file and paste the following:
+```
+source 'https://rubygems.org'
+
+gem "github-pages", "VERSION"
+```
+replacing `VERSION` with the latest from https://rubygems.org/gems/github-pages (e.g. `gem "github-pages", "209"`)
+- `bundle`
+- `bundle exec jekyll 3.9.0 new .`
+- edit the `Gemfile` according to the instructions at [Creating Your Site](https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/creating-a-github-pages-site-with-jekyll#creating-your-site) Point n.8
+- `bundle exec jekyll serve`
+
+
 ## Other templates
 There are many other templates which also support publish your foam workspace to github pages
 
@@ -20,6 +41,6 @@ There are many other templates which also support publish your foam workspace to
 [[todo]] [[good-first-task]] Improve this documentation
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo.md "Todo"
-[good-first-task]: good-first-task.md "Good First Task"
+[todo]: ../dev/todo.md "Todo"
+[good-first-task]: ../dev/good-first-task.md "Good First Task"
 [//end]: # "Autogenerated link references"

docs/publishing/publish-to-github.md

@@ -0,0 +1,17 @@
+# Publish to GitHub
+
+The standard [foam-template](https://github.com/foambubble/foam-template) is ready to be published to GitHub, and GitHub pages.
+
+## Enable navigation in GitHub
+
+To allow navigation from within the GitHub repo, make sure to generate the link references, by setting
+- `Foam › Edit: Link Reference Definitions` -> `withExtensions`
+
+See [[link-reference-definitions]] for more information.
+
+## Customising the style
+You can edit `assets/css/style.scss` to change how published pages look.
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[link-reference-definitions]: ../features/link-reference-definitions.md "Link Reference Definitions"
+[//end]: # "Autogenerated link references"

docs/publishing/publish-to-netlify-with-eleventy.md

@@ -1,4 +1,4 @@
-# Eleventy and Netlify
+# Publish to Netlify with Eleventy
 
 You can use [foam-eleventy-template](https://github.com/juanfrank77/foam-eleventy-template) to generate a static site with [Eleventy](https://www.11ty.dev/), and host it online on [Netlify](https://www.netlify.com/).
 

docs/publishing/publish-to-vercel.md

@@ -1,6 +1,8 @@
-# Vercel
+# Publish to Vercel
 
-[Vercel](https://vercel.com/) is a static website hosting solution similar to [[github-pages]]. This recipe shows you how to deploy the default Foam website template to Vercel.
+This #recipe shows you how to deploy the default Foam website template to Vercel.
+
+[Vercel](https://vercel.com/) is a static website hosting solution similar to GitHub Pages (see [[publish-to-github-pages]]).
 
 ## Setting up the project
 
@@ -37,7 +39,7 @@ The `theme` specifies a theme for our deployed Jekyll website. The default GitHu
 
 The `plugins` specifies a list of Jekyll plugins that we will be installing in the next section. As we won't be using GitHub Pages, we'll need to install these plugins that GitHub Pages installs for us under the hood.
 
-_If you want to use LaTeX rendered with KaTeX (which is what the plugin `jekyll-katex` does), you can specify it here. And yes, one of the benefits of deploying with Vercel is that we can use KaTeX to render LaTeX! More on: [[katex-math-rendering]]_
+_If you want to use LaTeX rendered with KaTeX (which is what the plugin `jekyll-katex` does), you can specify it here. And yes, one of the benefits of deploying with Vercel is that we can use KaTeX to render LaTeX! More on: [[math-support-with-katex]]_
 
 ### Adding a `Gemfile`
 
@@ -61,7 +63,7 @@ gem "jekyll-katex"  # Optional, the package that enables KaTeX math rendering
 
 ### Enable math rendering with KaTeX (optional)
 
-Besides adding the plugin `jekyll-katex` in `_config.yml` and `Gemfile`, we'll also have to follow the guides in [[katex-math-rendering]] to let our site fully support using KaTeX to render math equations.
+Besides adding the plugin `jekyll-katex` in `_config.yml` and `Gemfile`, we'll also have to follow the guides in [[math-support-with-katex]] to let our site fully support using KaTeX to render math equations.
 
 ### Commiting changes to GitHub repo
 
@@ -75,11 +77,11 @@ Next, select the folder to deploy from if prompted. If we are using the default
 
 Finally, if all is successful, Vercel will show the detected framework: Jekyll. Press `Deploy` to proceed on publishing our project.
 
-![](assets/images/vercel-detect-preset.png)
+![](../assets/images/vercel-detect-preset.png)
 
 And now, Vercel will take care of building and rendering our foam workspace each time on push. Vercel will publish our site to `xxx.vercel.app`, we can also define a custom domain name for our Vercel website.
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[github-pages]: github-pages.md "Github Pages"
-[katex-math-rendering]: katex-math-rendering.md "Katex Math Rendering"
+[publish-to-github-pages]: publish-to-github-pages.md "Github Pages"
+[math-support-with-katex]: math-support-with-katex.md "Katex Math Rendering"
 [//end]: # "Autogenerated link references"

docs/random-thoughts.md

@@ -1 +0,0 @@
-# Random thoughts

docs/reading-list.md

@@ -2,11 +2,11 @@
 
 - [Zettelkasten article, recommended by tchayen](https://github.com/alefore/weblog/blob/master/zettelkasten.md)
 - [Suping up VS Code as a Markdown editor](https://kortina.nyc/essays/suping-up-vs-code-as-a-markdown-notebook/)
-- [VSCode Extensions Packs](https://code.visualstudio.com/blogs/2017/03/07/extension-pack-roundup) [[Todo]] Evaluate for deployment
+- [VSCode Extensions Packs](https://code.visualstudio.com/blogs/2017/03/07/extension-pack-roundup) [[todo]] Evaluate for deployment
 - [Dark mode](https://css-tricks.com/dark-modes-with-css/)
 
 
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[Todo]: todo.md "Todo"
+[todo]: dev/todo.md "Todo"
 [//end]: # "Autogenerated link references"

docs/real-time-collaboration.md

@@ -1,3 +0,0 @@
-# Real-time Collaboration
-
-- Can already use VS Code live share for this

docs/recipes/add-images-to-notes.md

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

docs/recipes/automatic-git-syncing.md

@@ -0,0 +1,26 @@
+# Automatically Sync with Git
+
+With this #recipe you can regularly commit and push to git, to keep your repo in always synched.
+You can also easily manipulate the git history to reduce clutter.
+
+## Required Extensions
+
+ - [GitDoc](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.gitdoc)
+
+## Instructions
+
+Click on the extension link above to see how to use it.
+
+__For Foam specific needs, you can add a comment here by following the [[contribution-guide]]__
+
+## Feedback and issues
+
+- Feedback and issues with the extension should be reported to the authors themselves
+- Feedback and issues with the integration of the extension in Foam can be reported in our [issue tracker](https://github.com/foambubble/foam/issues)
+
+
+
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[contribution-guide]: ../contribution-guide.md "Contribution Guide"
+[//end]: # "Autogenerated link references"

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

@@ -1,6 +1,6 @@
 # Automatically Expand URLs to Well-Titled Links
 
-Convert a link to a fully-formed Markdown link, using the page's title as a display name. Useful for citations and creating link collections.
+With this #recipe you can convert a link to a fully-formed Markdown link, using the page's title as a display name. Useful for citations and creating link collections.
 
 ## Required Extensions
 
@@ -10,7 +10,7 @@ Markdown Link Expander will scrape your URL's `<title>` tag to create a nice Mar
 
 ## Instructions
 
-![Demo](./assets/images/prettify-links-demo.gif)
+![Demo](../assets/images/prettify-links-demo.gif)
 
 1. Highlight desired URL
 2. `Cmd` + `Shift` + `P`

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

@@ -1,15 +1,13 @@
 # Capture Notes With Drafts Pro
 
+With this #recipe you can create notes on your iOS device, which will automatically be imported into Foam.
+
 ## Context
 
 * You use [Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode) to manage your notes
 * You wish to adopt a practice such as [A writing inbox for transient and incomplete notes](https://notes.andymatuschak.org/A%20writing%20inbox%20for%20transient%20and%20incomplete%20notes)
 * You wish to use [Drafts Pro](https://docs.getdrafts.com/) to capture quick notes into your Foam notes from your iOS device
 
-## Required Extensions
-
-* [Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode)
-
 ## Other tools
 
 * We assume you are familiar with how to use GitHub (if you are using Foam this is implicit)

docs/recipes/diagrams-in-markdown.md

@@ -1,6 +1,6 @@
 # Diagrams in Markdown
 
-We have two alternative recipes for displaying diagrams in markdown:
+We have two alternative #recipe for displaying diagrams in markdown:
 
 - [Diagrams in Markdown](#diagrams-in-markdown)
   - [Mermaid](#mermaid)
@@ -12,13 +12,13 @@ We have two alternative recipes for displaying diagrams in markdown:
 
 You can use [Mermaid](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid) plugin to draw and preview diagrams in your content.
 
-⚠️ Be aware that Mermaid diagrams don't automatically get rendered in published Foams in [[github-pages]], and would require you to eject to another static site generation approach that supports Mermaid plugins.
+⚠️ Be aware that Mermaid diagrams don't automatically get rendered in published Foams in [[publish-to-github-pages]], and would require you to eject to another static site generation approach that supports Mermaid plugins.
 
 ## Draw.io
 
-[Draw.io](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio) extension allows you to create, edit, and display your diagrams without leaving Visual Studio Code. The `.drawio.svg` or `.drawio.png` files can be automatically embedded and displayed in published Foams, no export needed. FYI, the diagram below was made using Draw.io! You can check the diagram [here](./assets/images/diagram-drawio-demo.drawio.svg).
+[Draw.io](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio) extension allows you to create, edit, and display your diagrams without leaving Visual Studio Code. The `.drawio.svg` or `.drawio.png` files can be automatically embedded and displayed in published Foams, no export needed. FYI, the diagram below was made using Draw.io! You can check the diagram [here](../assets/images/diagram-drawio-demo.drawio.svg).
 
-![diagram-drawio-demo](./assets/images/diagram-drawio-demo.drawio.svg)
+![diagram-drawio-demo](../assets/images/diagram-drawio-demo.drawio.svg)
 
 ### Using Draw.io
 
@@ -29,5 +29,5 @@ You can use [Mermaid](https://marketplace.visualstudio.com/items?itemName=bierne
 
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[github-pages]: github-pages.md "Github Pages"
+[publish-to-github-pages]: ../publishing/publish-to-github-pages.md "Github Pages"
 [//end]: # "Autogenerated link references"

docs/recipes/how-to-write-recipes.md

@@ -23,7 +23,7 @@ When creating new recipes, if you don't know which extension does what, you can
 
 Here we describe how the extension should be used.
 
-![Demo](assets/images/foam-navigation-demo.gif)
+![Demo](../assets/images/foam-navigation-demo.gif)
 
 You may include a screenshot or GIF of the feature in action by uploading an image to the `assets/images` directory. Please try to keep GIFs as small as possible by recording them with a low frame rate.
 
@@ -36,7 +36,7 @@ You can add [[recipes]] by creating a pull request to [foambubble/foam](https://
 Read more in our [[contribution-guide]].
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[recommended-extensions]: recommended-extensions.md "Recommended Extensions"
+[recommended-extensions]: ../recommended-extensions.md "Recommended Extensions"
 [recipes]: recipes.md "Recipes"
-[contribution-guide]: contribution-guide.md "Contribution Guide"
+[contribution-guide]: ../contribution-guide.md "Contribution Guide"
 [//end]: # "Autogenerated link references"

docs/recipes/make-backlinks-more-prominent.md

@@ -2,9 +2,11 @@
 
 One of the most most common early feature requests in Foam is to make the Markdown Notes Backlinks Explorer more prominent.
 
+This #recipe shows you how to do that.
+
 At the moment, you can drag the explorer pane to your bottom pane, and either show it side by side with another pane, or have take the full width of the editor:
 
-![Demo of dragging and dropping the pane](assets/images/demo-backlinks-explorer.gif)
+![Demo of dragging and dropping the pane](../assets/images/demo-backlinks-explorer.gif)
 
 In the future we'll want to improve this feature by
 
@@ -20,5 +22,5 @@ In the future we'll want to improve this feature by
 
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[materialized-backlinks]: materialized-backlinks.md "Materialized Backlinks (stub)"
+[materialized-backlinks]: ../dev/materialized-backlinks.md "Materialized Backlinks (stub)"
 [//end]: # "Autogenerated link references"

docs/recipes/migrating-from-obsidian.md

@@ -6,6 +6,6 @@ If you're interested in working on it, please start a conversation in [GitHub is
 
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo.md "Todo"
-[roadmap]: roadmap.md "Roadmap"
+[todo]: ../dev/todo.md "Todo"
+[roadmap]: ../dev/roadmap.md "Roadmap"
 [//end]: # "Autogenerated link references"

docs/recipes/migrating-from-onenote.md

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

docs/recipes/migrating-from-roam.md

@@ -5,6 +5,6 @@
 If you're interested in working on it, please start a conversation in [GitHub issues](https://github.com/foambubble/foam/issues).
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo.md "Todo"
-[roadmap]: roadmap.md "Roadmap"
+[todo]: ../dev/todo.md "Todo"
+[roadmap]: ../dev/roadmap.md "Roadmap"
 [//end]: # "Autogenerated link references"

docs/recipes/note-macros.md

@@ -1,6 +1,6 @@
 # Custom Note Macros
 
-This extension gives you the ability to create custom note macros. It was heavily inspired by Foam's [[daily-notes]] functionality.
+This #recipe allows you to create custom note macros.
 
 ## Installation
 
@@ -57,7 +57,5 @@ If you have any issues or questions please look at the [README.md](https://githu
 
 If you run into any issues that are not fixed by referring to the README or feature requests please open an [issue](https://github.com/kneely/note-macros/issues).
 
-[//begin]: # "Autogenerated link references for markdown compatibility"
-[daily-notes]: daily-notes.md "Daily notes"
-[//end]: # "Autogenerated link references"
+
 

docs/recipes/predefined-user-snippets.md

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

docs/recipes/real-time-collaboration.md

@@ -0,0 +1,4 @@
+# Real-time Collaboration
+
+This #recipe is here to just tell you that VS Code Live Share will allow you to collaborate live on your notes.
+

docs/recipes/recipes.md

@@ -1,7 +1,7 @@
 <!-- omit in toc -->
 # Recipes
 
-Guides, tips and strategies for getting the most out of your Foam workspace!
+A #recipe is a guide, tip or strategy for getting the most out of your Foam workspace!
 
 - [Contribute](#contribute)
 - [Take smart notes](#take-smart-notes)
@@ -31,17 +31,17 @@ Guides, tips and strategies for getting the most out of your Foam workspace!
 - Simulating [[unlinked-references]]
 
 ## Organise
-- Using [[backlinking]] for [[reference-lists]].
+- Using [[backlinking]] for reference lists.
 
 ## Write
-- Link documents with [[wiki-links]], using Foam's [[link-formatting-and-autocompletion]].
+- Link documents with [[wiki-links]].
 - Use shortcuts for [[creating-new-notes]]
 - Instantly create and access your [[daily-notes]]
 - Use custom [[note-macros]] to create weekly, monthly etc. notes
 - Draw [[diagrams-in-markdown]]
 - Prettify your links, [[automatically-expand-urls-to-well-titled-links]]
 - Style your environment with [[custom-markdown-preview-styles]]
-- Paste and link [[images-from-your-clipboard]]
+- Paste and link [[add-images-to-notes]]
 - [[shows-image-preview-on-hover]]
 - [Markdown All-in-One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one) features [[todo]] [[good-first-task]]
   - Manage checklists
@@ -54,24 +54,24 @@ Guides, tips and strategies for getting the most out of your Foam workspace!
 ## Version control
 
 - Quick commits with VS Code's built in [[git-integration]]
-- Store your workspace in an auto-synced GitHub repo with [[gistpad]]
+- Store your workspace in an auto-synced GitHub repo with [[write-your-notes-in-github-gist]]
 - Sync your GitHub repo automatically [[todo]].
 
 ## Publish
 
 - Publish using official Foam template
-  - Publish to [[github-pages]]
-  - Publish to [[gitlab-pages]]
-  - Publish to [[azure-devops-wiki]]
-  - Publish to [[vercel]]
+  - Publish to [[publish-to-github-pages]]
+  - Publish to [[publish-to-gitlab-pages]]
+  - Publish to [[publish-to-azure-devops-wiki]]
+  - Publish to [[publish-to-vercel]]
 - Publish using community templates
-  - [[eleventy-and-netlify]] by [@juanfrank77](https://github.com/juanfrank77)
-  - [[foam-gatsby-template]] by [@mathieudutour](https://github.com/mathieudutour)
+  - [[publish-to-netlify-with-eleventy]] by [@juanfrank77](https://github.com/juanfrank77)
+  - [[generate-gatsby-site]] by [@mathieudutour](https://github.com/mathieudutour)
   - [foamy-nextjs](https://github.com/yenly/foamy-nextjs) by [@yenly](https://github.com/yenly)
-- Make the site your own by [[customising-styles]].
+- Make the site your own by [[publish-to-github]].
 - Render math symbols, by either
-  - adding client-side [[math-support]] to the default [[github-pages]] site
-  - adding a custom Jekyll plugin to support [[katex-math-rendering]]
+  - adding client-side [[math-support-with-mathjax]] to the default [[publish-to-github-pages]] site
+  - adding a custom Jekyll plugin to support [[math-support-with-katex]]
 
 ## Collaborate
 
@@ -98,35 +98,33 @@ Thought of a recipe but don't see a category for them? Add them here and we'll o
 _See [[contribution-guide]] and [[how-to-write-recipes]]._
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[contribution-guide]: contribution-guide.md "Contribution Guide"
+[contribution-guide]: ../contribution-guide.md "Contribution Guide"
 [how-to-write-recipes]: how-to-write-recipes.md "How to Write Recipes"
-[todo]: todo.md "Todo"
+[todo]: ../dev/todo.md "Todo"
 [web-clipper]: web-clipper.md "Web Clipper"
-[graph-visualisation]: graph-visualisation.md "Graph visualisation"
-[backlinking]: backlinking.md "Backlinking"
-[unlinked-references]: unlinked-references.md "Unlinked references (stub)"
-[reference-lists]: reference-lists.md "Reference Lists"
-[wiki-links]: wiki-links.md "Wiki Links"
-[link-formatting-and-autocompletion]: link-formatting-and-autocompletion.md "Link Formatting and Autocompletion"
-[creating-new-notes]: creating-new-notes.md "Creating New Notes"
-[daily-notes]: daily-notes.md "Daily notes"
+[graph-visualisation]: ../features/graph-visualisation.md "Graph visualisation"
+[backlinking]: ../features/backlinking.md "Backlinking"
+[unlinked-references]: ../dev/unlinked-references.md "Unlinked references (stub)"
+[wiki-links]: ../wiki-links.md "Wiki Links"
+[creating-new-notes]: ../features/creating-new-notes.md "Creating New Notes"
+[daily-notes]: ../features/daily-notes.md "Daily notes"
 [note-macros]: note-macros.md "Custom Note Macros"
 [diagrams-in-markdown]: diagrams-in-markdown.md "Diagrams in Markdown"
 [automatically-expand-urls-to-well-titled-links]: automatically-expand-urls-to-well-titled-links.md "Automatically Expand URLs to Well-Titled Links"
-[custom-markdown-preview-styles]: custom-markdown-preview-styles.md "Custom Markdown Preview Styles"
-[images-from-your-clipboard]: images-from-your-clipboard.md "Images from your Clipboard"
+[custom-markdown-preview-styles]: ../features/custom-markdown-preview-styles.md "Custom Markdown Preview Styles"
+[add-images-to-notes]: add-images-to-notes.md "Add images to your notes"
 [shows-image-preview-on-hover]: shows-image-preview-on-hover.md "Shows Image Preview on Hover"
-[good-first-task]: good-first-task.md "Good First Task"
-[git-integration]: git-integration.md "Git integration"
-[gistpad]: gistpad.md "GistPad"
-[github-pages]: github-pages.md "Github Pages"
-[gitlab-pages]: gitlab-pages.md "GitLab Pages"
-[eleventy-and-netlify]: eleventy-and-netlify.md "Eleventy and Netlify"
-[azure-devops-wiki]: azure-devops-wiki.md "Azure DevOps Wiki"
-[vercel]: vercel.md "Vercel"
-[customising-styles]: customising-styles.md "Customising Styles"
-[math-support]: math-support.md "Math Support"
-[katex-math-rendering]: katex-math-rendering.md "Katex Math Rendering"
+[good-first-task]: ../dev/good-first-task.md "Good First Task"
+[git-integration]: ../features/git-integration.md "Git integration"
+[write-your-notes-in-github-gist]: write-your-notes-in-github-gist.md "Write your notes in GitHub Gist"
+[publish-to-github-pages]: ../publishing/publish-to-github-pages.md "Github Pages"
+[publish-to-gitlab-pages]: ../publishing/publish-to-gitlab-pages.md "GitLab Pages"
+[publish-to-azure-devops-wiki]: ../publishing/publish-to-azure-devops-wiki.md "Publish to Azure DevOps Wiki"
+[publish-to-vercel]: ../publishing/publish-to-vercel.md "Publish to Vercel"
+[publish-to-netlify-with-eleventy]: ../publishing/publish-to-netlify-with-eleventy.md "Publish to Netlify with Eleventy"
+[generate-gatsby-site]: ../publishing/generate-gatsby-site.md "Generate a site using Gatsby"
+[publish-to-github]: ../publishing/publish-to-github.md "Publish to GitHub"
+[math-support-with-mathjax]: ../publishing/math-support-with-mathjax.md "Math Support"
+[math-support-with-katex]: ../publishing/math-support-with-katex.md "Katex Math Rendering"
 [capture-notes-with-drafts-pro]: capture-notes-with-drafts-pro.md "Capture Notes With Drafts Pro"
-[foam-gatsby-template]: foam-gatsby-template.md "Foam Gatsby Template"
 [//end]: # "Autogenerated link references"

docs/recipes/search-for-notes.md

@@ -1,5 +1,7 @@
 # Search for Notes
 
+This #recipe contains tips on how to leverage VS Code search features.
+
 [[todo]] Add more VS Code search power user tips here
 
 Run `Cmd` + `P` ( `Ctrl` +  `P` on Windows ) and type a name (like 'issues') to find a note associated with that name (like 'known-issues.md' )
@@ -7,5 +9,5 @@ Run `Cmd` + `P` ( `Ctrl` +  `P` on Windows ) and type a name (like 'issues') to
 Run `Cmd` + `Shift` + `F` ( `Ctrl` + `Shift` + `F` on Windows ) and type a word (like 'links') to find all the notes that contain that term.
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo.md "Todo"
+[todo]: ../dev/todo.md "Todo"
 [//end]: # "Autogenerated link references"

docs/recipes/shows-image-preview-on-hover.md

@@ -1,8 +1,10 @@
 # Shows Image Preview on Hover
 
+This #recipe allows you to see a preview of an image on hover.
+
 Use extension: [Image preview](https://marketplace.visualstudio.com/items?itemName=kisstkondoros.vscode-gutter-preview) to shows image preview in the gutter and on hover
 
 It looks like this
 
-![picture 1](./assets/images/preview-image-on-hover.png)
-![picture 2](./assets/images/preview-image-in-glutter.png)
+![picture 1](../assets/images/preview-image-on-hover.png)
+![picture 2](../assets/images/preview-image-in-glutter.png)

docs/recipes/take-notes-from-mobile-phone.md

@@ -1,14 +1,14 @@
-# Mobile Apps
+# Take notes on mobile phones
 
-We must always ask ourselves, [[build-vs-assemble]].
+This #recipe offers solutions to taking Foam notes on the go.
 
-This Roadmap item discusses existing assembled solutions, and some thoughts on future Foam mobile experience.
+For the time being we have decided to not build a mobile app, but rely on third parties (see [[build-vs-assemble]]).
 
-## Existing solutions
+The most promising options are:
 
 ### [GitJournal](https://gitjournal.io/)
 
-#### Pros
+Pros
 - Open source
 - Already a usable solution.
 - Provides functionality to edit, create, and browser markdown files.
@@ -18,13 +18,26 @@ This Roadmap item discusses existing assembled solutions, and some thoughts on f
 - Supports Backlinks
 - Developer is happy to prioritize Foam compatibility
 
-#### Cons
+Cons
 - Doesn't generate link reference lists (but this is ok, since [[workspace-janitor]] as a GitHub action can solve this)
 - Not as sleek as Apple/Google notes, some keyboard state glitching on Android, etc.
 - Lack of control over roadmap. Established product with a paid plan, so may not be open to Foam-supportive changes and additions that don't benefit most users.
 
 Verdict: Good. By far best effort/outcome ratio would be to help improve GitJournal rather than building a [bespoke mobile app](#bespoke-mobile-app-for-foam).
 
+### GitHub Codespaces
+
+Pros
+- Works out of the box just like the desktop app
+
+Cons
+- not generally available quite yet
+- [Pricing](https://docs.github.com/en/free-pro-team@latest/github/developing-online-with-codespaces/about-billing-for-codespaces)
+
+For a quick demo, see https://www.youtube.com/watch?v=KI5m4Uy8_4I.
+
+Verdict: Good. Pricing should be reasonable for taking notes on the fly. Harder to assess for people who would constantly use Foam from mobile phone.
+
 ## Bespoke mobile app for Foam
 
 Given we already have a solution, why would we spend time and effort building a bespoke mobile app?
@@ -43,6 +56,6 @@ Given the effort vs reward ratio, it's a low priority for core team, but if some
 
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[build-vs-assemble]: build-vs-assemble.md "Build vs Assemble"
-[workspace-janitor]: workspace-janitor.md "Janitor"
+[build-vs-assemble]: ../dev/build-vs-assemble.md "Build vs Assemble"
+[workspace-janitor]: ../features/workspace-janitor.md "Janitor"
 [//end]: # "Autogenerated link references"

docs/recipes/web-clipper.md

@@ -0,0 +1,11 @@
+# Web Clipper
+
+This #recipe allows you to convert any web content into Markdown for storing them in your notes.
+
+There are a couple of options when it comes to clipping web pages:
+
+- [Web Clipper](https://marketplace.visualstudio.com/items?itemName=jsartelle.web-clipper)
+  - This is a Web Clipper as a VSCode extension, takes a webpage URL and outputs Markdown. Uses [mercury](https://github.com/postlight/mercury-parser)
+
+- [Markdown Clipper](https://github.com/deathau/markdownload)
+  - A Firefox and Google Chrome extension to clip websites and download them into a readable markdown file.

docs/recipes/write-your-notes-in-github-gist.md

@@ -1,6 +1,10 @@
-# GistPad
+# Write your notes in GitHub Gist
 
-[GistPad](https://aka.ms/gistpad) is a Visual Studio Code extension that allows you to edit your GitHub gists and repos, without needing to clone anything locally. It provides support for editing Foam workspaces, complete with `[[link]]` [completion/navigation](https://github.com/vsls-contrib/gistpad#links), [daily pages](https://github.com/vsls-contrib/gistpad#daily-pages), [pasting images](https://github.com/vsls-contrib/gistpad#pasting-images-1) and [backlinks](https://github.com/vsls-contrib/gistpad#backlinks). If you'd like to persist your notes in a GitHub repository, and automatically sync changes without needing to manually commit/push/pull, then GistPad might be an option worth exploring.
+This #recipe will allow you to persist your notes in a GitHub repository, and automatically sync changes without needing to manually commit/push/pull, then GistPad might be an option worth exploring.
+
+[GistPad](https://aka.ms/gistpad) is a Visual Studio Code extension that allows you to edit your GitHub gists and repos, without needing to clone anything locally.
+
+It provides support for editing Foam workspaces, complete with `[[link]]` [completion/navigation](https://github.com/vsls-contrib/gistpad#links), [daily pages](https://github.com/vsls-contrib/gistpad#daily-pages), [pasting images](https://github.com/vsls-contrib/gistpad#pasting-images-1) and [backlinks](https://github.com/vsls-contrib/gistpad#backlinks).
 
 <img width="700px" src="https://user-images.githubusercontent.com/116461/87234714-96ba9400-c388-11ea-92c3-544d9a3bb633.png" />
 

docs/recommended-extensions.md

@@ -8,7 +8,6 @@ This list is subject to change. Especially the Git ones.
 - [Markdown Notes](https://marketplace.visualstudio.com/items?itemName=kortina.vscode-markdown-notes)
 - [Markdown Links](https://marketplace.visualstudio.com/items?itemName=tchayen.markdown-links)
 - [Markdown All In One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one)
-- [Git Lens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens)
 
 
 ## Extensions For Additional Features
@@ -21,5 +20,6 @@ These extensions are not (yet?) defined in `.vscode/extensions.json`, but have b
 - [Mermaid Markdown Syntax Highlighting](https://marketplace.visualstudio.com/items?itemName=bpruitt-goddard.mermaid-markdown-syntax-highlighting)
 - [Paste Image](https://marketplace.visualstudio.com/items?itemName=mushan.vscode-paste-image)
 - [VSCode PDF Viewing](https://marketplace.visualstudio.com/items?itemName=tomoki1207.pdf)
+- [Git Lens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens)
 - [Markdown Extended](https://marketplace.visualstudio.com/items?itemName=jebbs.markdown-extended) (with `kbd` option disabled, `kbd` turns wiki-links into non-clickable buttons)
 - [GitDoc](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.gitdoc) (easy version management via git auto commits)

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

@@ -1,10 +0,0 @@
-# Refactoring via Language Server Protocol (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.md "Todo"
-[roadmap]: roadmap.md "Roadmap"
-[//end]: # "Autogenerated link references"

docs/reference-lists.md

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