Dokumentacja formatu plików

Stan na: 2026-10-22

Ta strona to precyzyjny kontrakt formatu na dysku dla każdego pliku w vaulcie Plainva. Jest napisana tak, aby narzędzie — inny program, skrypt lub asystent AI — mógł czytać i bezpiecznie edytować pliki vaultu bezpośrednio, bez przechodzenia przez interfejs użytkownika Plainva. Jeśli używasz tylko aplikacji, ta strona nigdy nie jest Ci potrzebna; pozostałe strony podręcznika opisują zwykłe użycie.

Wszystko tutaj to zwykły tekst UTF-8. Notatki to Markdown z frontmatter YAML; bazy danych to YAML. Nic nie jest zastrzeżone i nic nie jest ukryte.

Zasady podstawowe (przeczytaj najpierw)

1. Notatka jest źródłem prawdy. .base to tylko widok. Wartości właściwości znajdują się we frontmatter poszczególnych notatek — nigdy w .base. Aby zmienić wartość, edytujesz notatkę.
2. Notatki pozostają Obsidian-natywne. We frontmatter notatki zapisuj wyłącznie proste skalary i listy (string, liczba, boolean, data ISO, lista YAML). Nigdy nie zapisuj zagnieżdżonego obiektu ani flagi „aktywne/wybrane” w notatce.
3. .base używa tylko pięciu kluczy najwyższego poziomu Obsidian (filters, formulas, properties, summaries, views). Obsidian nie rozumie żadnego innego klucza najwyższego poziomu. Dlatego wszystkie dane specyficzne dla Plainva znajdują się pod zagnieżdżonymi podkluczami plainva:.
4. Zachowaj to, czego nie rozumiesz. Nieznane klucze muszą przetrwać cykl odczytu/zapisu bez zmian. Nie „porządkuj” kluczy, których nie rozpoznajesz.
5. Zapisuj UTF-8. Nowy plik dostaje zakończenia linii LF i nie ma BOM; plik, który już istnieje, zachowuje to, co ma. Plainva robi tak samo: to, co tworzy, zaczyna się od LF i bez BOM, a to, co zastaje, zachowuje swoje zakończenia linii i swój BOM — gdy edytujesz notatkę, zmieniają się tylko linie, które zmienisz. Plik, w którym mieszają się oba rodzaje zakończeń linii, przy pierwszej edycji dostaje w całości ten rodzaj, który ma większość jego linii. Sam znak powrotu karetki (CR) jako zakończenie linii — tak kończą się linie w starych plikach z Maca — jest odczytywany, ale nie jest zachowywany: przy pierwszej zmianie takiego pliku Plainva zapisuje go z LF (z CRLF, jeśli większość pozostałych zakończeń linii to CRLF) i informuje Cię o tym.

Vault w skrócie

Vault to zwykły folder. Typy plików, które napotkasz:

Zarezerwowane nazwy index.md i log.md nigdy nie są zwykłymi notatkami; nie twórz zwykłej treści pod tymi nazwami.

Notatki (.md)

Notatka to plik Markdown. Opcjonalny blok frontmatter YAML (między dwiema liniami ---) na samej górze zawiera jej właściwości; po nim następuje treść Markdown.

---
type: Note
tags: [project, active]
status: In progress
due: 2026-07-20
plainva:
  icon: "🚀"
  header_color: "#2f6f6f"
---
# My Project

A **bold** thought that links to [[Another Note]].

- [ ] First task

Blok może być pusty: ---, po którym bezpośrednio następuje ---, to blok bez właściwości, a nie dwa separatory — treść notatki zaczyna się w następnej linii. Plainva nie zostawia pustego bloku: gdy usuwana jest ostatnia właściwość, obie linie --- znikają razem z nią. Pozostają tylko wtedy, gdy sama treść zaczyna się od linii ---, która w przeciwnym razie zostałaby odczytana jako początek bloku.

Blok, którego Plainva nie potrafi odczytać jako właściwości, pozostaje dokładnie taki, jaki jest: tekst między dwiema liniami ---, który nie jest YAML-em, albo YAML będący listą zamiast linii klucz: wartość. Sekcja Właściwości mówi o tym, zamiast nie pokazywać żadnych właściwości, a zmiana właściwości takiej notatki — tam, w bazie danych, na tablicy korkowej, na liście zadań albo jej ikony i koloru — niczego nie zmienia, a Plainva o tym informuje: Nie udało się zapisać właściwości, a dalej przyczyna. Popraw blok w treści notatki, a zmiana zostanie zapisana. Pojedyncza wartość w nieoczekiwanej postaci nie czyni bloku nieczytelnym: Plainva odczytuje ją tak, jak jest zapisana — puste tags: to notatka bez tagów, liczba wśród tagów (- 2024) to tag 2024, liczba jako title to ten tytuł, a timestamp będący datą to zwykła właściwość.

Pola frontmatter OKF

Plainva stosuje się do OKF (Open Knowledge Format), minimalnej konwencji — obecnie w wersji 0.2. Jedno pole najwyższego poziomu jest wymagane, wszystko inne jest opcjonalne:

Plik bez type nadal otwiera się bez problemu; jest po prostu „niezgodny z OKF”. okf_version brakujące w notatce — lub wciąż w niej obecne — nie jest naruszeniem. Gdy tworzysz nową notatkę, dodanie type jest dobrą praktyką — nic więcej nie potrzeba. Pełne uzasadnienie znajdziesz w OKF.

Zaufanie i cykl życia (OKF 0.2)

OKF 0.2 dodaje pięć opcjonalnych pól najwyższego poziomu, którymi notatka mówi, skąd pochodzi, czy ktoś ją sprawdził i czy nadal jest aktualna. Plainva odczytuje je wszystkie; zapisuje je według stałych reguł (patrz niżej).

Aktorzy (by w generated i verified) stosują konwencję: osoba to human:<imię>, program to <producent>/<wersja>. Plainva zapisuje plainva-import/<wersja>, plainva-mail-capture/<wersja> i plainva-task-sync/<wersja> — a przy sprawdzeniu human:<Twoje imię>.

Przykład zaimportowanej, później sprawdzonej notatki:

---
type: Note
generated:
  by: plainva-import/0.6.7
  at: 2026-08-21T10:11:12Z
sources:
  - resource: https://example.org/article
    title: Article
verified:
  - by: human:Marco
    at: 2026-08-22T08:00:00Z
status: stable
stale_after: 2027-08-21
---

Reguły zapisu — kto ustawia co:

• generated i sources są zapisywane wyłącznie przez maszynowe ścieżki zapisu Plainva: importer (jeden moment na przebieg — raport importu też go niesie), przechwytywanie e-maili (z sources: [{ resource: “mid:<Message-ID>” }], gdy wiadomość ma stabilny Message-ID) oraz synchronizacja zadań (tylko gdy tworzy notatkę — kolejna synchronizacja zostawia znacznik bez zmian).
• verified jest zapisywane wyłącznie przez Oznacz jako sprawdzoną (komputer: sekcja Zaufanie i pochodzenie panelu właściwości; telefon: karta kontekstowa notatki) — i dopisuje, zamiast nadpisywać.
• Edytor nigdy sam nie dotyka żadnego z tych pól, a istniejące notatki nigdy nie są oznaczane z mocą wsteczną. Brakujące pole oznacza po prostu: brak stwierdzenia.
• status i stale_after ustawiasz sam (jako właściwość albo wprost we frontmatter). Wartość spoza draft/stable/deprecated — powiedzmy kolumna status: Open w bazie zadań — nie jest stanem cyklu życia, tylko zwykłą właściwością; Plainva nie pokazuje dla niej odznaki.
• Narzędzia i skrypty tworzące notatki powinny ustawiać generated z własnym aktorem (<Twoje-narzędzie>/<wersja>) i przenosić nieznane im pola zaufania bez zmian.

Serializacja wartości właściwości

Każdy klucz frontmatter to jedna właściwość. Zapisz wartość w natywnej formie YAML odpowiadającej jej typowi:

„Aktywna” wartość właściwości typu Wybór/Status to po prostu ten zwykły skalar. Paleta dozwolonych opcji i ich kolory nie znajdują się w notatce — znajdują się w nadrzędnym pliku .base (patrz Opcje i kolory). Dzięki temu notatka pozostaje w 100% Obsidian-natywna.

Ujmuj wartości linków wiki w cudzysłów ("[[X]]"). Nieocudzysłowione [[X]] to w YAML sekwencja flow i nie zostanie sparsowane tak, jak zamierzasz.

Przestrzeń nazw plainva: w notatkach

Specyficzne dla Plainva dodatki do notatek są zgrupowane pod jednym kluczem plainva:, dzięki czemu inne edytory mogą je ignorować:

Wszystkie te pola są opcjonalne. Jeśli nie zapisujesz żadnego z nich, pomiń klucz plainva: całkowicie. Nieprawidłowe wartości są ignorowane przy odczycie, nigdy traktowane jako błąd.

pim to kotwica integracji PIM (patrz Kalendarz i zewnętrzne zadania i Przechwytywanie e-maili). To małe mapowanie zapisywane przez Plainva, gdy notatka odzwierciedla zewnętrzny obiekt: uid plus informacja o pochodzeniu, a w zależności od rodzaju calendar (notatki ze spotkań), kind: task + list (zsynchronizowane zadania) lub kind: email + mailbox (przechwycone e-maile). Narzędzia powinny zachowywać je bez zmian; usunięcie kotwicy jedynie odłącza notatkę od jej zdalnego obiektu (nic nie jest przez to usuwane zdalnie). Przykład:

plainva:
  pim:
    kind: task
    uid: MTIzNDU2
    list: MDEyMzQ1
    provider: caldav
    identity: https://cloud.example.com:alice
    account: 3f9c21ab

Co opisuje pochodzenie. Dla zadania liczą się uid i list — uid jest unikalne u JEDNEGO dostawcy, nie u dwóch naraz. provider (google, microsoft, caldav) i identity (zweryfikowana tożsamość konta, jeśli dostawca ją udostępnia) zawężają to dalej, i oba przetrwają ponowne połączenie. account to LOKALNY identyfikator konta: Plainva nadal go zapisuje, aby starsze wersje mogły odczytać kotwicę, ale już go nie porównuje — jest on nadawany na nowo przy każdym połączeniu, i to właśnie dlatego ponownie połączone konto importowało kiedyś swoje zadania po raz drugi. Jeśli sam zapisujesz kotwice, ustaw uid i list; provider/identity są zalecane, account nie jest potrzebny. recurring: true Plainva dopisuje do kotwicy zadania, gdy zobaczy, że dostawca przywraca zadanie (ukończone, a potem ponownie otwarte pod tym samym uid z późniejszą datą). Klucz ma charakter czysto informacyjny, nigdy nie jest porównywany i można go usunąć.

Nazwa pliku nie jest częścią tożsamości. Odzwierciedlone zadanie nosi nazwę swojego tytułu (<tytuł>.md, przy tym samym tytule <tytuł> 2.md itd.); przypisanie odbywa się wyłącznie przez kotwicę. Narzędzia mogą zmieniać nazwę pliku i go przenosić, dopóki kotwica pozostaje. Nazwy w postaci <tytuł> — <16 lub 64 znaki szesnastkowe>.md pochodzą z wersji Plainva z 12–24 września 2026: znaki to początek skrótu SHA-256 z dostawcy, tożsamości, listy i uid. Widok zadań jednorazowo proponuje zmianę ich nazw na tytuły — tylko gdy znaki pasują do kotwicy w tym samym pliku.

templateFor to kontrakt pola przypisania szablonu (patrz Bazy danych (.base)): na notatce wewnątrz folderu szablonów wymienia bazy danych, w których menu Wpis domyślnie pokazuje ten szablon. Wartości to całe linki wiki wraz z rozszerzeniem .base — w formie gołej ("[[Tasks.base]]" pasuje do pliku o tej nazwie w dowolnym folderze, więc przetrwa samo przeniesienie folderu) albo kwalifikowanej ścieżką ("[[Projekte/Tasks.base]]" pasuje dokładnie do tej ścieżki). Plainva zapisuje gołe linki i kwalifikuje je tylko wtedy, gdy istnieją dwa pliki .base o tej samej nazwie. Skalar zamiast listy jest tolerowany. Gdy wpis jest tworzony z szablonu, templateFor — w odróżnieniu od pozostałych kluczy plainva: — nie jest kopiowany do nowej notatki.

Linki

• Link wiki: [[Nazwa notatki]] — rozwiązywany według nazwy notatki w całym vaulcie. Z kotwicą nagłówka: [[Notatka#Sekcja]] — kliknięcie otwiera notatkę przy tym nagłówku; [[#Sekcja]] przeskakuje w bieżącej notatce, a slug w stylu GitHuba ([[Notatka#cool-header]]) również jest rozwiązywany. Z odwołaniem do bloku: [[Notatka#^id]] dla wiersza kończącego się na ^id. Z tekstem wyświetlanym: [[Notatka|pokazywany tekst]].
• Jak rozwiązywany jest cel linku wiki — tak samo dla kliknięcia, osadzenia, relacji, grafu i linków zwrotnych, na komputerze i na telefonie. W tej kolejności: (1) jawna ścieżka — /Folder/Notatka od katalogu głównego vaultu, ./Notatka lub ../Folder/Notatka od folderu notatki z linkiem — i nic poza tym dla takiego celu; (2) ścieżka w vaulcie tak, jak została zapisana — plik zapisany dokładnie tak —, potem notatka pod tą ścieżką (.md); (3) końcówka ścieżki notatki: sama nazwa pliku albo z folderami przed nią (Klienci/List znajduje Projekty/Klienci/List.md); (4) plik, który nie jest notatką (plan.pdf, Tasks.base, LICENSE), przez swoją ścieżkę lub jej końcówkę — po notatkach, więc cel bez rozszerzenia oznacza notatkę wszędzie tam, gdzie taka istnieje; (5) title z właściwości notatki. Nazwy są porównywane bez rozróżniania wielkich i małych liter, a złożona i rozłożona postać litery liczą się jako ta sama nazwa. Gdy pasuje kilka plików: najpierw pisownia dokładnie taka jak zapisana, potem ścieżka odczytana od folderu notatki z linkiem (dla samej nazwy — notatka obok), potem najkrótsza ścieżka, potem kolejność alfabetyczna. Kroki od 1 do 4 to także sposób, w jaki Obsidian znajduje plik, choć może wybrać inny, gdy kilka ma tę samą nazwę; link przez title (krok 5) działa tylko w Plainvie — dlatego listy wyboru Plainvy zapisują nazwę pliku.
• Link Markdown: [tekst](cel). Cel jest czytany najpierw od folderu notatki z linkiem — plik zapisany dokładnie tak, potem notatka pod tą ścieżką (.md); jeśli tam niczego nie ma, jest rozwiązywany jak cel linku wiki (kroki od 2 do 5 powyżej: ścieżka od katalogu głównego vaultu, końcówka ścieżki, plik, który nie jest notatką, title). Jawna ścieżka — /Folder/Plik, ./Plik, ../Folder/Plik — wskazuje jedno miejsce i nic poza tym nie jest dla niej próbowane. Cel kończący się na / wskazuje folder i prowadzi do jego index.md. Kodowanie procentowe jest dekodowane (Mój%20list.md), nawiasy ostre i tytuł są odczytywane jak w CommonMark ([x](<Mój list.md> "Tytuł")), a pierwszy zapisany # zaczyna fragment: z [tekst](#cool-header) lub [tekst](inna.md#cool-header) kliknięcie trafia na nagłówek; #, który należy do nazwy pliku, zapisuje się jako %23. Linki w każdym z trzech formatów, których używa Obsidian — najkrótsza ścieżka, ścieżka względna, ścieżka bezwzględna w vaulcie — są rozwiązywane w ten sposób; gdy jeden plik leży pod ścieżką od folderu notatki z linkiem, a inny pod tą samą ścieżką od katalogu głównego vaultu, Plainva bierze pierwszy, tak jak robi to czytnik Markdown poza aplikacją. Sama Plainva zapisuje względne, zakodowane procentowo linki Markdown (przeglądy folderów, przygotowane przeglądy). Odpowiedź jest taka sama dla kliknięcia, grafu i linków zwrotnych, na komputerze i na telefonie.
• Linki zwrotne są wyprowadzane automatycznie, także z linków wiki we frontmatter (to właśnie sprawia, że relacje pojawiają się jako linki zwrotne).

Zależności (blockedBy)

Zwykła właściwość notatki — poza przestrzenią nazw plainva: — zgodna z RFC 9253, słownictwem, które zapisuje także wtyczka TaskNotes:

blockedBy:
  - uid: "[[Projects/Rollout]]"   # link wiki do poprzednika
    reltype: FINISHTOSTART        # słownictwo z RFC 9253
    gap: P1D                      # opcjonalny odstęp, ISO 8601

• Zapisuj tylko jeden kierunek (następnik wymienia swoich poprzedników). Odwrotność jest wyprowadzana; zapisana para to dwa fakty, które mogą sobie przeczyć.
• reltype może mieć wartość FINISHTOSTART, FINISHTOFINISH, STARTTOSTART lub STARTTOFINISH. Plainva ocenia i rysuje wyłącznie FINISHTOSTART; pozostałe zachowuje bez zmian.
• gap to czas trwania w formacie ISO-8601, opcjonalny.
• Nie zapisuj cyklu. Plainva go odrzuca i wskazuje ścieżkę, którą by zamknął.

Bazy danych (.base)

Plik .base to YAML. Przechowuje widok na notatki — jakie notatki (źródła), jak je pokazywać (widoki), jak filtrować i sortować oraz schemat kolumn. Nie przechowuje żadnych wartości notatek. Format jest zgodny z wtyczką Bases w Obsidian.

Zasady twarde — złamanie jednej sprawia, że Obsidian odrzuca cały plik

• Tylko te klucze najwyższego poziomu: filters, formulas, properties, views. Nigdy nie dodawaj innego klucza najwyższego poziomu. (Historycznie klucz najwyższego poziomu columns: psuł każdy plik — nie wprowadzaj ponownie tego wzorca.)
• Każdy widok potrzebuje niepustego stringa name.
• Obiekt filters niesie dokładnie jedno z and / or / not na każdym poziomie — nigdy dwa obok siebie.

Sam Plainva naprawia starsze pliki naruszające dwie ostatnie zasady przy następnym zapisie, ale narzędzie piszące bezpośrednio musi je od razu zastosować poprawnie.

Identyfikatory właściwości: kiedy używać przedrostka note.

To najczęstsza pułapka, więc wprost:

Reguła praktyczna: pola strukturalne zwrócone do Obsidian używają note.<key> (i file.<x> dla wbudowanych, jak file.name, file.folder, file.mtime); wszystko wewnątrz formuły filtra lub bloku plainva używa gołego klucza frontmatter.

Klucze najwyższego poziomu

• filters — które notatki należą do tej bazy danych. W Plainva ten klucz zawiera wyłącznie źródła (folder/tag); warunki właściwości są przechowywane osobno dla każdego widoku, w views[i].filters. Patrz Filtry.
• properties — schemat kolumn, indeksowany według id właściwości. Natywne podklucze Obsidian, jak displayName (etykieta nagłówka kolumny), są dozwolone i zachowywane; cała bogatość Plainva znajduje się pod properties[id].plainva.
• views — uporządkowana lista widoków. Każdy potrzebuje name i type.
• formulas — funkcja Obsidian. Plainva ich nie tworzy, ale zachowuje bez zmian.

Mapa podkluczy plainva:

Wszystko, co specyficzne dla Plainva, ma nadaną przestrzeń nazw. Trzy miejsca:

properties[<note.key>].plainva — na kolumnę:

views[i].plainva — na widok:

Oprócz bloku plainva, widok może nieść natywny obiekt views[i].filters — filtry właściwości dla poszczególnych widoków (ta sama jednokorzeniowa gramatyka and/or/not co filters na poziomie pliku). Plainva przechowuje tu reguły filtrów właściwości, po jednym zestawie na widok, dzięki czemu każdy widok filtruje niezależnie; filters na poziomie pliku zachowuje wtedy tylko źródła. Obsidian stosuje views[i].filters natywnie dla każdego widoku.

views[0].plainva — klucze dotyczące całego pliku, dozwolone wyłącznie na pierwszym widoku:

contextFilters to odpowiednik filtra „ta strona” z Notion w Plainva. Każdy wpis to klucz właściwości; gdy baza danych jest osadzona w notatce, jej wiersze są ograniczane do tej notatki głównej za pośrednictwem tej właściwości (rozwiązywane przez indeks linków: właściwość relacji, czyli strona właścicielska, lub zwykła właściwość z linkiem wiki dopasowuje wiersze wskazujące na notatkę główną, a obliczana kolumna odwrotna dopasowuje to, na co wskazuje notatka główna). Celowo nie jest zapisywany w natywnym filters, więc Obsidian go ignoruje i pokazuje wszystkie wiersze; przy samodzielnym otwarciu w Plainva jest on również pomijany (brak notatki głównej) i pokazywane są wszystkie wiersze. Wiele wpisów łączy się logiką AND.

taskList wskazuje listę zadań u dostawcy, na której również tworzone jest zadanie utworzone w Plainva (Google Tasks, przypomnienia iCloud, Microsoft). Wartość to id konta i id listy rozdzielone pierwszą spacją — sam id listy CalDAV może zawierać spacje. Bez tego klucza nowe zadanie pozostaje zwykłą notatką. Jeśli wartość przestanie się rozwiązywać (konto usunięte, lista usunięta), Plainva zachowuje się tak, jakby klucza nie było, zamiast zgadywać inną listę. Obsidian go ignoruje.

Typy wejścia

plainva.input to jeden z:

text  number  rating  checkbox  date  datetime
select  status  multiselect
list  tags  url  email  phone
relation

Obliczana kolumna odwrotna nie ma input — jest identyfikowana wyłącznie przez reverseOf. Kolumna rating trzyma w pliku zwykłą liczbę — nastroj: 4 — a rysowana jest jako kropki. Sterują tym dwa opcjonalne podklucze:

    note.nastroj:
      plainva:
        input: rating
        ratingMax: 5        # od 1 do 10, domyślnie 5
        ratingGlyph: "★"      # jeden znak, domyślnie kropka

Sortowanie i filtrowanie działają jak dla number. Obsidian nie zna rating i pokazuje kolumnę jako liczbę — czym ona jest.

file.day to pole wirtualne: dzień, który oznacza nazwa pliku notatki dziennej, według folderu i formatu sejfu. Nie stoi w żadnej notatce, jest wyliczane przy zapytaniu i tylko do odczytu; jedyne miejsce, w którym służy, to dateField widoku kalendarza albo osi czasu. Obsidian go nie zna — widok, który go używa, pozostaje tam pusty.

Agregacja

Kolumna agregacji też nie ma input. Oblicza wartość na podstawie notatek, na które wskazuje kolumna linku TEJ bazy danych:

properties:
  note.offen:
    displayName: Open
    plainva:
      rollup:
        through: aufgaben      # kolumna relacji LUB odwrotna tej bazy danych
        of: status             # właściwość powiązanych notatek
        fn: countWhere
        where:
          op: "!="             # ==  !=  contains  notContains  >  <  >=  <=
          value: Erledigt

• fn to jedno z: count, countWhere, percentWhere, sum, average, median, min, max, earliest, latest, checked, unchecked, empty, filled, unique.
• of jest pomijane tylko dla count. where jest dozwolone tylko dla countWhere i percentWhere, gdzie jest wymagane.
• Pusty operand (value: "") to operator jest-puste, dokładnie jak w filtrach.
• Wartość nie znajduje się w żadnym pliku. Nigdy nie zapisuj jej we frontmatter — jest przeliczana przy każdym zapytaniu, a zapisana wartość byłaby błędna już od pierwszej zmiany.
• Niekompletna lub nieznana agregacja jest przy odczycie pomijana, a nie traktowana jako błąd: kolumna pozostaje pusta, plik się otwiera.
• Obsidian nie zna tego klucza i pokazuje pustą kolumnę. Plik pozostaje ważny.

Opcje i kolory

Kolumny Wybór/Status/Wielokrotny wybór mogą nieść kuratorowaną listę opcji. Każda opcja:

options:
  - value: Open          # required
    color: amber         # optional palette name (see below)
    group: Active        # optional; STATUS only — orders options into stages
  - value: Done
    color: green
    group: Closed

color to nazwa palety, nie kolor CSS. Prawidłowe nazwy: gray, teal, blue, green, amber, coral, purple, pink. Nieznany kolor przechodzi na kolor wyprowadzony z wartości.

Typy widoków

views[i].type na dysku to natywny typ Obsidian. Widoki dostępne tylko w Plainva są zapisywane jako type: table plus wskazówka plainva.render, dzięki czemu Obsidian degraduje je do zwykłej tabeli:

Filtry

filters wybiera, które notatki znajdują się w bazie danych, i zawęża je.

Warunki źródła decydują o przynależności:

• Folder: file.folder == "Path/To/Folder" (względny do vaultu; folder główny to "").
• Tag: file.hasTag("project") (bez wiodącego #).

Wiele źródeł to po prostu wiele wpisów. Brak filters w ogóle = każda notatka w vaulcie.

Gdzie znajdują się warunki właściwości: na poziomie pliku filters obowiązuje dla każdego widoku. Plainva zamiast tego przechowuje reguły filtrów właściwości dla każdego widoku osobno w views[i].filters (ta sama jednokorzeniowa struktura) i zachowuje na poziomie pliku tylko źródła, dzięki czemu każdy widok może filtrować niezależnie. Oba warianty są zgodne z formatem Obsidian; narzędzie może zapisać dowolny z nich. Starszy plik z warunkami właściwości na poziomie pliku nadal działa — Plainva rozdziela je do poszczególnych widoków przy najbliższym zapisie.

Warunki właściwości używają gołych nazw właściwości i tych operatorów:

Struktura (jednokorzeniowa!): jedno z and / or / not, którego wpisy są stringami warunków — lub jeden poziom zagnieżdżonych obiektów grup {and:[...]} / {or:[...]} (grupy w stylu Notion). Przykład łączący źródło, warunek i grupę OR:

filters:
  and:
    - 'file.folder == "Projects"'
    - 'status != "Done"'
    - or:
        - 'priority == "1"'
        - 'priority == "2"'

Kompletna, opisana .base

filters:
  and:
    - 'file.folder == "Projects"'          # source: notes in the Projects folder
properties:
  note.status:                             # column id is note.-prefixed
    displayName: Status                    # optional Obsidian column label
    plainva:
      input: status
      options:
        - value: Open
          color: amber
          group: Active
        - value: Done
          color: green
          group: Closed
views:
  - type: table                            # first view: also carries file-wide keys
    name: All projects                     # every view needs a name
    order: [file.name, note.status]        # order uses note.-prefixed ids
    plainva:
      fileIconColor: "#2f6f6f"
      newItemFolder: Projects
  - type: table                            # a board is a native table + render hint
    name: Board
    plainva:
      render: board
      groupBy: status                      # groupBy uses the BARE key

Relacje (kontrakt dwustronny)

Relacja łączy notatki ze sobą. To najbardziej podatna na błędy rzecz do napisania ręcznie, ponieważ obejmuje trzy miejsca. Utrzymaj wszystkie trzy spójne.

1. Wartość znajduje się we frontmatter notatki źródłowej, jako link wiki (lub ich lista):

   ---
   type: Task
   project: "[[Project Alpha]]"
   ---

2. Źródłowa .base deklaruje kolumnę relacji (relationBase = docelowa baza danych; relationLimit: one dla pojedynczego linku):

   properties:
     note.project:
       plainva:
         input: relation
         relationBase: Projects.base
         relationLimit: one

3. Docelowa .base może pokazać relację odwrotną za pomocą kolumny obliczanej. Jej wartości nie są nigdzie przechowywane — są wyprowadzane z linków notatek źródłowych:

   properties:
     note.tasks:
       plainva:
         reverseOf:
           base: Tasks.base       # the source .base (vault-relative path)
           property: project      # the BARE source property key

Przykład krok po kroku: Zadania ↔ Projekty

Tasks.base

filters:
  and:
    - 'file.folder == "Tasks"'
properties:
  note.status:
    plainva:
      input: status
      options:
        - value: Open
          color: amber
        - value: Done
          color: green
  note.project:
    plainva:
      input: relation
      relationBase: Projects.base
      relationLimit: one
views:
  - type: table
    name: All tasks
    order: [file.name, note.status, note.project]

Projects.base

filters:
  and:
    - 'file.folder == "Projects"'
properties:
  note.tasks:
    plainva:
      reverseOf:
        base: Tasks.base
        property: project
views:
  - type: table
    name: All projects
    order: [file.name, note.tasks]

Tasks/Write proposal.md

---
type: Task
status: Open
project: "[[Project Alpha]]"
---
# Write proposal

Projects/Project Alpha.md

---
type: Project
---
# Project Alpha

Wynik: w Projects.base obliczana kolumna tasks dla Project Alpha wymienia „Write proposal”, ponieważ pole project tego zadania linkuje z powrotem do niej. Zauważ, że Project Alpha.md nie ma klucza tasks: — strona odwrotna jest obliczana, nigdy przechowywana.

Czego NIE robić w relacjach

• Nie zapisuj wartości odwrotnych w notatkach. Kolumna reverseOf jest obliczana. Zapisanie klucza tasks: w Project Alpha.md jest błędne i nie przetrwa cyklu odczytu/zapisu.
• Zadbaj, aby cele linków się rozwiązywały. "[[Project Alpha]]" musi pasować do istniejącej nazwy notatki, w przeciwnym razie link pokazuje się jako uszkodzony.
• Utrzymuj ścieżki względne do vaultu z ukośnikami do przodu i bez wiodącego ./ (Projects.base, DB/Projects.base).
• reverseOf.property to goły klucz źródłowy (project), nie note.project.

Relacje do samej siebie i elementy podrzędne

Dla relacji, której celem jest ta sama baza danych, skieruj relationBase na tę samą .base. Aby zagnieździć dzieci pod rodzicami w widoku tabeli, ustaw views[i].plainva.subItemsProperty na goły klucz relacji nadrzędnej. Cykle są obsługiwane; przy wyłączonych elementach podrzędnych wiersze pozostają płaskie, a wartości są zachowane.

index.md (spis treści folderu)

index.md to zarezerwowana nazwa dla spisu treści folderu.

• Tylko główna index.md może nieść frontmatter, i tylko okf_version — wersję konwencji, którą przestrzega vault (obecnie "0.2"; oznacza to vault jako aktywny w OKF). Vault, który wciąż deklaruje "0.1", jest podnoszony w Ustawienia → Vault → Treść i struktura → Wersja pakietu → Podnieś…; w tym samym kroku można usunąć przestarzałe pole okf_version z notatek. index.md poza folderem głównym musi być wolna od frontmatter — frontmatter tam jest naruszeniem nazwy zarezerwowanej.
• Zarządzana przez Plainva index.md kończy się znacznikiem <!-- plainva:index generated --> (komentarz HTML, niewidoczny w trybie czytania). Jego obecność oznacza, że Plainva automatycznie utrzymuje plik aktualny. Jeśli edytujesz taki plik ręcznie, albo zachowaj znacznik (i utrzymaj wygenerowany kształt), albo usuń go świadomie, aby na stałe przejąć plik.
• Generowane listingi to sekcje linków w formie * [Tytuł](względny/url) - opis.

Jeśli generujesz przegląd folderu ręcznie, bezpiecznym wyborem jest nie dodawać znacznika — wtedy Plainva nigdy go nie nadpisze.

Widoki grafu (plainva.render: "graph")

Widok grafu jest przechowywany tak jak każdy niekative widok: type: table plus wskazówka render. Jego opcje żyją w TEJ SAMEJ przestrzeni nazw views[i].plainva:

views:
  - type: table
    name: Net
    plainva:
      render: graph
      graphEdges: [projekt]        # klucze właściwości relacji rysowane jako krawędzie
      graphColorBy: status         # właściwość wybór/status -> kolor węzła
      graphSizeBy: prio            # właściwość liczbowa -> rozmiar węzła
      graphShowExternal: true      # dołącz cele relacji spoza widoku
      graphShowIncoming: true      # relacje z INNYCH baz danych, które tu wskazują (np. zadania projektu)

Wszystkie klucze opcji grafu są opcjonalne; pomiń je całkowicie, gdy nieustawione. Obsidian renderuje ten sam plik jako zwykłą tabelę i nie może zgłosić błędu.

Widok Tablica (plainva.render: "board") może dodatkowo nieść views[i].plainva.boardColumnOrder — listę kluczy kolumn grupujących (__UNGROUPED__ oznacza kolumnę bez wartości), która zapamiętuje ręczną kolejność kolumn. Tablice Wybór/Status zamiast tego zmieniają kolejność options właściwości. Pomiń klucz, gdy nieustawiony.

Widok tablicy korkowej (plainva.render: "pinboard")

Tablica korkowa jest przechowywana tak jak każdy nienatywny widok: type: table plus wskazówka render. Jej klucze znajdują się w tej samej przestrzeni nazw views[i].plainva:

views:
  - type: table
    name: Pinboard
    plainva:
      render: pinboard
      pinboardOrder:                  # ręczna kolejność nieprzypiętych kart
        - "Notes/Groceries.md"
      pinboardPinned:                 # przypięte; kolejność listy = kolejność sekcji
        - "Notes/Idea.md"
      pinboardFilterBy: note.labels   # źródło etykiet paska chipów; pomiń = tags

Zasady: przypięte ścieżki nie powtarzają się w pinboardOrder. Karty spoza obu list renderują się na górze, od najnowszych (czas utworzenia). Wpisy, których plik już nie istnieje lub opuścił zestaw źródłowy, są ignorowane i usuwane przy najbliższym zapisie. Gdy notatka zostanie przemianowana lub przeniesiona, Plainva automatycznie przekierowuje ścieżki na obu listach; narzędzia zewnętrzne muszą robić to samo. Obsidian ignoruje te klucze i pokazuje widok jako tabelę.

Nie dotykaj i bezpieczeństwo

• .plainva/ przechowuje kopie zapasowe i stan wewnętrzny. Nigdy nie czytaj z niego logiki programu ani do niego nie zapisuj.
• Nieznane klucze są święte. Gdy przepisujesz .base lub notatkę, przenieś każdy klucz, którego nie zamierzałeś zmienić, bez zmian. Sam Plainva zachowuje nieznane klucze .base przez wewnętrzną surową kopię; zewnętrzny program piszący powinien robić to samo (sparsuj → zmień tylko to, co zamierzasz → zserializuj).
• Wartości zmieniają się w notatce, nie w .base. Aby ustawić komórkę, edytuj frontmatter notatki. .base decyduje tylko o tym, które notatki i kolumny są pokazywane.
• Nie dodawaj kluczy najwyższego poziomu .base poza filters / formulas / properties / views.
• Kodowanie: UTF-8. Nowe pliki: zakończenia linii LF, bez BOM. Notatka lub plik tekstowy, który ma już zakończenia linii CRLF albo BOM, zachowuje je — Plainva ich nie zmienia i narzędzie też nie powinno. Jedynym wyjątkiem jest .base: Plainva zapisuje go na nowo, z LF i bez BOM, za każdym razem, gdy zmienia się jego konfiguracja. Sam znak powrotu karetki (CR) jako zakończenie linii (stare pliki z Maca) jest odczytywany, ale nie jest zachowywany: przy pierwszej zmianie takiego pliku Plainva zapisuje go z LF.

Zobacz też

• Notatki i Markdown — ten sam materiał z perspektywy pisania ręcznego w aplikacji
• Bazy danych (.base) — bazy danych wyjaśnione dla codziennego użytku
• OKF — type, wersja pakietu, pola zaufania OKF 0.2, index.md i konwersja vaultu

Pasek koloru / Ikona / Tagi · cała notatka

Filtruj według paska koloru, ikony, tagów całej notatki lub właściwości etykiet wybranej dla tablicy. Tagi pasują dokładnie: #work nie pasuje do #workshop ani #work/child. Tekst i frontmatter są łączone. Wartości są dostępne z całego źródła także bez wyników; nieznane nazwy ikon zostają zachowane.

filters:
  and:
    - file.folder == "Notes"
views:
  - type: table
    name: Example
    filters:
      and:
        - 'note.plainva.header_color == "#2a7f7b"'
        - 'note.plainva.icon == "lucide:pin"'
        - 'file.tags.contains("#work")'

• nie zawiera: !file.tags.contains("#work")
• jest puste: file.tags.isEmpty()
• nie jest puste: !file.tags.isEmpty()

Właściwości zadania: godzina, priorytet, przypomnienie, stany

• Godzina terminu. Właściwość terminu zadania — kolumna daty w bazie danych, termin w polskim vaulcie — może nosić godzinę: termin: 2026-09-21T14:00. Plainva odczytuje godzinę niezależnie od typu kolumny; sam dzień (2026-09-21) i północ (T00:00) oznaczają oba „brak godziny”. Baza zadań utworzona przez Plainvę typuje tę kolumnę jako data i godzina; starsza zachowuje zwykłą kolumnę daty, dopóki nie przyjmiesz jednorazowej propozycji przełączenia. W stronę Google, Microsoft i CalDAV zadanie nadal podróżuje tylko ze swoim dniem.
• Priorytet. Kolumna wyboru, której nazwa w jednym z dziesięciu języków Plainvy oznacza „priorytet” (priority, priorität, prioridad, priorité, priorità, 優先度, prioriteit, priorytet, prioridade, 优先级). Ranga to pozycja opcji: pierwsza = wysoki, druga = średni, trzecia = niski; pusta = brak. Treść opcji zależy od Ciebie.
• Wyjątek przypomnienia. remind: off wycisza przypomnienie jednego zadania; remind: 30 przypomina 30 minut przed jego godziną (ma sens tylko dla zadania z godziną). Bez tej właściwości obowiązują ustawienia.
• Stany pola wyboru. - [ ] otwarte, - [x] ukończone, - [/] w toku, - [-] anulowane. W toku liczy się jako otwarte, anulowane jako zamknięte; anulowane podzadanie opuszcza licznik file.tasks. Plainva zapisuje [/] i [-] tylko wtedy, gdy wybierzesz Ustaw stan.
• Znaczniki priorytetu na polu wyboru. Odczyt: 🔺 ⏫ (wysoki), 🔼 (średni), 🔽 ⏬ (niski). Zapis: ⏫, 🔼 lub 🔽, umieszczony przed pierwszym polem z datą.

Wpisy dziennika

• Gdzie. Pod nagłówkiem notatki dziennej, którego tekst jest nagłówkiem dziennika vaulta (ustawienie Nagłówek dziennika, domyślnie Journal); poziom nagłówka (# do ######) nie ma znaczenia. Sekcja kończy się na następnym nagłówku najwyższego poziomu notatki. Wiersze wewnątrz bloków kodu i komentarzy HTML nie są wpisami.
• Forma zapisu. - HH:mm Tekst — 24-godzinny czas lokalny urządzenia, jedna spacja, potem tekst. Kolejne wiersze tego samego wpisu to wiersze kontynuacji, wcięte do tekstu. Wpis zadania niesie pole wyboru przed godziną: - [ ] HH:mm Tekst.
• Odczytywane również. HH:mm:ss, jednocyfrowa godzina (9:05), znaczniki * i +, każdy stan pola wyboru ([ ], [x], [/], [-]) oraz listy z pustymi liniami między wpisami. Wiersz listy bez godziny nie jest wpisem i pozostaje nietknięty.
• Kolejność. Nowe wpisy są dopisywane na końcu sekcji, przed końcowymi pustymi liniami; lista zachowuje znacznik i odstępy, których notatka już używa. Brakujący nagłówek jest dodawany ze skonfigurowanym tekstem jako ## Journal na końcu notatki, w odstępie jednej pustej linii. Żaden istniejący wiersz nie jest przeformatowywany; zakończenia linii (LF lub CRLF) i frontmatter pozostają takie, jakie są.
• Scalanie. Gdy dwa urządzenia dopisały do tej samej sekcji, synchronizacja jednoczy wpisy według godziny — całe wpisy, nigdy pojedyncze wiersze; identyczne wiersze raz, przy równych godzinach najpierw lokalny. Dotyczy to też sytuacji, gdy oba urządzenia utworzyły notatkę. Każda inna różnica jest konfliktem jak dotychczas.
• Ustawienie. journalHeading jest częścią profilu ustawień vaulta, obok folderu i formatu notatek dziennych, dzięki czemu każde urządzenie odczytuje ten sam nagłówek.