PRD Document For Tauri React Markdown App With YAML Relationships

Hey guys! Let's dive into creating a powerful, local-first markdown knowledge base application using Tauri, React, and a few other cool technologies. This article outlines a detailed Product Requirements Document (PRD) to guide the development process. Think of it as your blueprint for building a Notion-like experience that keeps your data in plain text files, giving you the best of both worlds!

🧾 PRD: Markdown Knowledge Base with Structured Relationships

This document provides a comprehensive overview of the features, goals, and technical stack required to build our application. It's designed to be a living document, evolving as the project progresses and new ideas emerge. So, buckle up and let's get started!

1. 📌 Product Overview

Our goal is to build a lightweight and efficient markdown editor that empowers users to manage their knowledge locally. This app will be powered by Tauri, React, and TypeScript, offering a fast and responsive user interface. Here's what users will be able to do:

• Open a folder of .md files: The app should seamlessly load existing markdown files from a directory of the user's choice.
• View and edit each file using a rich WYSIWYG editor: We'll integrate a What You See Is What You Get (WYSIWYG) editor to make markdown editing intuitive and user-friendly.
• Store metadata in YAML frontmatter: YAML frontmatter will allow users to add structured data to their markdown files, such as titles, tags, and dependencies.
• Define relationships between files (e.g., projects, dependencies): Users can link files together, creating a network of interconnected knowledge.
• Visually organize and navigate relationships: The app will provide visual tools to explore and understand the relationships between files.
• Use a Notion-like UI while preserving plain-text and folder structure: We aim for a clean, modern interface similar to Notion, while ensuring users retain control over their files and folder organization.

This approach blends the flexibility of markdown with the organizational power of structured data and visual relationships. The key here is to provide a Notion-like user experience while keeping the data in simple, portable .md files. This means you're never locked into a proprietary format and you always have access to your raw data. This local-first approach is vital for privacy and control, guys!

We envision a system where you can easily manage your notes, project plans, and even complex documentation sets, all within a single application. The integration of YAML frontmatter for metadata is a game-changer, allowing you to add structure and context to your markdown files. Think of it as adding a brain to your notes! The ability to define relationships, like dependencies or project affiliations, is where the real power comes in. Imagine being able to visualize your entire project workflow, seeing how tasks connect and depend on each other. This is the kind of productivity boost we're aiming for.

The WYSIWYG editor is also a crucial piece of the puzzle. While markdown is fantastic for its simplicity and portability, sometimes you just want to see your text formatted as you type. By integrating a rich text editor, we make the app accessible to a wider range of users, not just the markdown aficionados. Plus, the Notion-like UI ensures a familiar and intuitive experience, minimizing the learning curve. This is about making knowledge management as seamless and enjoyable as possible.

2. 🎯 Goals

To make this vision a reality, we've defined a set of specific goals for the application. These goals will guide our development efforts and ensure we stay focused on delivering the core features that matter most. Let's break down the key objectives:

• ✅ Load markdown files from a user-selected directory: The app must be able to open and read .md files from any folder chosen by the user. This is the foundation of our local-first approach.
• ✅ Display metadata extracted from YAML frontmatter: The app needs to parse YAML frontmatter from markdown files and present this information in a clear and organized way. This allows us to surface crucial details like titles, tags, and dependencies.
• ✅ Edit markdown content in a rich WYSIWYG editor: Integrating a WYSIWYG editor is essential for providing a smooth and intuitive editing experience. Users should be able to format their text easily without needing to memorize markdown syntax.
• ✅ Allow files to “link” to one another (dependencies, tags, etc.): This is where the relationship magic happens! The app should enable users to create connections between files, representing dependencies, related topics, or project affiliations.
• ✅ Group markdown files into “Projects” based on frontmatter or folder: Organizing files into projects is crucial for managing large knowledge bases. The app should allow users to group files based on YAML frontmatter fields or folder structure.
• ✅ Display relationships in a clear and interactive UI: Visualizing relationships is key to understanding the connections between ideas and tasks. The app needs to provide an intuitive interface for exploring file dependencies and other relationships.

These goals represent the core functionality of our markdown knowledge base application. Achieving these milestones will set the stage for future enhancements and expansions. We're aiming for a user-friendly, powerful tool that helps you organize and connect your thoughts. The ability to load markdown files from any directory is fundamental. It's about giving you complete control over your data and where it's stored. Displaying metadata from YAML frontmatter unlocks a whole new level of organization. Imagine seeing key information like titles, statuses, and due dates at a glance, right within the app.

The rich WYSIWYG editor is all about making the writing process more enjoyable. No more struggling with markdown syntax – just format your text as you see fit! The linking feature is where things get really exciting. By connecting files together, you can create a web of knowledge, easily navigating between related topics and tasks. Grouping files into projects is essential for managing complexity. Whether you prefer to use YAML frontmatter or folder structure, the app will adapt to your workflow. And finally, visualizing relationships is the ultimate power-up. Seeing how your ideas and tasks connect can spark new insights and help you stay on track.

3. 🧱 Features & Requirements

Let's break down the specific features and requirements that will bring our markdown knowledge base to life. This section delves into the technical details and design considerations for each key aspect of the application.

3.1. File System Support

File system support is the backbone of our application. Since we're building a local-first tool, the ability to read and manage files directly is paramount. Here's how we'll handle file system interactions:

• Users select a root directory: The app will provide a user-friendly interface for selecting a folder containing markdown files. This will be the starting point for our knowledge base.
• App recursively reads .md files in that directory: Once a root directory is selected, the app will automatically scan all subfolders for .md files, ensuring no note is left behind.
• Optionally reads _project.json files for folder-level metadata: We'll support an optional _project.json file within folders to store metadata about the project itself, such as a description or cover image.
• File metadata includes:
  • path: The full file path.
  • filename: The name of the file.
  • folder: The name of the folder containing the file.
  • lastModified: The last modified timestamp of the file.

This detailed file metadata will be crucial for organization, searching, and displaying information within the app. We want to make it effortless for you to import your existing markdown notes, no matter how they're organized. The ability to recursively read files ensures that even deeply nested notes are discovered and included. The optional _project.json file is a clever addition, allowing you to add context and information at the folder level. This is particularly useful for projects with multiple files, where you might want to include a description, team members, or other relevant details.

The file metadata we collect is not just for show – it's the foundation for many of the app's features. The path is essential for accessing and modifying the file. The filename is useful for displaying titles and creating links. The folder helps with project organization. And the lastModified timestamp allows us to sort files by recency. This attention to detail is what sets a great knowledge management tool apart. By providing robust file system support, we're ensuring that our app can handle any size and structure of markdown notes. This scalability is vital for long-term use.

Tech: To implement this, we'll leverage Tauri's filesystem API (@tauri-apps/api/fs). This API provides secure and efficient access to the local file system, ensuring the app can read files without compromising user security.

3.2. Markdown + YAML Frontmatter

Markdown is the language of our knowledge base, and YAML frontmatter is the key to adding structure and metadata. This combination allows us to create rich, organized notes that are still easy to read and edit in any text editor. Here's how we'll handle markdown and YAML frontmatter:

Each .md file supports a frontmatter block:

---
title: "Add LNURL support"
project: "lightning-integration"
status: "todo"
due: "2025-08-01"
depends_on:
  - "refactor-auth.md"
tags: ["lightning", "lnurl"]
---

• Use gray-matter to parse.
• Support fields:
  • title (string): The title of the note.
  • project (string): The project the note belongs to.
  • status (todo, in-progress, done, etc.): The current status of the task or note.
  • depends_on (array of filenames): A list of files that this note depends on.
  • tags (string[]): Keywords or categories associated with the note.

Files missing frontmatter will be assumed to be unstructured notes.

YAML frontmatter is a game-changer for markdown. It allows you to embed metadata directly within your files, making them more organized and searchable. Think of it as adding labels and categories to your notes, but in a machine-readable format. This is what enables us to build features like project views, dependency graphs, and advanced filtering. The specific fields we're supporting are designed to cover a wide range of use cases, from project management to personal knowledge management. The title is the obvious one, providing a clear and concise name for your note. The project field allows you to group related notes together. The status field is great for tracking progress on tasks or projects. The depends_on field is the heart of our relationship system, allowing you to define dependencies between files. And the tags field provides a flexible way to categorize your notes.

The beauty of this approach is that it's opt-in. You don't have to use frontmatter if you don't want to. Files without frontmatter will simply be treated as unstructured notes, allowing you to mix and match structured and unstructured content within your knowledge base. We understand that everyone has their own style of note-taking, and we want our app to accommodate that. The choice of YAML for frontmatter is also important. YAML is a human-readable data serialization format, making it easy to edit by hand. This is crucial for maintaining the portability and simplicity of markdown files. We want you to be able to open your notes in any text editor and understand the metadata at a glance.

Tech: We'll use the gray-matter library to parse YAML frontmatter from markdown files. This library is widely used and well-tested, ensuring robust and reliable parsing.

3.3. Rich Text Editor

A rich text editor is crucial for providing a smooth and intuitive writing experience. While markdown is powerful, sometimes you just want to see your text formatted as you type. Our rich text editor will bridge the gap between markdown and WYSIWYG, making the app accessible to a wider range of users.

• Inline markdown editor with formatting controls:
  • Bold, italic, heading, code, checkbox, quote, bullet list.
• Syntax highlighting for code blocks.
• Live markdown preview with frontmatter extraction.

Our editor will offer inline markdown formatting, meaning you'll see the formatting applied as you type, but you'll still be writing in markdown. This gives you the best of both worlds – the visual feedback of a WYSIWYG editor and the portability of markdown. We'll provide formatting controls for common markdown elements like bold, italic, headings, code, checkboxes, quotes, and bullet lists. This will make it easy to format your text without needing to memorize markdown syntax. Syntax highlighting for code blocks is a must-have for any technical knowledge base. It makes code snippets much easier to read and understand. And finally, a live markdown preview with frontmatter extraction will provide a real-time view of how your note will look, including the metadata from the YAML frontmatter. This is invaluable for ensuring your notes are well-formatted and organized.

The goal here is to make writing in markdown less intimidating and more enjoyable. We want you to be able to focus on your content, not on the syntax. The live preview is particularly important, as it allows you to see the final result without having to switch between editing and preview modes. This seamless workflow is key to productivity. The choice of an inline markdown editor is also a deliberate one. We want to preserve the integrity of markdown as our core format, while still providing a visual editing experience. This approach ensures that your notes remain portable and compatible with other tools.

Tech: We'll use @tiptap/react with markdown extensions to build our rich text editor. Tiptap is a headless editor framework for React that provides a flexible and extensible foundation for creating custom text editors. Its markdown extensions will allow us to easily integrate markdown formatting and syntax highlighting.

3.4. Project & Action Views

To help you organize your knowledge base, we'll provide two key views: Project View and Action View. These views will allow you to group and manage your notes in a way that makes sense for your workflow.

• Project View
  • Group files by project frontmatter field or folder.
  • Show project name, description (optional _project.json).
  • Display contained actions as clickable items.
• Action View
  • Show full WYSIWYG editor.
  • Display metadata from frontmatter.
  • Show “depends on” list with links to other files.
  • Allow updating title/status/tags inline (frontmatter editing).

The Project View is all about big-picture organization. It allows you to see your notes grouped by project, either based on the project field in the YAML frontmatter or by folder structure. This is ideal for managing projects with multiple files, allowing you to see all the relevant notes in one place. We'll also display the project name and description, which can be stored in an optional _project.json file. And finally, we'll display the actions (notes) contained within the project as clickable items, making it easy to navigate to specific notes.

The Action View is where you'll focus on the details. It provides a full WYSIWYG editor for editing your notes, as well as a display of the metadata from the YAML frontmatter. This allows you to see all the key information about a note at a glance. We'll also show a “depends on” list, which displays the files that this note depends on, with links to those files. This is crucial for understanding dependencies and managing complex workflows. And finally, we'll allow you to update the title, status, and tags inline, directly within the Action View. This makes it quick and easy to keep your metadata up-to-date.

These views are designed to work together seamlessly. You can use the Project View to get an overview of your projects, and then drill down into individual notes using the Action View. This hierarchical approach makes it easy to manage both the big picture and the small details. We're aiming for a workflow that's both flexible and efficient, allowing you to organize your knowledge base in a way that makes sense for you.

3.5. Relationships & Dependency Graphs

The ability to define and visualize relationships between files is a core feature of our markdown knowledge base. This is what allows you to connect ideas, track dependencies, and build a true web of knowledge.

• Render depends_on as links or reference blocks.
• Highlight broken links or missing dependencies.
• Optional graph view for file relationships.

We'll start by rendering the depends_on field from the YAML frontmatter as links or reference blocks within the notes themselves. This will allow you to easily navigate between related files. We'll also highlight broken links or missing dependencies, making it easy to identify and fix any issues. This is crucial for maintaining the integrity of your knowledge base. But the real magic happens with the optional graph view. This view will allow you to visualize the relationships between your files in a graphical format, showing dependencies, connections, and clusters of ideas. This can be incredibly powerful for understanding complex relationships and sparking new insights.

Imagine being able to see a visual map of your project, showing how all the tasks and files are connected. Or imagine being able to explore a network of ideas, following links and discovering new connections. This is the kind of intellectual exploration we're aiming to enable. The graph view is an ambitious feature, but it has the potential to be a game-changer for knowledge management. It's about taking the linear structure of markdown files and transforming it into a dynamic, interconnected web.

Tech: For the graph view, we'll explore using libraries like react-flow or elkjs for DAG (Directed Acyclic Graph) graph rendering. These libraries provide powerful tools for creating interactive and visually appealing graphs.

3.6. Search & Filter

As your knowledge base grows, the ability to search and filter your notes becomes essential. We'll provide a robust search and filter system to help you find what you need, when you need it.

• Search by:
  • Title (from frontmatter).
  • Tags.
  • Status.
• Filter actions by project, due date, etc.

Our search functionality will allow you to search your notes by title (from the YAML frontmatter), tags, and status. This covers the most common search use cases and makes it easy to find specific notes quickly. We'll also provide filtering options, allowing you to filter your notes by project, due date, and other criteria. This is useful for focusing on specific tasks or projects, or for managing your workflow. The goal here is to make it easy to find the right information, no matter how large your knowledge base becomes. We want you to be able to quickly locate the notes you need, without having to sift through a mountain of irrelevant information.

The ability to search by tags is particularly important, as it allows you to categorize your notes and find them based on keywords or topics. Filtering by project is essential for managing project-related notes. And filtering by due date is crucial for staying on top of deadlines. We're aiming for a flexible and powerful search and filter system that adapts to your needs.

Tech: We'll use a fuzzy search library like fuse.js to implement our search functionality. Fuzzy search allows you to find results even if you misspell your search query, making the search experience more forgiving and user-friendly.

3.7. Styling & Theming

A clean and modern user interface is crucial for a pleasant user experience. We'll use Tailwind CSS to create a stylish and consistent look and feel for our markdown knowledge base.

• TailwindCSS with modern UI defaults.
• Dark/light mode support.
• Notion-inspired layout with minimal chrome:
  • Sidebar: Project list.
  • Main: File view/editor.
  • Optional: Preview panel or graph view.

We'll use Tailwind CSS to create a modern and responsive user interface. Tailwind provides a set of pre-designed CSS classes that make it easy to style your application consistently. We'll also support dark and light mode, allowing users to choose the theme that best suits their preferences. Our layout will be inspired by Notion, with a minimal chrome design that focuses on the content. We'll have a sidebar for the project list, a main area for the file view and editor, and an optional preview panel or graph view. This layout is designed to be clean, efficient, and easy to navigate. The goal is to create a distraction-free writing environment that allows you to focus on your thoughts.

The choice of Tailwind CSS is important. It allows us to create a customizable and maintainable UI without having to write a lot of CSS from scratch. Dark mode support is a must-have for any modern application, and we'll make sure our app looks great in both light and dark themes. The Notion-inspired layout is a proven design pattern for knowledge management tools, and we'll adapt it to fit our specific needs.

4. 🔌 Tech Stack

Here's a summary of the technologies we'll be using to build our markdown knowledge base:

Layer	Choice
Framework	Tauri + React
Language	TypeScript
Editor	Tiptap
Markdown Parsing	gray-matter
UI Framework	Tailwind CSS
FS Access	Tauri APIs
Graphs (future)	react-flow, elkjs

5. 🧪 MVP Scope (v0.1)

For our Minimum Viable Product (MVP), we'll focus on the core functionality needed to make the application usable. Here's the scope for v0.1:

Functional:

• User selects a folder.
• All .md files loaded into app.
• YAML frontmatter parsed and shown.
• Project view with files grouped.
• WYSIWYG editor with save-to-disk.
• Show depends_on links as clickable refs.

Non-functional:

• Dark mode.
• Tailwind base styling.
• Desktop app via Tauri.

6. 🚧 Future Features

These are some features we'd like to add in the future:

• Graph view of relationships (e.g., depends_on).
• Bi-directional linking (like [[wikilinks]]).
• Global tags view.
• Versioning support via local Git.
• Collaborative mode (local-first sync engine).

7. 🗂 Example Folder Structure

Here's an example of a folder structure you might use with our markdown knowledge base:

/my-notes
├── lightning-integration/
│   ├── add-lnurl.md
│   ├── refactor-auth.md
│   └── _project.json
├── general/
│   └── random-thought.md

8. 📆 Milestones

Here's a potential timeline for our development milestones:

Week	Milestone
1	Set up Tauri + React + Tailwind base
2	Implement folder picker + file loader
3	Parse markdown + YAML frontmatter
4	Create project + action views
5	Add WYSIWYG editor + save functionality
6	Display depends_on and clickable refs
7	Polish UI, add dark mode, prep release

9. 📋 Notes

• Should work offline, store nothing in the cloud.
• No proprietary format — .md files are the source of truth.
• Structure is opt-in — files can be pure markdown with no metadata.
• Editable frontmatter fields will be built with forms embedded in the UI.

Would you like this scaffolded as a starter repo? I can generate the folder and file structure and install the initial dependencies for you. This could save you a ton of setup time, guys!