Initial commit

docs/features/daily-notes.md

@@ -0,0 +1,42 @@
+# 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 automatically open today's note via the `Foam › Open Daily Note: On Startup` setting.
+
+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/daily-note-2020-07-25.mdx`, with the heading `Journal Entry, Sunday, July 25`.

docs/features/graph-visualization.md

@@ -0,0 +1,38 @@
+# 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 its connections
+
+## Custom Graph Styles
+
+By default, the Foam graph will use the VS Code 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 [[wikilinks]] 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

docs/features/link-reference-definitions.md

@@ -0,0 +1,31 @@
+# Link Reference Definitions
+
+When you use `[[wikilinks]]`, the [foam-vscode](https://github.com/foambubble/foam/tree/master/packages/foam-vscode) extension can 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 `[[wikilinks]]` directly.
+
+This feature can be disabled by default (as it's done in the foam-template) because you don't need it to navigate your workspace, it is useful for publishing and compatibility of your notes.
+
+## 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.

docs/features/note-properties.md

@@ -0,0 +1,30 @@
+---
+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:
+
+```text
+---
+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]])

docs/features/note-templates.md

@@ -0,0 +1,7 @@
+# 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 [VS Code Snippets](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_variables).

docs/features/spell-checking.md

@@ -0,0 +1,17 @@
+# Spell Checking
+
+Foam comes 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 VS Code.
+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,22 @@
+---
+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]].

docs/features/wikilinks.md

@@ -0,0 +1,13 @@
+# Wikilinks
+
+Wikilinks are the internal links that connect the files in your knowledge base.
+
+To create a wikilink 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 wikilink that doesn't have a target file and a link to a placeholder is styled differently so you can easily tell them apart.
+They can still be helpful to highlight connections.
+
+Open the graph with `Foam: Show Graph` command, and look at the placeholder node.
+
+Remember, with `CTRL/CMD+click` on a wikilink you can navigate to the note, or create it (if the link is a placeholder).

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

@@ -0,0 +1,43 @@
+# Getting started with VS Code
+
+VS Code is a powerful text editor, hidden behind a simple interface.
+
+VS Code 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 [VS Code 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 VS Code 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 VS Code site](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette).
+
+If you want to learn more about VS Code, 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 VS Code, press `cmd+,`

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

@@ -0,0 +1,14 @@
+# 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/shortcut-list.md

@@ -0,0 +1,13 @@
+# Shortcut-List
+
+You can use either the name or the id to find each shortcut in the settings (File > Preferences > Keyboard Shortcuts) and find out what it is bound to on your system and change it according to your liking.
+
+| Shortcut       | Name            | ID                                      | Extension           | Use                                 |
+| -------------- | --------------- | --------------------------------------- | ------------------- | ----------------------------------- |
+| `alt+c`        | \-              | markdown.extension.checkTaskList        | Markdown All in One | Toggle TODO items.                  |
+| `cmd+b`        | \-              | markdown.extension.editing.toggleBold   | Markdown All in One | Make selection bold.                |
+| `cmd+i`        | \-              | markdown.extension.editing.toggleItalic | Markdown All in One | Make selection italic.              |
+| `ctrl+shift+f` | Format Document | editor.action.formatDocument            | Base                | Format tables                       |
+| `cmd+shift+f`  | Find files      | workbench.action.findInFiles            | Base                | Search in workspace.                |
+| `cmd+shift+e`  | Show Explorer   | workbench.view.explorer                 | Base                | Show the file explorer.             |
+| `cmd+alt+v`    | Paste Image     | extension.pasteImage                    | Paste Image         | Paste an image from your clipboard. |

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

@@ -0,0 +1,44 @@
+# Use Keyboard Shortcuts for Editing
+
+Here are some keyboard shortcuts you'll love when editing your notes.
+>If you are not on mac or are using non-default shortcuts you can check the [[shortcut-list]] for each shortcut used in this note!
+
+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,69 @@
+# 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 wikilink (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
+
+```text
+you can create
+code blocks
+```