Cum să implementați un blog Hugo pe paginile GitHub cu acțiuni

După ani de construire a software-ului și de scriere a documentației tehnice, am decis să creez un blog pentru a-mi împărtăși experiența și pentru a-i ajuta pe alții în călătorii similare.

Alegerea platformei

În timp ce construirea propriului meu script de publicare Markdown-to-HTML este o idee pentru viitor, prioritatea mea imediată a fost să obțin blogul online rapid.

În zilele noastre, nu cred că există o dificultate în crearea unui site web personal.Există o mare varietate de opțiuni care ajută în acest efort. Voi începe cu listarea alternativelor care îmi vin în minte:

• CMS (de exemplu, WordPress, Content Hub, Joomla, etc.): În timp ce platformele precum WordPress sunt puternice, s-au simțit excesive pentru un blog de conținut static.

• Jekyll: Acest software pare să fie perfect și utilizat pe scară largă de alți dezvoltatori pentru a găzdui bloguri, dar din cauza lipsei mele de experiență cu Ruby, am ales să nu folosesc acest lucru.

• Hugo este scris în Go și folosește sintaxa familiară a șabloanelor Go (dacă se întâmplă să codezi mult în Go), în timp ce afișezi pagini în Markdown (similar cu Jekyll).

• 11ty, Astro, Hexo și alte alternative bazate pe Node.js. Este o chestiune de preferință, dar personal, am decis să minimizez utilizarea instrumentelor Node.js. În timp ce există multe instrumente puternice, ecosistemul Node.js este notoriu pentru schimbarea rapidă, ceea ce m-a condus adesea să nu pot rula proiectele vechi care aveau în mod natural multe dependențe vechi.

Întoarce-te la Hugo

După ce am produs o cantitate substanțială de documentație despre proiectele mele anterioare legate de software, mă simt foarte încrezător să folosesc Markdown și un editor de text pe bază de terminal pentru scrierea mea.

Using a GitHub Repository

Anterior, am creat deja un site GitHub Pages cu fișiere de localizare și am conectat un domeniu la acesta, deci pentru a umple fișierele într-un repo existent, trebuie să introduceți următoarea comandă:

hugo new site . --force

Acest lucru va umple directorul actual al depozitului cu fișiere care sunt necesare pentru a rula site-ul Hugo. După aceea, a fost necesar să setați tema și alți parametri înhugo.tomlDupă ce totul este setat, este posibil să rulați serverul prin introducerea comenzii:hugo server

Executarea serverului în modul de dezvoltare

În acest moment, site-ul este disponibil dinlocalhostDeoarece dezvolt pe un VM cloud la distanță, accesarea serverului local Hugo prinlocalhostA fost necesar să expunem în siguranță instanța localhost lumii exterioare - pentru astfel de nevoi, se utilizează un proxy invers.

În timp ce balancerii de sarcină și proxy-urile inversate, cum ar fi Nginx, sunt destul de frecvente și populare, am alesCaddypentru a servi site-ul meu de dezvoltare, deoarece stabilește certificate SSL (prin Let's Encrypt) fără efort.CaddyEste făcută cuCaddyfile, în cazul în care pentru domeniul de interes scrie unreverse_proxyDeclarație cu portul necesar:

test-blog-domain.com {
	reverse_proxy localhost:1313
}

După lansarea Caddy cu configurația de mai sus, site-ul de dezvoltare va fi disponibil de lahttps://test-blog-domain.com(Având în vedere că unAÎnregistrarea DNS pentrutest-blog-domain.comeste completată cu o adresă IP publică a VM).

Adăugarea unui subiect

Hugo are o serie de teme gratuite care sunt disponibile public pe GitHub.Ceea ce este necesar să faceți pentru a instala unul este să clonați un depozit cu o temă și apoi să actualizațithemeParametrii înhugo.tomlAm ales o temă numităcactusDupă instalare, am primit o eroare de construcție care se plânge că șablonul async Google Analytics nu a fost găsit:

Error: error building site: render: failed to render pages: render of "/" failed: "/home/user/projects/nexo-tech.github.io/themes/cactus/layouts/_default/baseof.html:3:3": execute of template failed: template: index.html:3:3: executing "index.html" at <partial "head.html" .>: error calling partial: execute of template failed: html/template:partials/head.html:47:16: no such template "_internal/google_analytics_async.html"
make: *** [Makefile:2: up] Error

O soluție pentru o astfel de problemă poate fi găsită pegithubComunitatea Hugo este activă, iar multe probleme - inclusiv această eroare Google Analytics - au patch-uri sau discuții existente pe GitHub.

După fixarea altor avertismente de depreciere, site-ul a început să funcționeze:

Implementarea unui site web în CDN: Pagini GitHub

Există numeroase modalități de a implementa un site web static și, în cele mai multe cazuri, este necesar să aveți un hosting sau un server. De obicei, acestea nu sunt gratuite sau au un plan restricționat; cu toate acestea, există excepții de la acest lucru, cum ar fi paginile GitHub. Este posibil să serviți conținut static dintr-o anumită ramură a unui depozit GitHub sau să utilizați acțiuni GitHub pre-construite care se bazează pe crearea de artefacte de construcție și implementarea lor într-un mod personalizat.

Știind că, conturile personale GitHub sunt foarte limitate în ceea ce privește spațiul de stocare a artefactelor, iar gestionarea acelui spațiu de stocare este plictisitoare, am optat pentru soluția mai simplă în care activele site-ului static vor fi actualizate într-o ramură git predefinită (gh-pagesDin fericire, existăactionsÎn special pentru Hugo, tocmai în acest scop:

• action-hugo de Shohei Ueda. O modalitate simplă de a configura Hugo într-un mediu GitHub Actions
• Acțiuni-gh-pagini De asemenea, de Shohei Ueda, această acțiune împinge activele statice către ramura specificată.

Iată codul unui flux de lucru GitHub Actions care va implementa Hugo pe paginile gh. Rețineți că, dacă este nevoie de un domeniu particularizat, un fișier CNAME trebuie copiat înpublicdirectorul înainte de a conducegh-pagesÎn plus, permisiunile de flux de lucru ale depozitului trebuie să fie setate la „Citește și scrie” (se poate găsi înSettings > Actions > General) din

name: Build and Deploy Hugo
on:
  push:
    branches:
      - main  
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v3
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true
      - name: Build site
        run: hugo --minify
      - name: Add CNAME file
        run: cp CNAME public/CNAME
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public
          publish_branch: gh-pages

Odată ce implementarea trece, site-ul ar trebui să fie încărcat la GitHub CDN. Asigurați-vă că configurați paginile GitHub pentru ramura care conține artefacte construite în cazul în care site-ul nu funcționează.

Cu Hugo setat și implementat, mă pot concentra acum pe ceea ce contează - împărtășirea de informații tehnice din experiența mea.

Resurse conexe

• Repository pentru acest site
• Hugo începe rapid
• Configurarea setărilor DNS pentru paginile GitHub
• Cactus tematic pentru Hugo
• Setarea Google Analytics în Hugo
• Caddy reverse proxy pentru pornire rapidă