Foam for Gollum – Visual Studio Code Extension

Foam for Gollum is a fork of the Foam Visual Studio Code extension, which adds support for the wikilink syntax that is used in Markdown documents in Gollum-based wikis.

Gollum is a wiki software based on the Git version control system. For example, GitHub's repository wikis are based on Gollum and use its syntax.

Wikilinks are page name links in double brackets ([[Page Name]]), which are used in wiki pages to link to other wiki pages. The main differences of the Gollum-style wikilinks to the standard wikilink syntax of MediaWiki are:

• When a wikilink has an alias, the alias comes first: [[Alias|Page Name]]
• Section headings after a hash (#) have a different syntax.
• Wikilinks are relative to the current document directory and not to the root directory of the wiki.

New Settings

New settings in this extension and their defaults are:

"foam.wikilinks.syntax": "gollum",
"foam.wikilinks.caseInsensitive": true,
"foam.useCustomFileDropdownProvider": true,
"foam.fileDropdown.uploadsFolderName": "uploads",
"foam.fileDropdown.fileTemplateFormat": "markdown",
"foam.fileDropdown.imageTemplateFormat": "markdown"

Possible values for the settings are:

You don't need to specify these settings in Visual Studio Code's settings, if the defaults work for you.

In the case you have multiple repositories with different Markdown syntaxes, you can add Foam for Gollum's settings to workspace settings, so that they are specific to a repository. For repositories using the MediaWiki syntax, you need to specify:

"foam.wikilinks.syntax": "mediawiki",
"foam.wikilinks.caseInsensitive": false,
"foam.useCustomFileDropdownProvider": false

New Features in This Extension

1. Gollum-Style Wikilinks

This extension adds support for the following Gollum-style wikilink features, when "foam.wikilinks.syntax" setting is "gollum".

1.1. Alias First in Wikilinks

Wikilinks with an alias follow the convention [[Alias|Page Name]].

1.2. Section Heading Anchors Follow Gollum Notation

Anchors for section headings (# + the section heading name in the wikilink) use the Gollum format, which is the following:

• The text is converted to lower case.
• Special characters are removed.
• Spaces are replaced with dashes.

For example, if you have a section heading 4. My Test Heading, you should use #4-my-test-heading as the anchor in the wikilink.

1.3. Gollum-Style Relative and Absolute Path Support

In Gollum, wikilinks are relative to the current document directory and not to the root of the wiki. If you are working with files in subdirectories, you need to pay attention to the path in wikilinks, since [[Page Name]] links to a document in the current subdirectory and not to a document in the root directory of the wiki. To access parent and root directories, you need to use / and ../ before the page name in a wikilink.

This extension adds support for the following notations for wikilinks:

Multiple levels of subdirectories are supported.

2. Case-Insensitive Wikilinks

When "foam.wikilinks.caseInsensitive" setting is true, wikilink parsing is case-insensitive.

Example

• [[my page]] links to My page.md but shows as my page in the preview.

3. Custom File Dropdown Provider

When the "foam.useCustomFileDropdownProvider" setting is true, Visual Studio Code uses a custom file dropdown provider that places dropped files under /uploads/ using a special logic. It creates a folder under /uploads/ based on the current document folder and the current document name. For example, files related to /Items/Amulets.md will go under /uploads/Items/Amulets/.

Dots in a page name are kept, and only the file extension is removed: files related to /Comparisons/A vs. B.md will go under /uploads/Comparisons/A vs. B/.

When you drop files into a Markdown file, Foam's upload ("Insert as Gollum upload") is the default drop option. The drop widget shown after a drop still offers VS Code's own options. Set "foam.useCustomFileDropdownProvider": false to restore VS Code's built-in behavior.

3.1. Uploads Folder Name Customization

The uploads folder name is customizable via the "foam.fileDropdown.uploadsFolderName" setting.

The default value is "uploads".

3.2. File Dropdown Template

You can customize the file dropdown template with the foam.fileDropdown.fileTemplateFormat setting.

3.3. Image Dropdown Template

You can customize the image dropdown template with the foam.fileDropdown.imageTemplateFormat setting.

Foam Extension Features

Please refer to the Foam for Gollum documentation for the full description of the features of the Foam extension.

Settings

All settings are listed in the VS Code Settings editor: search for foam.. Each feature's page in the documentation explains the settings it uses.

Telemetry

Foam for Gollum sends error reports only, never usage data. When something goes wrong in the extension, a report goes to Sentry (servers in the EU), operated by Hyvän mielen pelit ry, the maintainers of this extension. A report contains:

• the type of error, its message and its stack trace, with file and folder paths removed;
• the extension version;
• the VS Code version and the operating system.

The same error is reported once per session, and at most 20 reports are sent per session.

Reports never contain your notes, file names or paths, your user or machine ID, or your IP address. VS Code for the Web sends no reports.

Error reports follow VS Code's telemetry.telemetryLevel setting: they are sent when it is all or error, and never when it is crash or off. See Telemetry for details.