Docs sync @ 52b7f86 Updated TOC in FAQ docs (#49)

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

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

docs/recipes/automatic-git-syncing.md

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

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

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

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

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

docs/recipes/capture-notes-with-shortcuts-and-github-actions.md

@@ -0,0 +1,60 @@
+# Capture Notes With Shortcuts and GitHub Actions
+
+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 [Shorcuts](https://support.apple.com/guide/shortcuts/welcome/ios) to capture quick notes into your Foam notes from your iOS device
+
+## Other tools
+
+* We assume you are familiar with how to use GitHub (if you are using Foam this is implicit)
+* You have an iOS device.
+
+## Instructions
+
+1. Setup the [`foam-capture-action`]() in your GitHub Repository, to be triggered by "Workflow dispatch" events.
+
+```
+name: Manually triggered workflow
+on:
+  workflow_dispatch:
+    inputs:
+      data:
+        description: 'What information to put in the knowledge base.'
+        required: true
+
+jobs:
+  store_data:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@master
+    - uses: anglinb/foam-capture-action@main
+      with:
+        {% raw %}
+        capture: ${{ github.event.inputs.data }}
+        {% endraw %}
+    - run: |
+        git config --local user.email "example@gmail.com"
+        git config --local user.name "Your name"
+        git commit -m "Captured from workflow trigger" -a
+        git push -u origin master
+```
+
+2. In GitHub [create a Personal Access Token](https://github.com/settings/tokens) and give it `repo` scope - make a note of the token
+3. Run this command to find your `workflow-id` to be used in the Shortcut.
+
+```bash
+curl \
+  -H "Accept: application/vnd.github.v3+json" \
+  -H "Authorization: Bearer <GITHUB_TOKEN>" \
+    https://api.github.com/repos/<owner>/<repository>/actions/workflows
+```
+
+4. Copy this [Shortcut](https://www.icloud.com/shortcuts/57d2ed90c40e43a5badcc174ebfaaf1d) to your iOS devices and edit the contents of the last step, `GetContentsOfURL`
+   - Make sure you update the URL of the shortcut step with the `owner`, `repository`, `workflow-id` (from the previous step)
+   - Make sure you update the headers of the shortcut step, replaceing `[GITHUB_TOKEN]` with your Personal Access Token (from step 2)
+
+5. Run the shortcut & celebrate! ✨ (You should see a GitHub Action run start and the text you entered show up in `inbox.md` in your repository.)

docs/recipes/diagrams-in-markdown.md

@@ -0,0 +1,25 @@
+# Diagrams in Markdown
+
+We have two alternative #recipe for displaying diagrams in markdown:
+
+- [Diagrams in Markdown](#diagrams-in-markdown)
+  - [Mermaid](#mermaid)
+  - [Draw.io](#drawio)
+    - [Using Draw.io](#using-drawio)
+
+## Mermaid
+
+You can use [Mermaid](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid) plugin to draw and preview diagrams in your content.
+
+## 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).
+
+![diagram-drawio-demo](../../assets/images/diagram-drawio-demo.drawio.svg)
+
+### Using Draw.io
+
+1. Install [Draw.io](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio) VS Code extension.
+2. Create a new `*.drawio.svg` or `*.drawio.png` file.
+3. Start drawing your diagram. Once you done, save it.
+4. Embed the diagram file as you embedding the image file, for example: `![My Diagram](my-diagram.drawio.svg)`

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

@@ -0,0 +1,38 @@
+# How to Write Recipes
+
+This is an example of how to structure a Recipe. The first paragraph or two should explain the purpose of the recipe succinctly, including why it's useful, if that's not obvious.
+
+Recipes are intended to document:
+
+- How to use Foam's basic features
+- Power user pro-tips
+- Useful customisations of the default Foam environment
+- Integrations with third party tools and extensions (should be listed below)
+
+## Required Extensions
+
+- **[Hacker Typer](https://marketplace.visualstudio.com/items?itemName=jevakallio.vscode-hacker-typer)** (not really required for this recipe, just an example)
+- [Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode) (installed by default)
+
+The first section should be a bulleted list of extensions required to use this recipe. At a minimum, this section should list all additional, non-standard extensions.
+
+Ideally, you should also note which Foam [[recommended-extensions]] are responsible for providing this feature, so any issue reports can be directed to the correct repositories.
+
+When creating new recipes, if you don't know which extension does what, you can leave it out.
+
+## Instructions
+
+Here we describe how the extension should be used.
+
+![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.
+
+That's pretty much it!
+
+## How to contribute
+
+You can add [[recipes]] by creating a pull request to [foambubble/foam](https://github.com/foambubble/foam) on GitHub.
+
+Read more in our [[contribution-guide]].
+

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

@@ -0,0 +1,18 @@
+# Make Backlinks More Prominent
+
+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)
+
+In the future we'll want to improve this feature by
+
+- [[materialized-backlinks]]
+- Providing more context around back link reference
+  - Could be done by tweaking Markdown Notes slightly. Maybe a user setting?
+- Make back links editable using [VS Code Search Editors](https://code.visualstudio.com/updates/v1_43#_search-editors)
+  - [Suggested by @Jash on Discord](https://discordapp.com/channels/729975036148056075/729978910363746315/730999992419876956)
+

docs/recipes/markup-converter.md

@@ -0,0 +1,43 @@
+# Markup Converter
+
+This #recipe allows you to convert any document into Markdown for storing them in your notes.
+
+We will be using [Pandoc](https://pandoc.org/), a popular universal document converter. It can convert documents in Microsoft Word, HTML, LaTeX, and many other formats to various formats including markdown and many others.
+
+## Instructions
+
+We will go through the example of converting Microsoft Word documents to Markdown. For detailed instructions on how to use Pandoc, please refer to the [Pandoc documentation](https://pandoc.org/MANUAL.html).
+
+1. [Install Pandoc](https://pandoc.org/installing.html)
+1. Open the terminal of your choice and verify that Pandoc is installed by running `pandoc --version`
+1. Copy the Microsoft Word documents that you want to convert into a new folder
+1. Change the current directory to the folder containing the Microsoft Word documents
+1. Copy one of the following commands (based on your operating system) into your terminal and press `Enter` to run
+
+### Linux and macOS (Bash)
+
+```bash
+find -name "*.docx" -type f -exec sh -c '
+      for f; do
+         pandoc --extract-media=./ -f docx -t markdown -o "${f%.*}.md" "$f"
+      done
+   ' find-sh {} +
+```
+
+### Windows (PowerShell)
+
+```powershell
+Get-ChildItem . -Filter *.docx | 
+Foreach-Object {
+    pandoc --extract-media=./ --from docx --to markdown $_ -o $_.Name.Replace('.docx', '.md')
+}
+```
+
+### Relevant Configurations
+
+[Pandoc](https://pandoc.org/) accepts a range of command line arguments to control the conversion process. Here, we'll mention a few that are relevant to the example above.
+
+- `--extract-media=./` is used to extract the images from the Microsoft Word documents and store them in a subfolder named `media`
+- `-t markdown` converts the Microsoft Word documents to [Pandoc’s Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown). You can also use `-t gfm` to convert to [GitHub Flavored Markdown](https://docs.github.com/en/get-started/writing-on-github)
+
+Note that you may want to review the converted Markdown files to ensure that the conversion was successful. Then, You may want to delete the original Microsoft Word documents.

docs/recipes/migrating-from-obsidian.md

@@ -0,0 +1,6 @@
+# Migrating from Obsidian (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).
+

docs/recipes/migrating-from-onenote.md

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

docs/recipes/migrating-from-roam.md

@@ -0,0 +1,6 @@
+# Migrating from Roam (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).
+

docs/recipes/note-macros.md

@@ -0,0 +1,58 @@
+# Custom Note Macros
+
+This #recipe allows you to create custom note macros.
+
+## Installation
+
+**This extension is not included in the template**
+
+To install search note-macros in vscode or head to [note-macros - Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=NeelyInnovations.note-macros)
+
+## Instructions
+
+### Run macro From command pallette
+
+Simply use `Ctrl+P` or `Alt+P` depend on your os, and type `Note Macros: Run A Macro` then chose the macro you want to execute.
+
+### Create Custom Note Macros
+
+Create your own custom macros by adding them to your `settings.json` (Code|File > Preferences > User Settings). A full example can be found at [settings.json](https://github.com/kneely/note-macros/blob/master/settings.json)
+
+For example:
+
+This macro creates a Weekly note in the Weekly note Directory.
+
+```json
+{
+  "note-macros": {
+    "Weekly": [
+      {
+        "type": "note",
+        "directory": "Weekly",
+        "extension": ".md",
+        "name": "weekly-note",
+        "date": "yyyy-W"
+      }
+    ]
+  }
+}
+```
+
+For an explanation of the fields please go to [note-macros - Explanation of Fields](https://github.com/kneely/note-macros#explanation-of-fields)
+
+### Add Keybindings to Run your Macros
+
+in `keybindings.json` (Code|File > Preferences > Keyboard Shortcuts) add bindings to your macros:
+
+```json
+{
+  "key": "ctrl+cmd+/",
+  "command": "note-macros.Weekly"
+}
+```
+
+## Issues and Feedback
+
+If you have any issues or questions please look at the [README.md](https://github.com/kneely/note-macros#note-macros) on the [note-macros](https://github.com/kneely/note-macros) GitHub.
+
+If you run into any issues that are not fixed by referring to the README or feature requests please open an [issue](https://github.com/kneely/note-macros/issues).

docs/recipes/predefined-user-snippets.md

@@ -0,0 +1,50 @@
+# Pre-defined User Snippets
+
+This #recipe allows us to introduce Roam style commands to Foam, by using [VS Code Snippets](https://code.visualstudio.com/docs/editor/userdefinedsnippets). Consider the below snippets:
+
+```json
+{
+  "Zettelkasten Id": {
+    "scope": "markdown",
+    "prefix": "/id",
+    "description": "Zettelkasten Id",
+    "body": [
+      "${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE} ${CURRENT_HOUR}:${CURRENT_MINUTE}:${CURRENT_SECOND}"
+    ]
+  },
+  "Current date": {
+    "scope": "markdown",
+    "prefix": "/date",
+    "description": "Current date",
+    "body": [
+      "${CURRENT_YEAR}-${CURRENT_MONTH}-${CURRENT_DATE} ${CURRENT_HOUR}:${CURRENT_MINUTE}:${CURRENT_SECOND}"
+    ]
+  }
+}
+```
+
+Which would look like:
+![GIF demonstrating User Snippets](../../assets/images/snippets.gif)
+
+Using snippets enables Foam users to add [[custom-snippets]] themselves so they live alongside the first-class `/commands`.
+
+## Notes & Considerations
+
+- VS Code supplies "commands" already via the command palette
+  - Consider the UX around this. Users less familiar with VS Code are more likely to be familiar with `/` to trigger a command menu. Experienced VS Code users may be more likely to favour the command palette.
+- We can use `TabCompletionProvider` and `snippets` and mix them (maybe) via the following VS Code setting: `"editor.snippetSuggestions": "inline" | "top" | "bottom" | "none"`
+- For more discussion, consult the PR [here](https://github.com/foambubble/foam/pull/192).
+
+## Simplifying Markdown Syntax
+
+Some markdown syntax is difficult for users who have never authored markdown before. Take for example a checkbox/todo. The following syntax is required:
+
+```
+- [ ] Something todo...
+```
+
+We could provide snippets that expand out into the associated markdown syntax, like in the below GIF:
+![GIF demonstrating markdown snippets](../../assets/images/markdown-snippets.gif)
+
+The JSON for these snippets can be found [here](https://github.com/foambubble/foam/pull/192#issuecomment-666736270).
+

docs/recipes/real-time-collaboration.md

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

@@ -0,0 +1,108 @@
+<!-- omit in toc -->
+# Recipes
+
+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)
+- [Discover](#discover)
+- [Organise](#organise)
+- [Write](#write)
+- [Version control](#version-control)
+- [Publish](#publish)
+- [Collaborate](#collaborate)
+- [Workflow](#workflow)
+- [Creative ideas](#creative-ideas)
+- [Other](#other)
+
+## Contribute
+
+- Start by reading [[contribution-guide]]
+- If you discover features not listed here, we'd love to have them! [[how-to-write-recipes]].
+
+## Take smart notes
+
+- Introduction to Zettelkasten [[todo]]
+- Clip webpages with [[web-clipper]]
+- Convert Microsoft Word files into Markdown with [[markup-converter]]
+
+## Discover
+
+- Explore your notes using [[graph-visualization]]
+- Discover relationships with [[backlinking]]
+- Simulating [[unlinked-references]]
+
+## Organise
+
+- Using [[backlinking]] for reference lists.
+
+## Write
+
+- Link documents with [[wikilinks]].
+- Use shortcuts for [[creating-new-notes]]
+- Instantly create and access your [[daily-notes]]
+- Add and explore [[tags]]
+- Create [[note-templates]]
+- Find [[orphans]]
+- 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 [[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
+  - Automatic Table of Contents
+  - Live preview markdown
+  - _More..._
+- VS Code Advanced Features [[todo]] [[good-first-task]]
+  - Focus with Zen Mode
+- Display content of other notes in the preview tab by [[including-notes]]
+
+## Version control
+
+- Quick commits with VS Code's built in [[git-integration]]
+- Store your workspace in an auto-synced GitHub repo with [[write-your-notes-in-github-gist]]
+- Sync your GitHub repo automatically using the [GitDoc VSCode Plugin](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.gitdoc) [[automatic-git-syncing]].
+
+## Publish
+
+- Publish using official Foam template
+  - 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
+  - [[publish-to-netlify-with-eleventy]] by [@juanfrank77](https://github.com/juanfrank77)
+  - [[generate-gatsby-site]] by [@mathieudutour](https://github.com/mathieudutour) and [@hikerpig](https://github.com/hikerpig)
+  - [foamy-nextjs](https://github.com/yenly/foamy-nextjs) by [@yenly](https://github.com/yenly)
+- Make the site your own by [[publish-to-github]].
+- Render math symbols, by either
+  - 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
+
+- Give your team push access to your [GitHub repo](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/inviting-collaborators-to-a-personal-repository)
+- Real-time collaboration via VS Code Live Share [[real-time-collaboration]]
+- Accept patches via GitHub PRs [[todo]]
+
+## Workflow
+
+- Capture notes from Drafts app on iOS [[capture-notes-with-drafts-pro]]
+- Capture notes from iOS Shortcuts [[capture-notes-with-shortcuts-and-github-actions]]
+
+## Creative ideas
+
+Creative ideas welcome!
+
+- Support [Anki](https://apps.ankiweb.net/) cards from notes like [Remnote](https://www.remnote.io/) [[todo]]
+
+_See [[contribution-guide]] and [[how-to-write-recipes]]._
+
+## Other
+
+Thought of a recipe but don't see a category for them? Add them here and we'll organise them once we detect a theme.
+
+_See [[contribution-guide]] and [[how-to-write-recipes]]._
+

docs/recipes/search-for-notes.md

@@ -0,0 +1,10 @@
+# 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' )
+
+Run `Cmd` + `Shift` + `F` ( `Ctrl` + `Shift` + `F` on Windows ) and type a word (like 'links') to find all the notes that contain that term.
+

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

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

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

@@ -0,0 +1,60 @@
+# Take notes on mobile phones
+
+This #recipe offers solutions to taking Foam notes on the go.
+
+For the time being we have decided to not build a mobile app, but rely on third parties (see [[build-vs-assemble]]).
+
+The most promising options are:
+
+### [GitJournal](https://gitjournal.io/)
+
+Pros
+
+- Open source
+- Already a usable solution.
+- Provides functionality to edit, create, and browser markdown files.
+- Support journal mode, todo lists, and free writing
+- Syncs to GitHub repo
+- Supports Wikilinks
+- Supports Backlinks
+- Developer is happy to prioritize Foam compatibility
+
+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?
+
+- Taking notes on the go is a key part of a good note taking process, and the process should feel effortless
+- Having a custom app could help us support key user workflows in a more Foam-specific manner
+
+If such an app was worth building, it would have to have the following features:
+
+- Instant loading and syncing for quick notes
+- Sleek, simple, beautifully designed user experience.
+- Ability to search and navigate forward links and back links (onlly in paid GitJournal version)
+- Killer feature that makes it the best note taking tool for Foam (?)
+
+Given the effort vs reward ratio, it's a low priority for core team, but if someone wants to work on this, we can provide support! Talk to us on the #mobile-apps channel on [Foam Discord](https://foambubble.github.io/join-discord/w).
+

docs/recipes/web-clipper.md

@@ -0,0 +1,14 @@
+# 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.
+
+- [Web Clipper](https://clipper.website/)
+  - A Firefox, Chrome and Edge extension to clip websites and save them directly to the GitHub repository into a readable markdown file.

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

@@ -0,0 +1,55 @@
+# Write your notes in GitHub Gist
+
+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" />
+
+## Getting started
+
+To start using GistPad for your Foam-based knowledge base, simply perform the following steps:
+
+1. Download the [GistPad extension](https://aka.ms/gistpad) and then re-start Visual Studio Code
+
+1. Run the `GistPad: Sign In` command and then complete the authentication flow using your GitHub account
+
+1. Run the `GistPad: Open Repository` command and select the `Create repo from template...` or `Create private repo from template...` depending on your preference
+
+1. Select the `Foam-style wiki` template, and then specify a name for your Foam workspace (e.g. `my-foam-notes`, `johns-knowledge-base`)
+
+Your new repo will be created in your GitHub account, and the `Foam` welcome page will be automatically opened. If you already have an existing Foam workspace in GitHub, then when you run step #3 above, simply select or specify the name of the GitHub repository instead.
+
+> Note: If you have any and all feedback on how GistPad can be improved to support your Foam workflow, please don't hesitate to [let us know](https://github.com/vsls-contrib/gistpad)! 👍
+
+<img width="700px" src="https://user-images.githubusercontent.com/116461/87863222-c1b76180-c90d-11ea-87d9-04bee1c58a0d.png" />
+
+## Managing your workspace
+
+Once you've opened/created the Foam repository, it will appear in the `Repositories` view of the `GistPad` tab (the one with the little notebook icon). From this tree view, you can add/edit/delete/rename new pages, upload local files, as well as view the backlinks for each page (they appear as child notes of a page).
+
+<img width="250px" src="https://user-images.githubusercontent.com/116461/87234704-83a7c400-c388-11ea-90a8-2a660bef4dc5.png" />
+
+## Editing your workspace
+
+When you create or open a page, you can edit the markdown content as usual, as well as [paste images](https://github.com/vsls-contrib/gistpad#pasting-images-1), and create [`[[links]]` to other pages](https://github.com/vsls-contrib/gistpad#links). When you type `[[`, you'll receive auto-completion for the existing pages in your workspace, and you can also automatically create new pages by simply creating a link to it.
+
+Since you're using the Visual Studio Code markdown editor, you can benefit from all of the rich language services (e.g. syntax highlighting, header collapsing), as well as the extension ecosystem (e.g. [Emojisense](https://marketplace.visualstudio.com/items?itemName=bierner.emojisense)).
+
+## Navigating your workspace
+
+When editing a file, you can easily navigate `[[links]]` by hovering over them to see a preview of their contents and/or `cmd+clicking` on them in order to jump to the respective page. Furthermore, when you add a link to a page, a [backlink](https://github.com/vsls-contrib/gistpad#backlinks) is automatically added to it.
+
+You can view a page's backlinks using either of the following techniques:
+
+1. Expanding the file's node in the `Repositories` tree, since it's child nodes will represent backlinks. This makes it easy to browse your pages and their backlinks in a single hierachical view.
+
+1. Opening a file, and then viewing it's backlinks list at the bottom of the editor view. This makes it easy to read a page and then see its backlinks in a contextually rich way.
+
+## Daily Pages
+
+In addition to creating arbitrary pages, you can use GistPad for journaling or capturing [daily notes](https://github.com/vsls-contrib/gistpad#daily-pages). Simply click the calendar icon in the `Repositories` tree, which will open up the page that represents today. If the page doesn't already exist, then it will be created in the workspace before being opened.
+
+<img width="700px" src="https://user-images.githubusercontent.com/116461/87234721-b356cc00-c388-11ea-946a-e7f9c92258a6.png" />