Added onboarding and major changes to template (#28)

* removed gitlens

* adjusted various settings

* added foam onboarding to template

* removed prettier extension

* added setting to match OS color scheme

* a couple of minor changes re todos and readme

* added spellright to list of recommended extensions, and added to getting started guide

* added reference to LTeX in spell checking doc

* Added logo to readme

* fixed link to LTeX extension

* styling logo in readme

* more style experiments

.vscode/extensions.json

@@ -5,12 +5,6 @@
     // Foam's own extension
     "foam.foam-vscode",
 
-    // Prettier for auto formatting code
-    "esbenp.prettier-vscode",
-
-    // GitLens for seeing version history inline
-    "eamodio.gitlens",
-
     // Tons of markdown goodies (lists, tables of content, so much more)
     "yzhang.markdown-all-in-one",
 
@@ -18,6 +12,9 @@
     "kortina.vscode-markdown-notes",
 
     // Image-pasting for markdown
-    "mushan.vscode-paste-image"
+    "mushan.vscode-paste-image",
+
+    // Spell checking for text, markdown and latex
+    "ban.spellright",
   ]
 }

.vscode/settings.json

@@ -1,5 +1,4 @@
 {
-  "prettier.singleQuote": false,
   "editor.minimap.enabled": false,
   "editor.wrappingIndent": "indent",
   "editor.overviewRulerBorder": false,
@@ -7,8 +6,6 @@
   "[markdown]": {
     "editor.quickSuggestions": true
   },
-  "git.enableSmartCommit": true,
-  "git.postCommitCommand": "sync",
   "files.defaultLanguage": "markdown",
   "files.exclude": {
     "**/node_modules": true
@@ -16,11 +13,17 @@
   "files.watcherExclude": {
     "**/node_modules": true
   },
-  "vscodeMarkdownNotes.noteCompletionConvention": "noExtension",
-  "vscodeMarkdownNotes.slugifyMethod": "github-slugger",
   "foam.edit.linkReferenceDefinitions": "withExtensions",
   "foam.openDailyNote.directory": "journal",
   "foam.openDailyNote.titleFormat": "fullDate",
-  "pasteImage.path": "${currentFileDir}/images/${currentFileNameWithoutExt}",
+  "git.enableSmartCommit": true,
-  "markdown.preview.breaks": true
+  "git.postCommitCommand": "sync",
+  "markdown.preview.breaks": true,
+  "pasteImage.path": "${projectRoot}/attachments",
+  "pasteImage.showFilePathConfirmInputBox": true,
+  "prettier.singleQuote": false,
+  "spellright.notificationClass": "warning",
+  "vscodeMarkdownNotes.noteCompletionConvention": "noExtension",
+  "vscodeMarkdownNotes.slugifyMethod": "github-slugger",
+  "window.autoDetectColorScheme": true,
 }

.vscode/spellright.dict

@@ -0,0 +1 @@
+wikilink

docs/features/daily-notes.md

@@ -0,0 +1,44 @@
+# Daily Notes
+
+Daily notes allow you to quickly create and access notes for today.
+
+Try it out, run the `Foam: Open Daily Note` command.
+
+## Shortcuts and Snippets
+
+You can quickly open today's daily note by pressing `alt+d`.
+
+You can also quickly create link to your daily notes, in the configured format, using [snippets](https://code.visualstudio.com/docs/editor/userdefinedsnippets).
+
+Type `/today` and press `enter` to link to today's note.
+You can also write:
+
+| Snippet      | Date          |
+| ------------ | ------------- |
+| `/tomorrow`  | tomorrow      |
+| `/yesterday` | yesterday     |
+| `/monday`    | next monday   |
+| `/+1d`       | tomorrow      |
+| `/-3d`       | 3 days ago    |
+| `/+1w`       | in a week     |
+| `/-1m`       | one month ago |
+| `/+1y`       | in one year   |
+
+You get the idea ;)
+
+## Configuration
+
+It's possible to customize path and heading of your daily notes, by following the [dateformat masking syntax](https://github.com/felixge/node-dateformat#mask-options).
+The following properties can be used:
+```json
+  "foam.openDailyNote.directory": "journal",
+  "foam.openDailyNote.filenameFormat": "'daily-note'-yyyy-mm-dd",
+  "foam.openDailyNote.fileExtension": "mdx",
+  "foam.openDailyNote.titleFormat": "'Journal Entry, ' dddd, mmmm d",
+```
+
+The above configuration would create a file `journal/note-2020-07-25.mdx`, with the heading `Journal Entry, Sunday, July 25`.
+
+
+
+

docs/features/graph-visualization.md

@@ -0,0 +1,43 @@
+# Graph Visualization
+
+Foam comes with a graph visualization of your notes.
+To see the graph execute the `Foam: Show Graph` command.
+
+## Graph Navigation
+
+With the graph you can:
+- highlight a node by hovering on it, to quickly see how it's connected to the rest of your notes
+- select one or more (by keeping `shift` pressed while selecting) nodes by clicking on them, to better understand the structure of your notes
+- navigate to a note by clicking on it while pressing `ctrl` or `cmd`
+- automatically center the graph on the currently edited note, to immediately see it's connections
+
+## Custom Graph Styles
+
+By default the Foam graph will use the VsCode theme, but it's possible to customize it with the `foam.graph.style` setting.
+
+A sample configuration object is provided below, you can provide as many or as little configuration as you wish:
+
+```json
+"foam.graph.style": {
+    "background": "#202020",
+    "fontSize": 12,
+    "highlightedForeground": "#f9c74f",
+    "node": {
+        "note": "#277da1",
+        "placeholder": "#545454",
+        "feature": "green",
+    }
+}
+```
+
+- `note` defines the color for regular nodes
+- `placeholder` defines the color for links that don't match any existing note. This is a [[placeholder]] because no file with such name exists (see [[wiki-links]] for more info).
+- `feature` shows an example of how you can use note types to customize the graph. It defines the color for the notes of type `feature`
+  - see [[note-properties]] for details
+  - you can have as many types as you want
+
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[wiki-links]: wiki-links.md "Wiki Links"
+[note-properties]: note-properties.md "Note Properties"
+[//end]: # "Autogenerated link references"

docs/features/link-reference-definitions.md

@@ -0,0 +1,30 @@
+# Link Reference Definitions
+
+When you use `[[wiki-links]]`, the [foam-vscode](https://github.com/foambubble/foam/tree/master/packages/foam-vscode) extension will automatically generate [Markdown Link Reference Definitions](https://spec.commonmark.org/0.29/#link-reference-definitions) at the bottom of the file.
+
+This is done to make the content of the file compatible with various Markdown tools (e.g. parsers, static site generators, VS code plugins etc), which don't support `[[wiki-links]]` directly.
+
+## Example
+
+The following example:
+  ```md
+  - [[graph-visualization]]
+  ```
+...generates the following link reference definitions to the bottom of the file:
+  ```md
+  [graph-visualization]: graph-visualization "Graph Visualization"
+  ```
+
+## Configuration
+
+You can use the `foam.edit.linkReferenceDefinitions` to configure the definitions (see [[get-started-with-vscode]]):
+- `withoutExtensions` (default): this works better with certain web publishing tools (e.g. GitHub pages)
+- `withExtensions`: this works better with standard markdown-based tools (e.g GitHub web UI)
+- `off`: this disables the generation of definitions
+
+After changing the setting in your workspace, you can run the `Foam: Run Janitor (Experimental)` command to convert all existing definitions.
+
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[get-started-with-vscode]: ../how-to/get-started-with-vscode.md "Getting started with VsCode"
+[//end]: # "Autogenerated link references"

docs/features/note-properties.md

@@ -0,0 +1,34 @@
+---
+type: feature
+keywords: hello world
+---
+
+# Note Properties
+
+At the top of the file you can have a section where you define your properties.
+
+> Be aware that this section needs to be at the very top of the file to be valid
+
+For example, for this file, we have:
+```
+---
+type: feature
+keywords: hello world
+---
+```
+
+Those are properties.
+Properties can be used to organize your notes.
+
+## Special Properties
+Some properties have special meaning for Foam:
+- the `title` property will assign the name to the note that you will see in the graph, regardless of the filename or the first heading (also see how to [[write-notes-in-foam]])
+- the `type` property can be used to style notes differently in the graph (also see [[graph-visualization]])
+- the `tags` property can be used to add tags to a note (see [[tags-and-tag-explorer]])
+
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[write-notes-in-foam]: ../how-to/write-notes-in-foam.md "Writing Notes"
+[graph-visualization]: graph-visualization.md "Graph Visualization"
+[tags-and-tag-explorer]: tags-and-tag-explorer.md "Tags and Tag Explorer"
+[//end]: # "Autogenerated link references"

docs/features/note-templates.md

@@ -0,0 +1,8 @@
+# Note Templates
+
+You can create notes from templates by running the `Foam: Create New Note from Template` command and follow the instructions.
+
+To create a template, just add regular `.md` files in `.foam/templates` (create the directory if necessary).
+
+Templates can use all the variables available in [VsCode Snippets](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_variables).
+

docs/features/spell-checking.md

@@ -0,0 +1,16 @@
+# Spell Checking
+
+Foam come with a spell checker.
+
+Misspelled words are highlighted, like hellow.
+You can place the cursor on top of the word, and press `cmd+.` for suggestions on how to fix the problem.
+
+You can configure the extension in the settings, for example to:
+- ignore certain files
+- change the language(s)
+- and much more
+
+For more information go to the [Spellright extension page](https://marketplace.visualstudio.com/items?itemName=ban.spellright).
+
+There are many spell checking extensions for VsCode.
+Another one of our favorites is [LTeX](https://marketplace.visualstudio.com/items?itemName=valentjn.vscode-ltex&ssr=false#overview), which is a bit heavier but offers some extra functionality.

docs/features/tags-and-tag-explorer.md

@@ -0,0 +1,24 @@
+---
+tags: my-tag1 my-tag2
+---
+
+# Tags and Tag Explorer
+
+## Tags
+
+You can add tags to your notes to categorize them, or in any way you want.
+
+There are two ways to add tags:
+- you can add #tags just by writing them in the note
+- another way is through [[note-properties]], as you can see at the top of this file
+
+## Tag Explorer
+In the sidebar to the left, you will see a panel called `Tag Explorer`.
+
+You can use this panel to see the tags in your notes, and navigate them.
+
+Notice `my-tag1` and `my-tag2`, which were added via [[note-properties]].
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[note-properties]: note-properties.md "Note Properties"
+[//end]: # "Autogenerated link references"

docs/features/wiki-links.md

@@ -0,0 +1,14 @@
+# Wiki Links
+
+Wiki links are the internal links that connect the files in your knowledge base.
+
+To create a wiki link use `[[` and type the name of another file in your repo, for example [[graph-visualization]]
+
+You can also create a [[placeholder]].
+A placeholder is a wiki link that doesn't have a target file.
+They can still be helpful to highlight connections.
+Open the graph with `Foam: Show Graph` command, and look at the placeholder node.
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[graph-visualization]: graph-visualization.md "Graph Visualization"
+[//end]: # "Autogenerated link references"

docs/how-to/get-started-with-vscode.md

@@ -0,0 +1,46 @@
+# Getting started with VsCode
+
+VsCode is an powerful text editor, hidden behind a simple interface.
+
+## Keyboard shortcuts
+VsCode supports various **keyboard shortcuts**, the most important for us are:
+
+| Shortcut      | Action                       |
+| ------------- | ---------------------------- |
+| `cmd+N`       | create a new file            |
+| `cmd+S`       | save the current file        |
+| `cmd+O`       | open a file                  |
+| `cmd+P`       | use quickpick to open a file |
+| `cmd+shift+P` | invoke a command (see below) |
+
+For more information, see the [vscode keyboard cheat sheets](https://code.visualstudio.com/docs/getstarted/keybindings#_keyboard-shortcuts-reference), where you can also see how to customize your keybindings.
+
+## Commands
+Commands make VsCode extremely powerful.
+
+To invoke a command, press `cmd+shift+P` and select the command you want to execute.
+For example, to see the Foam graph:
+- press `cmd+shift+P`
+- start typing `show graph`
+- select the `Foam: Show Graph` command
+
+And watch the magic unfold.
+
+For more information on commands, see [commands on the VsCode site](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette).
+
+
+If you want to learn more about VsCode, check out their [website](https://code.visualstudio.com/docs#first-steps).
+
+## Panels
+
+You can see a few panels on the left, including:
+- `Outline`: this panel shows you the structure of the file based on the headings
+- `Tag Explorer`: This shows you the tags in your workspace, see [[tags-and-tag-explorer]] for more information on tags
+
+## Settings
+
+To view or change the settings in VsCode, press `cmd+,`
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[tags-and-tag-explorer]: ../features/tags-and-tag-explorer.md "Tags and Tag Explorer"
+[//end]: # "Autogenerated link references"

docs/how-to/paste-images-from-clipboard.md

@@ -0,0 +1,13 @@
+# Paste Images from Clipboard
+
+You can paste an image from the clipboard with `cmd+alt+v`.
+
+Images are automatically copied to the `/attachments` folder and a reference is added in the file where you pasted them.
+
+A prompt will ask you to confirm the name of the image, to disable it set   `"pasteImage.showFilePathConfirmInputBox": false,` in the settings.
+
+To change the location where the image is created, change the `pasteImage.path` property, e.g.:
+- `${currentFileDir}`: save the image next to the file
+- `${currentFileDir}/images`: create an `images` directory next to the file and save the image there
+
+For more info check the [vscode-paste-image](https://github.com/mushanshitiancai/vscode-paste-image) extension page.

docs/how-to/use-keyboard-shortcuts-for-editing.md

@@ -0,0 +1,43 @@
+# Use Keyboard Shortcuts for Editing
+
+Here are some keyboard shortcuts you'll love when editing your notes.
+
+This works best if you can see the result in the preview panel, run the `Markdown: Open Preview to the Side` command.
+
+- [ ] `alt+c` changes state to a TODO item. Try it while the cursor is on this line.
+
+---
+
+- [ ] `cmd+b` makes the selection bold. Select me and make me bold.
+
+---
+
+- [ ] `cmd+i` makes the selection italic. Select me and make me italic.
+
+---
+
+- [ ] `alt+shift+f` formats a table. Place the cursor in the table below and format the table.
+
+| column 1 | column 2|
+|-|-|
+| one element | another element|
+| second row| last cell|
+
+---
+
+- [ ] Paste link on selected text
+  1. copy the following text: https://google.com
+  2. select me and paste
+
+---
+
+- [ ] Search in your repo with `cmd+shift+f`: type "search"
+  - (go back to the file explorer with `cmd+shift+e`)
+
+---
+
+- [ ] Paste an image
+  1. copy an image
+  2. move your cursor to the next line, then press `cmd+alt+v` and confirm the name of the file
+  3. .
+  4. the image file has been created in `/attachments` and a reference to it has been added here

docs/how-to/write-notes-in-foam.md

@@ -0,0 +1,73 @@
+# Writing Notes
+
+Notes are simple text files with some extra flavor, in the shape of Markdown syntax and support for extra properties (see [[note-properties]]).
+
+## Foam Syntax
+
+Foam uses standard markdown, with a few added twists:
+- the title of a note (e.g. in the [[graph-visualization]]) is given by precedence based on:
+  - the `title` property (see [[note-properties]])
+  - the first `# heading 1`  of the file
+  - the file name
+
+
+## Markdown Syntax
+With markdown we can style our notes in a simple way, while keeping the document a simple text file (the best way to future-proof your writings!).
+
+You can see the formatted output by running the `Markdown: Open Preview to the Side` command.
+
+Here is a high level overview of Markdown, for more information on the markdown syntax [see here](https://commonmark.org/help/).
+
+# Heading 1
+
+## Heading 2
+
+### Heading 3
+
+#### Heading 4
+
+##### Heading 5
+
+###### Heading 6
+
+This is a [link to google](https://www.google.com).
+
+This is a wiki link (aka internal link) to [[note-properties]].
+
+Here is an image:
+![image](../../attachments/foam-icon.png)
+
+> this is a blockquote
+> it can span multiple lines
+
+- list item
+- list item
+- list item
+
+1. One
+2. Two
+3. Three
+
+This text is **in bold** and this is *italic*.
+
+The following is a horizontal rule
+
+---
+
+This is a table:
+| Column 1 | Column 2 |
+| -------- | -------- |
+| R1C1     | R1C2     |
+| R2C1     | R2C2     |
+
+You can `inline code` or
+```
+you can create
+code blocks
+```
+
+
+[//begin]: # "Autogenerated link references for markdown compatibility"
+[note-properties]: ../features/note-properties.md "Note Properties"
+[graph-visualization]: ../features/graph-visualization.md "Graph Visualization"
+[//end]: # "Autogenerated link references"

getting-started.md

@@ -2,34 +2,59 @@
 
 Welcome to your new foam workspace, let's get you started.
 
+> if you are already familiar with Foam and don't need help, just remove the `docs` folder for a clean repo.
+
 Let's go through this to set up your repo:
 
-- [ ] you can navigate the links between your notes by `cmd+click` (or `ctrl+click` on Windows) on a wikilink. Here, go to your [[inbox]]
+- [ ] if you are new with VsCode, see how to [[get-started-with-vscode]] and how to [[use-keyboard-shortcuts-for-editing]]
 
-- [ ] to see how your notes are connected, execute the `Foam: Show Graph` command
+- [ ] you can navigate the links between your notes by `cmd+click` (or `ctrl+click` on Windows) on a wiki link. You can go back with `ctrl+-`. Here, go to your [[inbox]]
-  - **tip** - `cmd+click` on a node to navigate to it
-  - **tip** - keep the graph open. As you navigate your files, it will focus on the active note, so you can at a glance see how it's connected in your knowledge base
 
-- [ ] #tags can be used to further organize your content. Look at the `Tag Explorer` view on the left panel to find and navigate the tags in your knowledge base
+- [ ] to see how your notes are connected, execute the `Foam: Show Graph` command. See [[graph-visualization]].
 
-- [ ] You can use Foam for your daily notes, or journaling. Execute now the `Foam: Open Daily Note` command to create a new file in your `journal` folder.
+- [ ] #tags can be used to further organize your content. Look at the `Tag Explorer` view on the left panel to find and navigate the tags in your knowledge base. See [[tags-and-tag-explorer]].
-  - **tip** - you can customize location, filename and note title for you daily notes in the settings
 
-- [ ] The section at the end of this file contains [wikilink definitions](https://foambubble.github.io/foam/features/link-reference-definitions), which enable navigation of your notes from GitHub's web UI, and in general to make `[[wikilinks]]` understood by any markdown parser.
+- [ ] Foam supports [[spell-checking]].
-  - **tip** - Foam will sync links and definitions  whenever you save the file
-  - **tip** - If you are just using foam in VsCode you can turn off wikilink definitions in your VsCode settings
 
-- [ ] You can also paste images in your Foam, just press `cmd+alt+v` to create the image file and link to it from your note
+- [ ] You can also paste images in your Foam, just press `cmd+alt+v` to create the image file and link to it from your note. See [[paste-images-from-clipboard]].
+
+- [ ] You can use Foam for your daily notes, or journaling. Execute now the `Foam: Open Daily Note` command to create a new file in your `journal` folder. See [[daily-notes]].
 
 - [ ] Want to see how to manage your tasks? Go to the [[todo]] note
 
+- [ ] The section at the end of this file contains wikilink definitions, which enable navigation of your notes from GitHub's web UI, and in general to make `[[wikilinks]]` understood by any markdown parser. See [[link-reference-definitions]].
+
 - [ ] To explore all the Foam settings, press `cmd+,`, then `Extensions > Foam`
 
 - [ ] Living within VsCode, Foam can be customized in many ways! Look at the [Foam Recipes](https://foambubble.github.io/foam/recipes/recipes) for ideas!
 
 - [ ] Join the [Foam community on Discord](https://discord.gg/HV2tn2FpEk), introduce yourself and leave a message on how you found Foam and how the onboarding went :) We are always keen to do better
 
+## Advanced Features
+
+- [ ] You can create [[note-templates]] for things like book reviews, people, daily notes (coming soon), and more!
+
+## About Foam
+
+Foam doesn't do all this magic on its own, it relies on some amazing extensions. Look at their documentation if you want to fully unlock the possibilities!
+
+Here they are:
+- [Markdown All In One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one)
+- [Markdown Notes](https://marketplace.visualstudio.com/items?itemName=kortina.vscode-markdown-notes)
+- [vscode-paste-image](https://github.com/mushanshitiancai/vscode-paste-image)
+
+A special mention to [Markdown Links](https://marketplace.visualstudio.com/items?itemName=tchayen.markdown-links), which has now been replaced by our graph but was foundational to Foam's beginnings.
+
 [//begin]: # "Autogenerated link references for markdown compatibility"
+[get-started-with-vscode]: docs/how-to/get-started-with-vscode.md "Getting started with VsCode"
+[use-keyboard-shortcuts-for-editing]: docs/how-to/use-keyboard-shortcuts-for-editing.md "Use Keyboard Shortcuts for Editing"
 [inbox]: inbox.md "Inbox"
+[graph-visualization]: docs/features/graph-visualization.md "Graph Visualization"
+[tags-and-tag-explorer]: docs/features/tags-and-tag-explorer.md "Tags and Tag Explorer"
+[spell-checking]: docs/features/spell-checking.md "Spell Checking"
+[paste-images-from-clipboard]: docs/how-to/paste-images-from-clipboard.md "Paste Images from Clipboard"
+[daily-notes]: docs/features/daily-notes.md "Daily Notes"
 [todo]: todo.md "Todo"
+[link-reference-definitions]: docs/features/link-reference-definitions.md "Link Reference Definitions"
+[note-templates]: docs/features/note-templates.md "Note Templates"
 [//end]: # "Autogenerated link references"

inbox.md

@@ -12,5 +12,5 @@
   - You can always find them in your git history, if you really need it!
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
-[todo]: todo "Todo"
+[todo]: todo.md "Todo"
 [//end]: # "Autogenerated link references"

readme.md

@@ -1,6 +1,8 @@
+<img src="attachments/foam-icon.png" width=100 align="left">
+
 # Foam
 
-👋 Welcome to your new Foam Knowledge Base!
+**👋 Welcome to your new Foam Knowledge Base!**
 
 ## Getting started
 
@@ -24,10 +26,11 @@ And remember that you can always join our  [Foam community on Discord](https://d
 
 We've created a few Bubbles (markdown documents) to get you started.
 
-- [[inbox]] - a place to write down quick notes to be categorised later
+- [[inbox]] - a place to write down quick notes to be categorized later
 - [[getting-started]] - learn how to use your Foam workspace
 - [[todo]] - a place to keep track of things to do
 
+In the `docs` directory you can find everything you need to learn the basics of Foam.
 
 
 [//begin]: # "Autogenerated link references for markdown compatibility"

todo.md

@@ -1,9 +1,9 @@
 # Todo
 
+You can create todos in Foam.
+
 - [x] This is an example of a todo list item that's complete
-- [x] Todo lists are useful for keeping organised and focused
 - [ ] This one is not completed yet
 - [ ] You can mark it completed by pressing `Option`+`C` (or `Alt`+`C`) when your cursor is on this line
   - [ ] You can also select multiple lines and mark them all at once!
-- [ ] When you press enter at the end of a line, it adds a new todo item on the next line
+
-- [ ] This, and more is provided by the [Markdown All in One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one) plugin by [Yu Zhang](https://github.com/yzhang-gh)