ben/homefoam
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Riccardo
2023-03-22 10:59:54 -06:00
committed by GitHub
parent ab5d214535
commit c2e89638cc
59 changed files with 2276 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/features/backlinking.md Normal file
View File

@ -0,0 +1,9 @@
# Backlinking
When using [[wikilinks]], you can find all notes that link to a specific note in the **Backlinks Explorer**
- Run `Cmd` + `Shift` + `P` (`Ctrl` + `Shift` + `P` for Windows), type "backlinks" and run the **Explorer: Focus on Backlinks** view.
- Keep this pane always visible to discover relationships between your thoughts
- You can drag the backlinks pane to a different section in VS Code if you prefer. See: [[make-backlinks-more-prominent]]
- Finding backlinks in published Foam workspaces via [[materialized-backlinks]] is on the [[roadmap]] but not yet implemented.

73
docs/features/commands.md Normal file
View File

@ -0,0 +1,73 @@
# Foam Commands
Foam has various commands that you can explore by calling the command palette and typing "Foam".
In particular, some commands can be very customizible and can help with custom workflows and use cases.
## foam-vscode.create-note command
This command creates a note.
Although it works fine on its own, it can be customized to achieve various use cases.
Here are the settings available for the command:
- notePath: The path of the note to create. If relative it will be resolved against the workspace root.
- templatePath: The path of the template to use. If relative it will be resolved against the workspace root.
- title: The title of the note (that is, the `FOAM_TITLE` variable)
- text: The text to use for the note. If also a template is provided, the template has precedence
- variables: Variables to use in the text or template
- date: The date used to resolve the FOAM*DATE*\* variables. in `YYYY-MM-DD` format
- onFileExists?: 'overwrite' | 'open' | 'ask' | 'cancel': What to do in case the target file already exists
To customize a command and associate a key binding to it, open the key binding settings and add the appropriate configuration, here are some examples:
- Create a note called `test note.md` with some text. If the note already exists, ask for a new name
```
{
"key": "alt+f",
"command": "foam-vscode.create-note",
"args": {
"text": "test note ${FOAM_DATE_YEAR}",
"notePath": "test note.md",
"onFileExists": "ask"
}
}
```
- Create a note following the `weekly-note.md` template. If the note already exists, open it
```
{
"key": "alt+g",
"command": "foam-vscode.create-note",
"args": {
"templatePath": ".foam/templates/weekly-note.md",
"onFileExists": "open"
}
}
```
## foam-vscode.open-resource command
This command opens a resource.
Normally it receives a `URI`, which identifies the resource to open.
It is also possible to pass in a filter, which will be run against the workspace resources to find one or more matches.
- If there is one match, it will be opened
- If there is more than one match, a quick pick will show up allowing the user to select the desired resource
Examples:
```
{
"key": "alt+f",
"command": "foam-vscode.open-resource",
"args": {
"filter": {
"title": "Weekly Note*"
}
}
}
```

31
docs/features/custom-markdown-preview-styles.md Normal file
View File

@ -0,0 +1,31 @@
# Custom Markdown Preview Styles
Visual Studio Code allows you to use your own CSS in the Markdown preview tab.
## Instructions
Custom CSS for the Markdown preview can be implemented by using the `"markdown.styles": []` setting in `settings.json`. The stylesheets can either be https URLs or relative paths to local files in the current workspace.
For example, to load a stylesheet called `Style.css`, we can update `settings.json` with the following line:
```
{
"markdown.styles": ["Style.css"]
}
```
## Foam elements
### Foam note & placeholder links
It is possible to custom style the links to a note or placeholder. The links are an `<a>` tag. For notes use the class `foam-note-link`, for placeholders use `foam-placeholder-link`.
### Cyclic inclusion warnings
Foams offers the functionality to include other notes in your note. This will be displayed in the preview tab. Foam recognises a cyclic inclusion of notes and will display a warning when detected. The following html is used and can be custom styled using the class `foam-cyclic-link-warning`.
```html
<div class="foam-cyclic-link-warning">
Cyclic link detected for wikilink: ${wikilink}
</div>
```

10
docs/features/custom-snippets.md Normal file
View File

@ -0,0 +1,10 @@
# Adding Custom Snippets
You can add custom snippets whilst the default set of snippets are decided by following the below steps:
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)
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).

31
docs/features/daily-notes.md
View File

@ -1,18 +1,20 @@
# Daily Notes
Daily notes allow you to quickly create and access notes for today.
Daily notes allow you to quickly create and access a new notes file for each day. This is a surpisingly effective and increasingly common strategy to organize notes and manage events.
Try it out, run the `Foam: Open Daily Note` command.
View today's note file by running the `Foam: Open Daily Note` command, by using the shortcut `alt+d` (note: shortcuts can be [overridden](https://code.visualstudio.com/docs/getstarted/keybindings)), or by using [#snippets](#Snippets). The name, location, and title of daily notes files is [#configurable](#Configuration).
## Shortcuts and Snippets
## Roam-style Automatic Daily Notes
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 automatically open today's note on startup by setting the `Foam › Open Daily Note: On Startup` setting to `true`.
You can also quickly create link to your daily notes, in the configured format, using [snippets](https://code.visualstudio.com/docs/editor/userdefinedsnippets).
## Daily Note Templates
Type `/today` and press `enter` to link to today's note.
You can also write:
Daily notes can also make use of [[Note Templates]], by defining a special `.foam/templates/daily-note.md` template.
## Snippets
Create a link to a recent daily note 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 |
| ------------ | ------------- |
@ -25,10 +27,12 @@ You can also write:
| `/-1m` | one month ago |
| `/+1y` | in one year |
You get the idea ;)
## Configuration
By default, Daily Notes will be created in a file called `yyyy-mm-dd.md` in the workspace's `journals` folder, with a heading `yyyy-mm-dd`.
These settings can be overridden in your workspace or global `.vscode/settings.json` file, using the [**dateformat** date masking syntax](https://github.com/felixge/node-dateformat#mask-options):
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:
@ -40,3 +44,10 @@ The following properties can be used:
```
The above configuration would create a file `journal/daily-note-2020-07-25.mdx`, with the heading `Journal Entry, Sunday, July 25`.
> NOTE: It is possible to set the filepath of a daily note according to the date using the special [[note-properties]] configurable for [[Note Templates]]. Specifically see [[note-templates#Example of date-based|Example of date-based filepath]]. Using the template property will override any setting configured through `.vscode/settings.json`.
## Extend Functionality (Weekly, Monthly, Quarterly Notes)
Please see [[note-macros]]

79
docs/features/graph-visualization.md
View File

@ -3,18 +3,34 @@
Foam comes with a graph visualization of your notes.
To see the graph execute the `Foam: Show Graph` command.
Your files, such as notes and documents, are shown as the nodes of the graph along with the tags defined in your notes. The edges of the graph represent either a link between two files or a file that contains a certain tag. A node in the graph will grow in size with the number of connections it has, representing stronger or more defined concepts and topics.
## Graph Navigation
With the graph you can:
With the Foam graph visualization 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`
- navigate to a note by clicking on it's node while pressing `ctrl` or `cmd`
- automatically center the graph on the currently edited note, to immediately see its connections
## Filter View
If you only wish to view certain types of notes or tags, or want to hide linked attachment nodes then you can apply filters to the graph.
- Open the graph view using the `Foam: Show Graph` command
- Click the button in the top right corner of the graph view that says "Open Controls"
- Expand the "Filter By Type" dropdown to view the selection of types that you can filter by
- Uncheck the checkbox for any type you want to hide
- The types displayed in this dropdown are defined by [[note-properties]] which includes Foam-standard types as well as custom types defined by you!
![Graph filtering demo](../../assets/images/graph-filter.gif)
## 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.
The Foam graph will use the current VS Code theme by default, but it's possible to customize it with the `foam.graph.style` setting.
![Graph style demo](../../assets/images/graph-style.gif)
A sample configuration object is provided below, you can provide as many or as little configuration as you wish:
@ -22,17 +38,64 @@ A sample configuration object is provided below, you can provide as many or as l
"foam.graph.style": {
"background": "#202020",
"fontSize": 12,
"lineColor": "#277da1",
"lineWidth": 0.2,
"particleWidth": 1.0,
"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).
- `background` background color of the graph, adjust to increase contrast
- `fontSize` size of the title font for each node
- `lineColor` color of the edges between nodes in the graph
- `lineWidth` thickness of the edges between nodes
- `particleWidth` size of the particle animation showing link direction when highlighting a node
- `highlightedForeground` color of highlighted nodes and edges when hovering over a node
- to style individual types of nodes jump to the next section: [Style Nodes By Type](#style-nodes-by-type)
### Style Nodes by Type
It is possible to customize the style of a node based on the `type` property in the YAML frontmatter of the corresponding document.
There are a few default node types defined by Foam that are displayed in the graph:
- `note` defines the color for regular nodes whose documents have not overriden the `type` property.
- `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 <!--NOTE: this placeholder link should NOT have an associated file. This is to demonstrate the custom coloring-->
- `tag` defines the color for nodes representing #tags, allowing tags to be used as graph nodes similar to backlinks.
- see [[tags]] 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
For example the following `backlinking.md` note:
```markdown
---
type: feature
---
# Backlinking
...
```
And the following `settings.json`:
```json
"foam.graph.style": {
"background": "#202020",
"node": {
"note": "#277da1",
"placeholder": "#545454",
"tag": "#f9c74f",
"feature": "red",
}
}
```
Will result in the following graph:
![Style node by type](../../assets/images/style-node-by-type.png)

16
docs/features/including-notes.md Normal file
View File

@ -0,0 +1,16 @@
# Including notes in a note
In some situations it might be useful to include the content of another note in your current note. Foam supports this displaying within the vscode environment. Note, this does not work out-of-the-box for your publishing solutions.
## Including a note
Including a note can be done by adding an `!` before a wikilink defintion. For example `![[wikilink]]`.
## Custom styling
Displaying the inclusion of notes allows for some custom styling, see [[custom-markdown-preview-styles]]
## Future possibilities
Work on this feature is evolving and progressing. See the [[inclusion-of-notes]] proposal for the current discussion.

77
docs/features/link-reference-definitions.md
View File

@ -1,31 +1,84 @@
# 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.
When you use `[[wikilinks]]`, the [foam-vscode](https://github.com/foambubble/foam/tree/master/packages/foam-vscode) extension can automatically generate [Markdown Link Reference Definitions](https://spec.commonmark.org/0.29/#link-reference-definitions) at the bottom of the file. This is not needed to navigate your workspace with foam-vscode, but is useful for files to remain compatible with various Markdown tools (e.g. parsers, static site generators, VS code plugins etc), which don't support `[[wikilinks]]`.
## Example
The following example:
```md
- [[graph-visualization]]
- [[wikilinks]]
- [[github-pages]]
```
...generates the following link reference definitions to the bottom of the file:
```md
[graph-visualization]: graph-visualization "Graph Visualization"
[wikilinks]: wikilinks "Wikilinks"
[github-pages]: github-pages "GitHub Pages"
```
You can open the [raw markdown](https://foambubble.github.io/foam/features/link-reference-definitions.md) to see them at the bottom of this file
## Specification
The three components of a link reference definition are `[link-label]: link-target "Link Title"`
- **link label:** The link text to match in the surrounding markdown document. This matches the inner bracket of the double-bracketed `[[wikilink]]` notation
- **link destination** The target of the matched link
- By default we generate links without extension. This can be overridden, see [Configuration](#configuration) below
- **"Link Title"** Optional title for link (The Foam template has a snippet of JavaScript to replace this on the website at runtime)
## Configuration
You can use the `foam.edit.linkReferenceDefinitions` to configure the definitions (see [[get-started-with-vscode]]):
You can choose to generate link reference definitions with or without file extensions, depending on the target, or to disable the generation altogether. As a rule of thumb:
- `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
- Links with file extensions work better with standard markdown-based tools, such as GitHub web UI.
- Links without file extensions work better with certain web publishing tools that treat links as literal urls and don't transform them automatically, such as the standard GitHub pages installation.
By default, Foam generates links without file extensions for legacy reasons, but this may change in future versions.
You can override this setting in your Foam workspace's `settings.json`:
- `"foam.edit.linkReferenceDefinitions": "withoutExtensions"` (default)
- `"foam.edit.linkReferenceDefinitions": "withExtensions"`
- `"foam.edit.linkReferenceDefinitions": "off"`
### Ignoring files
Sometimes, you may want to ignore certain files or folders, so that Foam doesn't generate link reference definitions to them.
There are three options for excluding files from your Foam project:
1. `files.exclude` (from VSCode) will prevent the folder from showing in the file explorer.
> "Configure glob patterns for excluding files and folders. For example, the file explorer decides which files and folders to show or hide based on this setting. Refer to the Search: Exclude setting to define search-specific excludes."
2. `files.watcherExclude` (from VSCode) prevents VSCode from constantly monitoring files for changes.
> "Configure paths or glob patterns to exclude from file watching. Paths or basic glob patterns that are relative (for example `build/output` or `*.js`) will be resolved to an absolute path using the currently opened workspace. Complex glob patterns must match on absolute paths (i.e. prefix with `**/` or the full path and suffix with `/**` to match files within a path) to match properly (for example `**/build/output/**` or `/Users/name/workspaces/project/build/output/**`). When you experience the file watcher process consuming a lot of CPU, make sure to exclude large folders that are of less interest (such as build output folders)."
3. `foam.files.ignore` (from Foam) ignores files from being added to the Foam graph.
> "Specifies the list of globs that will be ignored by Foam (e.g. they will not be considered when creating the graph). To ignore the all the content of a given folder, use `<folderName>/**/*`" (requires reloading VSCode to take effect).
For instance, if you're using a local instance of [Jekyll](https://jekyllrb.com/), you may find that it writes copies of each `.md` file into a `_site` directory, which may lead to Foam generating references to them instead of the original source notes.
You can ignore the `_site` directory by adding any of the following settings to your `.vscode/settings.json` file:
```json
"files.exclude": {
"**/_site": true
},
"files.watcherExclude": {
"**/_site": true
},
"foam.files.ignore": [
"_site/**/*"
]
```
After changing the setting in your workspace, you can run the [[workspace-janitor]] command to convert all existing definitions.
See [[link-reference-definition-improvements]] for further discussion on current problems and potential solutions.
After changing the setting in your workspace, you can run the `Foam: Run Janitor (Experimental)` command to convert all existing definitions.

40
docs/features/note-properties.md
View File

@ -1,30 +1,50 @@
---
type: feature
keywords: hello world
keywords: hello world, bonjour
tags: [hello, bonjour]
---
# Note Properties
At the top of the file you can have a section where you define your properties.
At the top of the file you can have a section where you define your properties. This section is known as the [Front-Matter](https://learn.cloudcannon.com/jekyll/introduction-to-jekyll-front-matter/) of the document and uses [YAML formatting](https://www.codeproject.com/Articles/1214409/Learn-YAML-in-five-minutes).
> Be aware that this section needs to be at the very top of the file to be valid
> Be aware that this YAML section needs to be at the very top of the file to be valid.
For example, for this file, we have:
```text
```markdown
---
type: feature
keywords: hello world
keywords: hello world, bonjour
---
```
Those are properties.
Properties can be used to organize your notes.
This sets the `type` of this document to `feature` and sets **three** keywords for the document: `hello`, `world`, and `bonjour`. The YAML parser will treat both spaces and commas as the seperators for these YAML properties. If you want to use multi-word values for these properties, you will need to combine the words with dashes or underscores (i.e. instead of `hello world`, use `hello_world` or `hello-world`).
> You can set as many custom properties for a document as you like, but there are a few [special properties](#special-properties) defined by Foam.
## 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]])
| Name | Description |
| -------------------- | ------------------- |
| `title` | 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]]) |
| `type` | can be used to style notes differently in the graph (also see [[graph-visualization]]). The default type for a document is `note` unless otherwise specified with this property. |
| `tags` | can be used to add tags to a note (see [[tags]]) |
For example:
```markdown
---
title: "Note Title"
type: "daily-note"
tags: daily, funny, planning
---
```
## Foam Template Properties
There also exists properties that are even more specific to Foam templates, see [[note-templates#Metadata]] for more info.

213
docs/features/note-templates.md
View File

@ -1,7 +1,216 @@
# Note Templates
You can create notes from templates by running the `Foam: Create New Note from Template` command and follow the instructions.
Foam supports note templates which let you customize the starting content of your notes instead of always starting from an empty note.
To create a template, just add regular `.md` files in `.foam/templates` (create the directory if necessary).
Note templates are `.md` files located in the special `.foam/templates` directory of your workspace.
## Quickstart
Create a template:
* Run the `Foam: Create New Template` command from the command palette
* OR manually create a regular `.md` file in the `.foam/templates` directory
![Create new template GIF](../../assets/images/create-new-template.gif)
_Theme: Ayu Light_
To create a note from a template:
* Run the `Foam: Create New Note From Template` command and follow the instructions. Don't worry if you've not created a template yet! You'll be prompted to create a new template if none exist.
* OR run the `Foam: Create New Note` command, which uses the special default template (`.foam/templates/new-note.md`, if it exists)
![Create new note from template GIF](../../assets/images/create-new-note-from-template.gif)
_Theme: Ayu Light_
## Special templates
### Default template
The `.foam/templates/new-note.md` template is special in that it is the template that will be used by the `Foam: Create New Note` command.
Customize this template to contain content that you want included every time you create a note. To begin it is *recommended* to define the YAML Front-Matter of the template similar to the following:
```markdown
---
type: basic-note
---
```
### Default daily note template
The `.foam/templates/daily-note.md` template is special in that it is the template that will be used when creating daily notes (e.g. by using `Foam: Open Daily Note`).
Customize this template to contain content that you want included every time you create a daily note. To begin it is *recommended* to define the YAML Front-Matter of the template similar to the following:
```markdown
---
type: daily-note
---
```
## Variables
Templates can use all the variables available in [VS Code Snippets](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_variables).
In addition, you can also use variables provided by Foam:
| Name | Description |
| -------------------- | ------------ |
| `FOAM_SELECTED_TEXT` | Foam will fill it with selected text when creating a new note, if any text is selected. Selected text will be replaced with a wikilink to the new |
| `FOAM_TITLE` | The title of the note. If used, Foam will prompt you to enter a title for the note. |
| `FOAM_SLUG` | The sluggified title of the note (using the default github slug method). If used, Foam will prompt you to enter a title for the note unless `FOAM_TITLE` has already caused the prompt. |
| `FOAM_DATE_*` | `FOAM_DATE_YEAR`, `FOAM_DATE_MONTH`, `FOAM_DATE_WEEK` etc. Foam-specific versions of [VS Code's datetime snippet variables](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_variables). Prefer these versions over VS Code's. |
### `FOAM_DATE_*` variables
Foam defines its own set of datetime variables that have a similar behaviour as [VS Code's datetime snippet variables](https://code.visualstudio.com/docs/editor/userdefinedsnippets#_variables).
For example, `FOAM_DATE_YEAR` has the same behaviour as VS Code's `CURRENT_YEAR`, `FOAM_DATE_SECONDS_UNIX` has the same behaviour as `CURRENT_SECONDS_UNIX`, etc.
By default, prefer using the `FOAM_DATE_` versions. The datetime used to compute the values will be the same for both `FOAM_DATE_` and VS Code's variables, with the exception of the creation notes using the daily note template.
For more nitty-gritty details about the supported date formats, [see here](https://github.com/foambubble/foam/blob/master/packages/foam-vscode/src/services/variable-resolver.ts).
#### Relative daily notes
When referring to daily notes, you can use the relative snippets (`/+1d`, `/tomorrow`, etc.). In these cases, the new notes will be created with the daily note template, but the datetime used should be the relative datetime, not the current datetime.
By using the `FOAM_DATE_` versions of the variables, the correct relative date will populate the variables, instead of the current datetime.
For example, given this daily note template (`.foam/templates/daily-note.md`):
```markdown
# $FOAM_DATE_YEAR-$FOAM_DATE_MONTH-$FOAM_DATE_DATE
## Here's what I'm going to do today
* Thing 1
* Thing 2
```
When the `/tomorrow` snippet is used, `FOAM_DATE_` variables will be populated with tomorrow's date, as expected.
If instead you were to use the VS Code versions of these variables, they would be populated with today's date, not tomorrow's, causing unexpected behaviour.
When creating notes in any other scenario, the `FOAM_DATE_` values are computed using the same datetime as the VS Code ones, so the `FOAM_DATE_` versions can be used in all scenarios by default.
## Metadata
Templates can also contain metadata about the templates themselves. The metadata is defined in YAML "Frontmatter" blocks within the templates.
| Name | Description |
| ------------- | ---------------------- |
| `filepath` | The filepath to use when creating the new note. If the filepath is a relative filepath, it is relative to the current workspace. |
| `name` | A human readable name to show in the template picker. |
| `description` | A human readable description to show in the template picker. |
Foam-specific variables (e.g. `$FOAM_TITLE`) can be used within template metadata. However, VS Code snippet variables are ([currently](https://github.com/foambubble/foam/pull/655)) not supported.
### `filepath` attribute
The `filepath` metadata attribute allows you to define a relative or absolute filepath to use when creating a note using the template. If the filepath is a relative filepath, it is relative to the current workspace.
#### Example of **relative** `filepath`
For example, `filepath` can be used to customize `.foam/templates/new-note.md`, overriding the default `Foam: Create New Note` behaviour of opening the file in the same directory as the active file:
```yaml
---
# This will create the note in the "journal" subdirectory of the current workspace,
# regardless of which file is the active file.
foam_template:
filepath: 'journal/$FOAM_TITLE.md'
---
```
#### Example of **absolute** `filepath`
`filepath` can be an absolute filepath, so that the notes get created in the same location, regardless of which file or workspace the editor currently has open.
The format of an absolute filepath may vary depending on the filesystem used.
```yaml
---
foam_template:
# Unix / MacOS filesystems
filepath: '/Users/john.smith/foam/journal/$FOAM_TITLE.md'
# Windows filesystems
filepath: 'C:\Users\john.smith\Documents\foam\journal\$FOAM_TITLE.md'
---
```
#### Example of **date-based** `filepath`
It is possible to vary the `filepath` value based on the current date using the `FOAM_DATE_*` variables. This is especially useful for the [[daily-notes]] template if you wish to organize by years, months, etc. Below is an example of a daily-note template metadata section that will create new daily notes under the `journal/YEAR/MONTH-MONTH_NAME/` filepath. For example, when a note is created on November 15, 2022, a new file will be created at `C:\Users\foam_user\foam_notes\journal\2022\11-Nov\2022-11-15-daily-note.md`. This method also respects the creation of daily notes relative to the current date (i.e. `/+1d`).
```markdown
---
type: daily-note
foam_template:
description: Daily Note for $FOAM_TITLE
filepath: "C:\\Users\\foam_user\\foam_notes\\journal\\$FOAM_DATE_YEAR\\$FOAM_DATE_MONTH-$FOAM_DATE_MONTH_NAME_SHORT\\$FOAM_DATE_YEAR-$FOAM_DATE_MONTH-$FOAM_DATE_DATE-daily-note.md"
---
# $FOAM_DATE_YEAR-$FOAM_DATE_MONTH-$FOAM_DATE_DATE Daily Notes
```
> Note: this method **requires** the use of absolute file paths, and in this example is using Windows path conventions. This method will also override any filename formatting defined in `.vscode/settings.json`
### `name` and `description` attributes
These attributes provide a human readable name and description to be shown in the template picker (e.g. When a user uses the `Foam: Create New Note From Template` command):
![Template Picker annotated with attributes](../../assets/images/template-picker-annotated.png)
### Adding template metadata to an existing YAML Frontmatter block
If your template already has a YAML Frontmatter block, you can add the Foam template metadata to it.
#### Limitations
Foam only supports adding the template metadata to *YAML* Frontmatter blocks. If the existing Frontmatter block uses some other format (e.g. JSON), you will have to add the template metadata to its own YAML Frontmatter block.
Further, the template metadata must be provided as a [YAML block mapping](https://yaml.org/spec/1.2/spec.html#id2798057), with the attributes placed on the lines immediately following the `foam_template` line:
```yaml
---
existing_frontmatter: "Existing Frontmatter block"
foam_template: # this is a YAML "Block" mapping ("Flow" mappings aren't supported)
name: My Note Template # Attributes must be on the lines immediately following `foam_template`
description: This is my note template
filepath: `journal/$FOAM_TITLE.md`
---
This is the rest of the template
```
Due to the technical limitations of parsing the complex YAML format, unless the metadata is provided this specific form, Foam is unable to correctly remove the template metadata before creating the resulting note.
If this limitation proves inconvenient to you, please let us know. We may be able to extend our parsing capabilities to cover your use case. In the meantime, you can add the template metadata without this limitation by providing it in its own YAML Frontmatter block.
### Adding template metadata to its own YAML Frontmatter block
You can add the template metadata to its own YAML Frontmatter block at the start of the template:
```yaml
---
foam_template:
name: My Note Template
description: This is my note template
filepath: `journal/$FOAM_TITLE.md`
---
This is the rest of the template
```
If the note already has a Frontmatter block, a Foam-specific Frontmatter block can be added to the start of the template. The Foam-specific Frontmatter block must always be placed at the very beginning of the file, and only whitespace can separate the two Frontmatter blocks.
```yaml
---
foam_template:
name: My Note Template
description: This is my note template
filepath: `journal/$FOAM_TITLE.md`
---
---
existing_frontmatter: "Existing Frontmatter block"
---
This is the rest of the template
```

12
docs/features/paste-images-from-clipboard.md Normal file
View File

@ -0,0 +1,12 @@
# Paste Images from Clipboard
By installing the [vscode-paste-image](https://github.com/mushanshitiancai/vscode-paste-image) extension, 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

42
docs/features/resouce-filters.md Normal file
View File

@ -0,0 +1,42 @@
# Resource Filters
Resource filters can be passed to some Foam commands to limit their scope.
A filter supports the following parameters:
- `tag`: include a resource if it has the given tag (e.g. `{"tag": "#research"}`)
- `type`: include a resource if it is of the given type (e.g. `{"type": "daily-note"}`)
- `path`: include a resource if its path matches the given regex (e.g. `{"path": "/projects/*"}`). **Note that this parameter supports regex and not globs.**
- `expression`: include a resource if it makes the given expression `true`, where `resource` represents the resource being evaluated (e.g. `{"expression": "resource.type ==='weekly-note'"}`)
- `title`: include a resource if the title matches the given regex (e.g. `{"title": "Team meeting:*"}`)
A filter also supports some logical operators:
- `and`: include a resource if it matches all the sub-parameters (e.g `{"and": [{"tag": "#research"}, {"title": "Paper *"}]}`)
- `or`: include a resource if it matches any of the sub-parameters (e.g `{"or": [{"tag": "#research"}, {"title": "Paper *"}]}`)
- `not`: invert the result of the nested filter (e.g. `{"not": {"type": "daily-note"}}`)
Here is an example of a complex filter, for example to show the Foam graph only of a subset of the workspace:
```
{
"key": "alt+f",
"command": "foam-vscode.show-graph",
"args": {
"filter": {
"and": [
{
"or": [
{ "type": 'daily-note' },
{ "type": 'weekly-note' },
{ "path": '/projects/*' },
],
"not": {
{ "tag": '#b' },
},
},
],
}
}
}
```

22
docs/features/tags-and-tag-explorer.md
View File

@ -1,22 +0,0 @@
---
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]].

51
docs/features/tags.md Normal file
View File

@ -0,0 +1,51 @@
---
tags: my-tag1 my-tag2 my-tag3/notes
---
# Tags
You can add tags to your notes to categorize or link notes together.
## Creating a tag
There are two ways of creating a tag:
- Adding a `#tag` anywhere in the text of the note, for example: #my-tag1
- Using the `tags: tag1, tag2` yaml frontmatter [[note-properties|note property]]. Notice `my-tag1` and `my-tag2` tags which are added to this document this way.
Tags can also be hierarchical, so you can have `#parent/child` such as #my-tag3/info.
## Using *Tag Explorer*
It's possible to navigate tags via the Tag Explorer panel. Expand the Tag Explorer view in the left side bar which will list all the tags found in current Foam environment. Then, each level of tags can be expanded until the options to search by tag and a list of all files containing a particular tag are shown.
Tags can also be visualized in the Foam Graph Explorer. See [[graph-visualization]] for more info including how to change the color of nodes representing tags.
## Styling tags
It is possible to customize the way that tags look in the Markdown Preview panel that renders your Foam notes. This requires some knowledge of the CSS language, which is used to customize the styles of web technologies such as VSCode. A cursory introduction to CSS can be [found here](https://www.freecodecamp.org/news/get-started-with-css-in-5-minutes-e0804813fc3e/).
1. Create a CSS file within your Foam project, for example in `.foam/css/custom-tag-style.css` or [.vscode/custom-tag-style.css](../../.vscode/custom-tag-style.css)
2. Add CSS code that targets the `.foam-tag` class
3. Add a rule for each [CSS property](https://www.w3schools.com/cssref/index.php) you would like applied to your tags.
4. Open the `.vscode/settings.json` file (or the Settings browser with `ctrl+,`)
5. Add the path to your new stylesheet to the `markdown.styles` setting.
> Note: the file path for the stylesheet will be relative to the currently open folder in the workspace when changing this setting for the current workspace. If changing this setting for the user, then the file path will be relative to your global [VSCode settings](https://code.visualstudio.com/docs/getstarted/settings).
The end result will be a CSS file that looks similiar to the content below. Now you can make your tags standout in your note previews.
```css
.foam-tag{
color:#ffffff;
background-color: #000000;
}
```
![custom tag style demo](../../assets/images/custom-tag-style.png)
## Using backlinks in place of tags
Given the power of backlinks, some people prefer to use them as tags.
For example you can tag your notes about books with [[book]].

27
docs/features/wikilinks.md
View File

@ -1,13 +1,34 @@
# Wikilinks
Wikilinks are the internal links that connect the files in your knowledge base.
Wikilinks are the internal links that connect the files in your knowledge base. (Also called `[[MediaWiki]]` links).
To create a wikilink use `[[` and type the name of another file in your repo, for example [[graph-visualization]]
## Creating and navigating wikilinks
You can also create a [[placeholder]].
To create a wikilink, type `[[` and then start typing the name of another note in your repo. Once the desired note is selected press the `tab` key to autocomplete it. For example: [[graph-visualization]].
`Cmd` + `Click` ( `Ctrl` + `Click` on Windows ) on wikilink to navigate to that note (`F12` also works while your cursor is on the wikilink). If the file doesn't exist it will be created in your workspace based on your default [[note-templates]] settings.
## Placeholders
You can also create a [[placeholder]]. <!--NOTE: this placeholder link should NOT have an associated file. This is to demonstrate the concept-->
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).
## Support for sections
Foam supports autocompletion, navigation, embedding and diagnostics for note sections. Just use the standard wiki syntax of `[[resource#Section Title]]`.
## Markdown compatibility
The [Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode) extension automatically generates [[link-reference-definitions]] at the bottom of the file to make wikilinks compatible with other Markdown tools and parsers.
## Read more
- [[foam-file-format]]
- [[note-templates]]
- See [[link-reference-definition-improvements]] for further discussion on current problems and potential solutions.