Poniżej znajduje się opis mojego szablonu dla pliku wtyczki Obsidian Hypothes.is Plugin, która pobiera adnotacje z Hypothes.is. Dalej prezentuję cały szablon, a na końcu przedstawiam domyślny szablon, który znajduje się po uruchomieniu wtyczki, na podstawie którego przygotwałem własną wersję.
Ogólna struktura szablonu
- Mój szablon składa się właściwie z trzech części:
- nagłówka, zawierającego tytuł i źródło adnotacji;
- szablonu dla adnotacji do strony (page notes w terminologii Hypothes.is);
- szablonu adnotacji w ogóle (annotations).
Zasadniczo nie ma większej różnicy między adnotacjami do strony (page notes) czy adnotacjami w ogóle (annotations). Po prostu adnotacje do strony dotyczą jej całej (sprawdzają się jako miejsce na ogólny komentarz, czy streszczenie całości), a adnotacje w ogóle dotyczą poszczególnych elementów na stronie. W tych pierwszych nie pojawiają się zaznaczenia (cytaty) z treści, w tych drugich tak.
Problemem jest więc terminologia stosowana przez Hypohtes.is, ponieważ w Hypothes.is każdy element to adnotacja (annotation), czy to jest zaznaczenie (highlight), komentarz (annotation), odpowiedź (reply) czy notatka do strony (page note).
Jednakże w szablonie rozróżnione są adnotacje dla strony i adnotacje w ogóle. W tych drugich bowiem pojawia się element pobierający zaznaczenia (highlight), ponieważ w adnotacjach do strony nie dodaje się zaznaczenia.
Szablon został napisany w składni Nunjucks dla języka JavaScript, o której można przeczytać w oficjalnej dokumentacji (dostępnej w języku angielskim). Tam gdzie między linijkami kodu pojawia się wielokropek, czyli …, oznacza to, że opuszczam jakąś partię kodu.
Poszczególne elementy szablonu
Nagłówek
{% if is_new_article %}
# {{title}}
{% if url %}{{url}}{% endif %}
#{{author | replace(".", "_") | replace(" ", "_")}}
{% endif %}
I tak poszczególne elementy wyglądają następująco. Najpierw podaję kod, a następnie opis, wyjaśniający, co wykonuje.
{% if is_new_article %}
# {{title}}
{% if url %}{{url}}{% endif %}
#{{author | replace(".", "_") | replace(" ", "_")}}
{% endif %}
{% if is_new_article %} sprawdza, czy to jest nowy artykuł, jeśli tak, to zwraca to, co jest między tymi elementami, jeśli nie jest to nowy artykuł, to nie robi nic.
{% if is_new_article %}
# {{title}}
{% if url %}{{url}}{% endif %}
#{{author | replace(".", "_") | replace(" ", "_")}}
{% endif %}
# {{title}} zwraca tytuł strony (artykułu), a następnie formatuje go jako nagłówek pierwszego stopnia, ponieważ znajduje się tu znak #. Ważne, aby po tym znaku znajdowała się spacja, w przeciwym razie wygeneruje się tag. Więcej o składni Markdown można przeczytać np. w przewodniku, który zawiera podstawowe elementy tej składni.
{% if is_new_article %}
# {{title}}
{% if url %}{{url}}{% endif %}
#{{author | replace(".", "_") | replace(" ", "_")}}
{% endif %}
{% if url %}{{url}}{% endif %} sprawdza, czy strona posiada adres url. Jeśli jest url, a raczej jest, to zwraca url strony.
{% if is_new_article %}
# {{title}}
{% if url %}{{url}}{% endif %}
#{{author | replace(".", "_") | replace(" ", "_")}}
{% endif %}
#{{author | replace(".", "_") | replace(" ", "_")}} zwraca domenę strony, czyli jej podstawowy adres. Do tego zamienia (replace) kropki i spacje na podkreślnik, ponieważ tutaj domena zostaje zamieniona na tag, poniewż znajduje się tutaj znak #. Zatem jeśli nasza adnotacja znajduje się na stronie Wikipedii, a więc pod adresem pl.wikipedia.org, to w efekcie, po wygenerowaniu pliku w Obsidianie, otrzymamy następujący tag: #pl_wikipedia_org.
Adnotacje
Dla obu rodzajów adnotacji szablon wygląda bardzo podobnie, różnica polega tylko na tym, że w tym drugim rodzaju pojawia element zawierający cytat (highlight), czyli zaznaczenie ze strony.
Dla adnotacji do strony (page notes) cały blok kodu wygląda następująco:
{% for highlight in page_notes %}
---
### {{highlight.updated}}
#{{highlight.updated | truncate(4, true, "")}}/{{highlight.updated | truncate(7, true, "")}}/{{highlight.updated | truncate(10, true, "")}} #{{highlight.group | replace(" ", "-")}} {% for tag in highlight.tags %} #{{tag | replace(" ", "_") | replace(".", "_")}}{% endfor %}
{% if highlight.annotation %}{{highlight.annotation}}{% endif %}
{{highlight.incontext}}
{% endfor %}
Dla adnotacji w ogóle (annotation) cały blok kodu wygląda następująco:
{% for highlight in highlights %}
---
### {{highlight.updated}}
#{{highlight.updated | truncate(4, true, "")}}/{{highlight.updated | truncate(7, true, "")}}/{{highlight.updated | truncate(10, true, "")}} #{{highlight.group | replace(" ", "-")}} {% for tag in highlight.tags %} #{{tag | replace(" ", "_") | replace(".", "_")}}{% endfor %}
> {{highlight.text}}
{% if highlight.annotation %}{{highlight.annotation}}{% endif %}
{{highlight.incontext}}
{% endfor %}
Zatem poszczególne elementy szablonu prezentują się następująco:
{% for highlight in page_notes %}
…
{% endfor %}
Element obejmuje adnotacje do strony, czyli tych, które nazywane są page notes, czyli w tym elemencie definiujemy to, jak wyświetlą się adnotacje.
{% for highlight in highlights %}
…
{% endfor %}
Element obejmuje adnotacje do zaznaczeń i komentarzy, czyli tych, które są nazywane annotations, czyli w tym elemencie definiujemy to, jak wyświetlą się adnotacje.
Dla obu adnotacji poniższy element jest taki sam, zatem opisuję go raz.
### {{highlight.updated}}
Zwraca pełną datę i godzinę ostatniej aktualizacji (update) adnotacji w formacie ustawionym w ustawieniach, w moim przypadku YYYY-MM-DD HH:ss. Następnie całość formatuje się na nagłówek trzeciego stopnia, ponieważ pojawiają się trzy znaki #.
#{{highlight.updated | truncate(4, true, "")}}/{{highlight.updated | truncate(7, true, "")}}/{{highlight.updated | truncate(10, true, "")}}
Tutaj również zwraca datę aktualizacji adnotacji, tylko jednak w szczególny sposób i tworzy ponadto zagnieżdzone (dziedziczone) tagi.
Zatem na początku zwraca 4 cyfry daty, czyli rok, np. 2023, następnie zwraca 7 cyfr daty, czyli rok i miesiąc, np. 2023-04, a na końcu zwraca 10 cyfr daty, czyli rok, miesiąc i dzień, czyli 2023-04-27. Dzięki temu powstaje trójstopniowy zagnieżdzony tag w formacie: #YYYY/YYYY-MM/YYYY-MM-DD. W pliku daje to jeden tag, czyli #2023/2023-04/2023-04-27, ale w liście tagów pozwala na stworzenie struktury drzewiastej, czyli:
2023 --2023-04 ----2023-04-27
Może to wyglądać nienajlepiej, bo w pliku tworzy długi ciąg znaków, oraz może wydawać się bez sensu, ale wyświetlając tagi w Obsidianie w panelu z tagami, możemy przeglądać poszczególne adnotacje z podziałem na rok, miesiąc czy dzień, dzięki temu możemy tak sortować treści, widzieć ile adnotacji wykonaliśmy w danym okresie i nawigować pomiędzy stronami odwiedzanymi w poszczególnych okresach.
#{{highlight.group | replace(" ", "-")}}
Zwraca nazwę warstwy, czy też grupy, w której znajdują się adnotacje, np. Public, Private, czy jakąkolwiek jeszcze mamy. Zamienia też ewentualne spacje w nazwie na podkreślnik.
{% for tag in highlight.tags %} #{{tag | replace(" ", "_") | replace(".", "_")}}{% endfor %}
Zwraca listę tagów adnotacji, ponadto zamienia spacje i kropki na podkreślnik. Zatem jeśli w Hypothes.is mamy tag w postaci media społecznościowe, to w Obsidianie będzie wyglądał następująco: #media-społecznościowe.
> {{highlight.text}}
Zwraca zaznaczenie, cytat, czyli to, co zaznaczamy na stronie, korzystając z Hypothes.is, formatuje to jako cytat, ponieważ znajduje się znak >.
{% if highlight.annotation %}{{highlight.annotation}}{% endif %}
Sprawdza, czy są komentarze, czyli notatki do tego zaznaczenia, jeśli tak, to zwraca je tutaj.
{{highlight.incontext}}
I na końcu: zwraca link do adnotacji w kontekście, a więc podaje stronę źródłową z zaznaczeniem, dzięki czemu możemy udostępniać nasze adnotacje (jeśli to warstwa publiczna, lub warstwa, do której ktoś ma dostęp).
Mój aktualny pełny szablon
{% if is_new_article %}
# {{title}}
{% if url %}{{url}}{% endif %}
#{{author | replace(".", "_") | replace(" ", "_")}}
{% endif %}
{% for highlight in page_notes %}
---
### {{highlight.updated}}
#{{highlight.updated | truncate(4, true, "")}}/{{highlight.updated | truncate(7, true, "")}}/{{highlight.updated | truncate(10, true, "")}} #{{highlight.group | replace(" ", "-")}} {% for tag in highlight.tags %} #{{tag | replace(" ", "_") | replace(".", "_")}}{% endfor %}
{% if highlight.annotation %}{{highlight.annotation}}{% endif %}
{{highlight.incontext}}
{% endfor %}
{% for highlight in highlights %}
---
### {{highlight.updated}}
#{{highlight.updated | truncate(4, true, "")}}/{{highlight.updated | truncate(7, true, "")}}/{{highlight.updated | truncate(10, true, "")}} #{{highlight.group | replace(" ", "-")}} {% for tag in highlight.tags %} #{{tag | replace(" ", "_") | replace(".", "_")}}{% endfor %}
> {{highlight.text}}
{% if highlight.annotation %}{{highlight.annotation}}{% endif %}
{{highlight.incontext}}
{% endfor %}
Informacje lub ustawienia autora wtyczki
Repozytorium GitHub z wtyczką: https://github.com/weichenw/obsidian-hypothesis-pluginDomyślny szablon
{% if is_new_article %}
# {{title}}
## Metadata
{% if author %}- Author: [{{author}}]({{authorUrl}}){% endif %}
- Title: {{title}}
{% if url %}- Reference: {{url}}{% endif %}
- Category: #article
{% endif %}
{%- if is_new_article %}
## Page Notes
{% for highlight in page_notes -%}
{{highlight.annotation}}
{%- if highlight.tags | length %}
Tags: {% for tag in highlight.tags -%} #{{tag | replace(" ", "-")+" "}}{%- endfor %}
{% endif %}
{% endfor %}
{%- endif -%}
{%- if is_new_article -%}
## Highlights
{% for highlight in highlights -%}
- {{highlight.text}} — [Updated on {{highlight.updated}}]({{highlight.incontext}})
{%- if 'Private' != highlight.group %} — Group: #{{highlight.group | replace(" ", "-")}}{% endif %}
{% if highlight.tags | length %} - Tags: {% for tag in highlight.tags %} #{{tag | replace(" ", "-")+" "}}{% endfor %}
{% endif -%}
{% if highlight.annotation %} - Annotation: {{highlight.annotation}}{% endif %}
{% endfor %}
{% endif %}