mirror of
https://codeberg.org/Kankys/doxa.git
synced 2026-11-11 06:44:36 +01:00
225 lines
8.8 KiB
Markdown
225 lines
8.8 KiB
Markdown
# 🦅 NÁVOD K POUŽITÍ (DOXA-CLI)
|
||
|
||
**DOXA-CLI** je minimalistický, lokálně orientovaný nástroj pro správu poznámek z příkazové řádky. Slouží jako přímý ekvivalent k webové verzi [DOXA Notes](https://doxa-notes.org/), se kterou sdílí filozofii soustředění a identický datový formát JSON. Aplikace je napsaná v jazyce **Go** a využívá moderní terminálové rozhraní (**TUI**) postavené na knihovnách Bubble Tea a Lip Gloss od Charm.
|
||
|
||
<p align="center">
|
||
<img src="https://img.shields.io/badge/go-1.22+-00ADD8?style=flat-square&logo=go&logoColor=white" alt="Go 1.22+">
|
||
<img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT license">
|
||
<img src="https://img.shields.io/badge/tested-Linux-brightgreen?style=flat-square" alt="Tested on Linux">
|
||
</p>
|
||
<p align="center">
|
||
<img src="https://img.shields.io/badge/freebsd-AB2B28?style=for-the-badge&logo=freebsd&logoColor=white" alt="freeBSD">
|
||
</p>
|
||
|
||
---
|
||
|
||
## OBSAH
|
||
1. [Instalace a spuštění](#1-instalace-a-spuštění)
|
||
2. [Chování a struktura úložiště](#2-chování-a-struktura-úložiště)
|
||
3. [Uživatelské rozhraní a stavy](#3-uživatelské-rozhraní-a-stavy)
|
||
4. [Klávesové zkratky a ovládání](#4-klávesové-zkratky-a-ovládání)
|
||
5. [Detaily o exportu](#5-detaily-o-exportu)
|
||
6. [Odinstalace](#6-odinstalace)
|
||
|
||
---
|
||
|
||
## 1. INSTALACE A SPUŠTĚNÍ
|
||
|
||
### Systémové předpoklady
|
||
Před instalací je nutné mít na systému nainstalované vývojové prostředí **Go** (verze **1.20** nebo vyšší).
|
||
|
||
### Postup instalace (Linux / macOS)
|
||
1. **Stažení repozitáře:**
|
||
```bash
|
||
git clone https://codeberg.org/Kankys/doxa-cli.git
|
||
cd doxa-cli
|
||
```
|
||
2. **Spuštění instalačního skriptu:**
|
||
```bash
|
||
chmod +x install.sh
|
||
./install.sh
|
||
```
|
||
*Instalační skript automaticky stáhne závislosti Go, zkompiluje aplikaci, přesune binární soubor `doxa-cli` do adresáře `~/.local/bin/` a vytvoří výchozí prázdnou databázi v `~/.doxa-cli/doxa_notes.json`.*
|
||
|
||
3. **Přidání do PATH (pokud je potřeba):**
|
||
Pokud po instalaci nelze příkaz `doxa-cli` spustit, přidejte do svého profilu (např. `~/.bashrc` nebo `~/.zshrc`) následující řádek:
|
||
```bash
|
||
export PATH=$PATH:$HOME/.local/bin
|
||
```
|
||
Následně restartujte terminál nebo načtěte změny pomocí `source ~/.bashrc`.
|
||
|
||
### Úklid po instalaci
|
||
Jakmile skript doběhne, složku s klonovaným repozitářem můžete bezpečně odstranit:
|
||
```bash
|
||
rm -rf doxa-cli
|
||
```
|
||
|
||
|
||
|
||
# **Provoz a instalace doxa-cli na FreeBSD**
|
||
|
||
Build aplikace pro FreeBSD nefunguje vždy korektně, pokud vám nepomůže návod níže je možné ji spouštět přímo z repozitáře. A v .bashrc si udělat alias pro `doxa-cli`. Alikaci z repozitáře spustíte přímo z adresáře, kde je klonován příkazem `go run .`.
|
||
|
||
Systém FreeBSD má svá specifika – používá odlišné výchozí shelly, správu modulů jádra a cesty k interpretům než Linux. Pro bezproblémový chod aplikace postupuj následovně:
|
||
|
||
## **1\. Úprava instalačního skriptu (install.sh)**
|
||
|
||
Před spuštěním instalace je nutné zkontrolovat hlavičku (shebang) skriptu install.sh, protože FreeBSD striktně vyžaduje správnou cestu k interpretu příkazů:
|
||
|
||
> * Otevři install.sh a ujisti se, že první řádek odkazuje na univerzální cestu, nikoli natvrdo na linuxový bash:
|
||
```bash
|
||
\#\!/usr/bin/env bash
|
||
```
|
||
|
||
## **2\. Spuštění instalace**
|
||
|
||
Standardní postup klonování a spuštění:
|
||
|
||
```bash
|
||
git clone https://codeberg.org/Kankys/doxa-cli.git
|
||
cd doxa-cli
|
||
chmod \+x install.sh
|
||
./install.sh
|
||
rm \-rf doxa-cli
|
||
```
|
||
*Skript automaticky zkompiluje aplikaci a umístí binární soubor do adresáře \~/.local/bin/.*
|
||
|
||
## **3\. Nastavení proměnné prostředí PATH pro FreeBSD (shell sh)**
|
||
|
||
FreeBSD používá ve výchozím stavu jako standardní shell /bin/sh, který nepodporuje příkaz source. Pro trvalé i okamžité zprístupnění příkazu doxa-cli proveď tyto kroky:
|
||
|
||
> 1. **Přidej cestu do profilu:**
|
||
```bash
|
||
echo 'export PATH="$PATH:$HOME/.local/bin"' \>\> \~/.profile
|
||
```
|
||
> 2. **Načti změny v aktuálním terminálu (pomocí tečky, nikoliv příkazu source):**
|
||
```bash
|
||
. ~/.profile
|
||
```
|
||
|
||
|
||
---
|
||
|
||
## 2. CHOVÁNÍ A STRUKTURA ÚLOŽIŠTĚ
|
||
|
||
Aplikace funguje **zcela offline** a data ukládá na váš lokální disk.
|
||
|
||
- **Umístění databáze:** `~/.doxa-cli/doxa_notes.json` (na systémech, kde nelze detekovat domovský adresář, se vytvoří `doxa_notes.json` v aktuálním pracovním adresáři).
|
||
- **Záloha:** Pro zálohu stačí zkopírovat soubor `doxa_notes.json` na bezpečné místo.
|
||
|
||
### Formát dat (JSON)
|
||
Každá poznámka v JSON poli obsahuje následující strukturu kompatibilní s webovou verzí DOXA Notes:
|
||
```json
|
||
[
|
||
{
|
||
"id": 1722240000000,
|
||
"name": "Moje Poznámka",
|
||
"content": "Obsah poznámky s podporou více řádků.",
|
||
"tags": ["osobní", "práce"],
|
||
"folder": "", // nepoužito/prázdné
|
||
"created_at": "2026-07-29T14:30:00Z",
|
||
"modified_at": "2026-07-29T14:35:00Z"
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
## 3. UŽIVATELSKÉ ROZHRANÍ A STAVY
|
||
|
||
Aplikace se dynamicky přizpůsobuje velikosti terminálu a nabízí několik stavů:
|
||
|
||
### A. Hlavní seznam poznámek (`StateViewNotes`)
|
||
Zde vidíte přehled všech uložených poznámek.
|
||
- Pomocí šipek vybíráte aktivní poznámku.
|
||
- U vybrané poznámky se zobrazí její kompletní obsah, ID a přiřazené tagy.
|
||
- Ve spodní části obrazovky se nachází menu rychlých akcí a stavový řádek (ukazuje potvrzení o uložení, úpravě či exportu).
|
||
|
||
### B. Formulář pro Přidání / Úpravu poznámky (`StateAddNote` / `StateEditNote`)
|
||
Interaktivní rozhraní se 3 vstupními poli:
|
||
1. **Název:** (Povinné) Název vaší poznámky.
|
||
2. **Obsah:** (Povinné) Víceřádkové pole pro text poznámky.
|
||
3. **Tagy:** (Nepovinné) Štítky oddělené čárkou.
|
||
|
||
*Pohyb mezi poli se provádí klávesou `Tab` (dopředu) nebo `Shift+Tab` (dozadu).*
|
||
|
||
### C. Vyhledávání (`StateSearch`)
|
||
Umožňuje fulltextově filtrovat seznam poznámek. Vyhledává se shoda v názvu, obsahu i v jednotlivých tazích (velikost písmen se ignoruje).
|
||
|
||
### D. Procházení Tagů (`StateBrowse`)
|
||
Umožňuje rychle vyfiltrovat poznámky na základě existujících tagů.
|
||
- Klávesou `t` zobrazíte seznam všech existujících tagů.
|
||
- Výběrem položky a stisknutím `Enter` aplikujete filtr na hlavní seznam poznámek.
|
||
|
||
### E. Potvrzení smazání (`StateConfirmDelete`)
|
||
Bezpečnostní mezikrok, který zobrazí detail odstraňované poznámky a vyžaduje explicitní potvrzení stisknutím klávesy `y` (Ano) nebo `n` (Ne).
|
||
|
||
---
|
||
|
||
## 4. KLÁVESOVÉ ZKRATKY A OVLÁDÁNÍ
|
||
|
||
### Globální ovládání
|
||
| Klávesa | Akce |
|
||
| :--- | :--- |
|
||
| `ctrl + c` | Okamžité ukončení aplikace z jakéhokoliv stavu |
|
||
| `q` / `esc` | Návrat do předchozího stavu / Zrušení akce / Ukončení aplikace (z hlavního seznamu) |
|
||
|
||
### Ovládání v Hlavním seznamu poznámek (`StateViewNotes`)
|
||
| Klávesa | Akce |
|
||
| :--- | :--- |
|
||
| `↑` / `k` | Posunout výběr nahoru |
|
||
| `↓` / `j` | Posunout výběr dolů |
|
||
| `1` | Přidat novou poznámku (otevře formulář) |
|
||
| `2` / `Enter` | Upravit vybranou poznámku (otevře formulář) |
|
||
| `3` | Exportovat vybranou poznámku |
|
||
| `4` | Smazat vybranou poznámku (otevře potvrzovací dialog) |
|
||
| `/` | Otevřít vyhledávání |
|
||
| `l` | Přepnout jazyk rozhraní (CS <=> EN) |
|
||
|
||
### Ovládání ve formulářích (Přidání / Úprava)
|
||
| Klávesa | Akce |
|
||
| :--- | :--- |
|
||
| `Tab` | Přechod na další pole (Název -> Obsah -> Tagy -> Název...) |
|
||
| `Shift + Tab` | Přechod na předchozí pole |
|
||
| `Enter` | **Pokud jste v poli Obsah:** Vloží nový řádek.<br>**Pokud jste v jakémkoliv jiném poli:** Uloží poznámku. |
|
||
|
||
### Ovládání v režimu Procházení (`StateBrowse`)
|
||
| Klávesa | Akce |
|
||
| :--- | :--- |
|
||
| `t` | Přepnout na seznam **Tagů** |
|
||
| `↑` / `k` / `↓` / `j` | Pohyb v seznamu |
|
||
| `Enter` | Filtrovat hlavní seznam podle vybrané tagu |
|
||
|
||
---
|
||
|
||
## 5. DETAILY O EXPORTU
|
||
|
||
Při stisknutí klávesy `3` na vybrané poznámce v hlavním seznamu dojde k exportu poznámky do čistého textového souboru.
|
||
|
||
- **Adresář exportu:** `~/doxa-cli-txt/` (bude automaticky vytvořen v domovském adresáři).
|
||
- **Název exportovaného souboru:** `<Nazev_Poznamky>_<ID>.txt` (mezery v názvu jsou nahrazeny podtržítky).
|
||
- **Vnitřní struktura exportovaného souboru:**
|
||
*(Poznámka: Hlavička exportu je generována s českými popisky bez ohledu na zvolený jazyk rozhraní).*
|
||
```text
|
||
Název: <Název poznámky>
|
||
Tagy: <tag1, tag2, ...>
|
||
Vytvořeno: RRRR-MM-DD HH:MM
|
||
|
||
<Kompletní textový obsah poznámky>
|
||
```
|
||
|
||
---
|
||
|
||
## 6. ODINSTALACE
|
||
|
||
Pokud se rozhodnete aplikaci ze systému odstranit, postupujte takto:
|
||
|
||
1. **Smazání spustitelného souboru:**
|
||
```bash
|
||
rm ~/.local/bin/doxa-cli
|
||
```
|
||
2. **Smazání databáze a konfigurace (Upozornění: Smaže všechny vaše poznámky!):**
|
||
```bash
|
||
rm -rf ~/.doxa-cli
|
||
```
|