Easy Wikilinks

Kitbook supports using Foam to easily add wikilinks between your various documentation pages in a manner that ensures they always stay up-to-date. These links will also work in Github.

Setup Foam

• Add the Foam extension
• Add these settings:

.vscode/settings.json
json
{
  "foam.completion.label": "title",
  "foam.edit.linkReferenceDefinitions": "withExtensions",
  "foam.files.ignore": [
      "**/node_modules/**/*",
      // any folders containing unrelated markdown files not part of your Kitbook can be added here to avoid autocompletion noise
  ]
}

• Add a placeholder .vscode/foam.json file to tell the Foam extension to activate in your repo:

.vscode/foam.json
json
{
  "purpose": "this file exists to tell the foam-vscode plugin that it's currently in a foam workspace",
  "future": "we may use this for custom configuration"
}

• Adding the Markdown All in One extension is also recommended but not required for Foam functionality. It’s best feature is the ability to paste a URL on top of highlighted text to automatically create a markdown link.

Usage

You should read the Foam docs, but to get you started, you can create a link to any .md file in your repo by typing [[ and then letting Foam’s autocomplete help you as you type either the filename or the main heading. For example, to link to this page which has a name of 6-easy-wikilinks and a main heading of Easy Wikilinks, just start typing heading [[Easy Wi and select the autocomplete option to place[[6-easy-wikilinks]] in your code which will render like this: [Easy Wikilinks]. Now you can now click the link in your editor to jump to that file. Note that sometimes Foam is one keystroke behind, and you may need to make one more edit to your file (like a space) and before Foam automatically creates a wikilink reference at the bottom of your file. Foam handles the linking in your editor and Kitbook uses these wikilink references to give you appropriate links in the browser.

The Foam extension does a good job of automatically updating links as you change filenames but until you are very familiar with its behavior, it’s a good idea to occasionally run Foam: Run Janitor from VS Code’s command palette to ensure the links across your entire repo are up to date.

Using Aliases

Sometimes when you link to a page in mid sentence like [this project’s amazing guide to getting started] you want to use a custom alias for your wikilink. You can do that by adding a | character followed by your alias. That link you just saw looks like [[1-get-started|this project's amazing guide to getting started]] in the source code.

Linking to a sub-heading

Foam supports linking to specific sections of a page, which you can also take advantage of in Kitbook. So [[6-easy-wikilinks#Setup Foam]] would result in a direct link to the section above and looks like: [Setup Foam]. If you change your section titles, Foam will not automatically update the link to that section though it will give you an editor warning on the wikilink that no section with such title exists.