Hoe een Hugo-blog te implementeren op GitHub-pagina's met acties

Na jaren van het bouwen van software en het schrijven van technische documentatie, heb ik besloten om een blog te maken om mijn ervaring te delen en anderen te helpen op soortgelijke reizen.

Het kiezen van het platform

Hoewel het bouwen van mijn eigen Markdown-to-HTML-publicatie script een idee is voor de toekomst, was mijn directe prioriteit om de blog snel online te krijgen.

Tegenwoordig denk ik niet dat er een moeilijkheid is om een persoonlijke website te maken. Er zijn een breed scala aan opties die helpen bij deze inspanning.

• CMS (bijv. WordPress, Content Hub, Joomla, etc.): Hoewel platforms zoals WordPress krachtig zijn, voelden ze zich overdreven voor een statische contentblog.

• Jekyll: Deze software lijkt perfect en wordt veel gebruikt door andere ontwikkelaars om blogs te hosten, maar vanwege mijn gebrek aan ervaring met Ruby heb ik ervoor gekozen dit niet te gebruiken.

• Hugo is geschreven in Go en maakt gebruik van de vertrouwde syntax van Go-sjablonen (als je veel codeert in Go), terwijl je pagina's weergeeft in Markdown (vergelijkbaar met Jekyll).

• 11ty, Astro, Hexo en andere Node.js-gebaseerde alternatieven. Het is een kwestie van voorkeur, maar persoonlijk heb ik besloten om het gebruik van Node.js-tools te minimaliseren. Hoewel er veel krachtige tools zijn, is het Node.js-ecosysteem berucht om snel te veranderen, wat me vaak heeft geleid tot het niet kunnen uitvoeren van de oude projecten die van nature veel oude afhankelijkheden hadden.

Het opzetten van Hugo

Nadat ik een aanzienlijke hoeveelheid documentatie over mijn eerdere software-gerelateerde projecten heb geproduceerd, voel ik me erg zelfverzekerd met behulp van Markdown en een op terminal gebaseerde teksteditor voor mijn schrijven.

Gebruik een GitHub repository

Eerder had ik al een GitHub Pages-website gemaakt met placeholder-bestanden en er een domein mee verbonden, dus om bestanden in een bestaande repo te vullen, moet je de volgende opdracht invoeren:

hugo new site . --force

Dit zal de huidige repository directory vullen met bestanden die nodig zijn om de Hugo-website uit te voeren.hugo.tomlNadat alles is ingesteld, is het mogelijk om de server uit te voeren door de opdracht in te voeren:hugo server

Server draaien in de ontwikkelingsmodus

Op dit moment is de website beschikbaar vanaflocalhostAangezien ik op een externe cloud VM ontwikkel, heb ik toegang tot de lokale Hugo-server vialocalhostHet was noodzakelijk om de localhost instantie veilig bloot te stellen aan de buitenwereld - voor dergelijke behoeften wordt een omgekeerde proxy gebruikt.

Terwijl load balancers en reverse proxies zoals Nginx vrij gebruikelijk en populair zijn, heb ik gekozenCaddyom mijn dev-website te bedienen omdat het SSL-certificaten instelt (via Let's Encrypt) zonder moeite.CaddyHet is gedaan metCaddyfile, waar voor het domein van belang u eenreverse_proxyVermelding met de benodigde haven:

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

Nadat Caddy met de bovenstaande configuratie is gestart, is de ontwikkelingswebsite beschikbaar vanafhttps://test-blog-domain.com(Aangezien eenADNS-record voortest-blog-domain.comwordt ingevuld met een publiek IP-adres van de VM).

Een thema toevoegen

Hugo heeft een aantal gratis thema's die publiekelijk beschikbaar zijn op GitHub. Wat u moet doen om er een te installeren, is een repository met een thema te klonen en vervolgens dethemeParameters inhugo.tomlIk heb gekozen voor een thema genaamdcactusNa de installatie krijg ik een build-fout die klaagt dat de Google Analytics asynchrone sjabloon niet wordt gevonden:

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

Een oplossing voor een dergelijk probleem kan worden gevonden opgithubDe Hugo-gemeenschap is actief en veel problemen - waaronder deze Google Analytics-fout - hebben bestaande patches of discussies op GitHub.

Na het oplossen van andere afschrijvingswaarschuwingen, begon de site te werken:

Een website implementeren in een CDN: GitHub Pages

Er zijn tal van manieren om een statische website te implementeren, en in de meeste gevallen is het vereist om een hosting of server te hebben. Meestal zijn deze niet gratis of hebben ze een beperkt plan; er zijn echter uitzonderingen op dit, zoals GitHub Pages.

Weten dat, persoonlijke GitHub-accounts zijn zeer beperkt op de opslag artefact ruimte, en het is saai om die opslagruimte te beheren, heb ik gekozen voor de eenvoudiger oplossing waar statische website-activa worden bijgewerkt in een vooraf gedefinieerde git tak (gh-pagesGelukkig zijn eractionsSpeciaal voor Hugo, precies voor dit doel:

• actions-hugo door Shohei Ueda. Een eenvoudige manier om Hugo op te zetten in een GitHub Actions-omgeving
• ook, door Shohei Ueda, deze actie duwt statische activa naar de gespecificeerde tak.

Hier is de code van een GitHub Actions-werkstroom die Hugo zal implementeren op gh-pagina's. Merk op dat als er behoefte is aan een aangepast domein, een CNAME-bestand moet worden gekopieerd naar depublicDirectoraat voor het uitvoeren van degh-pagesBovendien moeten de werkstroommachtigingen van uw repository worden ingesteld op "Lees en schrijf" (kan worden gevonden inSettings > Actions > General) van

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

Zodra de implementatie voorbij is, moet de site worden geüpload naar GitHub CDN. Zorg ervoor dat u GitHub Pages instelt voor de tak die ingebouwde artefacten bevat in het geval de website niet werkt.

Met Hugo ingesteld en geïmplementeerd, kan ik nu concentreren op wat belangrijk is - het delen van technische inzichten uit mijn ervaring.

Gerelateerde middelen

• Repository voor deze website
• Hugo snelle start
• Configureren van DNS-instellingen voor GitHub-pagina's
• Cactus thema voor Hugo
• Google Analytics instellen in Hugo
• Caddy reverse proxy snelle start