docs: Adding user guides

docs/docs/01-getting-started/_category_.json

@@ -1,3 +1,4 @@
 {
-  "label": "Getting Started"
+  "label": "Getting Started",
+  "position": 1
 }

docs/docs/02-installation/01-docker.md

@@ -1,4 +1,4 @@
-# Docker Compose [Recommended]
+# Docker
 
 ### Requirements
 

docs/docs/02-installation/09-cloud-hosting.md

@@ -0,0 +1,13 @@
+# Karakeep Cloud
+
+:::tip
+If you want to use Karakeep without running your own servers, the hosted cloud option is the fastest way to start.
+:::
+
+[Karakeep Cloud](https://cloud.karakeep.app) is the fully managed version of Karakeep operated by the core team. It handles hosting, updates, monitoring, and backups for you, so you can focus on saving content instead of maintaining infrastructure.
+
+### Get started
+
+1. Visit [cloud.karakeep.app](https://cloud.karakeep.app) and create an account.
+2. Follow the onboarding flow to create your workspace.
+3. Install the browser extension or mobile apps from the [quick sharing page](../using-karakeep/quick-sharing) and start saving links immediately.

docs/docs/02-installation/10-pikapods.md

@@ -1,4 +1,4 @@
-# PikaPods [Paid Hosting]
+# PikaPods
 
 :::info
 Note: PikaPods shares some of its revenue from hosting Karakeep with the maintainer of this project.

docs/docs/02-installation/_category_.json

@@ -1,3 +1,4 @@
 {
     "label": "Installation",
+    "position": 3
 }

docs/docs/03-configuration/_category_.json

@@ -1,3 +1,4 @@
 {
-  "label": "Configuration"
+  "label": "Configuration",
+  "position": 4
 }

docs/docs/04-using-karakeep/_category_.json

@@ -1,3 +1,4 @@
 {
-  "label": "Using Karakeep"
+  "label": "Using Karakeep",
+  "position": 2
 }

docs/docs/04-using-karakeep/advanced-workflows.md

@@ -0,0 +1,23 @@
+---
+sidebar_position: 10
+slug: advanced-workflows
+---
+
+# Advanced workflows
+
+Push Karakeep further with automation and integrations.
+
+## Rule engine
+
+- Create if-this-then-that style rules to auto-tag, favourite, or route bookmarks into lists based on metadata or content.
+- Useful for keeping inboxes tidy (e.g. auto-archive newsletters, auto-tag domains, or flag videos).
+
+## API
+
+- Use the API to script imports, syncs, or custom tools. Same surface area the apps use.
+- Great for integrating with personal scripts, cron jobs, or other services.
+
+## Webhooks
+
+- Subscribe to bookmark events and trigger your own systems when something is added, updated, or archived.
+- Pair with the API to build end-to-end automations (e.g. push new saves into a writing queue or a team chat).

docs/docs/04-using-karakeep/bookmarking.md

@@ -0,0 +1,42 @@
+---
+sidebar_position: 1
+slug: bookmarking
+---
+
+# Bookmarking
+
+Everything in Karakeep starts as a bookmark. Here’s how the different types work and how to keep your home view tidy with favourites and archive.
+
+## Favourites
+
+- Star bookmarks you like so they sit in their own dedicated favourites view for quick return visits.
+- Handy for saved gems you want to re-open often like articles you enjoyed, references you come back to, or things worth sharing.
+
+## Archiving
+
+- Archive hides a bookmark from the homepage without deleting it.
+- Archived items stay searchable and keep all tags, highlights, and attachments.
+- Ideal for achieving inbox-zero style for your homepage.
+
+## Bookmark types
+
+- **Links**: URLs saved from the web or extension. Karakeep grabs metadata, previews, screenshots, and archives when configured.
+- **Text**: Quick notes or snippets you paste in. Great for ideas, quotes, or saving context alongside links.
+- **Media**: Images or PDFs you want to save for later. Karakeep automatically extracts content out of those files and makes them searchable.
+
+## Notes
+
+- Attach personal notes to any bookmark to capture context, reminders, or next steps.
+- Notes live with the bookmark and are searchable, so you can recall why something mattered.
+
+## Highlights
+
+- Save quotes, summaries, or TODOs while reading.
+- Highlights show up in the bookmark detail view/reader and are searchable, so you can jump straight to the key ideas.
+
+## Attachments
+
+- Store extra context alongside a bookmark: screenshots, page captures, videos, and files you upload.
+- **Screenshots & archives**: fallback when the original page changes or disappear.
+- **Uploaded files**: keep PDFs, notes, or supporting assets right with the link.
+- Manage attachments from the bookmark detail view: upload, download, or detach as needed.

docs/docs/04-using-karakeep/import.md

@@ -1,4 +1,9 @@
-# Importing Bookmarks
+---
+sidebar_position: 8
+slug: import
+---
+
+# Import your library
 
 
 Karakeep supports importing bookmarks using the Netscape HTML Format, Pocket's new CSV format & Omnivore's JSONs. Titles, tags and addition date will be preserved during the import. An automatically created list will contain all the imported bookmarks.

docs/docs/04-using-karakeep/lists.md

@@ -0,0 +1,18 @@
+---
+sidebar_position: 2
+---
+
+# Lists
+
+Lists are the core organizational layer in Karakeep. Every saved item can sit in multiple lists so you can group links by project, topic, or audience without duplicating them.
+
+## Manual lists
+
+- Curated sets you add bookmarks to by hand. Great for projects, reading queues, or hand-picked collections.
+- Can be **private** (visible only to you) or **public** (share a read-only link).
+- Can be **collaborative**: invite people by email as viewers or editors. Editors can add their own bookmarks; viewers can browse. Your personal states (favourite/archive) stay yours even inside a shared list.
+
+## Smart lists
+
+- Auto-updating lists powered by a saved search query (e.g. `#ai -archived`).
+- Best for dynamic views like `Youtube links added last week` or `All reddit links from r/selfhosted`.

docs/docs/04-using-karakeep/quick-sharing.md

@@ -1,4 +1,9 @@
-# Quick Sharing Extensions
+---
+sidebar_position: 7
+slug: quick-sharing
+---
+
+# Quick capture and sharing
 
 The whole point of Karakeep is making it easy to hoard the content. That's why there are a couple of 
 

docs/docs/04-using-karakeep/search-query-language.md

@@ -1,3 +1,8 @@
+---
+sidebar_position: 9
+slug: search-query-language
+---
+
 # Search Query Language
 
 Karakeep provides a search query language to filter and find bookmarks. Here are all the supported qualifiers and how to use them:

docs/docs/04-using-karakeep/tags.md

@@ -0,0 +1,11 @@
+---
+sidebar_position: 3
+---
+
+# Tags
+
+Tags are lightweight labels you can attach to any bookmark to add meaning without rigid folders.
+
+- Use tags to capture topics, sources, people, or workflow states (e.g. `ai`, `design`, `to-read`).
+- Combine multiple tags to filter or build smart lists; tags travel with a bookmark wherever it appears.
+- AI tags might look a little messy, but the extra labels make finding things easier. Use tags for broad discovery and lists when you want a clean, hand-picked setup.

docs/docs/05-integrations/_category_.json

@@ -1,3 +1,4 @@
 {
-  "label": "Integrations"
+  "label": "Integrations",
+  "position": 5
 }

docs/docs/06-administration/_category_.json

@@ -1,3 +1,4 @@
 {
-  "label": "Administration"
+  "label": "Administration",
+  "position": 6
 }

docs/docs/07-community/02-community-channels.md

@@ -0,0 +1,13 @@
+# Community Channels
+
+Stay connected with the Karakeep team and community for updates, support, and feature discussions.
+
+## Discord
+
+- Join the official server: [discord.gg/NrgeYywsFh](https://discord.gg/NrgeYywsFh)
+- Great for getting help, sharing setups, and chatting with the team and other users.
+
+## Twitter / X
+
+- Follow [@karakeep_app](https://twitter.com/karakeep_app) for release announcements, tips, and product news.
+- DM or tag us with feedback or things you'd like to see next.

docs/docs/07-community/_category_.json

@@ -1,3 +1,4 @@
 {
-  "label": "Community"
+  "label": "Community",
+  "position": 7
 }

docs/docs/08-development/_category_.json

@@ -1,3 +1,4 @@
 {
     "label": "Development",
+    "position": 8
 }

docs/docs/api/_category_.json

@@ -1 +1 @@
-{ "label": "API" }
+{ "label": "API", "position": 9 }