ryan/obswiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README to emphasize Obsidian vault compatibility

Browse Source 
- 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>
This commit is contained in:
Ryan Chen
2025-08-10 10:38:53 -04:00
parent db767dcabc
commit e55aa1153d
1 changed files with 119 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

145
README.md
View File

@@ -1,10 +1,17 @@
# ObsWiki # 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 ## 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**: - **Multi-provider authentication**:
- Local username/password - Local username/password
- GitHub OAuth - GitHub OAuth
@@ -17,6 +24,8 @@ A secure, Obsidian-style markdown wiki server built with Rust. Features authenti
## Quick Start ## Quick Start
### Option 1: Use an Existing Obsidian Vault
1. **Build the project**: 1. **Build the project**:
```bash ```bash
cargo build --release 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 # Edit config.toml with your settings
``` ```
3. **Create wiki directory**: 3. **Point to your Obsidian vault**:
```bash ```bash
mkdir wiki ./target/release/obswiki --wiki-path /path/to/your/obsidian/vault
echo "# Welcome to ObsWiki\n\nThis is your home page!" > wiki/index.md ```
### 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**: 4. **Run the server**:
```bash ```bash
./target/release/obswiki --wiki-path my-vault
# Or use default port and path:
./target/release/obswiki ./target/release/obswiki
# Or with custom settings:
./target/release/obswiki --port 8080 --wiki-path my-wiki
``` ```
5. **Access your wiki**: 5. **Access your wiki**:
- Open http://localhost:3000 - Open http://localhost:3000
- Default admin login: `admin` / `admin123` - 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 ## Configuration
### Basic Configuration ### Basic Configuration
@@ -132,40 +197,68 @@ The system creates a default admin user:
- Password: `admin123` - Password: `admin123`
- **⚠️ Change this password immediately in production!** - **⚠️ 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 ObsWiki supports all the markdown features that make Obsidian special:
- **Tags**: `#programming #rust` creates clickable tags
- **Frontmatter**: YAML metadata support - **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 ```markdown
--- ---
title: "My Page" title: "My Research Note"
author: "John Doe" author: "John Doe"
tags: "example, test" tags: [research, obsidian, markdown]
created: 2024-01-15
--- ---
# Page Content # 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/ vault/
├── index.md # Home page ├── index.md # Home page (or README.md)
├── projects/ ├── Daily Notes/
│ ├── project1.md │ ├── 2024-01-15.md
│ └── project2.md │ └── 2024-01-16.md
└── private/ ├── Projects/
└── secrets.md # Restricted by access rules │ ├── 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 ### Obsidian-Aware Search
- **Title and content search**: Finds matches in both
- **Tag search**: Use `#tagname` to search by tags - **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 ## API Endpoints