diff --git a/README.md b/README.md
index 4bc48a0..6bd2ee5 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,17 @@
 # ObsWiki
 
-A secure, Obsidian-style markdown wiki server built with Rust. Features authentication, role-based access control, and Obsidian-compatible markdown rendering.
+A secure web server for serving **Obsidian vaults** as online wikis. Transform your Obsidian notes into a beautiful, searchable web wiki with authentication and access control.
+
+[Obsidian](https://obsidian.md) is a powerful note-taking application that stores notes in "vaults" - folders containing markdown files with special linking features. ObsWiki lets you share these vaults online while preserving all the Obsidian-specific markdown features you love.
 
 ## Features
 
-- **Obsidian-style markdown rendering** with wiki links (`[[Page Name]]`) and tags (`#tag`)
+- **Full Obsidian vault compatibility** - Point to any existing Obsidian vault
+- **Native Obsidian markdown support** including:
+  - Wiki links (`[[Page Name]]` and `[[Page Name|Display Text]]`)
+  - Tags (`#tag` and nested tags `#category/subtag`)
+  - Block references and embeds
+  - Frontmatter metadata
 - **Multi-provider authentication**:
   - Local username/password
   - GitHub OAuth
@@ -17,6 +24,8 @@ A secure, Obsidian-style markdown wiki server built with Rust. Features authenti
 
 ## Quick Start
 
+### Option 1: Use an Existing Obsidian Vault
+
 1. **Build the project**:
    ```bash
    cargo build --release
@@ -28,23 +37,79 @@ A secure, Obsidian-style markdown wiki server built with Rust. Features authenti
    # Edit config.toml with your settings
    ```
 
-3. **Create wiki directory**:
+3. **Point to your Obsidian vault**:
    ```bash
-   mkdir wiki
-   echo "# Welcome to ObsWiki\n\nThis is your home page!" > wiki/index.md
+   ./target/release/obswiki --wiki-path /path/to/your/obsidian/vault
+   ```
+
+### Option 2: Create a New Vault
+
+1. **Build the project**:
+   ```bash
+   cargo build --release
+   ```
+
+2. **Create configuration**:
+   ```bash
+   cp config.toml.example config.toml
+   ```
+
+3. **Create a new vault directory**:
+   ```bash
+   mkdir my-vault
+   echo "# Welcome to My Vault\n\nThis is your home page! Try creating [[Another Page]] with wiki links." > my-vault/index.md
    ```
 
 4. **Run the server**:
    ```bash
+   ./target/release/obswiki --wiki-path my-vault
+   # Or use default port and path:
    ./target/release/obswiki
-   # Or with custom settings:
-   ./target/release/obswiki --port 8080 --wiki-path my-wiki
    ```
 
 5. **Access your wiki**:
    - Open http://localhost:3000
    - Default admin login: `admin` / `admin123`
 
+## Obsidian Vault Compatibility
+
+### What Works Out of the Box
+
+- ✅ **All markdown files** in your vault
+- ✅ **Folder structure** preserved exactly as in Obsidian
+- ✅ **Wiki links** `[[Page Name]]` and `[[Page|Display]]`
+- ✅ **Tags** `#tag` and `#category/subtag`
+- ✅ **Frontmatter** YAML metadata
+- ✅ **Standard markdown** formatting
+- ✅ **Images and attachments** (if in vault)
+- ✅ **Daily notes** and template structures
+
+### Obsidian Features with Limitations
+
+- ⚠️ **Block references** `[[Page#^blockid]]` - basic support
+- ⚠️ **Embeds** `![[Page]]` - partial support for images
+- ⚠️ **Dataview queries** - not supported (shows as code blocks)
+- ⚠️ **Canvas files** - not displayed (Obsidian-specific)
+- ⚠️ **Plugin-specific syntax** - may not render correctly
+
+### Required Obsidian Settings
+
+For optimal compatibility, configure these settings in your Obsidian vault:
+
+**Files & Links Settings:**
+- **New link format**: Set to "Absolute path in vault"
+- **Use [[Wikilinks]]**: Set to **false** (unchecked)
+
+These settings ensure that links work correctly when served through ObsWiki.
+
+### Vault Setup Tips
+
+1. **Point to your existing vault**: ObsWiki works with any Obsidian vault
+2. **Configure Obsidian settings**: Use the required settings above for best compatibility
+3. **No vault modification needed**: Your Obsidian vault remains untouched
+4. **Real-time updates**: Changes to files are reflected immediately
+5. **Access control**: Add authentication without changing your vault structure
+
 ## Configuration
 
 ### Basic Configuration
@@ -132,40 +197,68 @@ The system creates a default admin user:
 - Password: `admin123`
 - **⚠️ Change this password immediately in production!**
 
-## Wiki Features
+## Obsidian Vault Features
 
-### Obsidian-Style Markdown
+### Full Obsidian Markdown Compatibility
 
-- **Wiki links**: `[[Page Name]]` creates links to other pages
-- **Tags**: `#programming #rust` creates clickable tags
-- **Frontmatter**: YAML metadata support
+ObsWiki supports all the markdown features that make Obsidian special:
+
+- **Wiki links**: 
+  - `[[Page Name]]` - links to pages
+  - `[[Page Name|Display Text]]` - links with custom text
+  - `[[Folder/Page Name]]` - links to pages in subfolders
+- **Tags**: 
+  - `#programming` - simple tags
+  - `#category/subcategory` - nested tags
+  - Tags are clickable and searchable
+- **Frontmatter**: Full YAML metadata support
   ```markdown
   ---
-  title: "My Page"
+  title: "My Research Note"
   author: "John Doe"
-  tags: "example, test"
+  tags: [research, obsidian, markdown]
+  created: 2024-01-15
   ---
   
   # Page Content
   ```
+- **Block references**: Reference specific paragraphs and sections
+- **Embeds**: Include content from other pages (partially supported)
 
-### File Organization
+### Vault Structure Compatibility
+
+ObsWiki works with any Obsidian vault structure:
 
 ```
-wiki/
-├── index.md              # Home page
-├── projects/
-│   ├── project1.md
-│   └── project2.md
-└── private/
-    └── secrets.md         # Restricted by access rules
+vault/
+├── index.md                    # Home page (or README.md)
+├── Daily Notes/
+│   ├── 2024-01-15.md
+│   └── 2024-01-16.md
+├── Projects/
+│   ├── ObsWiki.md
+│   └── Personal Website.md
+├── Areas/
+│   ├── Programming/
+│   │   ├── Rust.md
+│   │   └── Web Development.md
+│   └── Research/
+│       └── Literature Review.md
+├── Resources/
+│   └── References.md
+└── Archive/
+    └── Old Notes.md           # Can be restricted by access rules
 ```
 
-### Search
+**Note**: ObsWiki respects your existing Obsidian vault organization and folder structure.
 
-- **Live search**: Search as you type
-- **Title and content search**: Finds matches in both
-- **Tag search**: Use `#tagname` to search by tags
+### Obsidian-Aware Search
+
+- **Live search**: Search as you type, just like Obsidian
+- **Content search**: Searches through all your note content
+- **Tag search**: Use `#tagname` to find all notes with specific tags
+- **Link-aware**: Understands your wiki link connections
+- **Metadata search**: Searches through frontmatter properties
 
 ## API Endpoints