Update README to emphasize Obsidian vault compatibility

- Clarify that ObsWiki serves existing Obsidian vaults as web wikis - Add explanation of what Obsidian and vaults are - Restructure Quick Start with options for existing vs new vaults - Add comprehensive Obsidian compatibility section with feature matrix - Document required Obsidian settings (absolute paths, disable wikilinks) - Enhance feature descriptions to highlight Obsidian-specific capabilities - Update vault structure examples to reflect realistic Obsidian organization 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-08-10 10:38:53 -04:00
parent db767dcabc
commit e55aa1153d
1 changed files with 119 additions and 26 deletions
--- 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