mirror of
https://codeberg.org/Kankys/doxa.git
synced 2026-11-11 06:44:36 +01:00
new-doxa-monorepo
This commit is contained in:
kankys committed
1 parent
b4401527a3
commit
5eacbb0182
162 files changed
+21820
-2
No files matched your search
@@ -0,0 +1,224 @@
|
||||
# 🦅 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
|
||||
```
|
||||
Reference in new issue
Block a user