For the time being, if you want to get [wiki-links] into all files within the workspace, you’ll need to generate the link reference definitions yourself file-by-file (with the assistance of Foam).
TL;DR; workaround in the end of the chapter.
If you click any of the wiki-links on GitHub web UI (such as the README.md
of a project), you’ll notice that the links break with a 404 error.
At the time of writing (June 28 2020) this is a known, but unsolved error. To understand why this is the case, we need to understand what we are trading off.
So, why don’t they work on GitHub?
The three components of [link-reference-definitions] are link label, link destination and Link Title.
The issue is the middle link destination component. It’s configured to point to the file name without file extension, i.e. “file-name” instead of “file-name.md”. This is to make the GitHub Pages rendering work, because if we generated the links to file-name.md
, the links would point to the raw markdown files instead of their generated HTML versions.
Environment | file-name |
file-name.md |
---|---|---|
VS Code | Works | Works |
GitHub pages | Works | Breaks |
GitHub UI | Breaks | Works |
So as you can see, we’ve prioritised GitHub Pages over GitHub Web UI for the time being.
Ideally, we’d like a solution that works with both, but it’s not defined yet (see [link-reference-definitions] for more details)
For the time being, you can use relative [markdown links](markdown-link.md)
syntax.
Pros:
Cons:
Since link reference definitions have [//begin]
and [//end]
guards with explanatory text that use certain words, these words (like “generate”) appear in VS Code search results if you happen to search matching strings from the workspace.
Problem space in essence:
The potential solution:
.md
file.// settings json
// see enumerations below for explanations on values
{
"foam": {
"publish": [
{
"name": "Gitlab Mirror", // name of the publish target
"linkTranspilation": "Off",
"linkReferenceDefinitions": "withExtensions"
},
{
"name": "GitHub Pages",
"linkTranspilation": "Off",
"linkReferenceDefinitions": "withoutExtensions"
},
{
"name": "Blog",
"linkTranspilation": "Off",
"linkReferenceDefinitions": "Off"
},
{
"name": "My Amazing PDF book",
"linkTranspilation": "WikiLinksToMarkdown"
}
],
"edit": {
"linkReferenceDefinitions": "Off"
}
}
}
// Defines if and how links in markdown files are somehow converted (in-place) during build time
// Note that this enumeration is not valid edit-time, since we (probably) don't want to change text like this while user is editing it
enum LinkTranspilation {
Off, // links are not transpiled
WikiLinksToMarkdown, // links using wiki-format [[link]] are converted to normal md links: [link](./some/file.md)
// if this is set, not link reference definitions are generated (not needed)
}
// Defines if and how link reference definition section is generated
enum LinkReferenceDefinitions {
Off, // link reference definitions are not generated
WithExtensions, // link reference definitions contain .md (or similar) file extensions
WithoutExtensions // link reference definitions do not contain file extenions
}
Note that the proposal above supports both (build-time) inline transpilation of wikilinks as well as creation reference definitions. Depending on the direction of Foam, also only one of them could be selected. In that case the other could be implemented at later point of time.
UI-wise, the publish targets could be picked in some similar fashion as the run/debug targets in vscode by implementing a separate panel, or maybe through command execution (CTRL+SHIFT+P) - not yet defined at this point.