Czasem zachodzi potrzeba użycia tego samego fragmentu treści w różnych miejscach. Można go skopiować i wkleić wielokrotnie, ale w razie potrzeby zmian trzeba by było edytować każdą kopię osobno. Dzięki specjalnym znacznikom można wstawiać całe strony lub wybrane fragmenty treści z innych miejsc.
Uwagi
Oto kilka rzeczy, na które warto zwrócić uwagę przy ponownym wykorzystywaniu fragmentów treści za pomocą znaczników „include”:
- Uprawnienia są respektowane przy użyciu „include”, więc treść zostanie wstawiona tylko z tych miejsc, do których użytkownik ma dostęp. Znaczniki te nie są widoczne podczas przeglądania, dlatego łatwo można nieświadomie udostępnić treść z ograniczonym dostępem.
- „Include” działają maksymalnie do trzech poziomów zagnieżdżenia, co ogranicza ryzyko problemów z wydajnością i rekursją.
- Treść wstawiona w ten sposób nie jest indeksowana jako przeszukiwalna zawartość dla stron, na których się pojawia.
- Treść wstawiona za pomocą „include” nie pojawi się w podglądzie ani w skrótach tekstu.
Łatwe pobieranie składni
Znalezienie identyfikatora strony może być trudne, dlatego dostępny jest prosty sposób na uzyskanie znaczników „include”. Otwórz stronę z treścią, którą chcesz ponownie wykorzystać. Zaznacz fragment treści myszką – pojawi się wyskakujące okienko z bezpośrednim linkiem do tego fragmentu. Kliknięcie ikony linku po lewej stronie przełączy widok i pokaże znacznik „include”. Skopiuj go i wklej tam, gdzie chcesz użyć treści. Aby wstawić całą stronę zamiast pojedynczego bloku, usuń znak # i identyfikator fragmentu.
Wymuszanie identyfikatorów treści
Podczas wstawiania konkretnego bloku treści używa się identyfikatora tego bloku (część po znaku #). Domyślnie identyfikatory są generowane automatycznie podczas zapisywania strony. W edytorze wizualnym identyfikator zwykle pozostaje niezmieniony, chyba że blok zostanie usunięty lub sformatowany od nowa. W edytorze Markdown identyfikator może zmieniać się przy każdym zapisie w zależności od treści, więc istnieje duże ryzyko jego zmiany. Dlatego zaleca się ręczne ustawienie identyfikatora, jeśli planujesz używać bloku w znacznikach „include”.
Uwaga: wszystkie identyfikatory powinny zaczynać się od bkmrk, aby uniknąć ich nadpisania.
Edytor WYSIWYG
W edytorze wizualnym można wymusić identyfikator, przechodząc do widoku kodu źródłowego i wpisując go ręcznie:
Edytor Markdown
W edytorze Markdown można wstawić kod HTML z przypisanym identyfikatorem, aby zagwarantować, że pozostanie niezmieniony:
<!-- Old Content -->
<p>Copyright BookStack Enterprises 2020</p>
<!-- Revised with ID -->
<p id="bkmrk-include-copyright-text">Copyright BookStack Enterprises 2020</p>
Znajdowanie strony docelowej znacznika Include
Czasami możesz natrafić na znacznik „include” i chcieć znaleźć stronę, z której pobiera treść.
Można to zrobić, korzystając z bezpośrednich linków do stron w formacie: <base_url>/link/<page_id>
Weź liczbowy identyfikator ze znacznika „include” (po @, ale przed #, jeśli istnieje) i użyj go jako <page_id> w powyższym formacie, aby przejść do strony źródłowej.
Przykład: dla znacznika {{@5#bkmrk-chapter-a}} przejdź do ścieżki /link/5.
Pełny przykładowy URL może wyglądać tak: https://cognivis.ai/link/5
Techniczna logika działania „include”
System stara się inteligentnie obsługiwać znaczniki „include”, odpowiednio przetwarzać różne typy treści i częściowo zachowywać zgodność z zasadami HTML. Oto kilka zasad, które obowiązują podczas analizowania „include”:
- Jeśli celem jest wstawienie konkretnej sekcji, zwykle pobierana jest i wstawiana jej zawartość wewnętrzna. Wyjątkiem są sytuacje, gdy sekcja musi być użyta w całości – wtedy wstawiany jest cały blok, np. tabele, listy czy bloki kodu.
- Przy wstawianiu całych bloków, stron lub zakresów treści system stara się odpowiednio ustrukturyzować zawartość, aby uniknąć zagnieżdżonych akapitów, które są nieprawidłowe w HTML i mogą powodować problemy w przeglądarkach. Dokładna lokalizacja wstawienia jest zachowywana w miarę możliwości, choć czasami treść może przesunąć się przed lub za sekcją, w której została wstawiona.
- Identyfikatory sekcji treści są deduplikowane po przetworzeniu „include”, co może powodować dynamiczną zmianę istniejących identyfikatorów treści na stronie po jej załadowaniu.