Using YAML frontmatter and wikilinks in LeafWiki

[johnjkr]

I am exploring how I might use Leaf Wiki for an interna; company communications archive. Here is some background on the project to date and the goals to provide context.
I have collected over 400 corporate documents and any associated pdf, image, audio, or video files. I have copied or transcribed all of these as 'notes', which are .md files in Obsidian (https://obsidian.md/). I selected Obsidian in part because it supported "Properties" for indexing and tagging documents; this is done using YAML frontmatter https://obsidian.md/help/properties
Obsidian adds some additional features to Markdown and also supports WikiLinks.
Obsidian stores notes in a "vault"; a vault is a folder on your local file system, including any subfolders. For linked files, e.g. jpeg or mp4, the paths are all relative to the vault folder.
To date I have over 400 'notes' (Obsidian flavored .md files) each with 'properties' for the Year (in yyyy-mm-dd format), tags, type, author, and division. These properties are saved in the note's .md file as YAML frontmatter. This frontmatter then allows for indexing, searching, grouping, etc. of notes by property value. These 400+ notes also have WikiLinks to other notes and files.

Here is an sample note for a company newsletter with frontmatter (properties) and WikiLinks. These WikiLinks are sometimes embedded - in the sample that would be the ![[happy_ppl_202306.jpg]] link; the preceding ! embeds it.
2023-07-18 - Company Newletter.md

While Obsidian has been very helpful for building this 'vault', it is not set up for sharing across more than a few people without paying for their hosted Obsidian Publish offering. I came across LeafWiki as a potential internally hosted way to publish this vault as a wiki. I am very impressed with LeafWiki's usability. If I could easily port these Obsidian flavored .md files without recreating every WikiLink and could use the YAML frontmatter or replicate this property and tag functionality within LeafWiki, I think I would have my solution.

As I mentioned in #761 I am prototyping this on a Windows machine. We are a MSFT shop so that likely would be the prod deployment as well.

Thank you for your work on this application and taking the time to understand my use case.

[perber]

Hi @johnjkr,

your use case is actually very close to what I want LeafWiki to support long-term.

Right now, the main limitation (as you’ve probably seen during your testing) is the import step, especially around WikiLinks and assets. Preserving the frontmatter is not a big issue and is something I should be able to implement fairly soon.

LeafWiki uses standard Markdown links internally, so Obsidian-style WikiLinks would need to be converted during import. There are also some differences in naming conventions. For example, a file like 2023-07-18 - Company Newsletter.md would become 2023-07-18-company-newsletter.md, and links would need to be updated accordingly.

So this is not just a simple file import — it needs more of a refactoring-like approach, where links are migrated consistently across the whole note set.

Your use case actually made me take a closer look at this area, and I’ll likely focus on improving the importer next.
I’ll likely start looking into this in early April, and aim to have a first version ready sometime around mid-April.
The goal would be to make imports from setups like yours much smoother and closer to “just works”.

In addition to that, I’m currently working on a related improvement for the next minor release:
when files are renamed or moved, LeafWiki will automatically update links across affected pages and show which pages were changed — so these updates are not hidden, but transparent.

If you’re open to it, I’d really value your input while working on this. I’d be happy to reach out once there’s an improved importer, or to validate specific edge cases from your dataset along the way.

Your vault is pretty much an ideal real-world test case for this.

Also, just to understand your priorities better: if you had to choose, what would be more critical for you initially — correct link migration or being able to filter/group notes by frontmatter (tags, year, etc.)?

Really appreciate you taking the time to write this up — this kind of input is super helpful.

[johnjkr]

Hi @perber,
I would be very honored and happy to provide input that can help you improve LeafWiki.

Preserving YAML frontmatter would be amazing b/c it lays the groundwork for so much new functionality and utility. I'll get back to frontmatter and some of my ideas for it's usage from the UI after covering link migration.

Link migration For correct link migration, I think I may be able to take some steps that will make my notes' links work in both Obsidian and LeafWiki:

1. Remove spaces from my files names for notes as well as related image, audio, video etc. files so there won't be the need for replacing file name spaces with - or %20 in non-Obsidian, standard Markdown apps.

Questions

a. Can a standard Markdown link be imported and if so, how much of the file path needs to be in the link - from C: drive,, e.g., C:\LeafWiki\data\attachments\audio , or from /LeafWiki folder, e.g., data\attachments\audio , and
b. Do the folders and files need to be all lower case or is 'human-friendly' upper and lowercase letters in the filename ok?

2. Also, it looks like someone has made a community plug-in that would allow me to quickly convert a vault's current WikiLinks to standard Markdown (or visa a versa). I will test it against a copy of my vault and test import into a test LeafWiki.
3. There is also this open python project that converts a WikiLink to hmtl.
   And, as a bonus, maybe the code from that plugin or the python converters can help you accelerate any efforts that you might take to make LeafWiki 'bilingual' like Obsidian is.

Filter/group notes by frontmatter (tags, year, etc.) I have thoughts on how to present and use the Frontmatter imported (preserved) or created within LeafWiki page composition / editing UI.

1. Managing the YAML Frontmatter attributes in LeafWiki. I would suggest LeafWiki use / assume / enforce the standard YAML property names and metadata attributes. I'm sure you are familiar with them but here's a summary for other readers.
2. Custom Properties Obsidian and other apps support the creation and use of custom properties, e.g., type and location in the Company Communications vault / note shared in the original post. Custom property have a Property Name and a Property Type. Custom property Names cannot use a reserved standard name - e.g.. Date, Tags, Author -should not start with special characters. Property types are Strings, Integers, Floats, Booleans, Nulls, Date, Date & Time, Binary (a/k/a Yes/No, True/False, Checkbox), Sequenced Lists, Mappings, Again, you are probably very familiar with this topic but here is some background on Property Types for other readers.
3. Display the Frontmatter in a panel below the title and above the 'body' of the note / page. This panel can be collapsed or opened / expanded using a control on the left margin, a/k/a 'an accordion". I would think the default is 'closed' / 'collapsed' to keep the body text as the main focus, but I suppose there could be a CLI or environment setting to toggle to the user's preferred default position. There would be a header "Properties" (Obsidian speak) or similar, with a clickable icon to the heading's left for Opening and closing the panel. I'm not precious about the icon choice, though right pointing chevron for closed and downward pointing chevron for open are pretty standard. (I should add that Obsidian does not allow this dynamic collapse / expand of the Properties; it is a vault level election to either make it visible or hidden)
4. *Display multiple property values horizontally, not vertically as they are listed in the Frontmatter. This will both save space and make for more intuitive 'left to right' reading of the values.
5. **Interaction with the Properties" from the page would be a great first feature. Each of the Property values would be "clickable" and the result would be either changing the current page or opening a new tab with a page that would display all the pages with that same Property value. Using the company communications vault from above, clicking the Tags = marketing would open a result page (same or new tab? I feel like new tab is a better default behavior) listing all the pages with a Tags = marketing property. For date, I think each date component - year, month, day - would work well as follows: click the year segment and all pages for that year are returned; click month and all pages for that month and year pair are returned; click the day and only other pages with that specific year and month and day are returned. Open to hearing other behaviors for the date field.
6. Current LeafWiki search support for Properties / Frontmatter would be modified / enhanced in a few ways. One, I would want the search results to prioritize matches against a Property value higher than a match against the string in a title or the 'body' of the page. Additionally, I would want the ability to restrict searches to Property values in at least these ways
   a. Ability to search for pages where the search text string is found in any Property field. Following common approaches, this could be done by appending "Within Properties:" to a search by either typing that text in the text box before the search term(s) and / or by clicking a new "Search Only in Properties" checkbox that prepopulates that prefix.
   b. Ability to search for pages where the search text string is only found in a particular "Property", e.g., search for all tags = newsletter. That could look like appending a "Property:" prefix to a search by either typing that text in the text box before the search term(s) and / or by clicking a new "Search Property" pull-down list of standard and defined custom properties, with the selected value used to repopulate the prefix values.
   c. Dates are likely a special case with eventual, advanced requirements to search by Year, Month and Year, Day and Month and Year.

To close this rather long response, let me answer your question regarding my priorities: and if I had to choose, what would be more critical for me initially — correct link migration or being able to filter/group notes by frontmatter (tags, year, etc.)?, I would say:

1. The ability to see frontmatter in pages and to filter/group/search notes by frontmatter. Dependencies for this that I see at first glance are:
   a. The ability to import and preserve YAML frontmatter as Properties.
   b. The ability to add and edit Properties to both previously imported pages AND while creating new pages.
   c. The ability to Create custom Properties. Once this is supported, the import function should validate / warn if an incoming .md file contains a custom Property that had not yet been defined.

2. Support for both standard Markdown links and WikiLinks, a/k/a being bilingual. That will eventually support more robust link migration, Until then, I will try a. replacing spaces in my filenames and b. using the WikiLinks <> Markdown community plugin on my Obsidian vault before trying another import.

I hope this has been helpful. I look forward to the answers to my Questions about filenames and paths. And I am excited to help you improve your application.

[perber]

Hi @johnjkr,

thank you for taking the time to write this up.

On link migration and your questions

First, a quick clarification on how LeafWiki currently handles links:

LeafWiki does not directly resolve links based on the filesystem structure.
Internally, pages are handled via their own URLs, so links need to be parsed and mapped to that internal routing model, not just copied as-is.

Because of that, the core challenge is not really:

WikiLinks vs. Markdown links
but:
consistently parsing and migrating references across the entire dataset

At the moment, full link migration is not implemented yet, so links are not automatically rewritten during import.

Your specific questions

a) Paths
You should not use absolute paths like:

C:\LeafWiki\...

Instead, use relative paths within your dataset, e.g.:

attachments/audio/file.mp3

That aligns best with how LeafWiki processes content during import.

b) Filename casing
Human-friendly filenames (mixed upper/lowercase) are completely fine.

LeafWiki currently normalizes filenames internally for consistency, so you don’t need to enforce lowercase yourself.
About your suggested approach

What you outlined is actually a very good strategy for now:

• removing spaces from filenames → reduces edge cases
• converting WikiLinks → Markdown links → helps simplify migration
• keeping everything relative → important

That won’t fully solve link migration yet, but it will make things much more predictable.

On frontmatter and properties

I fully agree with your direction here — frontmatter is a very strong foundation for more structured workflows.

From a prioritization perspective, my current focus is:

• Preserve frontmatter reliably during import
• Improve the importer so datasets like yours can be brought in safely
• Expose properties (frontmatter) in the UI in a simple way

More advanced features like filtering, grouping, search integration, etc. are definitely interesting, but will come after the import layer is solid.

About “bilingual” link support

Longer term, I agree that supporting both:

• WikiLinks
• standard Markdown links
  would be useful.

Thanks again and for your help to improve LeafWiki.

[perber]

One more note regarding the importer:

I’ll be starting to improve the importer next, especially around handling real-world datasets like yours (links, structure, etc.).

So if you’re not in a rush, it might be worth waiting a bit before doing a full migratiom.
The goal is to make this process much smoother and closer to “just works”.

I’ll update you here once a better version is ready.

[perber]

I have added your request to v0.10.0 - https://github.com/perber/leafwiki/milestone/14

[johnjkr]

Hi Perber,

I tried out some small imports over the weekend. One issue I keep encountering is the page titles created by the import contain file paths.

For example, for file 1999-07-23 - Memo to Staff.md the created page title is C:\Users\johnjkr\AppData\Local\Temp\import-1280817455\1999-07-23 - Memo to Staff

Some files do not get this path title, but almost all do and I don't see a pattern that explains why / why not.

Also, in the Import screen, when I see that there are problems with the "Import Plan", I do not see a way to cancel the plan. The only option is to Execute Import Plan. I've tried going back in the browser and logging out of my admin session. When I log back in and go to Import, the plan is still there, waiting to be executed. Any tips on how to cancel / delete pending import plans?

[johnjkr]

I am also running into a limitation with the Add an Image or File loader. A number of the notes have related audio and video files.
I cannot seem to create a link in a leafwiki page to these files using the Add an Image or File loader because the files are too large.

Also, even when we can link to these files, we very often do not want to embed the files in the page; we want it to be a link that would open a new page and display or play the image, audio, or video.

How do I make a link to an asset that was added without embedding it into the page?

[perber]

Thank you for your Feedback. I will create issues for that and link them here in the discussion.

[perber]

Also, in the Import screen, when I see that there are problems with the "Import Plan", I do not see a way to cancel the plan. The only option is to Execute Import Plan. I've tried going back in the browser and logging out of my admin session. When I log back in and go to Import, the plan is still there, waiting to be executed. Any tips on how to cancel / delete pending import plans?

You can just upload a new Zip. But you are right. A cancel button makes sense.

For example, for file 1999-07-23 - Memo to Staff.md the created page title is C:\Users\johnjkr\AppData\Local\Temp\import-1280817455\1999-07-23 - Memo to Staff

I think this is a issue because of windows paths. Will try to reproduce it and fix it.
Why some getting a different name could be because of the order, how the name is resolved.

1. LeafWiki checks if a title frontmatter field exists and if so it uses the value.
2. LeafWiki takes the first Headline when it starts with "# Headline"
3. It will take the filename (but shouldn't take the full path)

I am also running into a limitation with the Add an Image or File loader. A number of the notes have related audio and video files.
I cannot seem to create a link in a leafwiki page to these files using the Add an Image or File loader because the files are too large.

Currently the max upload size is hardcoded. I will introduce a flag to configure the upload limit.

Also, even when we can link to these files, we very often do not want to embed the files in the page; we want it to be a link that would
open a new page and display or play the image, audio, or video.

Usually it should be possible with files like this:

[Kafka Konzept](/assets/3xhVkZgDR/kafka_newkonzept.pdf)

Can you describe it in more detail? Maybe I miss something.

Today, I will release version v0.8.4.

I will create the issues later today and will release them in the next version v0.8.5, so the things should be improved until next monday.