MarkdownBrain

MarkdownBrain is an open-source Digital Garden builder that seamlessly integrates with Obsidian vaults. It features a client-server architecture allowing you to securely publish and share your markdown notes online. With simple configuration and Docker support, you can quickly set up your own knowledge sharing platform.

Key features

• Easy deployment with Docker
• Secure API key authentication
• Customizable configuration
• Cloud storage support (iCloud)

Server

Self-hosting and setup, system requirements:

• Docker (for running the server)
• Command-line tools
• Obsidian vault (optional)

1. Create Configuration File

First, create a config.yml file for the server:

echo 'lang: "en"
root_note_name: "Welcome"
name: "MarkdownBrain"
description: "MarkdownBrain"
api_key: "1234567890"' > config.yml

Configuration parameters:

• lang: System language (set to English)
• root_note_name: Name of the root note
• name: Site name
• description: Site description
• api_key: API key for client authentication

2. Launch the Server

Run the server using Docker:

docker run -dit --name markdownbrain \
    -v $(pwd)/config.yml:/markdownbrain/config.yml \
    -p 3000:3000 \
    ghcr.io/blackstorm/markdownbrain-server:latest

The server will run on port 3000 locally.

Client

1. Create Client Configuration

Create a config.yml file:

echo 'source: "~/Library/Mobile Documents/com~apple~CloudDocs/obsidian/example"
server: "https://your-server-url"
api_key: "1234567890"
ignores:
  - "Templates"' > config.yml

Configuration parameters:

• source: Path to your notes directory (Obsidian vault path if using Obsidian)
• server: Server URL
• api_key: Must match the API key in server configuration
• ignores: List of folders to ignore

2. Download and Run the Client

1. Download the client:

curl -L https://github.com/blackstorm/markdownbrain/releases/download/v0.1.1/markdownbrain-cli-darwin-amd64 -o markdownbrain-client

2. Add execution permissions:

chmod +x markdownbrain-client

3. Run the client:

./markdownbrain-client -c config.yml

Important Notes

1. Ensure the server is running before starting the client
2. Verify that the API keys match between client and server
3. If using Obsidian, make sure the vault path is correctly configured
4. It's recommended to add template folders to the ignore list

Workflow

1. Start the server first
2. Configure and run the client
3. The client will monitor the specified folder for changes and sync them to the server
4. Access your digital garden through the server's web interface

How It Works

MarkdownBrain creates a seamless workflow for maintaining your digital garden:

1. Content Creation: Write your notes in Markdown format (compatible with Obsidian)
2. Synchronization: The client automatically detects changes and syncs them to the server
3. Web Access: Your notes become accessible through a clean web interface
4. Organization: Maintains your note structure and links

By following these steps, you can easily set up MarkdownBrain to transform your notes into an accessible online knowledge base. The system maintains the integrity of your note connections while providing a public-facing interface for your digital garden.

Next Step

Integrating Analytics and Tracking Tools
Use CDN load HTMX script

Links

What is Digital Garden

Other languages

• MarkdownBrain 中文

Last updated: 2025-01-08.