makary/foam-template
Template
1
0
Fork 0
mirror of https://github.com/foambubble/foam-template.git synced 2025-06-07 20:08:54 +00:00
Code Issues Projects Releases Packages 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
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
59 changed files with 2276 additions and 117 deletions
Show stats 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
```

4
docs/how-to/paste-images-from-clipboard.md → docs/features/paste-images-from-clipboard.md
View file

@ -1,6 +1,6 @@
# Paste Images from Clipboard
You can paste an image from the clipboard with `cmd+alt+v`.
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.
@ -10,5 +10,3 @@ To change the location where the image is created, change the `pasteImage.path`
- `${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.

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.

23
docs/frequently-asked-questions.md Normal file
View file

@ -0,0 +1,23 @@
# Frequently Asked Questions
> ⚠️ Foam is still in preview. Expect the experience to be a little rough.
- [Frequently Asked Questions](#frequently-asked-questions)
- [Links/Graphs/BackLinks don't work. How do I enable them?](#linksgraphsbacklinks-dont-work-how-do-i-enable-them)
- [I don't want Foam enabled for all my workspaces](#i-dont-want-foam-enabled-for-all-my-workspaces)
- [I want to publish the graph view to GitHub pages or Vercel](#i-want-to-publish-the-graph-view-to-github-pages-or-vercel)
## Links/Graphs/BackLinks don't work. How do I enable them?
- Ensure that you have all the [[recommended-extensions]] installed in Visual Studio Code
- Reload Visual Studio Code by running `Cmd` + `Shift` + `P` (`Ctrl` + `Shift` + `P` for Windows), type "reload" and run the **Developer: Reload Window** command to for the updated extensions take effect
- Check the formatting rules for links on [[foam-file-format]] and [[wikilinks]]
## I don't want Foam enabled for all my workspaces
Any extension you install in Visual Studio Code is enabled by default. Given the philosophy of Foam, it works out of the box without doing any configuration upfront. In case you want to disable Foam for a specific workspace, or disable Foam by default and enable it for specific workspaces, it is advised to follow the best practices as [documented by Visual Studio Code](https://code.visualstudio.com/docs/editor/extension-marketplace#_manage-extensions)
## I want to publish the graph view to GitHub pages or Vercel
If you want a different front-end look to your published foam and a way to see your graph view, we'd recommend checking out these templates:
- [foam-gatsby](https://github.com/mathieudutour/foam-gatsby-template) by [Mathieu Dutour](https://github.com/mathieudutour)
- [foam-gatsby-kb](https://github.com/hikerpig/foam-template-gatsby-kb) by [hikerpig](https://github.com/hikerpig)

9
docs/getting-started/creating-new-notes.md Normal file
View file

@ -0,0 +1,9 @@
# Creating New Notes
- Write out a new `[[wikilink]]` and `Cmd` + `Click` to create a new file and enter it.
- For keyboard navigation, use the 'Follow Definition' key `F12` (or [remap the 'editor.action.revealDefinition' key binding](https://code.visualstudio.com/docs/getstarted/keybindings) to something more ergonomic)
- `Cmd` + `Shift` + `P` (`Ctrl` + `Shift` + `P` for Windows), execute `Foam: Create Note` and enter a **Title Case Name** to create `Title Case Name.md`
- Add a keyboard binding to make creating new notes easier. See [[commands]] for more info on this.
- The [[note-templates]] used by this command can be customized.
- You shouldn't worry too much about categorizing your notes. You can always [[search-for-notes]], and explore them using the [[graph-visualization]].

5
docs/how-to/get-started-with-vscode.md → docs/getting-started/get-started-with-vscode.md
View file

@ -36,8 +36,9 @@ If you want to learn more about VS Code, check out their [website](https://code.
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
- `Tag Explorer`: This shows you the tags in your workspace, see [[tags]] for more information on tags
## Settings
To view or change the settings in VS Code, press `cmd+,`
To view or change the settings in VS Code, press `cmd+,` on Mac and `ctrl+,` on Windows/Linux.

6
docs/how-to/shortcut-list.md → docs/getting-started/keyboard-shortcuts.md
View file

@ -1,4 +1,8 @@
# Shortcut-List
# Keyboard Shortcuts
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.
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.

25
docs/getting-started/recommended-extensions.md Normal file
View file

@ -0,0 +1,25 @@
# Recommended Extensions
These extensions defined in `.vscode/extensions.json` are automatically installed when you accept the workspace's recommended extensions.
This list is subject to change.
- [Foam for VSCode](https://marketplace.visualstudio.com/items?itemName=foam.foam-vscode) (alpha)
- [Markdown All In One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one)
- [Paste Image](https://marketplace.visualstudio.com/items?itemName=mushan.vscode-paste-image)
## Extensions For Additional Features
These extensions are not (yet?) defined in `.vscode/extensions.json`, but have been used by others and shown to play nice with Foam.
- [Emojisense](https://marketplace.visualstudio.com/items?itemName=bierner.emojisense)
- [Markdown Emoji](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-emoji) (adds `:smile:` syntax, works with emojisense to provide autocomplete for this syntax)
- [Markdown Preview Mermaid Support](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid)
- [Mermaid Markdown Syntax Highlighting](https://marketplace.visualstudio.com/items?itemName=bpruitt-goddard.mermaid-markdown-syntax-highlighting)
- [Excalidraw whiteboard and sketching tool integration](https://marketplace.visualstudio.com/items?itemName=pomdtr.excalidraw-editor)
- [VSCode PDF Viewing](https://marketplace.visualstudio.com/items?itemName=tomoki1207.pdf)
- [Project Manager](https://marketplace.visualstudio.com/items?itemName=alefragnani.project-manager) (to quickly switch between projects)
- [Markdown Extended](https://marketplace.visualstudio.com/items?itemName=jebbs.markdown-extended) (with `kbd` option disabled, `kbd` turns wikilinks into non-clickable buttons)
- [GitDoc](https://marketplace.visualstudio.com/items?itemName=vsls-contrib.gitdoc) (easy version management via git auto commits)
- [Markdown Footnotes](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-footnotes) (Adds [^footnote] syntax support to VS Code's built-in markdown preview)
- [Todo Tree](https://marketplace.visualstudio.com/items?itemName=Gruntfuggly.todo-tree) (Searches workspace for TODO and related comments and summarizes those lines in vs-code gutter)

12
docs/getting-started/sync-notes-with-soruce-control.md Normal file
View file

@ -0,0 +1,12 @@
# Sync notes with source control
Source control is a way to precicely manage the history and content of a directory of files.
Often used for program code, this feature is very useful for note taking as well.
There are (too) many ways to commit your changes to source control:
- Using VS Code's own git integration
- The quick and easy way is to use the `Git: Commit All` command after editing files. The default Foam workspace settings will stage & sync all of your changes to the remote:
- Using GitDoc for [[automatic-git-syncing]]
- Whatever way you like to do it (CLI?)

1
docs/how-to/write-notes-in-foam.md → docs/getting-started/write-notes-in-foam.md
View file

@ -67,3 +67,4 @@ You can `inline code` or
you can create
code blocks
```

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

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

53
docs/index.md Normal file
View file

@ -0,0 +1,53 @@
# Using Foam
Foam is a collection VS Code extensions and recipes that power up the editor
into a full-blown note taking system. This folder contains user documentation
describing how to get started using Foam, what its main features are, and
strategies for getting the most out of Foam. The full docs are included in the
`foam-template` repo that most users start from.
> See also [[frequently-asked-questions]].
## Getting Started
- [[get-started-with-vscode]]
- [[recommended-extensions]]
- [[creating-new-notes]]
- [[write-notes-in-foam]]
- [[sync-notes-with-soruce-control]]
- [[keyboard-shortcuts]]
## Features
- [[wikilinks]]
- [[tags]]
- [[backlinking]]
- [[daily-notes]]
- [[including-notes]]
- [[spell-checking]]
- [[graph-visualization]]
- [[note-properties]]
- [[note-templates]]
- [[paste-images-from-clipboard]]
- [[custom-markdown-preview-styles]]
- [[link-reference-definitions]]
- [[custom-snippets]]
## Recipes
[[recipes]] is a collection of user-contributed patterns that describe different ways you could utilize Foam or integrate it with other tools.
## Publishing
You can publish your Foam notes for consumption in different formats.
Examples: [[publish-to-github-pages]], [[generate-gatsby-site]], [[publish-to-vercel]]
See [[publishing]] for more details.
## Tools
- [[cli]]
- [[workspace-janitor]]
- [[orphans]]
- [[foam-logging-in-vscode]]

34
docs/publishing/generate-gatsby-site.md Normal file
View file

@ -0,0 +1,34 @@
# Generate a site using Gatsby
## Using foam-gatsby-template
You can use [foam-gatsby-template](https://github.com/mathieudutour/foam-gatsby-template) to generate a static site to host it online on GitHub or [Vercel](https://vercel.com).
### Publishing your foam to GitHub pages
It comes configured with GitHub actions to auto deploy to GitHub pages when changes are pushed to your main branch.
### Publishing your foam to Vercel
When you're ready to publish, run a local build.
```bash
cd _layouts
npm run build
```
Remove `public` from your .gitignore file then commit and push your public folder in `_layouts` to GitHub.
Log into your Vercel account. (Create one if you don't have it already.)
Import your project. Select `_layouts/public` as your root directory and click **Continue**. Then name your project and click **Deploy**.
That's it!
## Using foam-template-gatsby-kb
You can use another template [foam-template-gatsby-kb](https://github.com/hikerpig/foam-template-gatsby-kb), and host it on [Vercel](https://vercel.com) or [Netlify](https://www.netlify.com/).
## Using foam-template-gatsby-theme-primer-wiki
You can use another template [foam-template-gatsby-theme-primer-wiki](https://github.com/theowenyoung/foam-template-gatsby-theme-primer-wiki), ([Demo](https://demo-wiki.owenyoung.com/)), and host it on Github Pages, [Vercel](https://vercel.com) or [Netlify](https://www.netlify.com/).

54
docs/publishing/math-support-with-katex.md Normal file
View file

@ -0,0 +1,54 @@
# Katex Math Rendering
Apart from using the method mentioned in [[math-support-with-mathjax]], we can also use KaTeX to render our math equations in Foam. The caveat is: we can't rely on GitHub Pages to host and deploy our website anymore, because the plugin we'll be using to let Jekyll support KaTeX doesn't play well together with GitHub Pages.
The alternative solution is to using [[publish-to-vercel]] for building and publishing our website, so before you start integrating KaTeX into your Foam project, please follow the instructions to host your Foam workspace on [[publish-to-vercel]] first.
## Adding required plugins
Add the plugin `jekyll-katex` to your Foam workspace's `_config.yml` and `Gemfile` if you haven't done so already. For detailed instructions, please refer to the `#Adding a _config.yml` and `#Adding a Gemfile` in [[publish-to-vercel]].
## Loading KaTeX JS and CSS
Because we are using KaTeX to render math, we will also need to import KaTeX's JS and CSS files from CDN. The official method to load these files is documented at: [KaTeX/KaTeX#starter-template](https://github.com/KaTeX/KaTeX#starter-template). In our case, we will need to add the following code snippet to our `_layouts/page.html`:
```html
<!-- _layouts/page.html -->
---
layout: default
---
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/katex.min.css" integrity="sha384-AfEj0r4/OFrOo5t7NnNe46zW/tFgW6x/bCJG8FqQCEo3+Aro6EYUG4+cU+KJWu/X" crossorigin="anonymous">
<!-- The loading of KaTeX is deferred to speed up page rendering -->
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/katex.min.js" integrity="sha384-g7c+Jr9ZivxKLnZTDUhnkOnsh30B4H0rpLUpJ4jAIKs4fnJI+sEnkvrMWph2EDg4" crossorigin="anonymous"></script>
<!-- To automatically render math in text elements, include the auto-render extension: -->
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.12.0/dist/contrib/auto-render.min.js" integrity="sha384-mll67QQFJfxn0IYznZYonOWZ644AWYC+Pt2cHqMaRhXVrursRwvLnLaebdGIlYNa" crossorigin="anonymous" onload="renderMathInElement(document.body);"></script>
<!-- ... -->
```
## Adding liquid tags to wrap page content
The plugin `jekyll-katex` focuses on rendering:
- Single math equations wrapped inside `katex` liquid tags like {% raw %}`{% katex %} ... {% endkatex %}`{% endraw %}.
- Or multiple math equations in paragraphs wrapped inside {% raw %}`{% katexmm %} ... {% endkatexmm %}`{% endraw %}.
In our case, we'll be using the latter tag to wrap our {% raw %}`{{ content }}`{% endraw %}. Wrap {% raw %}`{{ content }}`{% endraw %} in the liquid tags inside `_layouts/page.html` like so:
```html
<!-- _layouts/page.html -->
<!-- ... -->
{% raw %}{% katexmm %} {{ content }} {% endkatexmm %}{% endraw %}
<!-- ... -->
```
## Render equations in Foam's homepage as well
You may have noticed that we only made modifications to the template `_layouts/page.html`, which means that `_layouts/home.html` won't have KaTeX support. If you wan't to render math in Foam's home page, you'll need to make the same modifications to `_layouts/home.html` as well.
Finally, if all goes well, then our site hosted on Vercel will support rendering math equations with KaTeX after commiting these changes to GitHub. Here's a demo of the default template with KaTeX support: [Foam Template with KaTeX support](https://foam-template.vercel.app/).

51
docs/publishing/math-support-with-mathjax.md Normal file
View file

@ -0,0 +1,51 @@
---
layout: mathjax
---
# Math Support
Published Foam pages don't support math formulas by default. To enable this feature, you can add the following code snippet to the end of `_layouts/page.html`:
```html
<script src="https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML" type="text/javascript"></script>
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
tex2jax: {
skipTags: ['script', 'noscript', 'style', 'textarea', 'pre'],
inlineMath: [['$','$']]
}
});
</script>
```
This approach uses the [MathJax](https://www.mathjax.org/) library to render anything delimited by ```$``` (customizable in the snippet above) pairs to inline math and ```$$``` to blocks of math (like a html div tag) using with the AMS-LaTeX dialect embedded within MathJax.
Example of inline math using `$...$`:
`$e^{i \pi}+1=0$`, becomes $e^{i \pi}+1=0$
Example of a math block using `$$...$$`:
`$$ f_{\mathbf{X}}\left(x_{1}, \ldots, x_{k}\right)=\frac{\exp \left(-\frac{1}{2}(\mathbf{x}-\boldsymbol{\mu})^{\mathrm{T}} \mathbf{\Sigma}^{-1}(\mathbf{x}-\boldsymbol{\mu})\right)}{\sqrt{(2 \pi)^{k}|\mathbf{\Sigma}|}} $$`
Becomes:
$$ f_{\mathbf{X}}\left(x_{1}, \ldots, x_{k}\right)=\frac{\exp \left(-\frac{1}{2}(\mathbf{x}-\boldsymbol{\mu})^{\mathrm{T}} \mathbf{\Sigma}^{-1}(\mathbf{x}-\boldsymbol{\mu})\right)}{\sqrt{(2 \pi)^{k}|\mathbf{\Sigma}|}} $$
## Alternative approaches
There are other dialects of LaTeX (instead of AMS), and other JavaScript rendering libraries you may want to use. In a future version of Foam, we may support KaTeX syntax out of the box, but at this time, these integrations are left as an exercise to the user.
## Why don't my Math expressions work on my Foam's home page?
If you want the index page of your Foam site to render maths, you'll need to add that to `_layouts/home.html` as well, or change the layout of the index page to be "page" instead of "home" by putting this Front Matter on the top of your `readme.md/index.md`:
```
---
layout: page
---
# Your normal title here
```
Reference: [How to support latex in github-pages](https://stackoverflow.com/questions/26275645/how-to-support-latex-in-github-pages)

66
docs/publishing/publish-to-azure-devops-wiki.md Normal file
View file

@ -0,0 +1,66 @@
# Publish to Azure DevOps Wiki
Publish your Foam workspace as an Azure DevOps wiki.
[Azure DevOps](https://azure.microsoft.com/en-us/services/devops/) is Microsoft's collaboration software for software development teams, formerly known as Team Foundation Server (TFS) and Visual Studio Team Services. It is available as an on-premise or SaaS version. The following recipe was tested with the SaaS version, but should work the same way for the on-premise.
The following recipe is written with the assumption that you already have an [Azure DevOps](https://azure.microsoft.com/en-us/services/devops/) project.
## Setup a Foam workspace
1. Generate a Foam workspace using the [foam-template project](https://github.com/foambubble/foam-template).
2. Change the remote to a git repository in Azure DevOps (Repos -> Import a Repository -> Add Clone URL with Authentication), or copy all the files into a new Azure DevOps git repository.
3. Define which document will be the wiki home page. To do that, create a file called `.order` in the Foam workspace root folder, with first line being the document filename without `.md` extension. For a project created from the Foam template, the file would look like this:
```
readme
```
4. Push the repository to remote in Azure DevOps.
## Publish repository to a wiki
1. Navigate to your Azure DevOps project in a web browser.
2. Choose **Overview** > **Wiki**. If you don't have wikis for your project, choose **Publish code as a wiki** on welcome page.
3. Choose repository with your Foam workspace, branch (usually `master` or `main`), folder (for workspace created from foam-template it is `/`), and wiki name, and press **Publish**.
A published workspace looks like this:
![Azure DevOps wiki](../../assets/images/azure-devops-wiki-demo.png)
There is default table of contents pane to the left of the wiki content. Here, you'll find a list of all directories that are present in your Foam workspace, and all wiki pages. Page names are derived from files names, and they are listed in alphabetical order. You may reorder pages by adding filenames without `.md` extension to `.order` file.
_Note that first entry in `.order` file defines wiki's home page._
## Update wiki
While you are pushing changes to GitHub, you won't see the wiki updated if you don't add Azure as a remote. You can push to multiple repositories simultaneously.
1. First open a terminal and check if Azure is added running: `git remote show origin`. If you don't see Azure add it in the output then follow these steps.
2. Rename your current remote (most likely named origin) to a different name by running: `git remote rename origin main`
3. You can then add the remote for your second remote repository, in this case, Azure. e.g `git remote add azure https://<YOUR_ID>@dev.azure.com/<YOUR_ID>/foam-notes/_git/foam-notes`. You can get it from: Repos->Files->Clone and copy the URL.
4. Now, you need to set up your origin remote to push to both of these. So run: `git config -e` and edit it.
5. Add the `remote origin` section to the bottom of the file with the URLs from each remote repository you'd like to push to. You'll see something like that:
```bash
[core]
...
(ignore this part)
...
[branch "master"]
remote = github
merge = refs/heads/master
[remote "github"]
url = git@github.com:username/repo.git
fetch = +refs/heads/*:refs/remotes/github/*
[remote "azure"]
url = https://<YOUR_ID>@dev.azure.com/<YOUR_ID>/foam-notes/_git/foam-notes
fetch = +refs/heads/*:refs/remotes/azure/*
[remote "origin"]
url = git@github.com:username/repo.git
url = https://<YOUR_ID>@dev.azure.com/<YOUR_ID>/foam-notes/_git/foam-notes
```
6. You can then push to both repositories by: `git push origin master` or a single one using: `git push github master` or `git push azure master`
For more information, read the [Azure DevOps documentation](https://docs.microsoft.com/en-us/azure/devops/project/wiki/publish-repo-to-wiki).

49
docs/publishing/publish-to-github-pages.md Normal file
View file

@ -0,0 +1,49 @@
# GitHub Pages
1. In VSCode workspace settings set `"foam.edit.linkReferenceDefinitions": "withoutExtensions"`
2. Execute the “Foam: Run Janitor” command from the command palette.
3. [Turn **GitHub Pages** on in your repository settings](https://guides.github.com/features/pages/).
- The default GitHub Pages template is called [Primer](https://github.com/pages-themes/primer). See Primer docs for how to customise html layouts and templates.
- GitHub Pages is built on [Jekyll](https://jekyllrb.com/), so it supports things like permalinks, front matter metadata etc.
## How to publish locally
If you want to test your published foam, follow the instructions:
- <https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/creating-a-github-pages-site-with-jekyll>
- <https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/testing-your-github-pages-site-locally-with-jekyll>
Assuming you have installed ruby/jekyll and the rest:
- `touch Gemfile`
- open the file and paste the following:
```
source 'https://rubygems.org'
gem "github-pages", "VERSION"
```
replacing `VERSION` with the latest from <https://rubygems.org/gems/github-pages> (e.g. `gem "github-pages", "209"`)
- `bundle`
- `bundle exec jekyll 3.9.0 new .`
- edit the `Gemfile` according to the instructions at [Creating Your Site](https://docs.github.com/en/free-pro-team@latest/github/working-with-github-pages/creating-a-github-pages-site-with-jekyll#creating-your-site) Point n.8
- `bundle exec jekyll serve`
## Other templates
There are many other templates which also support publish your foam workspace to github pages
* gatsby-digital-garden
* [repo](https://github.com/mathieudutour/gatsby-digital-garden)
* [demo-website](https://mathieudutour.github.io/gatsby-digital-garden/)
* foam-mkdocs-template
* [repo](https://github.com/Jackiexiao/foam-mkdocs-template)
* [demo-website](https://jackiexiao.github.io/foam/)
* foam-jekyll-template
* [repo](https://github.com/hikerpig/foam-jekyll-template)
* [demo-website](https://hikerpig.github.io/foam-jekyll-template/)
[[todo]] [[good-first-task]] Improve this documentation

16
docs/publishing/publish-to-github.md Normal file
View file

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

224
docs/publishing/publish-to-gitlab-pages.md Normal file
View file

@ -0,0 +1,224 @@
# GitLab Pages
You don't have to use GitHub to serve Foam pages. You can also use GitLab.
Gitlab pages can be kept private for private repo, so that your notes are still private.
## Setup a project
### Generate the directory from GitHub
Generate a solution using the [Foam template](https://github.com/foambubble/foam-template).
Change the remote to GitLab, or copy all the files into a new GitLab repo
## Publishing pages with Gatsby
### Setup the Gatsby config
Add a .gatsby-config.js file where:
* `$REPO_NAME` correspond to the name of your gtlab repo.
* `$USER_NAME` correspond to your gitlab username.
```js
const path = require("path");
const pathPrefix = `/$REPO_NAME`;
// Change me
const siteMetadata = {
title: "A title",
shortName: "A short name",
description: "",
imageUrl: "/graph-visualization.jpg",
siteUrl: "https://$USER_NAME.gitlab.io",
};
module.exports = {
siteMetadata,
pathPrefix,
flags: {
DEV_SSR: true,
},
plugins: [
`gatsby-plugin-sharp`,
{
resolve: "gatsby-theme-primer-wiki",
options: {
defaultColorMode: "night",
icon: "./path_to/logo.png",
sidebarComponents: ["tag", "category"],
nav: [
{
title: "Github",
url: "https://github.com/$USER_NAME/",
},
{
title: "Gitlab",
url: "https://gitlab.com/$USER_NAME/",
},
],
editUrl:
"https://gitlab.com/$USER_NAME/$REPO_NAME/tree/main/",
},
},
{
resolve: "gatsby-source-filesystem",
options: {
name: "content",
path: `${__dirname}`,
ignore: [`**/\.*/**/*`],
},
},
{
resolve: "gatsby-plugin-manifest",
options: {
name: siteMetadata.title,
short_name: siteMetadata.shortName,
start_url: pathPrefix,
background_color: `#f7f0eb`,
display: `standalone`,
icon: path.resolve(__dirname, "./path_to/logo.png"),
},
},
{
resolve: `gatsby-plugin-sitemap`,
},
{
resolve: "gatsby-plugin-robots-txt",
options: {
host: siteMetadata.siteUrl,
sitemap: `${siteMetadata.siteUrl}/sitemap/sitemap-index.xml`,
policy: [{ userAgent: "*", allow: "/" }],
},
},
],
};
```
And a `package.json` file containing:
```json
{
"private": true,
"name": "wiki",
"version": "1.0.0",
"license": "MIT",
"scripts": {
"develop": "gatsby develop -H 0.0.0.0",
"start": "gatsby develop -H 0.0.0.0",
"build": "gatsby build",
"clean": "gatsby clean",
"serve": "gatsby serve",
"test": "echo test"
},
"dependencies": {
"@primer/react": "^34.1.0",
"@primer/css": "^17.5.0",
"foam-cli": "^0.11.0",
"gatsby": "^3.12.0",
"gatsby-plugin-manifest": "^3.12.0",
"gatsby-plugin-robots-txt": "^1.6.9",
"gatsby-plugin-sitemap": "^5.4.0",
"gatsby-source-filesystem": "^3.12.0",
"gatsby-theme-primer-wiki": "^1.14.5",
"react": "^17.0.2",
"react-dom": "^17.0.2"
}
}
```
The theme will be based on [gatsby-theme-primer-wiki](https://github.com/theowenyoung/gatsby-theme-primer-wiki).
To test the theme locally first run `yarn install` and then use `gatsby develop` to serve the website.
See gatsby documentation for more details.
### Set-up the CI for deployment
Create a `.gitlab-ci.yml` file containing:
```yml
# To contribute improvements to CI/CD templates, please follow the Development guide at:
# https://docs.gitlab.com/ee/development/cicd/templates.html
# This specific template is located at:
# https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Pages/Gatsby.gitlab-ci.yml
image: node:latest
stages:
- deploy
pages:
stage: deploy
# This folder is cached between builds
# https://docs.gitlab.com/ee/ci/yaml/index.html#cache
cache:
paths:
- node_modules/
# Enables git-lab CI caching. Both .cache and public must be cached, otherwise builds will fail.
- .cache/
- public/
script:
- yarn install
- ./node_modules/.bin/gatsby build --prefix-paths
artifacts:
paths:
- public
rules:
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```
This pipeline will now serve your website on every push to the main branch of your project.
## Publish with Jekyll
### Add a _config.yaml
Add another file to the root directory (the one with `readme.md` in it) called `_config.yaml` (no extension)
```yaml
title: My Awesome Foam Project
baseurl: "" # the subpath of your site, e.g. /blog
url: "/" # the base hostname & protocol for your site
theme: jekyll-theme-minimal
plugins:
- jekyll-optional-front-matter
optional_front_matter:
remove_originals: true
defaults:
-
scope:
path: "" # we need to add this to properly render layouts
values:
layout: "default"
```
You can choose a theme if you want from places like [Jekyll Themes](https://jekyllthemes.io/)
### Add a Gemlock file
Add another file to the root directory (the one with `readme.md` in it) called `Gemfile` (no extension)
```ruby
source "https://rubygems.org"
gem "jekyll"
gem "jekyll-theme-minimal"
gem "jekyll-optional-front-matter"
```
Commit the file and push it to gitlab.
### Setup CI/CD
1. From the project home in GitLab click `Set up CI/CD`
2. Choose `Jekyll` as your template from the template dropdown
3. Click `commit`
4. Now when you go to CI / CD > Pipelines, you should see the code running
### Troubleshooting
- *Could not locate Gemfile* - You didn't follow the steps above to [Add a Gemlock file](#add-a-gemlock-file)
- *Conversion error: Jekyll::Converters::Scss encountered an error while converting* You need to reference a theme.
- *Pages are running in CI/CD, but I only ever see `test`, and never deploy* - Perhaps you've renamed the main branch (from master) - check the settings in `.gitlab-ci.yml` and ensure the deploy command is running to the branch you expect it to.
- *I deployed, but my .msd files don't seem to be being converted into .html files* - You need a gem that GitHub installs by default - check `gem "jekyll-optional-front-matter"` appears in the `Gemfile`

18
docs/publishing/publish-to-netlify-with-eleventy.md Normal file
View file

@ -0,0 +1,18 @@
# Publish to Netlify with Eleventy
You can use [foam-eleventy-template](https://github.com/juanfrank77/foam-eleventy-template) to generate a static site with [Eleventy](https://www.11ty.dev/), and host it online on [Netlify](https://www.netlify.com/).
With this template you can
- Have control over what to publish and what to keep private
- Customize the styling of the site to your own liking
## Publishing your foam
When you're ready to publish, import the GitHub repository you created with **foam-eleventy-template** into your Netlify account. (Create one if you don't have it already.)
Once that's done, all you have to do is make changes to your workspace in VS Code and push them to the main branch on GitHub. Netlify will recognize the changes, deploy them automatically and give you a link where your Foam is published.
That's it!
You can now see it online and use that link to share it with your friends, so that they can see it too.

83
docs/publishing/publish-to-vercel.md Normal file
View file

@ -0,0 +1,83 @@
# Publish to Vercel
This #recipe shows you how to deploy the default Foam website template to Vercel.
[Vercel](https://vercel.com/) is a static website hosting solution similar to GitHub Pages (see [[publish-to-github-pages]]).
## Setting up the project
### Using Foam's template
Generate a GitHub repository using the default [Foam template](https://github.com/foambubble/foam-template), this will be the workspace that we will be deploying with Vercel. This workspace is a barebone Jekyll source website, which means we can customize and install plugins just like any other Jekyll websites.
As we won't be using GitHub Pages, we will be adding a few configuration files in order to help Vercel pick up on how to build our site.
### Adding a `_config.yml`
First, we'll need to add a `_config.yml` at the root directory. This is the Jekyll configuration file. In here, we will set the site's title, theme, repository and permalink options, and also tell Jekyll what plugins to use:
```yaml
# _config.yml
title: Foam
# All the plugins we will be installing now that we won't be using GitHub Pages
plugins:
- jekyll-katex # optional
- jekyll-default-layout
- jekyll-relative-links
- jekyll-readme-index
- jekyll-titles-from-headings
- jekyll-optional-front-matter
# The default Jekyll theme we will be using
theme: jekyll-theme-primer
# The GitHub repository that we are hosting our foam workspace from
repository: user/repo
# Generate permalinks in format specified in: https://jekyllrb.com/docs/permalinks/#built-in-formats
permalink: pretty
```
The `theme` specifies a theme for our deployed Jekyll website. The default GitHub Pages template is called [Primer](https://github.com/pages-themes/primer). See Primer docs for how to customise html layouts and templates. We can also choose a theme if you want from places like [Jekyll Themes](https://jekyllthemes.io/).
The `plugins` specifies a list of Jekyll plugins that we will be installing in the next section. As we won't be using GitHub Pages, we'll need to install these plugins that GitHub Pages installs for us under the hood.
_If you want to use LaTeX rendered with KaTeX (which is what the plugin `jekyll-katex` does), you can specify it here. And yes, one of the benefits of deploying with Vercel is that we can use KaTeX to render LaTeX! More on: [[math-support-with-katex]]_
### Adding a `Gemfile`
Next up, we'll create another new file called `Gemfile` in the root directory. This is where we will let Vercel know what plugins to install when building our website.
In our `Gemfile`, we need to specify our Ruby packages:
```ruby
# Gemfile
source "https://rubygems.org"
gem "jekyll"
gem "kramdown-parser-gfm"
gem "jekyll-theme-primer"
gem "jekyll-optional-front-matter"
gem "jekyll-default-layout"
gem "jekyll-relative-links"
gem "jekyll-readme-index"
gem "jekyll-titles-from-headings"
gem "jekyll-katex" # Optional, the package that enables KaTeX math rendering
```
### Enable math rendering with KaTeX (optional)
Besides adding the plugin `jekyll-katex` in `_config.yml` and `Gemfile`, we'll also have to follow the guides in [[math-support-with-katex]] to let our site fully support using KaTeX to render math equations.
### Commiting changes to GitHub repo
Finally, commit the newly created files to GitHub.
## Importing project to Vercel
First, import our foam workspace (GitHub repository) to Vercel with [Vercel's _Import Git Repository_](https://vercel.com/import/git). Paste our GitHub repo's url and Vercel will automatically pull and analyze the tool we use to deploy our website. (In our case: Jekyll.)
Next, select the folder to deploy from if prompted. If we are using the default template, then Vercel will default to the root directory of our Foam workspace.
Finally, if all is successful, Vercel will show the detected framework: Jekyll. Press `Deploy` to proceed on publishing our project.
![](../../assets/images/vercel-detect-preset.png)
And now, Vercel will take care of building and rendering our foam workspace each time on push. Vercel will publish our site to `xxx.vercel.app`, we can also define a custom domain name for our Vercel website.

24
docs/publishing/publishing.md Normal file
View file

@ -0,0 +1,24 @@
# Publishing pages
Foam pages can be published.
TODO add publishing TOC
## Foam site generator?
Another case of the [[build-vs-assemble]] dilemma. We could provide a better publishing experience by building a bespoke static site generator (or a gatsby plugin) that's aware of Foam conventions (backlinks etc.)
Eventually we should probably do it, as that would unlock a huge amount of power, but we should always strive to keep it optional.
At a bare minimum, Foam repos should remain valid markdown, and should be publishable by any sufficiently complete markdown to html generation tools.
Would be cool if Foam pages could be published. Some ideas here.
- [x] Easymode: Make your GitHub public
- [x] Static site generator integration, publish from GH actions to GitHub pages / Netlify etc!!!
- [ ] Add annotations to pages for setting visibility (many ways to do this)
- [ ] Public by default, and `@private` annotations
- [ ] Private by default, and `@public` annotations
- [ ] Only public `/public` folder, just move a document there, no annotation needed
- [ ] More granular access control? Email someone a link with a hash? [Testing](testing.md)

9
docs/recipes/add-images-to-notes.md Normal file
View file

@ -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.

20
docs/recipes/automatic-git-syncing.md Normal file
View file

@ -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)

24
docs/recipes/automatically-expand-urls-to-well-titled-links.md Normal file
View file

@ -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)

140
docs/recipes/capture-notes-with-drafts-pro.md Normal file
View file

@ -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;
}
```

60
docs/recipes/capture-notes-with-shortcuts-and-github-actions.md Normal file
View file

@ -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.)

25
docs/recipes/diagrams-in-markdown.md Normal file
View file

@ -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)`

38
docs/recipes/how-to-write-recipes.md Normal file
View file

@ -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]].

18
docs/recipes/make-backlinks-more-prominent.md Normal file
View file

@ -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)

43
docs/recipes/markup-converter.md Normal file
View file

@ -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.

6
docs/recipes/migrating-from-obsidian.md Normal file
View file

@ -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).

36
docs/recipes/migrating-from-onenote.md Normal file
View file

@ -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!

6
docs/recipes/migrating-from-roam.md Normal file
View file

@ -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).

58
docs/recipes/note-macros.md Normal file
View file

@ -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).

50
docs/recipes/predefined-user-snippets.md Normal file
View file

@ -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).

3
docs/recipes/real-time-collaboration.md Normal file
View file

@ -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.

108
docs/recipes/recipes.md Normal file
View file

@ -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]]._

10
docs/recipes/search-for-notes.md Normal file
View file

@ -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.

10
docs/recipes/shows-image-preview-on-hover.md Normal file
View file

@ -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)

60
docs/recipes/take-notes-from-mobile-phone.md Normal file
View file

@ -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).

14
docs/recipes/web-clipper.md Normal file
View file

@ -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.

55
docs/recipes/write-your-notes-in-github-gist.md Normal file
View file

@ -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" />

10
docs/tools/cli.md Normal file
View file

@ -0,0 +1,10 @@
# Command Line Interface
Create a CLI tool to allow running common Foam commands. These may include:
- `foam init` - create a new foam workspace
- `foam janitor` - run [[workspace-janitor]] in current workspace
- `foam migrate <tool>` - migrate from tools like roam exports, obsidian and more
More commands to be added.

20
docs/tools/foam-logging-in-vscode.md Normal file
View file

@ -0,0 +1,20 @@
# Foam logging in VsCode
The Foam extension logs details about what its doing in vscode's `Output` tab.
Generally this is only useful if you're reporting an issue about Foam.
1. To show the tab, click on `View > Output`.
2. In the dropdown on the right of the tab, select `Foam`.
![Find the foam log](../../assets/images/foam-log.png)
When reporting an issue about Foam, set the log level to `Debug`:
## Change the log level for the session
Execute the command `Foam: Set log level`.
## Change the default logging level
1. Open workspace settings (`cmd+,`, or execute the `Preferences: Open Workspace Settings` command)
2. Look for the entry `Foam > Logging: Level`

10
docs/tools/orphans.md Normal file
View file

@ -0,0 +1,10 @@
# Orphaned Notes
Foam helps you to find orphans: notes that have neither forward links nor backlinks.
Orphans can be found in the Orphans panel.
Two settings allows you to control the behaviour of the Orphans panel:
- `foam.orphans.exclude`: list of glob patterns that will be used to exclude directories. For example, a value of `["journal/**/*"]` would exclude your daily notes.
- `foam.orphans.groupBy`: sets the default view mode of the Orphans panel: either groups by folder (by default), or lists all orphans. The view can be toggled on the fly from the panel, but it won't overwrite the setting.

38
docs/tools/workspace-janitor.md Normal file
View file

@ -0,0 +1,38 @@
# Janitor
To store your personal knowledge graph in markdown files instead of a database, we need some additional tooling to create and maintain relationships with notes.
**Foam Janitor** (inspired by Andy Matuschak's [note-link-janitor](https://github.com/andymatuschak/note-link-janitor)) helps you migrate existing notes to Foam, and maintain your Foam's health over time.
Currently, Foam's Janitor helps you to:
- Ensure your [[link-reference-definitions]] are up to date
- Ensure every document has a well-formatted title (required for Markdown Links, Markdown Notes, and Foam Gatsby Template compatibility)
In the future, Janitor can help you with
- Updating [[materialized-backlinks]]
- Lint, format and structure notes
- Rename and move notes around while keeping their references up to date.
## Using Janitor from VS Code (Experimental)
Execute the "Foam: Run Janitor" command from the command palette.
![Foam Janitor demo](../../assets/images/foam-janitor-demo.gif)
## Using Janitor from command line (Experimental)
> ⚠️ Improvements to this documentation are welcome!
The Janitor can be installed from [NPM](https://www.npmjs.com/) and executed as a standalone CLI tool:
```sh
> npm install -g foam-cli
> foam janitor path/to/workspace
```
You can run the Janitor as a git hook on every commit to ensure your workspace links are up to date. This can be especially helpful if you edit your markdown documents from other apps.
You can also run the Janitor from a GitHub action to ensure that all changes coming to your workspace are up to date. This can be useful when editing your Foam notes from mobile (i.e. via [GitJournal](https://gitjournal.io)), or your Foam has multiple contributors and you want to ensure that all changes are correctly integrated.