Modelowanie treści za pomocą Jekyll

Nie jest to całkiem nowy temat, ale ostatnio miałem powód, by ponownie przyjrzeć się umiejętności modelowania treści w pracy mojego zespołu. Nasze doświadczenie osiągnęło punkt, w którym ograniczenia sposobu, w jaki praktykujemy, stają się jasne. Naszym najczęstszym problemem jest to, że ludzie mają tendencję do przywiązywania siebie i swoich modeli mentalnych do wybranej platformy i jej konwencji.

Zamiast uczyć ludzi, jak modelować treści, uczymy ich modelowania treści w Drupalu lub modelowania treści w WordPressie. Wolałbym jednak, abyśmy podchodzili do tego z uwzględnieniem najlepiej pojętego interesu użytkowników, niezależnie od platformy, na której znajdą się treści.

Dalsze czytanie na SmashingMag:

• Zbuduj blog ze stronami Jekyll i GitHub
• Dlaczego statyczne generatory stron internetowych to kolejna wielka rzecz?
• Recenzowane statyczne generatory stron internetowych: Jekyll, pośrednik, korzenie, Hugo
• Automatyzacja opracowywania opartego na wytycznych stylistycznych

Ten sposób myślenia sprowadził mnie z powrotem do pomysłu, na punkcie którego mam obsesję, a mianowicie, że kiedy musimy stworzyć artefakt, aby przekazać pewne pomysły klientowi, proces prawie zawsze przebiega lepiej, gdy ten artefakt jest tak blisko, jak możliwe do rzeczywistej strony internetowej zamiast zdjęcia strony internetowej lub pliku PDF pełnego diagramów.

W ten sposób zadałem sobie pytanie: czy istnieje narzędzie, którego mógłbym użyć, aby pomóc ludziom w szybkim modelowaniu treści w sposób niezależny od platformy i jednocześnie zbudować artefakt, który byłby idealny do komunikowania intencji klientowi lub zespołowi?

Teoria wysokiego poziomu modelowania treści

Odwróćmy się trochę, zanim wejdziemy do Jekyll. Uważam, że możesz usunąć wszystkie konwencje i język specyficzny dla platformy z dyskusji na temat modelowania treści i zdefiniować go jako system składający się z trzech części:

1. Podstawową ideą jest obiekt : pewna jednostka treści, która łączy się w całej witrynie. Na przykład wpis na blogu lub osoba byłaby obiektem w witrynie.
2. Obiekty posiadają atrybuty, które je definiują . Post na blogu może mieć tytuł, treść, autora. Osoba może mieć imię, zdjęcie, biografię.
3. Obiekty mają relacje, które określają, gdzie trafiają do witryny , a układy mają logikę, która określa, które atrybuty obiektu są używane i gdzie. Nasz przykładowy obiekt postu na blogu jest połączony z obiektem person, ponieważ jego autorem jest osoba. Wypisujemy imię i nazwisko autora oraz link do jego profilu na stronie posta, a jego pełną biografię na stronie profilu.

Chciałem stworzyć system, który szanuje idee wysokiego poziomu, które nakreśliłem, ale daje zespołowi swobodę tworzenia atrybutów i relacji według własnego uznania, bez martwienia się o pomysły specyficzne dla niektórych platform. Zamiast tego mogą skupić się na definiowaniu treści na podstawie tego, co jest najlepsze dla użytkowników . I okazuje się, że Jekyll ma cechy, które to umożliwiają.

Wejdź Jekyll

Jekyll to statyczna platforma do blogowania. A zanim przejdziesz do sekcji komentarzy, tak, zdaję sobie sprawę, że słusznie jest uważać ją za samodzielną platformę. Ma jednak kilka zalet w stosunku do czegoś takiego jak Drupal czy WordPress.

Jekyll poważnie traktuje prostotę. Nie ma bazy danych, zamiast tego opiera się na płaskich plikach i niektórych znacznikach szablonów Liquid, które generują zwykły stary kod HTML. Płyn jest ograniczony, prosty i niezwykle czytelny dla człowieka. Odkryłem, że mogę pokazać komuś szablon skonstruowany z kilkoma znacznikami Liquid i dopóki mają trochę doświadczenia z kodem front-endowym, rozumieją, co robi szablon.

Fajne w tym jest to, że nie musimy nikomu pokazywać, jak uruchomić bazę danych, jak podłączyć do niej swoje szablony, jak skonfigurować obszar administracyjny ich CMS do pracy z ich szablonami i tak dalej. Zamiast tego możemy zainstalować Jekyll i nauczyć, jak uruchomić serwer. Jeśli użytkownik korzysta z komputera Mac, istnieje duża szansa, że ​​jest to dwuminutowy proces, który zadziała za pierwszym razem.

Jekyll również nie wymusza wielu konwencji w gardle użytkownika. Masz swobodę tworzenia preferowanej struktury plików i potoku zasobów, ustanawiania własnych relacji między plikami i pisania znaczników w sposób, który lubisz najbardziej. Nieliczne konwencje, które posiada, można łatwo przekonfigurować, aby pasowały do ​​Twojego stylu.

Używanie kolekcji do tworzenia i zawierania obiektów

Chociaż nadal jest to uważane za funkcję eksperymentalną, Jekyll ma coś, co nazywa się kolekcjami, które pozwolą nam stworzyć system, który opisuję.

Zasadniczo tworzysz folder i nazywasz go zgodnie z typem tworzonego obiektu. Następnie dodajesz pliki do tego folderu, a każdy plik reprezentuje obiekt w tej kolekcji. Gdy masz już obiekty, możesz utworzyć dla nich atrybuty, używając YAML na początku każdego pliku. YAML to składnia, która umożliwia definiowanie par klucz/wartość, które z łatwością przechowują informacje.

Fajne w tym systemie jest to, że jest niesamowicie prosty. Wszystko jest czytelne dla człowieka i działa w sposób łatwy do nauczenia dla nowego użytkownika. Zamiast tworzyć dużo dokumentacji na temat tego, jak ktoś powinien tworzyć treści i relacje w ostatecznym systemie, możesz po prostu to stworzyć. Projektanci mogą zobaczyć, jakie są obiekty i ich atrybuty, dzięki czemu mogą zaplanować swój system projektowania. Deweloperzy front-end mają działającą stronę internetową, za pomocą której mogą zaprojektować swoje znaczniki i CSS.

Ponieważ nie są zmuszeni do korzystania z określonego systemu lub konwencji, mogą po prostu użyć tego, który preferują, lub konwencji ostatecznej platformy dla projektu. A programiści zaplecza mogą łatwo określić intencje projektanta podczas przenoszenia szablonów i logiki do dowolnego systemu CMS, którego zdecydują się użyć, ponieważ zostało to już dla nich napisane.

Zbudujmy prostą witrynę z obiektami i relacjami

Jeśli zamierzamy wykorzystać ten pomysł, musimy założyć prostą witrynę Jekyll, a następnie zbudować nasze obiekty i relacje. Jeśli chcesz zobaczyć produkt końcowy, możesz go pobrać z tego repozytorium GitHub. (Uwaga: do niektórych tego będziesz musiał użyć terminala, ale obiecuję, że jest to dość podstawowe użycie.)

Instalowanie Jekylla

Jeśli korzystasz z komputera Mac, jest to całkiem proste. Ruby jest już zainstalowany, wystarczy zainstalować Jekyll. Otwórz terminal i wpisz:

 gem install jekyll

To zainstaluje klejnot Jekyll Ruby i jego zależności. Gdy skończy się bieg, to wszystko: masz Jekylla.

Konfigurowanie witryny

Teraz musimy uruchomić rusztowanie Jekyll. Wszystkie moje projekty internetowe przechowuję w folderze na moim Macu o nazwie Witryny w folderze domowym. Więc najpierw muszę przejść do niego za pomocą:

 cd ~/Sites

Następnie mogę wygenerować folder z odpowiednimi plikami i strukturą za pomocą tego polecenia:

 jekyll new my-new-site

Możesz zastąpić „moja-nowa-witryna” dowolną nazwą swojego projektu. Otrzymasz folder o tej nazwie i wszystkie odpowiednie pliki, które się w nim znajdują.

Otwórz Finder i przejdź do nowego folderu, aby zobaczyć, co jest w środku. Powinieneś zobaczyć coś takiego:

Ponieważ nie potrzebujemy wszystkiego, co oferuje Jekyll, najpierw usuniemy kilka plików i folderów. Rzućmy /_includes , /_posts , /_sass , about.md i feed.xml .

Konfiguracja

Teraz skonfigurujemy nasze konfiguracje dla całej witryny. Otwórz _config.yml . Jest tam mnóstwo rzeczy wprowadzających. Po prostu to usunę i zastąpię moimi preferowanymi konfiguracjami. Oto nowa konfiguracja tego projektu:

 permalink: pretty collections: projects people

Zrobiłem to tak, że moje adresy URL będą wyglądały jak /ścieżka/do/pliku/ zamiast /ścieżka/do/pliku.html , który jest po prostu osobistym wyborem. Założyłam również dwie kolekcje: projekty i ludzie . Każda nowa kolekcja musi zostać dodana do pliku konfiguracyjnego.

Teraz mogę tworzyć foldery dla tych kolekcji w moim projekcie:

Nazwy folderów muszą zaczynać się od znaku _ (podkreślenia), aby Jekyll wiedział, co z nimi zrobić.

Tworzenie niektórych przedmiotów

Pierwszymi przedmiotami, które wykonamy, będą nasi ludzie. Użyjemy Markdown do tworzenia tych plików, aby były ładne i czyste, ale nadal generowały poprawny, semantyczny kod HTML. Widać, że zrobiłem kilka plików do postaci z historii Ameryki (może to, ale nie musi być związane z faktem, że słucham Hamiltona non stop od miesiąca):

Atrybuty, które umieścimy w naszym pliku dla osoby, będą:

 --- object-id: first-name: last-name: job: listing-priority: wikipedia-url: ---

Użyjemy object-id aby później odnieść się do dowolnego z tych obiektów. Podzielimy imię i nazwisko, abyśmy mogli wybrać kombinację do użycia w różnych miejscach (jeśli twój system tego wymaga) i użyjemy funkcji job do zdefiniowania ich działania. (Unikam „tytułu”, ponieważ jest to już zmienna, którą domyślnie mają strony w Jekyll.) Dołączyłem również atrybut priorytetu listy, który pozwoli mi posortować każdą osobę według kaprysu, ale możesz też sortować według niektóre wbudowane metody, takie jak alfabetyczne lub numeryczne. Na koniec mamy pole na link do strony Wikipedii danej osoby.

Wszystko to jest zawarte między trzema myślnikami na górze i na dole, aby zdefiniować to jako front-matter YAML. Zawartość każdej biografii będzie podążać za YAML i może być dowolną ilością i strukturą HTML (ale użyjemy formatowania Markdown, aby wszystko było ładne i czyste).

Całkowicie wypełniony obiekt osoby wygląda tak (zawartość jest skrócona dla jasności):

 --- object-id: alexander-hamilton first-name: Alexander last-name: Hamilton job: 1st United States Secretary of the Treasury listing-priority: 1 wikipedia-url: https://en.wikipedia.org/wiki/Alexander_Hamilton --- Alexander Hamilton (January 11, 1755 or 1757 – July 12, 1804) was...

A oto obiekt projektu (treść jest skrócona dla jasności):

 --- object-id: united-states-coast-guard title: United States Coast Guard featured: true featured-priority: 2 listing-priority: 1 architect-id: alexander-hamilton wikipedia-url: https://en.wikipedia.org/wiki/United_States_Coast_Guard --- The United States Coast Guard (USCG) is...

Ten ma kilka różnic. Ustawiłem featured atrybut. Jeśli projekt zostanie wyróżniony, zostanie wyświetlony na stronie głównej. Wszystkie projekty zostaną wymienione na stronie projektów. Mamy również preferowany zestaw kolejności sortowania dla każdego miejsca docelowego. I zamieściliśmy odniesienie do id osoby, która stworzyła projekt, więc możemy później odnieść się do niej bezpośrednio.

Generowanie stron z naszych obiektów

Zmieniając mój plik _config.yml mogę tworzyć strony dla każdego z tych obiektów.

 permalink: pretty collections: projects: output: true people: output: true

Ustawienie output: true w każdej kolekcji powoduje wygenerowanie strony dla każdego znajdującego się w niej obiektu. Ale ponieważ nasze obiekty nie mają zawartości w swoich plikach, obecnie nie wyświetlają żadnych danych, co oznacza, że ​​otrzymamy puste strony. Zbudujmy szablon układu, który zrobi to za nas.

Ten plik zostanie umieszczony w folderze _layouts . Ale najpierw mamy do czynienia z plikiem default.html . Spowoduje to przechowywanie wszystkich znaczników, które są spójne we wszystkich naszych plikach HTML.

 <!DOCTYPE html> <html> <head> <meta charset="utf-8"> <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> <title>{{ page.title }}</title> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <link rel="stylesheet" href="/css/styles.css" /> </head> <body> <header role="banner"> ... </header> <div role="main"> <div class="container"> {{ content }} </div> </div> <footer role="contentinfo"> ... </footer> </body> </html>

Zauważysz tag Liquid, który wygląda tak: {{ content }} . Każdy plik, który jest renderowany na stronę przez Jekyll, wymaga określonego dla niego szablonu. Po określeniu szablonu zawartość z tego pliku jest renderowana w lokalizacji znacznika {{ content }} w szablonie układu. Teraz nie musimy powtarzać tego, co będzie na każdej stronie.

Następnie zbudujemy unikalny szablon układu dla naszych obiektów osób. To będzie wyglądać tak:

 --- layout: default --- <header class="intro person-header"> <h1>{{ page.first-name }} {{ page.last-name }}</h1> <h2>{{ page.job }}</h2> </header> <div class="person-body"> {{ page.content }} <a href="{{ page.wikipedia-url }}">Read more about {{ page.first-name }} {{ page.last-name }} on Wikipedia</a> </div>

Ten plik określa, że ​​jego kod jest wstawiany do domyślnego szablonu układu, a następnie jego znaczniki są wypełniane z danych w plikach obiektów osoby.

Ostatnim krokiem jest upewnienie się, że każdy obiekt person określa, że ​​używa pliku układu person.html . Normalnie po prostu wstawilibyśmy to do YAML w naszych plikach osobistych w taki sposób:

 --- object-id: first-name: last-name: job: listing-priority: wikipedia-url: layout: person ---

Wolę jednak, aby dane w moich plikach obiektowych zawierały tylko atrybuty związane z modelem treści. Na szczęście mogę zmienić mój plik _config.yml , aby sobie z tym poradzić:

 exclude: - README.md permalink: pretty collections: projects: output: true people: output: true defaults: - scope: type: projects values: layout: project - scope: type: people values: layout: person

Teraz moja witryna wie, że każdy obiekt w kolekcji projektów powinien używać szablonu układu projektu, a każdy obiekt w kolekcji osób powinien używać układu osoby. Dzięki temu moje obiekty treści są ładne i czyste.

Wyświetlanie obiektów na stronie aukcji

Niezależnie od tego, czy zdecydujemy się wyświetlić strony dla naszych obiektów, czy nie, możemy je wyświetlić i posortować według różnych parametrów. Oto jak umieścilibyśmy wszystkie nasze projekty na stronie:

 --- layout: default title: Projects --- <header class="intro"> <h1>{{ page.title }}</h1> </header> <div class="case-studies-body"> <ul class="listing"> {% assign projects = site.projects | sort: 'listing-priority' %} {% for project in projects %} <li> <h2><a href="{{ project.url }}">{{ project.title }}</a></h2> {{ project.content }} </li> {% endfor %} </ul> </div>

To, co zrobiliśmy, to utworzenie <ul> , aby umieścić w nim naszą listę. Następnie utworzyliśmy zmienną na stronie o nazwie projects i przypisaliśmy do niej wszystkie nasze obiekty projektu i posortowaliśmy je według zmiennej listing-priority , którą utworzyliśmy w każdym z nich. Na koniec, dla każdego projektu w naszej zmiennej projects wyprowadzamy <li> , która zawiera dane z atrybutów w każdym pliku. Daje nam to wysoce kontrolowaną listę naszych obiektów projektu z linkami do ich unikalnych stron.

Na stronie głównej zamiast wyświetlać wszystkie projekty, pokażemy tylko nasze polecane:

 <ul class="listing"> {% assign projects = site.projects | where: "featured", "true" | sort: 'featured-priority' %} {% for project in projects %} <li> <h3>{{ project.title }}</h3> <a href="{{ project.url }}">Learn about {{ project.title }}</a> </li> {% endfor %} </ul>

Każdy obiekt projektu, którego atrybut featured jest ustawiony na wartość true , zostanie wyrenderowany na tej stronie i zostaną posortowane według specjalnej kolejności priorytetów, którą ustawiliśmy dla polecanych projektów.

Są to dość proste przykłady tworzenia i sortowania obiektów, ale pokazują różne możliwości, jakie możemy stworzyć w celu organizowania treści.

Łączenie z określonym obiektem

Ostatnią funkcją, jaką zamierzamy zbudować, jest połączenie z konkretnym obiektem. Jest to coś, co możesz chcieć zrobić, jeśli łączysz autora z postem na blogu lub czymś podobnym. W naszym przypadku zamierzamy dołączyć osobę do projektu, z którym jest powszechnie kojarzona. Jeśli pamiętasz, nasz obiekt projektu ma atrybut architect-id a nasi ludzie mają atrybut object-id . Za pomocą tych atrybutów możemy dołączyć odpowiednią osobę do konkretnego projektu.

Oto nasz szablon układu projektu:

 --- layout: default --- {% assign architect = site.people | where: "object-id", page.architect-id | first %} <header class="intro project-header"> <h1>{{ page.title }}</h1> <p>Architected by: <a href="{{ architect.url }}">{{ architect.first-name }} {{ architect.last-name }}</a></p> </header> <div class="project-body"> {{ page.content }} <a href="{{ page.wikipedia-url }}">Read more about {{ page.title }} on Wikipedia</a> </div>

Wiersz 4 tworzy zmienną o nazwie architect i przeszukuje wszystkie nasze obiekty ludzi pod kątem obiektów z object-id , który pasuje do atrybutu architect-id z projektu. Powinniśmy przypisać object-id , aby zawsze zwracany był tylko jeden wynik, ale aby upewnić się, że otrzymamy tylko jedną odpowiedź i odniesiemy się do niej zamiast do naszej listy jednego elementu, musimy ustawić | first | first na końcu naszego tagu płynnego {% assign %} . Pozwala to obejść ograniczenie Jekyll, w którym obiekty w kolekcjach nie mają na początku unikalnych identyfikatorów. Istnieje inna funkcja zwana danymi , która pozwala na unikatowe identyfikatory, ale nie wyświetla w łatwy sposób stron ani nie daje nam możliwości sortowania naszych obiektów; obejście ograniczeń kolekcji było łatwiejszym i czystszym sposobem uzyskania pożądanej funkcjonalności.

Teraz, gdy strona ma unikalny obiekt, który reprezentuje architekta tego projektu, możemy nazwać jej atrybuty takimi rzeczami, jak imię architekta i adres URL do jego strony Wikipedii. Voila! Łatwe łączenie z obiektami za pomocą unikalnego identyfikatora.

Zawijanie

Istnieje kilka świetnych dodatkowych funkcji, które można ustalić, bardziej szczegółowo zagłębiając się w dokumentację Jekyll, ale mamy tutaj podstawy dobrego prototypu modelowania treści: możliwość definiowania różnych typów obiektów, atrybutów dołączonych do tych obiektów, oraz identyfikatory, które pozwalają nam wywoływać określone obiekty z dowolnego miejsca. Otrzymujemy również bardzo elastyczną logikę do tworzenia szablonów i wyprowadzania naszych obiektów w różnych miejscach. Co najlepsze, cały system jest prosty i czytelny dla człowieka, a w razie potrzeby wyświetla zwykły kod HTML do wykorzystania w innym miejscu.

Do celów komunikacyjnych mamy teraz niezależny od platformy klikalny prototyp (prawdziwą stronę internetową), który zdefiniuje system lepiej niż PDF z mnóstwem diagramów. Możemy zmieniać nasz model treści na bieżąco, gdy uczymy się nowych rzeczy i musimy się dostosowywać. Możemy wprowadzić projektanta i programistę do systemu, aby ustanowił ich wzorce i architekturę front-endu, ponieważ zaakceptuje on wszelkie znaczniki i CSS, których chcą użyć. Możemy nawet wprowadzić do niego edytorów treści, konfigurując je z dostępem za pośrednictwem GitHub GUI lub platformy hostingowej, która umożliwia korzystanie z edytora wizualnego, takiego jak Prose.io, GitHub Pages, CloudCannon lub Netlify.

I nic z tego nie wiąże osoby z uczeniem się sposobów pracy specyficznych dla platformy, co pozwala jej zamiast tego pracować na poziomie koncepcyjnym, który koncentruje się na użytkownikach, a nie na technologii.