Birting með GitHub Pages

Tvær leiðir til að birta statíska heimasíðu: GitHub Actions þýðir kóðann fyrir þig, eða þú birtir tilbúið úttak úr útgáfumöppu.

Þegar skýrslan eða vefsíðan er tilbúin viljum við birta hana á vefnum. GitHub Pages birtir statíska heimasíðu ókeypis beint úr kóðageymslunni. Það eru tvær meginleiðir að því — og munurinn snýst um hver þýðir kóðann.

MikilvægtÍ þessu vinnuflæði birtum við frá main

GitHub Pages er stillanlegt. Í Leið 1 er uppspretta síðunnar GitHub Actions og hún birtir úttakið eftir breytingar á main-greininni. Í Leið 2 er uppspretta síðunnar tilbúið HTML-úttak í valinni grein og möppu. Í báðum tilfellum þarf birtingin að byggja á skrám sem eru komnar á main, svo breytingar á annarri grein birtast ekki fyrr en þær hafa verið sameinaðar.

Forskoðun með quarto preview

Áður en breytingar fara á main — og þar með í birtingu — viltu sjá hvernig síðan lítur út. Til þess er forskoðun (e. preview): Quarto þýðir bókina á tölvunni þinni og opnar hana í vafranum á staðbundinni slóð (http://localhost:…), án þess að nokkuð fari á vefinn.

Skipunin quarto preview gerir þrennt:

  1. þýðir bókina og opnar hana í vafranum,
  2. fylgist með heimildaskránum — í hvert sinn sem þú vistar .qmd-skrá þýðir Quarto hana upp á nýtt, og
  3. endurhleður vafrann sjálfkrafa svo þú sérð breytinguna strax.

Þetta er live reload-vinnuflæði: þú skrifar, vistar og lítur á vafrann. Forskoðunin keyrir áfram í skipanaglugganum þar til þú stöðvar hana með Ctrl+C.

Forskoðunin þýðir á þinni tölvu og notar þína R/Python-uppsetningu. Hún segir því ekki til um hvort byggingin heppnist í skýinu (Leið 1) — til þess þarf að ýta á grein og láta GitHub Actions reyna.

MikilvægtÞú verður að vera í réttri möppu

Quarto-verkefnið er skilgreint í skránni _quarto.yml, og í þessari geymslu er sú skrá í möppunni docs/ — ekki í rót geymslunnar. quarto preview leitar að _quarto.yml í möppunni sem þú stendur í (og upp á við); finni það hana ekki forskoðar það í mesta lagi eina staka skrá — eða gerir ekki neitt.

Því þarf að skipta í réttu möppuna fyrst:

cd docs
quarto preview

make preview (keyrt úr rót geymslunnar) er stytting á nákvæmlega þessu — það keyrir cd docs && quarto preview fyrir þig.

Leið 1 — GitHub Actions þýðir fyrir þig

GitHub Actions er sjálfvirknikerfi GitHub: í hvert sinn sem þú ýtir breytingum getur GitHub keyrt kóðann þinn á sínum eigin þjónum. Fyrir Quarto-síðu þýðir það að GitHub:

  1. sækir kóðageymsluna,
  2. setur upp R/Python og Quarto,
  3. keyrir alla kóðabútana og þýðir .qmd skrárnar, og
  4. birtir tilbúna HTML-úttakið á GitHub Pages.

Kostur: þú ýtir bara .qmd skránum og GitHub sér um restina — úttakið er alltaf í takt við kóðann.

Galli: þýðingin fer fram í skýinu og tekur tíma (það þarf að setja upp R/Python og keyra alla kóðabútana í hvert sinn). Slík keyrsla notar GitHub Actions-mínútur/credits, sem eru takmarkaðar (ókeypis kvóti á opnum geymslum, en telja á einkageymslum).

ÁbendingLéttu bygginguna með freeze

Quarto getur fryst niðurstöður kóðabútanna í möppu (_freeze/) sem þú commit-ar með í kóðageymsluna. Á meðan .qmd-skráin er óbreytt keyrir Quarto ekki kóðann aftur — það notar frystu niðurstöðurnar. Þá þarf CI aðeins að setja upp Quarto (ekki R/Python) og byggja HTML úr frystu niðurstöðunum, sem gerir cloud-bygginguna mun léttari og ódýrari. Þú keyrir kóðann locally til að frysta hann; GitHub sér um afganginn.

MikilvægtÞarf að kveikja á Actions í stillingum

GitHub Actions er ekki sjálfvirkt á. Það þarf að bæta við workflow-skrá (undir .github/workflows/) og velja réttu stillinguna undir Settings → Pages → Build and deployment → Source: GitHub Actions í kóðageymslunni.

Leið 2 — Birta þýtt úttak úr útgáfumöppu

Ef þýðingin er of þung — t.d. dæmin taka langan tíma að keyra eða þarfnast pakka sem erfitt er að setja upp á þjóni GitHub — er hægt að slökkva á GitHub Actions og láta GitHub Pages frekar birta úttak úr fastri möppu.

Þá:

  1. þýðir notandinn sjálfur skýrsluna á eigin tölvu (quarto render),
  2. ýtir tilbúna HTML-úttakinu inn í kóðageymsluna, og
  3. stillir Settings → Pages → Source: Deploy from a branch og velur möppuna sem geymir HTML-úttakið.

GitHub keyrir þá engan kóða — það birtir bara skrárnar eins og þær koma fyrir.

Aðvörundocs/ er ekki sjálfkrafa útgáfumappa

Í þessari geymslu eru .qmd-heimildaskrárnar í docs/, en venjulegt quarto render skrifar HTML-úttakið í _site/, sem er ekki committað. Ef þú velur Deploy from a branch þarf útgáfumappan að innihalda HTML-skrárnar sem GitHub á að birta. Það þýðir annaðhvort að breyta Quarto-stillingunni þannig að úttakið fari í möppu sem á að committa, eða færa/copy-a tilbúna úttakið í slíka möppu áður en þú ýtir á GitHub.

AthugasemdHvernig þessi vefsíða er birt

Þessi bók notar Leið 1: GitHub Actions þýðir hana og birtir sjálfkrafa við merge á main.

Hún frystir ekki. CI setur upp R og keyrir kóðabútana frá grunni við hverja byggingu, svo það sem stendur á síðunni er alltaf nýkeyrt. Frysting er valkostur sem borgar sig þegar kóðinn er þungur í keyrslu eða þarf uppsetningu sem er fyrirhafnarsöm í skýinu — hvorugt á við hér.

Höfundur þýðir locally (quarto render) til að forskoða, en það er valkvætt; GitHub byggir hvort eð er upp á nýtt.

Hvor leiðin hentar?

Actions þýðir Útgáfumappa
Hver keyrir kóðann? GitHub Þú, á eigin tölvu
Kostnaður Actions-mínútur/credits (þýðing í skýi) Enginn (bara birting)
Handavinna Ýta .qmd og gleyma því Muna að render + ýta HTML-úttaki
Best þegar Þýðing er létt og hröð Þýðing er þung eða flókin

Í stuttu máli: byrjaðu á GitHub Actions því það heldur úttakinu sjálfkrafa í takt við kóðann. Ef byggingin verður of þung skaltu skipta yfir í útgáfumöppu-leiðina.