În acest articol, vom compara nuanțele creării temelor pentru primii doi generatori de site-uri statice.

Am preluat recent sarcina de a crea o temă de documentare a site-ului pentru două proiecte. Ambele proiecte aveau nevoie de aceleași caracteristici de bază, dar unul folosește Jekyll în timp ce celălalt îl folosește pe Hugo.

În raționalitatea tipică a dezvoltatorului, în mod clar exista o singură opțiune. Am decis să creez aceeași temă în ambele cadre și să vă ofer, dragă cititoare, o comparație side-by-side.

Această postare nu este un ghid cuprinzător de construire a temelor, ci este mai degrabă destinat să vă familiarizeze cu procesul de construire a unei teme în ambele generatoare. Iată ce vom acoperi:

  • Cum sunt organizate fișierele tematice
  • Unde să puneți conținut
  • Cum funcționează șablonarea
  • Crearea unui meniu de nivel superior cu pages obiect
  • Crearea unui meniu cu linkuri imbricate dintr-o listă de date
  • Punerea împreună a șablonului
  • Crearea stilurilor
  • Cum se configurează și se implementează în paginile GitHub

Iată un wireframe prost al temei pe care o voi crea.

Hugo vs Jekyll o batalie epica a temelor generatoare de

Dacă intenționați să construiți, poate fi util să serviți tema local pe măsură ce o construiți – și ambele generatoare oferă această funcționalitate. Pentru Jekyll, fugiți jekyll serve, iar pentru Hugo, hugo serve.

Există două elemente principale: zona principală de conținut și meniul important al barei laterale. Pentru a le crea, veți avea nevoie de fișiere șablon care să spună generatorului de site cum să genereze pagina HTML. Pentru a organiza fișierele șablon tematic într-un mod sensibil, trebuie mai întâi să știți ce structură de directoare se așteaptă generatorul de site.

Cum sunt organizate fișierele tematice

Jekyll acceptă teme bazate pe bijuterii, pe care utilizatorii le pot instala ca orice alte pietre prețioase Ruby. Această metodă ascunde fișierele tematice în bijuterie, astfel încât, în scopul acestei comparații, nu folosim teme bazate pe bijuterii.

Când alergi jekyll new-theme <name>, Jekyll va schela o nouă temă pentru dvs. Iată cum arată aceste fișiere:

.
├── assets
├── Gemfile
├── _includes
├── _layouts
│   ├── default.html
│   ├── page.html
│   └── post.html
├── LICENSE.txt
├── README.md
├── _sass
└── <name>.gemspec

Numele de directoare sunt descriptive în mod corespunzător. _includes directorul este pentru bucăți mici de cod pe care le reutilizați în locuri diferite, în același mod în care ați pune unt pe toate. (Doar eu?)

_layouts directorul conține șabloane pentru diferite tipuri de pagini de pe site-ul dvs. _sass folderul este pentru Sass fișiere utilizate pentru a construi foaia de stil a site-ului dvs.

Puteți schela o nouă temă Hugo rulând hugo new theme <name>. Are aceste fișiere:

.
├── archetypes
│   └── default.md
├── layouts
│   ├── 404.html
│   ├── _default
│   │   ├── baseof.html
│   │   ├── list.html
│   │   └── single.html
│   ├── index.html
│   └── partials
│       ├── footer.html
│       ├── header.html
│       └── head.html
├── LICENSE
├── static
│   ├── css
│   └── js
└── theme.toml

Puteți vedea unele asemănări. Fișierele șablonului de pagină ale lui Hugo sunt ascunse layouts/. Rețineți că _default tipul de pagină conține fișiere pentru un list.html și a single.html.

Spre deosebire de Jekyll, Hugo folosește aceste nume de fișiere specifice pentru a distinge între pagini de listă (cum ar fi o pagină cu linkuri către toate postările de pe blog) și pagini unice (ca una dintre postările dvs. de pe blog). layouts/partials/ directorul conține biții reutilizabili, iar fișierele de foi de stil au un loc ales în static/css/.

Aceste structuri de directoare nu sunt setate în piatră, deoarece ambele generatoare de site permit o anumită măsură de personalizare. De exemplu, Jekyll vă permite să definiți colecții, iar Hugo folosește pachete de pagini. Aceste funcții vă permit să vă organizați conținutul în mai multe moduri, dar, deocamdată, să ne uităm unde să puneți câteva pagini simple.

Unde să puneți conținut

Pentru a crea un meniu de site care arată astfel:

Introduction
    Getting Started
    Configuration
    Deploying
Advanced Usage
    All Configuration Settings
    Customizing
    Help and Support

Veți avea nevoie de două secțiuni („Introducere” și „Utilizare avansată”) care să conțină subsecțiunile respective.

Jekyll nu este strict cu locația conținutului său. Se așteaptă pagini în rădăcina site-ului dvs. și va construi orice este acolo. Iată cum puteți organiza aceste pagini în rădăcina site-ului dvs. Jekyll:

.
├── 404.html
├── assets
├── Gemfile
├── _includes
├── index.markdown
├── intro
│   ├── config.md
│   ├── deploy.md
│   ├── index.md
│   └── quickstart.md
├── _layouts
│   ├── default.html
│   ├── page.html
│   └── post.html
├── LICENSE.txt
├── README.md
├── _sass
├── <name>.gemspec
└── usage
    ├── customizing.md
    ├── index.md
    ├── settings.md
    └── support.md

Puteți schimba locația sursei site-ului în Configurație Jekyll.

În Hugo, tot conținutul redat este așteptat în content/ pliant. Acest lucru îl împiedică pe Hugo să încerce să redea pagini pe care nu le doriți, cum ar fi 404.html, ca conținut al site-ului. Iată cum vă puteți organiza content/ director în Hugo:

.
├── _index.md
├── intro
│   ├── config.md
│   ├── deploy.md
│   ├── _index.md
│   └── quickstart.md
└── usage
    ├── customizing.md
    ├── _index.md
    ├── settings.md
    └── support.md

Pentru Hugo, _index.md și index.md înseamnă lucruri diferite. Poate fi util să știți ce fel de Pachet de pagini doriți pentru fiecare secțiune: Leaf, care nu are copii, sau Ramură.

Acum, că aveți o idee despre unde să puneți lucrurile, să ne uităm la cum să creați un șablon de pagină.

Cum funcționează șablonarea

Șabloanele de pagină Jekyll sunt construite cu Limbaj de modelare lichid. Folosește paranteze pentru a afișa conținut variabil pe o pagină, cum ar fi titlul paginii: {{ page.title }}.

Șabloanele lui Hugo folosesc și bretele, dar sunt construite cu Go Șabloane. Sintaxa este similară, dar diferită: {{ .Title }}.

Atât șabloanele lichide, cât și cele de tip Go pot gestiona logica. Utilizări lichide Etichete sintaxă pentru a indica operații logice:

{% if user %}
  Hello {{ user.name }}!
{% endif %}

Și Go Templates își plasează funcțiile și argumentele în sintaxa parantezelor:

{{ if .User }}
    Hello {{ .User }}!
{{ end }}

Limbile de șablonare vă permit să creați o singură pagină HTML scheletică, apoi spuneți generatorului de site să plaseze conținut variabil în zonele pe care le definiți. Să comparăm două posibile default șabloane de pagini pentru Jekyll și Hugo.

Schela lui Jekyll default tema este goală, așa că ne vom uita la tema lor inițială Minime. Iată _layouts/default.html în Jekyll (lichid):

<!DOCTYPE html>
<html lang="{{ page.lang | default: site.lang | default: "en" }}">

  {%- include head.html -%}

  <body>

    {%- include header.html -%}

    <main class="page-content" aria-label="Content">
      <div class="wrapper">
        {{ content }}
      </div>
    </main>

    {%- include footer.html -%}

  </body>

</html>

Iată tema schelelor lui Hugo layouts/_default/baseof.html (Șabloane Go):

<!DOCTYPE html>
<html>
    {{- partial "head.html" . -}}
    <body>
        {{- partial "header.html" . -}}
        <div id="content">
        {{- block "main" . }}{{- end }}
        </div>
        {{- partial "footer.html" . -}}
    </body>
</html>

Sintaxă diferită, aceeași idee. Ambele șabloane aduc biți reutilizabili pentru head.html, header.html, și footer.html. Acestea apar pe o mulțime de pagini, deci are sens să nu trebuie să te repeti.

Ambele șabloane au, de asemenea, un loc pentru conținutul principal, deși șablonul Jekyll folosește o variabilă ({{ content }}) în timp ce Hugo folosește un bloc ({{- block "main" . }}{{- end }}). Blocuri sunt doar un alt mod în care Hugo vă permite să definiți biți reutilizabili.

Acum că știți cum funcționează șablonarea, puteți crea meniul din bara laterală pentru temă.

Crearea unui meniu de nivel superior cu pages obiect

Puteți crea programatic un meniu de nivel superior din paginile dvs. Va arăta astfel:

Introduction
Advanced Usage

Să începem cu Jekyll. Puteți afișa linkuri către paginile site-ului în șablonul dvs. lichid, iterând prin site.pages obiect pe care Jekyll îl oferă și construirea unei liste:

<ul>
    {% for page in site.pages %}
    <li><a href="https://www.freecodecamp.org/news/hugo-vs-jekyll-battle-of-static-site-generator-themes/{{ page.url" absolute_url }}">{{ page.title }}</a></li>
    {% endfor %}
</ul>

Aceasta returnează toate paginile site-ului, inclusiv toate cele pe care s-ar putea să nu le doriți, cum ar fi 404.html. Puteți filtra pentru paginile pe care le doriți efectiv cu încă câteva etichete, cum ar fi includerea condiționată a paginilor dacă au un section: true set de parametri:

<ul>
    {% for page in site.pages %}
    {%- if page.section -%}
    <li><a href="https://www.freecodecamp.org/news/hugo-vs-jekyll-battle-of-static-site-generator-themes/{{ page.url" absolute_url }}">{{ page.title }}</a></li>
    {%- endif -%}
    {% endfor %}
</ul>

Puteți obține același efect cu un pic mai puțin cod în Hugo. Treceți prin Hugo .Pages obiect folosind Go Template range acțiune:

<ul>
{{ range .Pages }}
    <li>
        <a href="https://www.freecodecamp.org/news/hugo-vs-jekyll-battle-of-static-site-generator-themes/{{.Permalink}}">{{.Title}}</a>
    </li>
{{ end }}
</ul>

Acest șablon folosește .Pages obiect pentru a returna toate paginile de nivel superior din content/ a site-ului dvs. Hugo. Deoarece Hugo folosește un folder specific pentru conținutul site-ului pe care doriți să îl redați, nu este necesară nicio filtrare suplimentară pentru a crea un meniu simplu de pagini ale site-ului.

Ambii generatori de site-uri pot utiliza o listă de date definită separat de linkuri pentru a reda un meniu în șablonul dvs. Acest lucru este mai potrivit pentru crearea de legături imbricate, ca aceasta:

Introduction
    Getting Started
    Configuration
    Deploying
Advanced Usage
    All Configuration Settings
    Customizing
    Help and Support

Jekyll acceptă fișiere de date în câteva formate, inclusiv YAML. Iată definiția meniului de mai sus în _data/menu.yml:

section:
  - page: Introduction
    url: /intro
    subsection:
      - page: Getting Started
        url: /intro/quickstart
      - page: Configuration
        url: /intro/config
      - page: Deploying
        url: /intro/deploy
  - page: Advanced Usage
    url: /usage
    subsection:
      - page: Customizing
        url: /usage/customizing
      - page: All Configuration Settings
        url: /usage/settings
      - page: Help and Support
        url: /usage/support

Iată cum să redați datele din șablonul barei laterale:

{% for a in site.data.menu.section %}
<a href="https://www.freecodecamp.org/news/hugo-vs-jekyll-battle-of-static-site-generator-themes/{{ a.url }}">{{ a.page }}</a>
<ul>
    {% for b in a.subsection %}
    <li><a href="{{ b.url }}">{{ b.page }}</a></li>
    {% endfor %}
</ul>
{% endfor %}

Această metodă vă permite să creați un meniu personalizat, la două niveluri de cuibărire. Nivelurile de cuibărire sunt limitate de for bucle în șablon. Pentru o versiune recursivă care gestionează alte niveluri de cuibărire, consultați Navigare în copac imbricată cu recursivitate.

Hugo face ceva similar cu șabloane de meniu. Puteți defini linkuri de meniu în Configurarea site-ului Hugoși chiar adaugă proprietăți utile pe care Hugo le înțelege, cum ar fi ponderarea. Iată o definiție a meniului de mai sus în config.yaml:

sectionPagesMenu: main

menu:  
  main:
    - identifier: intro
      name: Introduction
      url: /intro/
      weight: 1
    - name: Getting Started
      parent: intro
      url: /intro/quickstart/
      weight: 1
    - name: Configuration
      parent: intro
      url: /intro/config/
      weight: 2
    - name: Deploying
      parent: intro
      url: /intro/deploy/
      weight: 3
    - identifier: usage
      name: Advanced Usage
      url: /usage/
    - name: Customizing
      parent: usage
      url: /usage/customizing/
      weight: 2
    - name: All Configuration Settings
      parent: usage
      url: /usage/settings/
      weight: 1
    - name: Help and Support
      parent: usage
      url: /usage/support/
      weight: 3

Hugo folosește identifier, care trebuie să se potrivească cu numele secțiunii, împreună cu parent variabilă pentru a gestiona cuibărirea. Iată cum să redați meniul din șablonul barei laterale:

<ul>
    {{ range .Site.Menus.main }}
    {{ if .HasChildren }}
    <li>
        <a href="https://www.freecodecamp.org/news/hugo-vs-jekyll-battle-of-static-site-generator-themes/{{ .URL }}">{{ .Name }}</a>
    </li>
    <ul class="sub-menu">
        {{ range .Children }}
        <li>
            <a href="https://www.freecodecamp.org/news/hugo-vs-jekyll-battle-of-static-site-generator-themes/{{ .URL }}">{{ .Name }}</a>
        </li>
        {{ end }}
    </ul>
    {{ else }}
    <li>
        <a href="https://www.freecodecamp.org/news/hugo-vs-jekyll-battle-of-static-site-generator-themes/{{ .URL }}">{{ .Name }}</a>
    </li>
    {{ end }}
    {{ end }}
</ul>

range funcția iterează peste datele din meniu și ale lui Hugo .Children variabilă gestionează paginile imbricate pentru dvs.

Punerea împreună a șablonului

Cu meniul în bara laterală reutilizabilă (_includes/sidebar.html pentru Jekyll și partials/sidebar.html pentru Hugo), îl puteți adăuga la default.html șablon.

În Jekyll:

<!DOCTYPE html>
<html lang="{{ page.lang | default: site.lang | default: "en" }}">

{%- include head.html -%}

<body>
    {%- include sidebar.html -%}

    {%- include header.html -%}

    <div id="content" class="page-content" aria-label="Content">
        {{ content }}
    </div>

    {%- include footer.html -%}

</body>

</html>

În Hugo:

<!DOCTYPE html>
<html>
{{- partial "head.html" . -}}

<body>
    {{- partial "sidebar.html" . -}}

    {{- partial "header.html" . -}}
    <div id="content" class="page-content" aria-label="Content">
        {{- block "main" . }}{{- end }}
    </div>
    {{- partial "footer.html" . -}}
</body>

</html>

Când site-ul este generat, fiecare pagină va conține tot codul din sidebar.html.

Creați o foaie de stil

Ambele generatoare de site acceptă Sass pentru crearea foilor de stil CSS. Jekyll are încorporată procesarea Sass, iar Hugo folosește Hugo Pipes. Ambele opțiuni au câteva ciudățenii.

Sass și CSS în Jekyll

Pentru a procesa un fișier Sass în Jekyll, creați definițiile stilului în _sass director. De exemplu, într-un fișier la _sass/style-definitions.scss:

$background-color: #eef !default;
$text-color: #111 !default;

body {
  background-color: $background-color;
  color: $text-color;
}

Jekyll nu va genera acest fișier direct, deoarece procesează doar fișiere cu materie primă. Pentru a crea calea de fișier a rezultatului final pentru foaia de stil a site-ului dvs., utilizați un substituent cu elementul gol gol unde doriți .css fișierul să apară. De exemplu, assets/css/style.scss. În acest fișier, pur și simplu importați stilurile:

---
---

@import "style-definitions";

Această configurație destul de ciudată are un avantaj: puteți utiliza etichete și variabile de șablon lichide în fișierul dvs. substituent. Acesta este un mod frumos de a permite utilizatorilor să seteze variabile de pe site _config.yml, de exemplu.

Foaia de stil CSS rezultată din site-ul dvs. generat are calea /assets/css/style.css. Puteți face link către acesta din site-ul dvs. head.html folosind:

<link rel="stylesheet" href="https://www.freecodecamp.org/news/hugo-vs-jekyll-battle-of-static-site-generator-themes/{{"/assets/css/style.css" | relative_url }}" media="screen">

Sass și Hugo Pipes în Hugo

Hugo folosește Hugo Pipes pentru a procesa Sass la CSS. Puteți realiza acest lucru utilizând funcția de procesare a activelor lui Hugo, resources.ToCSS, care așteaptă o sursă în assets/ director. Acesta ia fișierul SCSS ca argument.

Cu definițiile stilului dvs. într-un fișier Sass la assets/sass/style.scss, iată cum puteți obține, procesa și conecta Sass-ul dvs. la tema dvs. head.html:

{{ $style := resources.Get "/sass/style.scss" | resources.ToCSS }}
<link rel="stylesheet" href="https://www.freecodecamp.org/news/hugo-vs-jekyll-battle-of-static-site-generator-themes/{{ $style.RelPermalink }}" media="screen">

Prelucrarea activelor Hugo necesită Hugo extins, pe care este posibil să nu îl aveți în mod implicit. Puteți obține extins Hugo de la pagina de lansări.

Configurați și implementați în paginile GitHub

Înainte ca generatorul de site să vă poată construi site-ul, are nevoie de un fișier de configurare pentru a seta câțiva parametri necesari. Fișierele de configurare sunt live în directorul rădăcină al site-ului. Printre alte setări, puteți declara numele temei de utilizat atunci când construiți site-ul.

Configurați Jekyll

Iată un minim _config.yml pentru Jekyll:

title: Your awesome title
description: >- # this means to ignore newlines until "baseurl:"
  Write an awesome description for your new site here. You can edit this
  line in _config.yml. It will appear in your document head meta (for
  Google search results) and in your feed.xml site description.
baseurl: "" # the subpath of your site, e.g. /blog
url: "" # the base hostname & protocol for your site, e.g. http://example.com
theme: # for gem-based themes
remote_theme: # for themes hosted on GitHub, when used with GitHub Pages

Cu remote_theme, orice Tema Jekyll găzduită pe GitHub poate fi utilizată cu site-uri găzduite pe paginile GitHub.

Jekyll are o configurare implicită, deci orice parametru adăugat în fișierul de configurare va suprascrie valorile implicite. Aici sunt setări suplimentare de configurare.

Configurați-l pe Hugo

Iată un exemplu minim al lui Hugo config.yml:

baseURL: https://example.com/ # The full domain your site will live at
languageCode: en-us
title: Hugo Docs Site
theme: # theme name

Hugo nu face presupuneri, așa că, dacă lipsește un parametru necesar, veți vedea un avertisment atunci când vă construiți sau serviți site-ul. Aici sunt toate setările de configurare pentru Hugo.

Implementați în paginile GitHub

Ambii generatori construiesc site-ul dvs. cu o comandă.

Pentru Jekyll, utilizați jekyll build. Vedea mai multe opțiuni de construire aici.

Pentru Hugo, folosește hugo. Poți fugi hugo help sau vezi mai multe opțiuni de construire aici.

Va trebui să alegeți sursa pentru site-ul dvs. GitHub Pages. După ce ați terminat, site-ul dvs. se va actualiza de fiecare dată când apelați la o nouă versiune. Desigur, puteți automatiza și construirea paginilor GitHub folosind GitHub Actions. Iată unul pentru construirea și implementarea cu Hugo, și unul pentru construirea și implementarea Jekyll.

Arată timpul!

Toate diferențele substanțiale dintre acești doi generatori se află sub capotă. Totuși, să aruncăm o privire asupra temelor terminate, în două variante de culoare.

Iată Hugo:

Hugo vs Jekyll o batalie epica a temelor generatoare de

Iată Jekyll:

1612119850 245 Hugo vs Jekyll o batalie epica a temelor generatoare de

Stai cine a câștigat?

?

Atât Hugo, cât și Jekyll își au ciudățenii și facilitățile.

Din perspectiva acestui dezvoltator, Jekyll este o alegere viabilă pentru site-uri simple, fără nevoi organizatorice complicate. Dacă doriți să redați câteva postări de o pagină într-un tema disponibilă și gazdă cu GitHub Pages, Jekyll vă va pune în funcțiune destul de repede.

Personal, îl folosesc pe Hugo. Îmi plac capacitățile organizatorice ale pachetelor sale de pagini și sunt susținute de o echipă dedicată și conștiincioasă care pare să se străduiască într-adevăr să le faciliteze utilizatorilor confortul. Acest lucru este evident în numeroasele funcții ale lui Hugo și în trucurile utile Procesarea imaginii și Shortcodes. Se pare că lansează noi remedieri și versiuni cam atât de des pe cât prepar o ceașcă nouă de cafea – care, în funcție de cazul dvs. de utilizare, poate fi fantastic sau enervant.

Dacă tot nu poți decide, nu-ți face griji. Tema de documentare OpenGitDocs Am creat este disponibil atât pentru Hugo, cât și pentru Jekyll. Începeți cu unul, comutați mai târziu dacă doriți. Acesta este avantajul de a avea opțiuni.