Fixing Wiki-Link Handling in Eleventy.js
This document outlines the changes made to .eleventy.js to fix issues with wiki-link handling in the Digital Garden.
This document has been updated to include an additional fix for the root file path resolution issue documented here.
Issues Fixed
- Wiki-links using permalinks (like
Daily Notes) were causing build errors - The system was incorrectly prepending the base path (
src/site/notes/) multiple times - Automatic creation of stub files for missing links was causing bloat and confusion
- File read operations on directories were causing EISDIR errors
- A permalink format issue in one file was causing file/directory conflicts
- Wiki-links to root files were incorrectly resolving to
/notes/filenameinstead of using the permalink
Detailed Changes
1. Adding Special Handling for Permalink Wiki-Links
Issue: Links in the format Title were being treated as file paths with slashes instead of as permalinks.
Before:
function getAnchorAttributes(filePath, linkTitle) {
let fileName = filePath.replaceAll("&", "&");
let header = "";
let headerLinkPath = "";
if (filePath.includes("#")) {
[fileName, header] = filePath.split("#");
headerLinkPath = `#${headerToId(header)}`;
}
let noteIcon = process.env.NOTE_ICON_DEFAULT;
const title = linkTitle ? linkTitle : fileName;
let permalink = `/notes/${slugify(fileName)}`;
let deadLink = false;
// ... rest of function
After:
function getAnchorAttributes(filePath, linkTitle) {
let fileName = filePath.replaceAll("&", "&");
let header = "";
let headerLinkPath = "";
// Handle permalinks in wiki-links
if (filePath.startsWith('/') && filePath.endsWith('/')) {
// This is a permalink-style link, extract without the slashes
const permalinkPath = filePath.slice(1, -1);
let noteIcon = process.env.NOTE_ICON_DEFAULT;
const title = linkTitle ? linkTitle : permalinkPath;
// Simply use the permalink directly
return {
attributes: {
"class": "internal-link",
"target": "",
"data-note-icon": noteIcon,
"href": `${filePath}`,
},
innerHTML: title,
}
}
if (filePath.includes("#")) {
[fileName, header] = filePath.split("#");
headerLinkPath = `#${headerToId(header)}`;
}
// ... rest of function
Explanation: This change adds special handling for wiki-links that use the permalink format (Title). When detected, it immediately returns the correct attributes without attempting to resolve the file path, preventing errors when trying to read directories.
2. Preventing Duplicate Path Prefixes
Issue: The system was incorrectly adding src/site/notes/ to paths that already included this prefix.
Before:
// If the path already contains a directory structure, treat it differently
if (fileName.includes('/')) {
// Try to get or create the file if it doesn't exist
try {
fullPath = getOrCreateNoteStub(fileName);
} catch (e) {
fullPath = fileName.endsWith(".md")
? `${startPath}${fileName}`
: `${startPath}${fileName}.md`;
}
}
After:
// Make sure we don't duplicate the base path
if (fileName.startsWith('src/site/notes/')) {
fileName = fileName.replace('src/site/notes/', '');
}
// If the path already contains a directory structure, treat it differently
if (fileName.includes('/')) {
// Don't attempt to create stub files, just construct the path
fullPath = fileName.endsWith(".md")
? `${startPath}${fileName}`
: `${startPath}${fileName}.md`;
}
Explanation: This change checks if the file path already includes the base path and removes it if found. This prevents file paths like src/site/notes/src/site/notes/file.md which were causing errors.
3. Removing Automatic Stub File Creation
Issue: The system was automatically creating stub files for links that pointed to non-existent files.
Before:
// Helper function to handle missing files by creating stubs
function getOrCreateNoteStub(filePath) {
const startPath = "./src/site/notes/";
const fullPath = filePath.endsWith(".md")
? `${startPath}${filePath}`
: `${startPath}${filePath}.md`;
try {
// Check if file exists first
fs.readFileSync(fullPath, "utf8");
return fullPath; // Return the path if it exists
} catch (e) {
// File doesn't exist, try to create a stub
try {
const fileName = filePath.split("/").pop();
const dirPath = fullPath.substring(0, fullPath.lastIndexOf("/"));
// Create directory if it doesn't exist
if (!fs.existsSync(dirPath)) {
fs.mkdirSync(dirPath, { recursive: true });
}
// Create a minimal stub file
const stubContent = `---
dg-publish: true
permalink: /${slugify(fileName)}/
---
# ${fileName}
This is a stub page. Content will be added later.
`;
// Only write the file if it doesn't exist
if (!fs.existsSync(fullPath)) {
fs.writeFileSync(fullPath, stubContent);
console.log(`Created stub file: ${fullPath}`);
}
return fullPath;
} catch (stubError) {
console.warn(`Error creating stub file: ${stubError.message}`);
throw e; // Re-throw the original error
}
}
}
After:
// Helper function to handle missing files by creating stubs
function getOrCreateNoteStub(filePath) {
const startPath = "./src/site/notes/";
const fullPath = filePath.endsWith(".md")
? `${startPath}${filePath}`
: `${startPath}${filePath}.md`;
try {
// Check if file exists first
fs.readFileSync(fullPath, "utf8");
return fullPath; // Return the path if it exists
} catch (e) {
// File doesn't exist, but don't create a stub - just return the path
// This disables the automatic stub file creation
console.warn(`File not found: ${fullPath}`);
return fullPath;
}
}
Explanation: This change eliminates the automatic creation of stub files, which was causing confusion and bloat in the repository. Now it simply logs a warning and returns the path.
4. Adding File Existence Check Before Reading
Issue: The system was attempting to read files that didn't exist, causing errors.
Before:
const file = fs.readFileSync(fullPath, "utf8");
const frontMatter = matter(file);
// Use permalink from frontmatter if available
if (frontMatter.data.permalink) {
permalink = frontMatter.data.permalink;
}
// ... more code
After:
// Only try to read the file if it exists
if (fs.existsSync(fullPath)) {
const file = fs.readFileSync(fullPath, "utf8");
const frontMatter = matter(file);
// Use permalink from frontmatter if available
if (frontMatter.data.permalink) {
permalink = frontMatter.data.permalink;
}
// ... more code
} else {
console.warn(`File not found: ${fullPath}`);
deadLink = true;
}
Explanation: This change adds a check to verify that a file exists before attempting to read it, preventing file system errors.
5. Fixing Permalink Format in a File
Issue: The file 202503261845.md had a permalink without the standard leading and trailing slashes, causing path conflicts.
Before:
---
dg-publish: false
tags:
- programming-language
permalink: java
hide: true
aliases:
- java
---
After:
---
dg-publish: false
tags:
- programming-language
permalink: /java/
hide: true
aliases:
- java
---
Explanation: This change standardizes the permalink format to include leading and trailing slashes, consistent with the rest of the site's URL structure. This prevents a conflict where both a file and directory were trying to be created at the same path (dist/java).
6. Fixing Root File Resolution
Issue: Wiki-links to files in the root directory (e.g., Daily Notes Archive) were incorrectly resolving to /notes/daily-notes instead of using the file's permalink (/daily-notes/).
Problem in getAnchorAttributes Function
First, the issue was thought to be in the getAnchorAttributes function, and we added a check for direct file matches in the root directory:
// Check for exact file match in the root directory first
const rootFilePath = `${startPath}${fileName}${fileName.endsWith('.md') ? '' : '.md'}`;
if (fs.existsSync(rootFilePath)) {
// Direct match in root directory
fullPath = rootFilePath;
} else if (fileName.includes('/')) {
// If the path already contains a directory structure...
}
However, this change alone didn't resolve the issue.
Actual Fix in link Filter Function
The critical issue was in the link filter function, which processes wiki-links. The function was incorrectly finding files during the recursive search process:
Before:
eleventyConfig.addFilter("link", function (str) {
return (
str &&
str.replace(/\[\[(.*?)(?:\|(.*?))?\]\]/g, function (match, fileLink, linkTitle) {
// ...other checks...
// Try to find the file by alias or by searching through the file structure
const startPath = "./src/site/notes/";
let foundFilePath = null;
try {
const files = fs.readdirSync(startPath, { recursive: true });
// First try to find a direct match by filename
const exactMatch = files.find(file => {
return file.toLowerCase() === `${fileLink.toLowerCase()}.md` ||
file.toLowerCase() === fileLink.toLowerCase();
});
if (exactMatch) {
foundFilePath = exactMatch.replace(/\.md$/, '');
} else {
// Try to find by alias...
}
} catch (e) {
// ... error handling
}
// Use the found path or fall back to the original fileLink
return getAnchorLink(foundFilePath || fileLink, linkTitle || fileLink);
})
);
});
After:
eleventyConfig.addFilter("link", function (str) {
return (
str &&
str.replace(/\[\[(.*?)(?:\|(.*?))?\]\]/g, function (match, fileLink, linkTitle) {
// ...other checks...
// Try to find the file by alias or by searching through the file structure
const startPath = "./src/site/notes/";
let foundFilePath = null;
try {
// First, check for exact file match in root directory
const rootFilePath = fileLink.endsWith('.md')
? `${startPath}${fileLink}`
: `${startPath}${fileLink}.md`;
if (fs.existsSync(rootFilePath)) {
// Direct match in root directory, keep file name as is
foundFilePath = fileLink;
} else {
// If not found in root, search recursively
const files = fs.readdirSync(startPath, { recursive: true });
// Try to find a direct match by filename
const exactMatch = files.find(file => {
if (!file.includes('/')) return false; // Skip root files (already checked)
return file.toLowerCase() === `${fileLink.toLowerCase()}.md` ||
file.toLowerCase() === fileLink.toLowerCase();
});
if (exactMatch) {
foundFilePath = exactMatch.replace(/\.md$/, '');
} else {
// Try to find by alias...
}
}
} catch (e) {
// ... error handling
}
// Use the found path or fall back to the original fileLink
return getAnchorLink(foundFilePath || fileLink, linkTitle || fileLink);
})
);
});
Explanation: The key issue was that when searching for files, the recursive directory search would find all files, including those in subdirectories. For a wiki-link like Daily Notes Archive, it could find both "Daily Notes.md" in the root and potentially files within a "Daily Notes" directory.
The fix prioritizes checking for an exact file match in the root directory first. Only if no match is found in the root does it proceed to search subdirectories, and in that case, it explicitly skips root files (which were already checked). This ensures that for a file like "Daily Notes.md" in the root directory, its permalink will be correctly used for wiki-links.
Results
These changes resulted in:
- Successful resolution of wiki-links using permalinks
- Elimination of EISDIR errors during build
- Prevention of stub file creation
- Correct handling of file paths without duplication
- Consistent permalink formatting
- Proper resolution of wiki-links to files in the root directory, using their frontmatter permalinks
The build system now properly handles wiki-links in all formats, including direct permalink references and links to files in the root directory, and doesn't attempt to create unnecessary stub files.