From 04b9c29170d2f99eabc9720ec5d1dd7ef03d2daa Mon Sep 17 00:00:00 2001 From: Mohamed Bassem Date: Sat, 13 Dec 2025 12:03:55 +0000 Subject: docs: Adding user guides --- docs/docs/01-getting-started/_category_.json | 3 +- docs/docs/02-installation/01-docker.md | 2 +- docs/docs/02-installation/05-pikapods.md | 32 --------- docs/docs/02-installation/09-cloud-hosting.md | 13 ++++ docs/docs/02-installation/10-pikapods.md | 32 +++++++++ docs/docs/02-installation/_category_.json | 1 + docs/docs/03-configuration/_category_.json | 3 +- docs/docs/04-using-karakeep/01-quick-sharing.md | 21 ------ docs/docs/04-using-karakeep/02-import.md | 49 ------------- .../04-using-karakeep/03-search-query-language.md | 76 -------------------- docs/docs/04-using-karakeep/_category_.json | 3 +- docs/docs/04-using-karakeep/advanced-workflows.md | 23 ++++++ docs/docs/04-using-karakeep/bookmarking.md | 42 +++++++++++ docs/docs/04-using-karakeep/import.md | 54 +++++++++++++++ docs/docs/04-using-karakeep/lists.md | 18 +++++ docs/docs/04-using-karakeep/quick-sharing.md | 26 +++++++ .../04-using-karakeep/search-query-language.md | 81 ++++++++++++++++++++++ docs/docs/04-using-karakeep/tags.md | 11 +++ docs/docs/05-integrations/_category_.json | 3 +- docs/docs/06-administration/_category_.json | 3 +- docs/docs/07-community/02-community-channels.md | 13 ++++ docs/docs/07-community/_category_.json | 3 +- docs/docs/08-development/_category_.json | 1 + docs/docs/api/_category_.json | 2 +- 24 files changed, 329 insertions(+), 186 deletions(-) delete mode 100644 docs/docs/02-installation/05-pikapods.md create mode 100644 docs/docs/02-installation/09-cloud-hosting.md create mode 100644 docs/docs/02-installation/10-pikapods.md delete mode 100644 docs/docs/04-using-karakeep/01-quick-sharing.md delete mode 100644 docs/docs/04-using-karakeep/02-import.md delete mode 100644 docs/docs/04-using-karakeep/03-search-query-language.md create mode 100644 docs/docs/04-using-karakeep/advanced-workflows.md create mode 100644 docs/docs/04-using-karakeep/bookmarking.md create mode 100644 docs/docs/04-using-karakeep/import.md create mode 100644 docs/docs/04-using-karakeep/lists.md create mode 100644 docs/docs/04-using-karakeep/quick-sharing.md create mode 100644 docs/docs/04-using-karakeep/search-query-language.md create mode 100644 docs/docs/04-using-karakeep/tags.md create mode 100644 docs/docs/07-community/02-community-channels.md diff --git a/docs/docs/01-getting-started/_category_.json b/docs/docs/01-getting-started/_category_.json index 41f4c00e..3562d433 100644 --- a/docs/docs/01-getting-started/_category_.json +++ b/docs/docs/01-getting-started/_category_.json @@ -1,3 +1,4 @@ { - "label": "Getting Started" + "label": "Getting Started", + "position": 1 } diff --git a/docs/docs/02-installation/01-docker.md b/docs/docs/02-installation/01-docker.md index 1a89796c..916a0134 100644 --- a/docs/docs/02-installation/01-docker.md +++ b/docs/docs/02-installation/01-docker.md @@ -1,4 +1,4 @@ -# Docker Compose [Recommended] +# Docker ### Requirements diff --git a/docs/docs/02-installation/05-pikapods.md b/docs/docs/02-installation/05-pikapods.md deleted file mode 100644 index dad0785a..00000000 --- a/docs/docs/02-installation/05-pikapods.md +++ /dev/null @@ -1,32 +0,0 @@ -# PikaPods [Paid Hosting] - -:::info -Note: PikaPods shares some of its revenue from hosting Karakeep with the maintainer of this project. -::: - -[PikaPods](https://www.pikapods.com/) offers managed paid hosting for many open source apps, including Karakeep. -Server administration, updates, migrations and backups are all taken care of, which makes it well suited -for less technical users. As of Nov 2024, running Karakeep there will cost you ~$3 per month. - -### Requirements - -- A _PikaPods_ account. Can be created for free [here](https://www.pikapods.com/register). You get an initial welcome credit of $5. - -### 1. Choose app - -Choose _Karakeep_ from their [list of apps](https://www.pikapods.com/apps) or use this [direct link](https://www.pikapods.com/pods?run=hoarder). This will either -open a new dialog to add a new _Karakeep_ pod or ask you to log in. - -### 2. Add settings - -There are a few settings to configure in the dialog: - -- **Basics**: Give the pod a name and choose a region that's near you. -- **Env Vars**: Here you can disable signups or set an OpenAI API key. All settings are optional. -- **Resources**: The resources your _Karakeep_ pod can use. The defaults are fine, unless you have a very large collection. - -### 3. Start pod and add user - -After hitting _Add pod_ it will take about a minute for the app to fully start. After this you can visit -the pod's URL and add an initial user under _Sign Up_. After this you may want to disable further sign-ups -by setting the pod's `DISABLE_SIGNUPS` _Env Var_ to `true`. diff --git a/docs/docs/02-installation/09-cloud-hosting.md b/docs/docs/02-installation/09-cloud-hosting.md new file mode 100644 index 00000000..08b9e054 --- /dev/null +++ b/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. diff --git a/docs/docs/02-installation/10-pikapods.md b/docs/docs/02-installation/10-pikapods.md new file mode 100644 index 00000000..290e5819 --- /dev/null +++ b/docs/docs/02-installation/10-pikapods.md @@ -0,0 +1,32 @@ +# PikaPods + +:::info +Note: PikaPods shares some of its revenue from hosting Karakeep with the maintainer of this project. +::: + +[PikaPods](https://www.pikapods.com/) offers managed paid hosting for many open source apps, including Karakeep. +Server administration, updates, migrations and backups are all taken care of, which makes it well suited +for less technical users. As of Nov 2024, running Karakeep there will cost you ~$3 per month. + +### Requirements + +- A _PikaPods_ account. Can be created for free [here](https://www.pikapods.com/register). You get an initial welcome credit of $5. + +### 1. Choose app + +Choose _Karakeep_ from their [list of apps](https://www.pikapods.com/apps) or use this [direct link](https://www.pikapods.com/pods?run=hoarder). This will either +open a new dialog to add a new _Karakeep_ pod or ask you to log in. + +### 2. Add settings + +There are a few settings to configure in the dialog: + +- **Basics**: Give the pod a name and choose a region that's near you. +- **Env Vars**: Here you can disable signups or set an OpenAI API key. All settings are optional. +- **Resources**: The resources your _Karakeep_ pod can use. The defaults are fine, unless you have a very large collection. + +### 3. Start pod and add user + +After hitting _Add pod_ it will take about a minute for the app to fully start. After this you can visit +the pod's URL and add an initial user under _Sign Up_. After this you may want to disable further sign-ups +by setting the pod's `DISABLE_SIGNUPS` _Env Var_ to `true`. diff --git a/docs/docs/02-installation/_category_.json b/docs/docs/02-installation/_category_.json index acb94a71..1778985f 100644 --- a/docs/docs/02-installation/_category_.json +++ b/docs/docs/02-installation/_category_.json @@ -1,3 +1,4 @@ { "label": "Installation", + "position": 3 } diff --git a/docs/docs/03-configuration/_category_.json b/docs/docs/03-configuration/_category_.json index 78e56008..0aea1748 100644 --- a/docs/docs/03-configuration/_category_.json +++ b/docs/docs/03-configuration/_category_.json @@ -1,3 +1,4 @@ { - "label": "Configuration" + "label": "Configuration", + "position": 4 } diff --git a/docs/docs/04-using-karakeep/01-quick-sharing.md b/docs/docs/04-using-karakeep/01-quick-sharing.md deleted file mode 100644 index 254bec84..00000000 --- a/docs/docs/04-using-karakeep/01-quick-sharing.md +++ /dev/null @@ -1,21 +0,0 @@ -# Quick Sharing Extensions - -The whole point of Karakeep is making it easy to hoard the content. That's why there are a couple of - -## Mobile Apps - -mobile screenshot - - -- **iOS app**: [App Store Link](https://apps.apple.com/us/app/karakeep-app/id6479258022). -- **Android App**: [Play Store link](https://play.google.com/store/apps/details?id=app.hoarder.hoardermobile&pcampaignid=web_share). - -## Browser Extensions - -mobile screenshot - -- **Chrome extension**: [here](https://chromewebstore.google.com/detail/karakeep/kgcjekpmcjjogibpjebkhaanilehneje). -- **Firefox addon**: [here](https://addons.mozilla.org/en-US/firefox/addon/karakeep/). - -- ## Community Extensions -- **Safari extension**: [App Store Link](https://apps.apple.com/us/app/karakeeper-bookmarker/id6746722790). For macOS and iOS to allow a simple way to add your bookmarks to your self hosted karakeep instance. diff --git a/docs/docs/04-using-karakeep/02-import.md b/docs/docs/04-using-karakeep/02-import.md deleted file mode 100644 index 4114ff79..00000000 --- a/docs/docs/04-using-karakeep/02-import.md +++ /dev/null @@ -1,49 +0,0 @@ -# Importing Bookmarks - - -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. - -:::info -All the URLs in the bookmarks file will be added automatically, you will not be able to pick and choose which bookmarks to import! -::: - -## Import from Chrome - -- Open Chrome and go to `chrome://bookmarks` -- Click on the three dots on the top right corner and choose `Export bookmarks` -- This will download an html file with all of your bookmarks. -- To import the bookmark file, go to the settings and click "Import Bookmarks from HTML file". - -## Import from Firefox -- Open Firefox and click on the menu button (☰) in the top right corner. -- Navigate to Bookmarks > Manage bookmarks (or press Ctrl + Shift + O / Cmd + Shift + O to open the Bookmarks Library). -- In the Bookmarks Library, click the Import and Backup button at the top. Select Export Bookmarks to HTML... to save your bookmarks as an HTML file. -- To import a bookmark file, go back to the Import and Backup menu, then select Import Bookmarks from HTML... and choose your saved HTML file. - -## Import from Pocket - -- Go to the [Pocket export page](https://getpocket.com/export) and follow the instructions to export your bookmarks. -- Pocket after a couple of minutes will mail you a zip file with all the bookmarks. -- Unzip the file and you'll get a CSV file. -- To import the bookmark file, go to the settings and click "Import Bookmarks from Pocket export". - -## Import from Omnivore - -- Follow Omnivore's [documentation](https://docs.omnivore.app/using/exporting.html) to export your bookmarks. -- This will give you a zip file with all your data. -- The zip file contains a lot of JSONs in the format `metadata_*.json`. You can either import every JSON file manually, or merge the JSONs into a single JSON file and import that. -- To merge the JSONs into a single JSON file, you can use the following command in the unzipped directory: `jq -r '.[]' metadata_*.json | jq -s > omnivore.json` and then import the `omnivore.json` file. You'll need to have the [jq](https://github.com/jqlang/jq) tool installed. - -## Import using the CLI - -:::warning -Importing bookmarks using the CLI requires some technical knowledge and might not be very straightforward for non-technical users. Don't hesitate to ask questions in github discussions or discord though. -::: - -If you can get your bookmarks in a text file with one link per line, you can use the following command to import them using the [karakeep cli](../integrations/command-line): - -``` -while IFS= read -r url; do - karakeep --api-key "" --server-addr "" bookmarks add --link "$url" -done < all_links.txt -``` diff --git a/docs/docs/04-using-karakeep/03-search-query-language.md b/docs/docs/04-using-karakeep/03-search-query-language.md deleted file mode 100644 index 8f55ec2f..00000000 --- a/docs/docs/04-using-karakeep/03-search-query-language.md +++ /dev/null @@ -1,76 +0,0 @@ -# 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: - -## Basic Syntax - -- Use spaces to separate multiple conditions (implicit AND) -- Use `and`/`or` keywords for explicit boolean logic -- Prefix qualifiers with `-` to negate them -- Use parentheses `()` for grouping conditions (note that groups can't be negated) - -## Qualifiers - -Here's a comprehensive table of all supported qualifiers: - -| Qualifier | Description | Example Usage | -| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | -| `is:fav` | Favorited bookmarks | `is:fav` | -| `is:archived` | Archived bookmarks | `-is:archived` | -| `is:tagged` | Bookmarks that has one or more tags | `is:tagged` | -| `is:inlist` | Bookmarks that are in one or more lists | `is:inlist` | -| `is:link`, `is:text`, `is:media` | Bookmarks that are of type link, text or media | `is:link` | -| `is:broken` | Bookmarks with broken/failed links (crawl failures or non-2xx status codes) | `is:broken` | -| `url:` | Match bookmarks with URL substring | `url:example.com` | -| `title:` | Match bookmarks with title substring | `title:example` | -| | Supports quoted strings for titles with spaces | `title:"my title"` | -| `#` | Match bookmarks with specific tag | `#important` | -| | Supports quoted strings for tags with spaces | `#"work in progress"` | -| `list:` | Match bookmarks in specific list | `list:reading` | -| | Supports quoted strings for list names with spaces | `list:"to review"` | -| `after:` | Bookmarks created on or after date (YYYY-MM-DD) | `after:2023-01-01` | -| `before:` | Bookmarks created on or before date (YYYY-MM-DD) | `before:2023-12-31` | -| `feed:` | Bookmarks imported from a particular rss feed | `feed:Hackernews` | -| `age:` | Match bookmarks based on how long ago they were created. Use `<` or `>` to indicate the maximum / minimum age of the bookmarks. Supported units: `d` (days), `w` (weeks), `m` (months), `y` (years). | `age:<1d` `age:>2w` `age:<6m` `age:>3y` | - -### Examples - -```plaintext -# Find favorited bookmarks from 2023 that are tagged "important" -is:fav after:2023-01-01 before:2023-12-31 #important - -# Find archived bookmarks that are either in "reading" list or tagged "work" -is:archived and (list:reading or #work) - -# Find bookmarks that are not tagged or not in any list --is:tagged or -is:inlist -# Find bookmarks with "React" in the title -title:React -``` - -## Combining Conditions - -You can combine multiple conditions using boolean logic: - -```plaintext -# Find favorited bookmarks from 2023 that are tagged "important" -is:fav after:2023-01-01 before:2023-12-31 #important - -# Find archived bookmarks that are either in "reading" list or tagged "work" -is:archived and (list:reading or #work) - -# Find bookmarks that are not favorited and not archived --is:fav -is:archived -``` - -## Text Search - -Any text not part of a qualifier will be treated as a full-text search: - -```plaintext -# Search for "machine learning" in bookmark content -machine learning - -# Combine text search with qualifiers -machine learning is:fav -``` diff --git a/docs/docs/04-using-karakeep/_category_.json b/docs/docs/04-using-karakeep/_category_.json index 96a7071a..b0784ea6 100644 --- a/docs/docs/04-using-karakeep/_category_.json +++ b/docs/docs/04-using-karakeep/_category_.json @@ -1,3 +1,4 @@ { - "label": "Using Karakeep" + "label": "Using Karakeep", + "position": 2 } diff --git a/docs/docs/04-using-karakeep/advanced-workflows.md b/docs/docs/04-using-karakeep/advanced-workflows.md new file mode 100644 index 00000000..5efd889a --- /dev/null +++ b/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). diff --git a/docs/docs/04-using-karakeep/bookmarking.md b/docs/docs/04-using-karakeep/bookmarking.md new file mode 100644 index 00000000..0e2f350f --- /dev/null +++ b/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. diff --git a/docs/docs/04-using-karakeep/import.md b/docs/docs/04-using-karakeep/import.md new file mode 100644 index 00000000..59e82647 --- /dev/null +++ b/docs/docs/04-using-karakeep/import.md @@ -0,0 +1,54 @@ +--- +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. + +:::info +All the URLs in the bookmarks file will be added automatically, you will not be able to pick and choose which bookmarks to import! +::: + +## Import from Chrome + +- Open Chrome and go to `chrome://bookmarks` +- Click on the three dots on the top right corner and choose `Export bookmarks` +- This will download an html file with all of your bookmarks. +- To import the bookmark file, go to the settings and click "Import Bookmarks from HTML file". + +## Import from Firefox +- Open Firefox and click on the menu button (☰) in the top right corner. +- Navigate to Bookmarks > Manage bookmarks (or press Ctrl + Shift + O / Cmd + Shift + O to open the Bookmarks Library). +- In the Bookmarks Library, click the Import and Backup button at the top. Select Export Bookmarks to HTML... to save your bookmarks as an HTML file. +- To import a bookmark file, go back to the Import and Backup menu, then select Import Bookmarks from HTML... and choose your saved HTML file. + +## Import from Pocket + +- Go to the [Pocket export page](https://getpocket.com/export) and follow the instructions to export your bookmarks. +- Pocket after a couple of minutes will mail you a zip file with all the bookmarks. +- Unzip the file and you'll get a CSV file. +- To import the bookmark file, go to the settings and click "Import Bookmarks from Pocket export". + +## Import from Omnivore + +- Follow Omnivore's [documentation](https://docs.omnivore.app/using/exporting.html) to export your bookmarks. +- This will give you a zip file with all your data. +- The zip file contains a lot of JSONs in the format `metadata_*.json`. You can either import every JSON file manually, or merge the JSONs into a single JSON file and import that. +- To merge the JSONs into a single JSON file, you can use the following command in the unzipped directory: `jq -r '.[]' metadata_*.json | jq -s > omnivore.json` and then import the `omnivore.json` file. You'll need to have the [jq](https://github.com/jqlang/jq) tool installed. + +## Import using the CLI + +:::warning +Importing bookmarks using the CLI requires some technical knowledge and might not be very straightforward for non-technical users. Don't hesitate to ask questions in github discussions or discord though. +::: + +If you can get your bookmarks in a text file with one link per line, you can use the following command to import them using the [karakeep cli](../integrations/command-line): + +``` +while IFS= read -r url; do + karakeep --api-key "" --server-addr "" bookmarks add --link "$url" +done < all_links.txt +``` diff --git a/docs/docs/04-using-karakeep/lists.md b/docs/docs/04-using-karakeep/lists.md new file mode 100644 index 00000000..9882ec59 --- /dev/null +++ b/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`. diff --git a/docs/docs/04-using-karakeep/quick-sharing.md b/docs/docs/04-using-karakeep/quick-sharing.md new file mode 100644 index 00000000..e1f031a5 --- /dev/null +++ b/docs/docs/04-using-karakeep/quick-sharing.md @@ -0,0 +1,26 @@ +--- +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 + +## Mobile Apps + +mobile screenshot + + +- **iOS app**: [App Store Link](https://apps.apple.com/us/app/karakeep-app/id6479258022). +- **Android App**: [Play Store link](https://play.google.com/store/apps/details?id=app.hoarder.hoardermobile&pcampaignid=web_share). + +## Browser Extensions + +mobile screenshot + +- **Chrome extension**: [here](https://chromewebstore.google.com/detail/karakeep/kgcjekpmcjjogibpjebkhaanilehneje). +- **Firefox addon**: [here](https://addons.mozilla.org/en-US/firefox/addon/karakeep/). + +- ## Community Extensions +- **Safari extension**: [App Store Link](https://apps.apple.com/us/app/karakeeper-bookmarker/id6746722790). For macOS and iOS to allow a simple way to add your bookmarks to your self hosted karakeep instance. diff --git a/docs/docs/04-using-karakeep/search-query-language.md b/docs/docs/04-using-karakeep/search-query-language.md new file mode 100644 index 00000000..a1e830e8 --- /dev/null +++ b/docs/docs/04-using-karakeep/search-query-language.md @@ -0,0 +1,81 @@ +--- +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: + +## Basic Syntax + +- Use spaces to separate multiple conditions (implicit AND) +- Use `and`/`or` keywords for explicit boolean logic +- Prefix qualifiers with `-` to negate them +- Use parentheses `()` for grouping conditions (note that groups can't be negated) + +## Qualifiers + +Here's a comprehensive table of all supported qualifiers: + +| Qualifier | Description | Example Usage | +| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | +| `is:fav` | Favorited bookmarks | `is:fav` | +| `is:archived` | Archived bookmarks | `-is:archived` | +| `is:tagged` | Bookmarks that has one or more tags | `is:tagged` | +| `is:inlist` | Bookmarks that are in one or more lists | `is:inlist` | +| `is:link`, `is:text`, `is:media` | Bookmarks that are of type link, text or media | `is:link` | +| `is:broken` | Bookmarks with broken/failed links (crawl failures or non-2xx status codes) | `is:broken` | +| `url:` | Match bookmarks with URL substring | `url:example.com` | +| `title:` | Match bookmarks with title substring | `title:example` | +| | Supports quoted strings for titles with spaces | `title:"my title"` | +| `#` | Match bookmarks with specific tag | `#important` | +| | Supports quoted strings for tags with spaces | `#"work in progress"` | +| `list:` | Match bookmarks in specific list | `list:reading` | +| | Supports quoted strings for list names with spaces | `list:"to review"` | +| `after:` | Bookmarks created on or after date (YYYY-MM-DD) | `after:2023-01-01` | +| `before:` | Bookmarks created on or before date (YYYY-MM-DD) | `before:2023-12-31` | +| `feed:` | Bookmarks imported from a particular rss feed | `feed:Hackernews` | +| `age:` | Match bookmarks based on how long ago they were created. Use `<` or `>` to indicate the maximum / minimum age of the bookmarks. Supported units: `d` (days), `w` (weeks), `m` (months), `y` (years). | `age:<1d` `age:>2w` `age:<6m` `age:>3y` | + +### Examples + +```plaintext +# Find favorited bookmarks from 2023 that are tagged "important" +is:fav after:2023-01-01 before:2023-12-31 #important + +# Find archived bookmarks that are either in "reading" list or tagged "work" +is:archived and (list:reading or #work) + +# Find bookmarks that are not tagged or not in any list +-is:tagged or -is:inlist +# Find bookmarks with "React" in the title +title:React +``` + +## Combining Conditions + +You can combine multiple conditions using boolean logic: + +```plaintext +# Find favorited bookmarks from 2023 that are tagged "important" +is:fav after:2023-01-01 before:2023-12-31 #important + +# Find archived bookmarks that are either in "reading" list or tagged "work" +is:archived and (list:reading or #work) + +# Find bookmarks that are not favorited and not archived +-is:fav -is:archived +``` + +## Text Search + +Any text not part of a qualifier will be treated as a full-text search: + +```plaintext +# Search for "machine learning" in bookmark content +machine learning + +# Combine text search with qualifiers +machine learning is:fav +``` diff --git a/docs/docs/04-using-karakeep/tags.md b/docs/docs/04-using-karakeep/tags.md new file mode 100644 index 00000000..0ac93bfd --- /dev/null +++ b/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. diff --git a/docs/docs/05-integrations/_category_.json b/docs/docs/05-integrations/_category_.json index e37aa473..c2495ffd 100644 --- a/docs/docs/05-integrations/_category_.json +++ b/docs/docs/05-integrations/_category_.json @@ -1,3 +1,4 @@ { - "label": "Integrations" + "label": "Integrations", + "position": 5 } diff --git a/docs/docs/06-administration/_category_.json b/docs/docs/06-administration/_category_.json index 5b581902..8998ac56 100644 --- a/docs/docs/06-administration/_category_.json +++ b/docs/docs/06-administration/_category_.json @@ -1,3 +1,4 @@ { - "label": "Administration" + "label": "Administration", + "position": 6 } diff --git a/docs/docs/07-community/02-community-channels.md b/docs/docs/07-community/02-community-channels.md new file mode 100644 index 00000000..3e08e6bc --- /dev/null +++ b/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. diff --git a/docs/docs/07-community/_category_.json b/docs/docs/07-community/_category_.json index b9240603..6fe06d4a 100644 --- a/docs/docs/07-community/_category_.json +++ b/docs/docs/07-community/_category_.json @@ -1,3 +1,4 @@ { - "label": "Community" + "label": "Community", + "position": 7 } diff --git a/docs/docs/08-development/_category_.json b/docs/docs/08-development/_category_.json index 73dd67ec..9ab891bc 100644 --- a/docs/docs/08-development/_category_.json +++ b/docs/docs/08-development/_category_.json @@ -1,3 +1,4 @@ { "label": "Development", + "position": 8 } diff --git a/docs/docs/api/_category_.json b/docs/docs/api/_category_.json index 49c10f38..695d9dbe 100644 --- a/docs/docs/api/_category_.json +++ b/docs/docs/api/_category_.json @@ -1 +1 @@ -{ "label": "API" } +{ "label": "API", "position": 9 } -- cgit v1.2.3-70-g09d2